[next] [prev] [prev-tail] [tail] [up]

### 23 Using Paths

#### 23.1 Overview

Once a path has been constructed, it can be used in different ways. For example, you can draw the path or fill it or use it for clipping.

Numerous graph parameters influence how a path will be rendered. For example, when you draw a path, the line width is important as well as the dashing pattern. The options that govern how paths are rendered can all be set with commands starting with \pgfset. All options that influence how a path is rendered always influence the complete path. Thus, it is not possible to draw part of a path using, say, a red color and drawing another part using a green color. To achieve such an effect, you must use two paths.

In detail, paths can be used in the following ways:

1. You can stroke (also known as draw) a path.
2. You can fill a path with a uniform color.
3. You can clip subsequent renderings against the path.
4. You can shade a path.
5. You can use the path as bounding box for the whole picture.

You can also perform any combination of the above, though it makes no sense to fill and shade a path at the same time.

To perform (a combination of) the first three actions, you can use the following command:

\pgfusepath{<actions>}

  Applies the given <actions> to the current path. Afterwards, the current path is (globally) empty. The following actions are possible:

  - fill fills the path. See Section 23.3 for further details.

    \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{1cm}} \pgfpathlineto{\pgfpoint{1cm}{0cm}} \pgfusepath{fill}
    \end{pgfpicture}

  - stroke strokes the path. See Section 23.2 for further details.

    \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{1cm}} \pgfpathlineto{\pgfpoint{1cm}{0cm}} \pgfusepath{stroke}
    \end{pgfpicture}

  - clip clips all subsequent drawings against the path. See Section 23.4 for further details.

    \begin{pgfpicture} \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{1cm}} \pgfpathlineto{\pgfpoint{1cm}{0cm}} \pgfusepath{stroke,clip}
    \pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm}
    \pgfusepath{fill}
    \end{pgfpicture}

  - discard discards the path, that is, it is not used at all. Giving this option (alone) has the same effect as giving an empty options list.

  When more than one of the first three actions are given, they are applied in the above ordering, regardless of their ordering in <actions>. Thus, {stroke,fill} and {fill,stroke} have the same effect.

To shade a path, use the \pgfshadepath command, which is explained in Section 28.

#### 23.2 Stroking a Path

When you use \pgfusepath{stroke} to stroke a path, several graphic parameters influence how the path is drawn. The commands for setting these parameters are explained in the following.

Note that all graphic parameters apply to the path as a whole, never only to a part of it.

All graphic parameters are local to the current {pgfscope}, but they persists past TEX groups, except for the interior rule (even-odd or nonzero) and the arrow tip kinds. The latter graphic parameters only persist till the end of the current TEX group, but this may change in the future, so do not count on this.

##### 23.2.1 Graphic Parameter: Line Width

\pgfsetlinewidth{<line width>}

  This command sets the line width for subsequent strokes (in the current pgfscope). The line width is given as a normal TEX dimension like 0.4pt or 1mm.

  \begin{pgfpicture} \pgfsetlinewidth{1mm} \pgfpathmoveto{\pgfpoint{0mm}{0mm}} \pgfpathlineto{\pgfpoint{2cm}{0mm}} \pgfusepath{stroke}
  \pgfsetlinewidth{2\pgflinewidth} % double in size
  \pgfpathmoveto{\pgfpoint{0mm}{5mm}}
  \pgfpathlineto{\pgfpoint{2cm}{5mm}}
  \pgfusepath{stroke}
  \end{pgfpicture}

\pgflinewidth

  You can access the current line width via the TEX dimension \pgflinewidth. It will be set to the correct line width, that is, even when a TEX group closed, the value will be correct since it is set globally, but when a {pgfscope} closes, the value is set to the correct value it had before the scope.

##### 23.2.2 Graphic Parameter: Caps and Joins

\pgfsetbuttcap

  Sets the line cap to a butt cap. See Section 10.2.1 for an explanation of what this is.

\pgfsetroundcap

  Sets the line cap to a round cap. See again Section 10.2.1.

\pgfsetrectcap

  Sets the line cap to a square cap. See again Section 10.2.1.

\pgfsetroundjoin

  Sets the line join to a round join. See again Section 10.2.1.

\pgfsetbeveljoin

  Sets the line join to a bevel join. See again Section 10.2.1.

