☰
PGF/TikZ Manual | PGFplots | TikZ Editor

TikZ and PGF Manual

TikZ

15 Actions on Paths

15.1 Overview

Once a path has been constructed, different things can be done with it. It can be drawn (or stroked) with a “pen”, it can be filled with a color or shading, it can be used for clipping subsequent drawing, it can be used to specify the extend of the picture – or any combination of these actions at the same time.

To decide what is to be done with a path, two methods can be used. First, you can use a special-purpose command like \draw to indicate that the path should be drawn. However, commands like \draw and \fill are just abbreviations for special cases of the more general method: Here, the \path command is used to specify the path. Then, options encountered on the path indicate what should be done with the path.

For example, \path (0,0) circle [radius=1cm]; means: “This is a path consisting of a circle around the origin. Do not do anything with it (throw it away).” However, if the option draw is encountered anywhere on the path, the circle will be drawn. “Anywhere” is any point on the path where an option can be given, which is everywhere where a path command like circle [radius=1cm] or rectangle (1,1) or even just (0,0) would also be allowed. Thus, the following commands all draw the same circle:


\path [draw] (0,0) circle [radius=1cm];
\path (0,0) [draw] circle [radius=1cm];
\path (0,0) circle [radius=1cm] [draw];

Finally, \draw (0,0) circle [radius=1cm]; also draws a path, because \draw is an abbreviation for \path [draw] and thus the command expands to the first line of the above example.

Similarly, \fill is an abbreviation for \path[fill] and \filldraw is an abbreviation for the command \path[fill,draw]. Since options accumulate, the following commands all have the same effect:


\path [draw,fill] (0,0) circle [radius=1cm];
\path [draw] [fill] (0,0) circle [radius=1cm];
\path [fill] (0,0) circle [radius=1cm] [draw];
\draw [fill] (0,0) circle [radius=1cm];
\fill (0,0) [draw] circle [radius=1cm];
\filldraw (0,0) circle [radius=1cm];

In the following subsection the different actions that can be performed on a path are explained. The following commands are abbreviations for certain sets of actions, but for many useful combinations there are no abbreviations:

  • \draw

    • Inside {tikzpicture} this is an abbreviation for \path[draw].

  • \shade

    • Inside {tikzpicture} this is an abbreviation for \path[shade].

15.2 Specifying a Color

The most unspecific option for setting colors is the following:

As pointed out above, the color= option applies to “everything” (except to shadings), which is not always what you want. Because of this, there are several more specialized color options. For example, the draw= option sets the color used for drawing, but does not modify the color used for filling. These color options are documented where the path action they influence is described.

3 Cont users should be aware that \definecolor has a different meaning in Cont. There is a low-level equivalent named \pgfutil@definecolor which can be used instead.

15.3 Drawing a Path

You can draw a path using the following option:

The following subsections list the different options that influence how a path is drawn. All of these options only have an effect if the draw option is given (directly or indirectly).

15.3.1 Graphic Parameters: Line Width, Line Cap, and Line Join

There are a number of predefined styles that provide more “natural” ways of setting the line width. You can also redefine these styles.

15.3.2 Graphic Parameters: Dash Pattern

  • /tikz/dash=⟨dash pattern⟩phase⟨dash phase⟩(no default)

    • Sets the dashing pattern and phase at the same time.

    (-tikz- diagram)


    \begin{tikzpicture}
    \draw [dash=on 20pt off 10pt phase 0pt] (0pt,3pt) -- (3.5cm,3pt);
    \draw [dash=on 20pt off 10pt phase 10pt] (0pt,0pt) -- (3.5cm,0pt);
    \end{tikzpicture}

As for the line thickness, some predefined styles allow you to set the dashing conveniently.

15.3.3 Graphic Parameters: Draw Opacity

When a line is drawn, it will normally “obscure” everything behind it as if you had used perfectly opaque ink. It is also possible to ask TikZ to use an ink that is a little bit (or a big bit) transparent using the draw opacity option. This is explained in Section 23 on transparency in more detail.

