Repository navigation
PDF20 Spec 08 Path Construction
Part of: PDF20-Spec-08-Graphics
Navigation: PDF20-Spec-08-Graphics-Objects | PDF20-Spec-Index | PDF20-Spec-08-Colour-Spaces
8.5
Path construction and painting
8.5.1 General Paths define shapes, trajectories, and regions of all sorts. They shall be used to draw lines, define the shapes of filled areas, and specify boundaries for clipping other graphics. The graphics state shall include a current clipping path that shall define the clipping boundary for the current page. At the beginning of each page, the clipping path shall be initialised to the size of the MediaBox. A path may contain any combination of zero or more line segments, which may be straight or curved. Paths may connect to one another or may be disconnected. A pair of segments shall be said to connect only if they are defined consecutively, with the second segment starting where the first one ends. Thus, the order in which the segments of a path are defined shall be significant. Nonconsecutive segments that meet or intersect fortuitously shall not be considered to connect. NOTE
A path is made up of one or more disconnected subpaths, each comprising a sequence of connected segments. The topology of the path is unrestricted: it can be concave or convex, can contain multiple subpaths representing disjoint areas, and can intersect itself in arbitrary ways.
The h operator explicitly shall connect the end of a subpath back to its starting point; such a subpath is said to be closed. A subpath that has not been explicitly closed is said to be open. As discussed in 8.2, "Graphics objects", a path object is defined by a sequence of operators to construct the path, followed by one or more operators to paint the path or to use it as a clipping boundary. PDF path operators fall into three categories: •
Path construction operators (8.5.2, "Path construction operators") define the geometry of a path. A path is constructed by sequentially applying one or more of these operators.
•
Path-painting operators (8.5.3, "Path-painting operators") end a path object, usually causing the object to be painted on the current page in any of a variety of ways.
•
Clipping path operators (8.5.4, "Clipping path operators"), invoked immediately before a pathpainting operator, cause the path object also to be used for clipping of subsequent graphics objects.
© ISO 2020 – All rights reserved
169
ISO 32000-2:2020(E)
8.5.2 Path construction operators 8.5.2.1
General
A path description is built up through the invocation of one or more path construction operators that add segments to it. The path construction operators may be invoked in any sequence, but the first one invoked shall be m or re to begin a new subpath. The path definition may conclude with the application of a path-painting operator such as S, f, or b (see 8.5.3, "Path-painting operators"); this operator may optionally be preceded by one of the clipping path operators W or W* (8.5.4, "Clipping path operators"). NOTE
Note that the path construction operators do not place any marks on the page; only the painting operators do that. A path definition is not complete until a path-painting operator has been applied to it.
The path currently under construction is called the current path. In PDF (unlike PostScript), the current path is not part of the graphics state and is not saved and restored along with the other graphics state parameters. PDF paths shall be strictly internal objects with no explicit representation. After the current path has been painted, it shall become no longer defined; there is then no current path until a new one is begun with the m or re operator. The trailing endpoint of the segment most recently added to the current path is referred to as the current point. If the current path is empty, the current point shall be undefined. Most operators that add a segment to the current path start at the current point; if the current point is undefined, an error shall be generated. "Table 58 — Path construction operators" shows the path construction operators. All operands shall be numbers denoting coordinates in user space. Table 58 — Path construction operators Operands
Operator
Description
xy
m
Begin a new subpath by moving the current point to coordinates (x, y), omitting any connecting line segment. If the previous path construction operator in the current path was also m, the new m overrides it; no vestige of the previous m operation remains in the path.
xy
l (lowercase L) Append a straight line segment from the current point to the point (x, y). The new current point shall be (x, y).
x1 y1 x2 y2 x3 y3
c
Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (x3, y3), using (x1, y1 ) and (x2, y2 ) as the Bézier control points (see 8.5.2.2, "Cubic Bézier curves"). The new current point shall be (x3, y3 ).
x2 y2 x3 y3
v
Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (x3, y3 ), using the current point and (x2, y2 ) as the Bézier control points (see 8.5.2.2, "Cubic Bézier curves"). The new current point shall be (x3, y3 ).
170
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Operands
Operator
Description
x1 y1 x3 y3
y
Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (x3, y3 ), using (x1, y1 ) and (x3, y3 ) as the Bézier control points (see 8.5.2.2, "Cubic Bézier curves"). The new current point shall be (x3, y3 ).
—
h
Close the current subpath by appending a straight line segment from the current point to the starting point of the subpath. If the current subpath is already closed, h shall do nothing. This operator terminates the current subpath. Appending another segment to the current path shall begin a new subpath, even if the new segment begins at the endpoint reached by the h operation.
x y width height
re
Append a rectangle to the current path as a complete subpath, with lower-left corner (x, y) and dimensions width and height in user space. The operation: x y width height re is equivalent to: 𝑥𝑦m ( 𝑥 + 𝑤𝑖𝑑𝑡ℎ ) y 𝐥 ( 𝑥 + 𝑤𝑖𝑑𝑡ℎ )( 𝑦 + ℎ𝑒𝑖𝑔ℎ𝑡 ) 𝐥 𝑥 ( 𝑦 + ℎ𝑒𝑖𝑔ℎ𝑡 ) 𝐥 h
8.5.2.2
Cubic Bézier curves
Curved path segments shall be specified as cubic Bézier curves. Such curves shall be defined by four points: the two endpoints (the current point P0 and the final point P3) and two control points P1 and P2.Given the coordinates of the four points, the curve shall be generated by varying the parameter t from 0.0 to 1.0 in the following equation: 𝑅(𝑡) = (1 − 𝑡)3 𝑃0 + 3𝑡(1 − 𝑡)2 𝑃1 + 3𝑡 2 (1 − 𝑡)𝑃2 + 𝑡 3 𝑃3 When t = 0.0, the value of the function R(t) coincides with the current point P0 ; when t = 1.0, R(t) coincides with the final point P3. Intermediate values of t generate intermediate points along the curve. The curve does not, in general, pass through the two control points P1 and P2. NOTE 1
NOTE 2
Cubic Bézier curves have two useful properties: o
The curve can be very quickly split into smaller pieces for rapid rendering.
o
The curve is contained within the convex hull of the four points defining the curve, most easily visualized as the polygon obtained by stretching a rubber band around the outside of the four points. This property allows rapid testing of whether the curve lies completely outside the visible region, and hence does not have to be rendered.
The Bibliography lists several books that describe cubic Bézier curves in more depth.
The most general PDF operator for constructing curved path segments is the c operator, which specifies the coordinates of points P1, P2, and P3 explicitly, as shown in "Figure 16 — Cubic Bézier curve generated by the c operator". (The starting point, P0, is defined implicitly by the current point.) © ISO 2020 – All rights reserved
171
ISO 32000-2:2020(E)
Figure 16 — Cubic Bézier curve generated by the c operator Two more operators, v and y, each specify one of the two control points implicitly (see "Figure 17 — Cubic Bézier curves generated by the v and y operators"). In both of these cases, one control point and the final point of the curve shall be supplied as operands; the other control point shall be implied: •
For the v operator, the first control point shall coincide with initial point of the curve.
•
For the y operator, the second control point shall coincide with final point of the curve.
Figure 17 — Cubic Bézier curves generated by the v and y operators
8.5.3 Path-painting operators 8.5.3.1
General
The path-painting operators end a path object, causing it to be painted on the current page in the manner that the operator specifies. The principal path-painting operators shall be S (for stroking) and f (for filling). Variants of these operators combine stroking and filling in a single operation or apply different rules for determining the area to be filled. Attempting to execute a painting operator when the current path is undefined (at the beginning of a new page or immediately after a painting operator has been executed) shall generate an error. "Table 59 — Path-painting operators" lists all the path172
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
painting operators. Table 59 — Path-painting operators Operands Operator Description —
S
Stroke the path.
—
s
Close and stroke the path. This operator shall have the same effect as the sequence h S.
—
f
Fill the path, using the non-zero winding number rule to determine the region to fill (see 8.5.3.3.2, "Non-zero winding number rule"). Any subpaths that are open shall be implicitly closed before being filled.
—
F
Equivalent to f; deprecated in PDF 2.0 and included only for compatibility. Although PDF readers shall be able to accept this operator, PDF writers should use f instead.
—
f*
Fill the path, using the even-odd rule to determine the region to fill (see 8.5.3.3.3, "Evenodd rule").
—
B
Fill and then stroke the path, using the non-zero winding number rule to determine the region to fill. This operator shall produce the same result as constructing two identical path objects, painting the first with f and the second with S. NOTE
The filling and stroking portions of the operation consult different values of several graphics state parameters, such as the current colour. See also 11.7.4.4, "Special pathpainting considerations".
—
B*
Fill and then stroke the path, using the even-odd rule to determine the region to fill. This operator shall produce the same result as B, except that the path is filled as if with f* instead of f. See also 11.7.4.4, "Special path-painting considerations".
—
b
Close, fill, and then stroke the path, using the non-zero winding number rule to determine the region to fill. This operator shall have the same effect as the sequence h B. See also 11.7.4.4, "Special path-painting considerations".
—
b*
Close, fill, and then stroke the path, using the even-odd rule to determine the region to fill. This operator shall have the same effect as the sequence h B*. See also 11.7.4.4, "Special path-painting considerations".
—
n
End the path object without filling or stroking it. This operator shall be a path-painting no-op, used primarily for the side effect of changing the current clipping path (see 8.5.4, "Clipping path operators").
8.5.3.2
Stroking
The S operator shall paint a line along the current path. The stroked line shall follow each straight or curved segment in the path, centred on the segment with sides parallel to it. Each of the path’s subpaths shall be treated separately. The results of the S operator shall depend on the current settings of various parameters in the graphics state (see 8.4, "Graphics state", for further information on these parameters): •
The width of the stroked line is defined by the current line width parameter (8.4.3.2, "Line width").
© ISO 2020 – All rights reserved
173
ISO 32000-2:2020(E)
•
The colour or pattern of the line is defined by the current colour and colour space for stroking operations.
•
The line may be painted either solid or with a dash pattern, as specified by the current line dash pattern (8.4.3.6, "Line dash pattern").
•
If a subpath is open, the unconnected ends shall be treated according to the current line cap style, which may be butt, rounded, or square (see 8.4.3.3, "Line cap style").
•
Wherever two consecutive segments are connected, the joint between them shall be treated according to the current line join style, which may be mitered, rounded, or beveled (see 8.4.3.4, "Line join style"). Mitered joins shall be subject to the current miter limit (see 8.4.3.5, "Miter limit").
Points at which unconnected segments happen to meet or intersect receive no special treatment. In particular, using an explicit l operator to give the appearance of closing a subpath, rather than using h, may result in a messy corner, because line caps are applied instead of a line join. •
The stroke adjustment parameter (PDF 1.2) specifies that coordinates and line widths be adjusted automatically to produce strokes of uniform thickness despite rasterization effects (see 10.7.5, "Automatic stroke adjustment").
•
For transparency compositing purposes a path shall be treated as a single graphics object as described in 11.6.2, "Specifying source and backdrop colours".
If a subpath is degenerate (consists of a single-point closed path or of two or more points at the same coordinates), the S operator shall paint it only if round line caps have been specified, producing a filled circle centred at the single point. If butt or projecting square line caps have been specified, S shall produce no output, because the orientation of the caps would be indeterminate. This rule shall apply only to zero-length subpaths of the path being stroked, and not to zero-length dashes in a dash pattern of a non-degenerate subpath. In the latter case, the line caps shall always be painted, since their orientation is determined by the direction of the underlying path except in the case of a degenerate subpath. A single-point open subpath (specified by a trailing m operator) shall produce no output.
8.5.3.3
Filling
8.5.3.3.1
General
The f operator shall use the current nonstroking colour to paint the entire region enclosed by the current path. If the path consists of several disconnected subpaths, f shall paint the insides of all subpaths, considered together. Any subpaths that are open shall be implicitly closed before being filled, except that if the last subpath in the path is a single-point open subpath (specified by a trailing m operator), it shall be disregarded and not considered to be part of the path. If a subpath is degenerate (consists entirely of one or more points at the same coordinates), the subpath shall be considered to enclose the single device pixel lying under that point; the result is device-dependent and not generally useful. For a simple path, it is intuitively clear what region lies inside. However, for a more complex path, it is not always obvious which points lie inside the path. For more detailed information, see 10.7.4, "Scan conversion rules".
174
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
EXAMPLE
A path that intersects itself or has one subpath that encloses another.
The path machinery shall use one of two rules for determining which points lie inside a path: the nonzero winding number rule and the even-odd rule, both discussed in detail below. The non-zero winding number rule is more versatile than the even-odd rule and shall be the standard rule the f operator uses. Similarly, the W operator shall use this rule to determine the inside of the current clipping path. The even-odd rule is occasionally useful for special effects or for compatibility with other graphics systems; the f* and W* operators invoke this rule.
8.5.3.3.2
Non-zero winding number rule
The non-zero winding number rule determines whether a given point is inside a path by conceptually drawing a ray from that point to infinity in any direction and then examining the places where a segment of the path crosses the ray. Starting with a count of 0, the rule adds 1 each time a path segment crosses the ray from left to right and subtracts 1 each time a segment crosses from right to left. After counting all the crossings, if the result is 0, the point is outside the path; otherwise, it is inside. The method just described does not specify what to do if a path segment coincides with or is tangent to the chosen ray. Since the direction of the ray is arbitrary, the rule simply chooses a ray that does not encounter such problem intersections. For simple convex paths, the non-zero winding number rule defines the inside and outside as one would intuitively expect. The more interesting cases are those involving complex or self-intersecting paths like the ones shown in "Figure 18 — Non-zero winding number rule". For a path consisting of a five-pointed star, drawn with five connected straight line segments intersecting each other, the rule considers the inside to be the entire area enclosed by the star, including the pentagon in the centre. For a path composed of two concentric circles, the areas enclosed by both circles are considered to be inside, provided that both are drawn in the same direction. If the circles are drawn in opposite directions, only the doughnut shape between them is inside, according to the rule; the doughnut hole is outside.
Figure 18 — Non-zero winding number rule
8.5.3.3.3
Even-odd rule
An alternative to the non-zero winding number rule is the even-odd rule. This rule determines whether a point is inside a path by drawing a ray from that point in any direction and simply counting the © ISO 2020 – All rights reserved
175
ISO 32000-2:2020(E)
number of path segments that cross the ray, regardless of direction. If this number is odd, the point is inside; if even, the point is outside. This yields the same results as the non-zero winding number rule for paths with simple shapes, but produces different results for more complex shapes. "Figure 19 — Even-odd rule" shows the effects of applying the even-odd rule to complex paths. For the five-pointed star, the rule considers the triangular points to be inside the path, but not the pentagon in the centre. For the two concentric circles, only the doughnut shape between the two circles is considered inside, regardless of the directions in which the circles are drawn.
Figure 19 — Even-odd rule
8.5.4 Clipping path operators The graphics state shall contain a current clipping path that limits the regions of the page affected by painting operators. The closed subpaths of this path shall define the area that can be painted. Marks falling inside this area shall be applied to the page; those falling outside it shall not be. Subclause 8.5.3.3, "Filling" defines what is inside a path as well as stating rules for closing paths and for degenerate paths. For a given path definition, the same area that would be filled by the f operator is the area that would be used for a clip. In the context of the transparent imaging model (PDF 1.4), the current clipping path constrains an object’s shape (see 11.2, "Overview of transparency"). The effective shape is the intersection of the object’s intrinsic shape with the clipping path; the source shape value shall be 0.0 outside this intersection. Similarly, the shape of a transparency group (defined as the union of the shapes of its constituent objects) shall be influenced both by the clipping path in effect when each of the objects is painted and by the one in effect at the time the group’s results are painted onto its backdrop. The initial clipping path shall include the entire page. A clipping path operator (W or W*, shown in "Table 60 — Clipping path operators") may appear after the last path construction operator and before the path-painting operator that terminates a path object. Although the clipping path operator appears before the painting operator, it shall not alter the clipping path at the point where it appears. Rather, it shall modify the effect of the succeeding painting operator. After the path has been painted, the clipping path in the graphics state shall be set to the intersection of the current clipping path and the newly constructed path.
176
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Table 60 — Clipping path operators Operands Operator Description —
W
Modify the current clipping path by intersecting it with the current path, using the non-zero winding number rule to determine which regions lie inside the clipping path.
—
W*
Modify the current clipping path by intersecting it with the current path, using the even-odd rule to determine which regions lie inside the clipping path.
NOTE 1
In addition to path objects, text objects can also be used for clipping; see 9.3.6, "Text rendering mode".
The n operator (see "Table 59 — Path-painting operators") is a no-op path-painting operator; it shall cause no marks to be placed on the page, but can be used with a clipping path operator to establish a new clipping path. That is, after a path has been constructed, the sequence W n shall intersect that path with the current clipping path and shall establish a new clipping path. NOTE 2
Navigation: PDF20-Spec-08-Graphics-Objects | PDF20-Spec-Index | PDF20-Spec-08-Colour-Spaces