\pgfsetmiterjoin

  Sets the line join to a miter join. See again Section 10.2.1.

\pgfsetmiterlimit{<miter limit factor>}

  Sets the miter limit to <miter limit factor>. See again Section 10.2.1.

##### 23.2.3 Graphic Parameter: Dashing

\pgfsetdash{<list of even length of dimensions>}{<phase>}

  Sets the dashing of a line. The first entry in the list specifies the length of the first solid part of the list. The second entry specifies the length of the following gap. Then comes the length of the second solid part, following by the length of the second gap, and so on. The <phase> specifies where the first solid part starts relative to the beginning of the line.

  \begin{pgfpicture} \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm} \pgfpathmoveto{\pgfpoint{0mm}{0mm}} \pgfpathlineto{\pgfpoint{2cm}{0mm}} \pgfusepath{stroke}
  \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm}
  \pgfpathmoveto{\pgfpoint{0mm}{1mm}}
  \pgfpathlineto{\pgfpoint{2cm}{1mm}}
  \pgfusepath{stroke}
  \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm}
  \pgfpathmoveto{\pgfpoint{0mm}{2mm}}
  \pgfpathlineto{\pgfpoint{2cm}{2mm}}
  \pgfusepath{stroke}
  \end{pgfpicture}

  Use \pgfsetdash{}{0pt} to get a solid dashing.

##### 23.2.4 Graphic Parameter: Stroke Color

\pgfsetstrokecolor{<color>}

  Sets the color used for stroking lines to <color>, where <color> is a LA TEX color like red or black!20!red. Unlike the \color command, the effect of this command lasts till the end of the current {pgfscope} and not till the end of the current TEX group.

  The color used for stroking may be different from the color used for filling. However, a \color command will always “immediately override” any special settings for the stroke and fill colors.

  In plain TEX, this command will also work, but the problem of defining a color arises. After all, plain TEX does not provide LA TEX colors. For this reason, P G F implements a minimalistic “emulation” of the \definecolor, \colorlet, and \color commands. Only gray-scale and rgb colors are supported. For most cases this turns out to be enough.

  \begin{pgfpicture} \pgfsetlinewidth{1pt} \color{red} \pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke} \pgfsetstrokecolor{black}
  \pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke}
  \color{red}
  \pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke}
  \end{pgfpicture}

\pgfsetcolor{<color>}

  Sets both the stroke and fill color. The difference to the normal \color command is that the effect lasts till the end of the current {pgfscope}, not only till the end of the current TEX group.

##### 23.2.5 Graphic Parameter: Stroke Opacity

\pgfsetstrokeopacity{<value>}

  Sets the opacity of stroking operations. The <value> should be a number between 0 and 1, where 1 means “fully opaque” and 0 means “fully transparent.” A value like 0.5 will cause paths to be stroked in a semitransparent way.

  Note: For PostScript output, opacity is rendered correctly only with the most recent versions of GhostScript. Printers and other programs will ignore the opacity setting.

  \begin{pgfpicture} \pgfsetlinewidth{5mm} \color{red} \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke} \color{black}
  \pgfsetstrokeopacity{0.5}
  \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke}
  \end{pgfpicture}

##### 23.2.6 Graphic Parameter: Arrows

After a path has been drawn, P G F can add arrow tips at the ends. Currently, it will only add arrows correctly at the end of paths that consist of a single open part. For other paths, like closed paths or path consisting of multiple parts, the result is not defined.

\pgfsetarrowsstart{<arrow kind>}

  Sets the arrow tip kind used at the start of a (possibly curved) path. When this option is used, the line will often be slightly shortened to ensure that the tip of the arrow will exactly “touch” the “real” start of the line.

  To “clear” the start arrow, say \pgfsetarrowsstart{}.

  \begin{pgfpicture} \pgfsetarrowsstart{latex} \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{0cm}} \pgfusepath{stroke}
  \pgfsetarrowsstart{to}
  \pgfpathmoveto{\pgfpoint{0cm}{2mm}}
  \pgfpathlineto{\pgfpoint{1cm}{2mm}}
  \pgfusepath{stroke}
  \end{pgfpicture}

  The effect of this command persists only till the end of the current TEX scope.

  The different possible arrow kinds are explained in Section 24.