15.3.4 Graphic Parameters: Double Lines and Bordered Lines

  • /tikz/double distance=⟨dimension⟩ (no default, initially 0.6pt)

    • Sets the distance the “two” lines are spaced apart. In reality, this is the thickness of the line that is used to draw the path for the second time. The thickness of the first time the path is drawn is twice the normal line width plus the given ⟨dimension⟩. As a side-effect, this option “selects” the double option.

    (-tikz- diagram)


    \begin{tikzpicture}
    \draw[very thick,double] (0,0) arc (180:90:1cm);
    \draw[very thick,double distance=2pt] (1,0) arc (180:90:1cm);
    \draw[thin,double distance=2pt] (2,0) arc (180:90:1cm);
    \end{tikzpicture}

  • /tikz/double distance between line centers=⟨dimension⟩(no default)

    • This option works like double distance, only the distance is not the distance between (inner) borders of the two main lines, but between their centers. Thus, the thickness the first time the path is drawn is the normal line width plus the given ⟨dimension⟩, while the line width of the second line that is drawn is ⟨dimension⟩ minus the normal line width. As a side-effect, this option “selects” the double option.

    (-tikz- diagram)


    \begin{tikzpicture}[double distance between line centers=3pt]
    \foreach \lw in {0.5,1,1.5,2,2.5}
    \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0);
    \end{tikzpicture}

    (-tikz- diagram)


    \begin{tikzpicture}[double distance=3pt]
    \foreach \lw in {0.5,1,1.5,2,2.5}
    \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0);
    \end{tikzpicture}
15.4 Adding Arrow Tips to a Path

In different situations, TikZ will add arrow tips to the end of a path. For this to happen, a number of different things need to be specified:

  • 1. You must have used the arrows key, explained in detail in Section 16, to setup which kinds of arrow tips you would like.

  • 2. The path may not be closed (like a circle or a rectangle) and, if it consists of several subpaths, further restrictions apply as explained in Section 16.

  • 3. The tips key must be set to an appropriate value, see Section 16 once more.

For the current section on paths, it is only important that when you add the tips option to a path that is not drawn, arrow tips will still be added at the beginning and at the end of the current path. This is true even when “only” arrow tips get drawn for a path without drawing the path itself. Here is an example:

(-tikz- diagram)

\usetikzlibrary {arrows.meta,bending}
\tikz \path[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);

(-tikz- diagram)

\usetikzlibrary {arrows.meta,bending}
\tikz \draw[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);
15.5 Filling a Path

To fill a path, use the following option:

15.5.1 Graphic Parameters: Fill Pattern

Instead of filling a path with a single solid color, it is also possible to fill it with a tiling pattern. Imagine a small tile that contains a simple picture like a star. Then these tiles are (conceptually) repeated infinitely in all directions, but clipped against the path.

Tiling patterns come in two variants: inherently colored patterns and form-only patterns. An inherently colored pattern is, say, a red star with a black border and will always look like this. A form-only pattern may have a different color each time it is used, only the form of the pattern will stay the same. As such, form-only patterns do not have any colors of their own, but when it is used the current pattern color is used as its color.

Patterns are not overly flexible. In particular, it is not possible to change the size or orientation of a pattern without declaring a new pattern. For complicated cases, it may be easier to use two nested \foreach statements to simulate a pattern, but patterns are rendered much more quickly than simulated ones.

15.5.2 Graphic Parameters: Interior Rules

The following two options can be used to decide how interior points should be determined:

15.5.3 Graphic Parameters: Fill Opacity

Analogously to the draw opacity, you can also set the fill opacity. Please see Section 23 for more details.

15.6 Generalized Filling: Using Arbitrary Pictures to Fill a Path

Sometimes you wish to “fill” a path with something even more complicated than a pattern, let alone a single color. For instance, you might wish to use an image to fill the path or some other, complicated drawing. In principle, this effect can be achieved by first using the path for clipping and then, subsequently, drawing the desired image or picture. However, there is an option that makes this process much easier:

15.7 Shading a Path

You can shade a path using the shade option. A shading is like a filling, only the shading changes its color smoothly from one color to another.

  • /tikz/shade(no value)

    • Causes the path to be shaded using the currently selected shading (more on this later). If this option is used together with the draw option, then the path is first shaded, then drawn.

    It is not an error to use this option together with the fill option, but it makes no sense.

    (-tikz- diagram)


    \tikz \shade (0,0) circle [radius=1ex];

    (-tikz- diagram)


    \tikz \shadedraw (0,0) circle [radius=1ex];

For some shadings it is not really clear how they can “fill” the path. For example, the ball shading normally looks like this: (-tikz- diagram). How is this supposed to shade a rectangle? Or a triangle?

To solve this problem, the predefined shadings like ball or axis fill a large rectangle completely in a sensible way. Then, when the shading is used to “shade” a path, what actually happens is that the path is temporarily used for clipping and then the rectangular shading is drawn, scaled and shifted such that all parts of the path are filled.

The default shading is a smooth transition from gray to white and from top to bottom. However, other shadings are also possible, for example a shading that will sweep a color from the center to the corners outward. To choose the shading, you can use the shading= option, which will also automatically invoke the shade option. Note that this does not change the shading color, only the way the colors sweep. For changing the colors, other options are needed, which are explained below.

You can also define new shading types yourself. However, for this, you need to use the basic layer directly, which is, well, more basic and harder to use. Details on how to create a shading appropriate for filling paths are given in Section 114.3.

15.8 Establishing a Bounding Box

pgf is reasonably good at keeping track of the size of your picture and reserving just the right amount of space for it in the main document. However, in some cases you may want to say things like “do not count this for the picture size” or “the picture is actually a little large”. For this you can use the option use as bounding box or the command \useasboundingbox, which is just a shorthand for \path[use as bounding box].

There is a node that allows you to get the size of the current bounding box. The current bounding box node has the rectangle shape and its size is always the size of the current bounding box.

Similarly, the current path bounding box node has the rectangle shape and the size of the bounding box of the current path.

(image)


\begin{tikzpicture}
\draw[red] (0,0) circle [radius=2pt];
\draw[red] (2,1) circle [radius=3pt];

\draw (current bounding box.south west) rectangle
(current bounding box.north east);

\draw[red] (3,-1) circle [radius=4pt];

\draw[thick] (current bounding box.south west) rectangle
(current bounding box.north east);
\end{tikzpicture}

Occasionally, you may want to align multiple tikzpicture environments horizontally and/or vertically at some prescribed position. The vertical alignment can be realized by means of the baseline option since supports the concept of box depth natively. For horizontal alignment, things are slightly more involved. The following approach is realized by means of negative \hspaces before and/or after the picture, thereby removing parts of the picture. However, the actual amount of negative horizontal space is provided by means of image coordinates using the trim left and trim right keys:

  • /tikz/trim right=⟨dimension or coordinate or default⟩(no default)

    • This key is similar to trim left: it discards everything which is right of the provided ⟨dimension or coordinate⟩. As for trim left, ⟨dimension⟩ denotes a single \(x\) coordinate of the picture and ⟨coordinate⟩ a coordinate with \(x\) and \(y\) value (although only its \(x\) component will be used).

    We use the same example from above and add trim right:

    (image)


    Text before image.%
    \begin{tikzpicture}[trim left, trim right=2cm, baseline]
    \draw (-1,-1) grid (3,2);
    \fill (0,0) circle [radius=5pt];
    \end{tikzpicture}%
    Text after image.

    In addition to trim left=0pt, we also discard everything which is right of \(x\)=2cm. Furthermore, the baseline key supports vertical alignment as well (using the \(y\)=0cm baseline).

    Use trim right=default to reset the value.

Note that baseline, trim left and trim right are currently the only supported way of truncated bounding boxes which are compatible with image externalization (see the external library for details).

15.9 Clipping and Fading (Soft Clipping)

Clipping path means that all painting on the page is restricted to a certain area. This area need not be rectangular, rather an arbitrary path can be used to specify this area. The clip option, explained below, is used to specify the region that is to be used for clipping.

A fading (a term that I propose, fadings are commonly known as soft masks, transparency masks, opacity masks or soft clips) is similar to clipping, but a fading allows parts of the picture to be only “half clipped”. This means that a fading can specify that newly painted pixels should be partly transparent. The specification and handling of fadings is a bit complex and it is detailed in Section 23, which is devoted to transparency in general.

15.10 Doing Multiple Actions on a Path

If more than one of the basic actions like drawing, clipping and filling are requested, they are automatically applied in a sensible order: First, a path is filled, then drawn, and then clipped (although it took Apple two major revisions of their operating system to get this right…). Sometimes, however, you need finer control over what is done with a path. For instance, you might wish to first fill a path with a color, then repaint the path with a pattern and then repaint it with yet another pattern. In such cases you can use the following two options:

15.11 Decorating and Morphing a Path

Before a path is used, it is possible to first “decorate” and/or “morph” it. Morphing means that the path is replaced by another path that is slightly varied. Such morphings are a special case of the more general “decorations” described in detail in Section 24. For instance, in the following example the path is drawn twice: Once normally and then in a morphed (=decorated) manner.

(-tikz- diagram)

\usetikzlibrary {decorations.pathmorphing}
\begin{tikzpicture}
\draw (0,0) rectangle (3,2);
\draw [red, decorate, decoration=zigzag]
(0,0) rectangle (3,2);
\end{tikzpicture}

Naturally, we could have combined this into a single command using pre- or postaction. It is also possible to deform shapes:

(-tikz- diagram)

\usetikzlibrary {decorations.pathmorphing,shadows}
\begin{tikzpicture}
\node [circular drop shadow={shadow scale=1.05},minimum size=3.13cm,
decorate, decoration=zigzag,
fill=blue!20,draw,thick,circle] {Hello!};
\end{tikzpicture}