\pgfsetarrowsend{<arrow kind>}

  Sets the arrow tip kind used at the end of a path.

  \begin{pgfpicture} \pgfsetarrowsstart{latex} \pgfsetarrowsend{to} \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{0cm}}
  \pgfusepath{stroke}
  \end{pgfpicture}

\pgfsetarrows{<start kind>-<end kind>}

  Sets the start arrow kind to <start kind> and the end kind to <end kind>.

  \begin{pgfpicture} \pgfsetarrows{latex-to} \pgfpathmoveto{\pgfpointorigin} \pgfpathlineto{\pgfpoint{1cm}{0cm}} \pgfusepath{stroke}
  \end{pgfpicture}

\pgfsetshortenstart{<dimension>}

  This command will shortened the start of every stroked path by the given dimension. This shortening is done in addition to automatic shortening done by a start arrow, but it can be used even if no start arrow is given.

  This command is useful if you wish arrows or lines to “stop shortly before” a given point.

  \begin{pgfpicture} \pgfpathcircle{\pgfpointorigin}{5mm} \pgfusepath{stroke} \pgfsetarrows{latex-} \pgfsetshortenstart{4pt}
  \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle
  \pgfpathlineto{\pgfpoint{2cm}{0cm}}
  \pgfusepath{stroke}
  \end{pgfpicture}

\pgfsetshortenend{<dimension>}

  Works like \pgfsetshortenstart.

#### 23.3 Filling a Path

Filling a path means coloring every interior point of the path with the current fill color. It is not always obvious whether a point is “inside” a path when the path is self-intersecting and/or consists or multiple parts. In this case either the nonzero winding number rule or the even-odd crossing number rule is used to decide, which points lie “inside.” These rules are explained in Section 10.3.

##### 23.3.1 Graphic Parameter: Interior Rule

You can set which rule is used using the following commands:

\pgfseteorule

  Dictates that the even-odd rule is used in subsequent fillings in the current T E X scope. Thus, for once, the effect of this command does not persist past the current TEX scope.

  \begin{pgfpicture} \pgfseteorule \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} \pgfusepath{fill}
  \end{pgfpicture}

\pgfsetnonzerorule

  Dictates that the nonzero winding number rule is used in subsequent fillings in the current TEX scope. This is the default.

  \begin{pgfpicture} \pgfsetnonzerorule \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm} \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm} \pgfusepath{fill}
  \end{pgfpicture}

##### 23.3.2 Graphic Parameter: Filling Color

\pgfsetfillcolor{<color>}

  Sets the color used for filling paths to <color>. Like the stroke color, the effect lasts only till the next use of \color.

##### 23.3.3 Graphic Parameter: Fill Opacity

\pgfsetfillopacity{<value>}

  Sets the opacity of filling operations. As for stroking, the <value> should be a number between 0 and 1.

  The “filling transparency” will also be used for text and images.

  \begin{tikzpicture} \pgfsetfillopacity{0.5} \fill[red] (90:1cm) circle (11mm); \fill[green] (210:1cm) circle (11mm); \fill[blue] (-30:1cm) circle (11mm);
  \end{tikzpicture}

#### 23.4 Clipping a Path

When you add the clip option, the current path is used for clipping subsequent drawings. The same rule as for filling is used to decide whether a point is inside or outside the path, that is, either the even-odd rule or the nonzero rule.

Clipping never enlarges the clipping area. Thus, when you clip against a certain path and then clip again against another path, you clip against the intersection of both.

The only way to enlarge the clipping path is to end the {pgfscope} in which the clipping was done. At the end of a {pgfscope} the clipping path that was in force at the beginning of the scope is reinstalled.

#### 23.5 Using a Path as a Bounding Box

When you add the use as bounding box option, the bounding box of the picture will be enlarged such that the path in encompassed, but any subsequent paths of the current TEX scope will not have any effect on the size of the bounding box. Typically, you use this command at the very beginning of a {pgfpicture} environment.

Left right. |

Left \begin{pgfpicture} \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}} \pgfusepath{use as bounding box} % draws nothing \pgfpathcircle{\pgfpointorigin}{2ex}
\pgfusepath{stroke}
\end{pgfpicture}
right.

[next] [prev] [prev-tail] [front] [up]