9 Syntax for Path Specifications

A path is a series of straight and curved line segments. It is specified following a \path command and the specification must follow a special syntax, which is described in the subsections of the present section.

\path<specification>;

This command is available only inside a {tikzpicture} environment.

The <specification> is a long stream of path operations. Most of these path operations tell TikZ how the path is build. For example, when you write --(0,0), you use a line-to operation and it means “continue the path from wherever you are to the origin.”

At any point where TikZ expects a path operation, you can also give some graphic options, which is a list of options in brackets, such as [rounded corners]. These options can have different effects:

1. Some options take “immediate” effect and apply to all subsequent path operations on the path. For example, the rounded corners option will round all following corners, but not the corners “before” and if the sharp corners is given later on the path (in a new set of brackets), the rounding effect will end.

   \tikz \draw (0,0) -- (1,1)            [rounded corners] -- (2,0) -- (3,1)            [sharp corners] -- (3,0) -- (2,1);

   Another example are the transformation options, which also apply only to subsequent coordinates.

2. The options that have immediate effect can be “scoped” by putting part of a path in curly braces. For example, the above example could also be written as follows:

   \tikz \draw (0,0) -- (1,1)            {[rounded corners] -- (2,0) -- (3,1)}            -- (3,0) -- (2,1);

3. Some options only apply to the path as a whole. For example, the color= option for determining the color used for, say, drawing the path always applies to all parts of the path. If several different colors are given for different parts of the path, only the last one (on the outermost scope) “wins”:

   \tikz \draw (0,0) -- (1,1)            [color=red] -- (2,0) -- (3,1)            [color=blue] -- (3,0) -- (2,1);

   Most options are of this type. In the above example, we would have had to “split up” the path into several \path commands:

   \tikz{\draw (0,0) -- (1,1);       \draw [color=red] (2,0) -- (3,1);       \draw [color=blue] (3,0) -- (2,1);}

By default, the \path command does “nothing” with the path, it just “throws it away.” Thus, if you write \path(0,0)--(1,1);, nothing is drawn in your picture. The only effect is that the area occupied by the picture is (possibly) enlarged so that the path fits inside the area. To actually “do” something with the path, an option like draw or fill must be given somewhere on the path. Commands like \draw do this implicitly.

Finally, it is also possible to give node specifications on a path. Such specifications can come at different locations, but they are always allowed when a normal path operation could follow. A node specification starts with node. Basically, the effect is to typeset the node’s text as normal TEX text and to place it at the “current location” on the path. The details are explained in Section 11.

Note, however, that the nodes are not part of the path in any way. Rather, after everything has been done with the path what is specified by the path options (like filling and drawing the path due to a fill and a draw option somewhere in the <specification>), the nodes are added in a post-processing step.

The following style influences scopes:

• style=every path This style is installed at the beginning of every path. This can be useful for (temporarily) adding, say, the draw option to everything in a scope.

  \begin{tikzpicture}[fill=examplefill] % only sets the color   \tikzstyle{every path}=[draw]           % all paths are drawn   \fill  (0,0) rectangle +(1,1);   \shade (2,0) rectangle +(1,1); \end{tikzpicture}

9.1 The Move-To Operation

The perhaps simplest operation is the move-to operation, which is specified by just giving a coordinate where a path operation is expected.

\path  ... <coordinate> ...;

The move-to operation normally starts a path at a certain point. This does not cause a line segment to be created, but it specifies the starting point of the next segment. If a path is already under construction, that is, if several segments have already been created, a move-to operation will start a new part of the path that is not connected to any of the previous segments.

\begin{tikzpicture}   \draw (0,0) --(2,0) (0,1) --(2,1); \end{tikzpicture}

In the specification (0,0) --(2,0) (0,1) --(2,1) two move-to operations are specified: (0,0) and (0,1). The other two operations, namely --(2,0) and --(2,1) are line-to operations, described next.

9.2 The Line-To Operation

9.2.1 Straight Lines

\path  ... --<coordinate> ...;

The line-to operation extends the current path from the current point in a straight line to the given coordinate. The “current point” is the endpoint of the previous drawing operation or the point specified by a prior move-to operation.

You use two minus signs followed by a coordinate in round brackets. You can add spaces before and after the --.

When a line-to operation is used and some path segment has just been constructed, for example by another line-to operation, the two line segments become joined. This means that if they are drawn, the point where they meet is “joined” smoothly. To appreciate the difference, consider the following two examples: In the left example, the path consists of two path segments that are not joined, but that happen to share a point, while in the right example a smooth join is shown.

\begin{tikzpicture}[line width=10pt]   \draw (0,0) --(1,1)  (1,1) --(2,0);   \draw (3,0) -- (4,1) -- (5,0);   \useasboundingbox (0,1.5); % make bounding box higher \end{tikzpicture}

9.2.2 Horizontal and Vertical Lines

Sometimes you want to connect two points via straight lines that are only horizontal and vertical. For this, you can use two path construction operations.

\path  ... -|<coordinate> ...;

This operation means “first horizontal, then vertical.”

\begin{tikzpicture}   \draw (0,0) node(a) [draw] {A}  (1,1) node(b) [draw] {B};   \draw (a.north) |- (b.west);   \draw[color=red] (a.east) -| (2,1.5) -| (b.north); \end{tikzpicture}

\path  ... |-<coordinate> ...;

This operations means “first vertical, then horizontal.”

9.2.3 Snaked Lines

The line-to operation can not only be used to append straight lines to the path, but also “snaked” lines (called thus because they look a little bit like snakes seen from above).

TikZ and PGF use a concept that I termed snakes for appending such “squiggly” lines. A snake specifies a way of extending a path between two points in a “fancy manner.”

Normally, a snake will just connect the start point to the end point without starting new subpaths. Thus, a path containing a snaked line can, nevetheless, still be used for filling. However, this is not always the case. Some snakes consist of numerous unconnected segments. “Lines” consisting of such snakes cannot be used as the borders of enclosed areas.

Here are some examples of snakes in action:

No special path operation is needed to use a snake. Instead, you use the following option to “switch on” snaking:

• snake=<snake name> This option causes the snake <snake name> to be used for subsequent line-to operations. So, whenever you use the -- syntax to specify that a straight line should be added to the path, a snake to this path will be added instead. Snakes will also be used when you use the -| and |- syntax and also when you use the rectangle operation. Snakes will not be used when you use the curve-to operation nor when any other “curved” line is added to the path.

  This option has to be given anew for each path. However, you can also leave out the <snake name>. In this case, the enclosing scope’s <snake name> is used. Thus, you can specify a “standard” snake name for scope and then just say \draw[snake] every time this snake should actually be used.

  The <snake name>none is special. It can be used to switch off snaking after it has been switched on on a path.

  A bit strangely, no valid <snake names> are defined by TikZ by default. Instead, you have to include the library package pgflibrarysnakes. This package defines numerous snakes, see Section 14.2 for the complete list.

Most snakes can be configured. For example, for a snake that looks like a sine curve, you might wish to change the amplitude or the frequency. There are numerous options that influence these parameters. Not all options apply to all snakes, see Section 14.2 once more for details.

• gap before snakes=<dimension> This option allows you to add a certain “gap” to the snake at its beginning. The snake will not start at the current point; instead the start point of the snake is move be <dimension> in the direction of the target.

  \begin{tikzpicture}   \draw[help lines] (0,0) grid (3,2);   \draw[snake=zigzag]                      (0,1) -- ++(3,1);   \draw[snake=zigzag,gap before snake=1cm] (0,0) -- ++(3,1); \end{tikzpicture}

• gap after snake=<dimension> This option has the same effect as gap before snake, only it affects the end of the snake, which will “end early.”
• gap around snake=<dimension> This option sets the gap before and after the gap to <dimension>.

  \begin{tikzpicture}   \draw[help lines] (0,0) grid (3,2);   \draw[snake=brace]                      (0,1) -- ++(3,1);   \draw[snake=brace,gap around snake=5mm] (0,0) -- ++(3,1); \end{tikzpicture}

• line before snake=<dimension> This option works like gap before snake, only it will connect the current point with a straight line to the start of the snake.

  \begin{tikzpicture}   \draw[help lines] (0,0) grid (3,2);   \draw[snake=zigzag]                       (0,1) -- ++(3,1);   \draw[snake=zigzag,line before snake=1cm] (0,0) -- ++(3,1); \end{tikzpicture}

• line after snake=<dimension> Works line gap after snake, only it adds a straight line.
• line around snake=<dimension> Works line gap around snake, only it adds straight lines.
• raise snake=<dimension> This option can be used with all snakes. It will offset the snake by “raising” it by <dimension>. A negative <dimension> will lower the snake. Raising and lowering is always relative to the line along which the snake is drawn. Here is an example:

  \begin{tikzpicture}   \node (a) {A};   \node (b) at (2,1) {B};   \draw                                  (a) -- (b);   \draw[snake=brace]                     (a) -- (b);   \draw[snake=brace,raise snake=5pt,red] (a) -- (b); \end{tikzpicture}

• mirror snake This option causes the snake to be “reflected along the path.” This is best understood by looking at an example:

  \begin{tikzpicture}   \node (a) {A};   \node (b) at (2,1) {B};   \draw                                     (a) -- (b);   \draw[snake=brace]                        (a) -- (b);   \draw[snake=brace,mirror snake,red,thick] (a) -- (b); \end{tikzpicture}

  This option can be used with every snake and can be combined with the raise snake option.

• segment amplitude=<dimension> This option sets the “amplitude” of the snake. For a snake that is a sine wave this would be the amplitude of this line. For other snakes this value typically describes how far the snakes “rises above” or “falls below” the path. For some snakes, this value is ignored.

  \begin{tikzpicture}   \node (a) {A}   node (b) at (2,1) {B}  node (c) at (2,-1) {C};   \draw[snake=zigzag]                                 (a) -- (b);   \draw[snake=zigzag,segment amplitude=5pt,red,thick] (a) -- (c); \end{tikzpicture}

• segment length=<dimension> This option sets the length of each “segment” of a snake. For a sine wave this would be the wave length, for other snakes it is the length of each “repetitive part” of the snake.

  \begin{tikzpicture}   \node (a) {A}   node (b) at (2,1) {B}  node (c) at (2,-1) {C};   \draw[snake=zigzag]                               (a) -- (b);   \draw[snake=zigzag,segment length=20pt,red,thick] (a) -- (c); \end{tikzpicture}

  \begin{tikzpicture}   \node (a) {A}   node (b) at (2,1) {B}  node (c) at (2,-1) {C};   \draw[snake=bumps]                               (a) -- (b);   \draw[snake=bumps,segment length=20pt,red,thick] (a) -- (c); \end{tikzpicture}

• segment object length=<dimension> This option sets the length of the objects inside each segment of a snake. This option is only used for snakes in which each segment contains an object like a triangle or a star.

  \begin{tikzpicture}   \node (a) {A}   node (b) at (2,1) {B}  node (c) at (2,-1) {C};   \draw[snake=triangles]                                     (a) -- (b);   \draw[snake=triangles,segment object length=8pt,red,thick] (a) -- (c); \end{tikzpicture}

• segment angle=<degrees> This option sets an angle that is interpreted in a snake-specific way. For example, the waves and expanding waves snakes interpret this as (half the) opening angle of the wave. The border snake uses this value for the angle of the little ticks.

  \begin{tikzpicture}[segment amplitude=10pt]   \node (a) {A}   node (b) at (2,0) {B};   \draw[snake=border]                            (a) -- (b);   \draw[snake=border,segment angle=20,red,thick] (a) -- (b); \end{tikzpicture}

  \begin{tikzpicture}[segment amplitude=10pt]   \node (a)            {A}   node (b)  at (2,0)  {B};   \node (a') at (0,-1) {A}   node (b') at (2,-1) {B};   \draw[snake=expanding waves]                            (a)  -- (b);   \draw[snake=expanding waves,segment angle=20,red,thick] (a') -- (b'); \end{tikzpicture}

• segment aspect=<ratio> This option sets an aspect ratio that is interpreted in a snake-specific way. For example, for the coils snake this describes the “direction” from which the coil is viewed.

  \begin{tikzpicture}[segment amplitude=5pt,segment length=5pt]   \node (a) {A}   node (b) at (2,1) {B}  node (c) at (2,-1) {C};   \draw[snake=coil]                            (a) -- (b);   \draw[snake=coil,segment aspect=0,red,thick] (a) -- (c); \end{tikzpicture}

It is possible to define new snakes, but this cannot be done inside TikZ. You need to use the command \pgfdeclaresnake from the basic level directly, see Section 22.

The following styles define combinations of segment settings that may be useful:

• style=snake triangles 45 Installs a snake the consists of little triangles with an opening angle of 45^o.
• style=snake triangles 60 Installs a snake the consists of little triangles with an opening angle of 60^o.
• style=snake triangles 90 Installs a snake the consists of little triangles with an opening angle of 90^o.

9.3 The Curve-To Operation

The curve-to operation allows you to extend a path using a Bézier curve.

\path  ... ..controls<c>and<d>..<y> ...;

This operation extends the current path from the current point, let us call it x, via a curve to a the current point y. The curve is a cubic Bézier curve. For such a curve, apart from y, you also specify two control points c and d. The idea is that the curve starts at x, “heading” in the direction of c. Mathematically spoken, the tangent of the curve at x goes through c. Similarly, the curve ends at y, “coming from” the other control point, d. The larger the distance between x and c and between d and y, the larger the curve will be.

If the “and<d>” part is not given, d is assumed to be equal to c.

\begin{tikzpicture}   \draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0)                                .. controls (5,0) and (5,1) .. (4,1);   \draw[color=gray] (0,0) -- (1,1) -- (4,0) -- (5,0) -- (5,1) -- (4,1); \end{tikzpicture}

As with the line-to operation, it makes a difference whether two curves are joined because they resulted from consecutive curve-to or line-to operations, or whether they just happen to have the same ending:

\begin{tikzpicture}[line width=10pt]   \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0);   \draw (3,0) -- (4,1) .. controls (4,0) and (5,0) .. (5,0);   \useasboundingbox (0,1.5); % make bounding box higher \end{tikzpicture}

9.4 The Cycle Operation

\path  ... --cycle ...;

This operation adds a straight line from the current point to the last point specified by a move-to operation. Note that this need not be the beginning of the path. Furthermore, a smooth join is created between the first segment created after the last move-to operation and the straight line appended by the cycle operation.

Consider the following example. In the left example, two triangles are created using three straight lines, but they are not joined at the ends. In the second example cycle operations are used.

\begin{tikzpicture}[line width=10pt]   \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0);   \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle;   \useasboundingbox (0,1.5); % make bounding box higher \end{tikzpicture}

9.5 The Rectangle Operation

A rectangle can obviously be created using four straight lines and a cycle operation. However, since rectangles are needed so often, a special syntax is available for them.

\path  ... rectangle<corner> ...;

When this operation is used, one corner will be the current point, another corner is given by <corner>, which becomes the new current point.

\begin{tikzpicture}   \draw (0,0) rectangle (1,1);   \draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0); \end{tikzpicture}

9.6 Rounding Corners

All of the path construction operations mentioned up to now are influenced by the following option:

• rounded corners=<inset> When this option is in force, all corners (places where a line is continued either via line-to or a curve-to operation) are replaced by little arcs so that the corner becomes smooth.

  \tikz \draw [rounded corners] (0,0) -- (1,1)            -- (2,0) .. controls (3,1) .. (4,0);

  The <inset> describes how big the corner is. Note that the <inset> is not scaled along if you use a scaling option like scale=2.

  \begin{tikzpicture}   \draw[color=gray,very thin] (10pt,15pt) circle (10pt);   \draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt); \end{tikzpicture}

  You can switch the rounded corners on and off “in the middle of path” and different corners in the same path can have different corner radii:

  \begin{tikzpicture}   \draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1)                      [sharp corners] -- (2,0)                [rounded corners=5pt] -- cycle; \end{tikzpicture}

  Here is a rectangle with rounded corners:

  \tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex);

  You should be aware, that there are several pitfalls when using this option. First, the rounded corner will only be an arc (part of a circle) if the angle is 90^o. In other cases, the rounded corner will still be round, but “not as nice.”

  Second, if there are very short line segments in a path, the “rounding” may cause inadverted effects. In such case it may be necessary to temporarily switch off the rounding using sharp corners.

• sharp corners This options switches off any rounding on subsequent corners of the path.

9.7 The Circle and Ellipse Operations

A circle can be approximated well using four Bézier curves. However, it is difficult to do so correctly. For this reason, a special syntax is available for adding such an approximation of a circle to the current path.

\path  ... circle(<radius>) ...;

The center of the circle is given by the current point. The new current point of the path will remain to be the center of the circle.

\path  ... ellipse(<half width> and <half height>) ...;

Note that you can add spaces after ellipse, but you have to place spaces around and.

\begin{tikzpicture}   \draw (1,0) circle (.5cm);   \draw (3,0) ellipse (1cm and .5cm) -- ++(3,0) circle (.5cm)     -- ++(2,-.5) circle (.25cm); \end{tikzpicture}

9.8 The Arc Operation

The arc operation allows you to add an arc to the current path.

\path  ... arc(<start angle>:<end angle>:<radius>/<half height>) ...;

The arc operation adds a part of a circle of the given radius between the given angles. The arc will start at the current point and will end at the end of the arc.

\begin{tikzpicture}   \draw (0,0) arc (180:90:1cm) -- (2,.5) arc (90:0:1cm);   \draw (4,0) -- +(30:1cm) arc (30:60:1cm) -- cycle;   \draw (8,0) arc (0:270:1cm/.5cm) -- cycle; \end{tikzpicture}

\begin{tikzpicture}   \draw (-1,0) -- +(3.5,0);   \draw (1,0) ++(210:2cm) -- +(30:4cm);   \draw (1,0) +(0:1cm) arc (0:30:1cm);   \draw (1,0) +(180:1cm) arc (180:210:1cm);   \path (1,0) ++(15:.75cm) node{$\alpha$};   \path (1,0) ++(15:-.75cm) node{$\beta$}; \end{tikzpicture}

9.9 The Grid Operation

You can add a grid to the current path using the grid path operation.

\path  ... grid[<options>]<corner> ...;

This operations adss a grid filling a rectangle whose two corners are given by <corner> and by the previous coordinate. Thus, the typical way in which a grid is drawn is \draw (1,1) grid (3,3);, which yields a grid filling the rectangle whose corners are at (1,1) and (3,3). All coordinate transformations apply to the grid.

\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2);

The stepping of the grid is governed by the following options:

• step=<dimension> sets the stepping in both the x and y-direction.
• xstep=<dimension> sets the stepping in the x-direction.
• ystep=<dimension> sets the stepping in the y-direction.

It is important to note that the grid is always “phased” such that it contains the point (0,0) if that point happens to be inside the rectangle. Thus, the grid does not always have an intersection at the corner points; this occurs only if the corner points are multiples of the stepping. Note that due to rounding errors, the “last” lines of a grid may be omitted. In this case, you have to add an epsilon to the corner points.

The following style is useful for drawing grids:

• style=help lines This style makes lines “subdued” by using thin gray lines for them. However, this style is not installed automatically and you have to say for example:

  \tikz \draw[style=help lines] (0,0) grid (3,3);

9.10 The Parabola Operation

The parabola path operation continues the current path with a parabola. A parabola is a (shifted and scaled) curve defined by the equation f(x) = x² and looks like this: .

\path  ... parabola[<options>]bend<bend coordinate><coordinate> ...;

This operation adds a parabola through the current point and the given <coordinate>. If the bend is given, it specifies where the bend should go; the <options> can also be used to specify where the bend is. By default, the bend is at the old current point.

\begin{tikzpicture}   \draw               (0,0) rectangle                (1,1.5)                       (0,0) parabola                 (1,1.5);   \draw[xshift=1.5cm] (0,0) rectangle                (1,1.5)                       (0,0) parabola[bend at end]    (1,1.5);   \draw[xshift=3cm]   (0,0) rectangle                (1,1.5)                       (0,0) parabola bend (.75,1.75) (1,1.5); \end{tikzpicture}

The following options influence parabolas:

• bend=<coordinate> Has the same effect as saying bend<coordinate> outside the <options>. The option specifies that the bend of the parabola should be at the given <coordinate>. You have to take care yourself that the bend position is a “valid” position; which means that if there is no parabola of the form f(x) = ax² +bx+c that goes through the old current point, the given bend, and the new current point, the result will not be a parabola.

  There is one special property of the <coordinate>: When a relative coordinate is given like +(0,0), the position relative to which this coordinate is “flexible.” More precisely, this position lies somewhere on a line from the old current point to the new current point. The exact position depends on the next option.

• bend pos=<fraction> Specifies where the “previous” point is relative to which the bend is calculated. The previous point will be at the <fraction>th part of the line from the old current point to the new current point.

  The idea is the following: If you say bend pos=0 and bend +(0,0), the bend will be at the old current point. If you say bend pos=1 and bend +(0,0), the bend will be at the new current point. If you say bend pos=0.5 and bend +(0,2cm) the bend will be 2cm above the middle of the line between the start and end point. This is most useful in situations such as the following:

  \begin{tikzpicture}   \draw[help lines] (0,0) grid (3,2);   \draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0); \end{tikzpicture}

  In the above example, the bend +(0,2) essentially means “a parabola that is 2cm high” and +(3,0) means “and 3cm wide.” Since this situation arises often, there is a special shortcut option:

• parabola height=<dimension> This option has the same effect as if you had written the following instead: [bend pos=0.5,bend={+(0pt,<dimension>)}].

  \begin{tikzpicture}   \draw[help lines] (0,0) grid (3,2);   \draw (-1,0) parabola[parabola height=2cm] +(3,0); \end{tikzpicture}

The following styles are useful shortcuts:

• style=bend at start This places the bend at the start of a parabola. It is a shortcut for the following options: bend pos=0,bend={+(0,0)}.
• style=bend at end This places the bend at the end of a parabola.

9.11 The Sine and Cosine Operation

The sin and cos operations are similar to the parabola operation. They, too, can be used to draw (parts of) a sine or cosine curve.

\path  ... sin<coordinate> ...;

The effect of sin is to draw a scaled and shifted version of a sine curve in the interval [0,/2]. The scaling and shifting is done in such a way that the start of the sine curve in the interval is at the old current point and that the end of the curve in the interval is at <coordinate>. Here is an example that should clarify this:

\tikz \draw (0,0) rectangle (1,1)     (0,0) sin (1,1)             (2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1);

\path  ... cos<coordinate> ...;

This operation works similarly, only a cosine in the interval [0,/2] is drawn. By correctly alternating sin and cos operations, you can create a complete sine or cosine curve:

\begin{tikzpicture}[xscale=1.57]   \draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1);   \draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0); \end{tikzpicture}

Note that there is no way to (conveniently) draw an interval on a sine or cosine curve whose end points are not multiples of /2.

9.12 The Plot Operation

The plot operation can be used to append a line or curve to the path that goes through a large number of coordinates. These coordinates are either given in a simple list of coordinates or they are read from some file.

The syntax of the plot comes in different versions.

\path  ... --plot<further arguments> ...;

This operation plots the curve through the coordinates specified in the <further arguments>. The current (sub)path is simply continued, that is, a line-to operation to the first point of the curve is implicitly added. The details of the <further arguments> will be explained in a moment.

\path  ... plot<further arguments> ...;

This operation plots the curve through the coordinates specified in the <further arguments> by first “moving” to the first coordinate of the curve.

The <further arguments> are used in three different ways to specifying the coordinates of the points to be plotted:

1. --plot[<local options>]coordinates{<coordinate 1><coordinate 2>...<coordinate n>}
2. --plot[<local options>]file{<filename>}
3. --plot[<local options>]function{<gnuplot formula>}

These different ways are explained in the following.

9.12.1 Plotting Points Given Inline

In the first two cases, the points are given directly in the TEX-file as in the following example:

Here is an example showing the difference between plot and --plot:

9.12.2 Plotting Points Read From an External File

The second way of specifying points is to put them in an external file named <filename>. Currently, the only file format that TikZ allows is the following: Each line of the <filename> should contain one line starting with two numbers, separated by a space. Anything following the two numbers on the line is ignored. Also, lines starting with a % or a # are ignored as well as empty lines. (This is exactly the format that GNUPLOT produces when you say set terminal table.) If necessary, more formats will be supported in the future, but it is usually easy to produce a file containing data in this form.

The file plots/pgfmanual-sine.table reads:

It was produced from the following source, using gnuplot:

The <local options> of the plot operation are local to each plot and do not affect other plots “on the same path.” For example, plot[yshift=1cm] will locally shift the plot 1cm upward. Remember, however, that most options can only be applied to paths as a whole. For example, plot[red] does not have the effect of making the plot red. After all, you are trying to “locally” make part of the path red, which is not possible.

9.12.3 Plotting a Function

Often, you will want to plot points that are given via a function like f(x) = xsinx. Unfortunately, TEX does not really have enough computational power to generate the points on such a function efficiently (it is a text processing program, after all). However, if you allow it, TEX can try to call external programs that can easily produce the necessary points. Currently, TikZ knows how to call GNUPLOT.

When TikZ encounters your operation plot[id=<id>] function{x*sin(x)} for the first time, it will create a file called <prefix><id>.gnuplot, where <prefix> is \jobname. by default, that is, the name of you main .tex file. If no <id> is given, it will be empty, which is alright, but it is better when each plot has a unique <id> for reasons explained in a moment. Next, TikZ writes some initialization code into this file followed by plot x*sin(x). The initialization code sets up things such that the plot operation will write the coordinates into another file called <prefix><id>.table. Finally, this table file is read as if you had said plot file{<prefix><id>.table}.

For the plotting mechanism to work, two conditions must be met:

1. You must have allowed TEX to call external programs. This is often switched off by default since this is a security risk (you might, without knowing, run a TEX file that calls all sorts of “bad” commands). To enable this “calling external programs” a command line option must be given to the TEX program. Usually, it is called something like shell-escape or enable-write18. For example, for my pdflatex the option --shell-escape can be given.
2. You must have installed the gnuplot program and TEX must find it when compiling your file.

Unfortunately, these conditions will not always be met. Especially if you pass some source to a coauthor and the coauthor does not have GNUPLOT installed, he or she will have trouble compiling your files.

For this reason, TikZ behaves differently when you compile your graphic for the second time: If upon reaching plot[id=<id>] function{...} the file <prefix><id>.table already exists and if the <prefix><id>.gnuplot file contains what TikZ thinks that it “should” contain, the .table file is immediately read without trying to call a gnuplot program. This approach has the following advantages:

1. If you pass a bundle of your .tex file and all .gnuplot and .table files to someone else, that person can TEX the .tex file without having to have gnuplot installed.
2. If the \write18 feature is switched off for security reasons (a good idea), then, upon the first compilation of the .tex file, the .gnuplot will still be generated, but not the .table file. You can then simply call gnuplot “by hand” for each .gnuplot file, which will produce all necessary .table files.
3. If you change the function that you wish to plot or its domain, TikZ will automatically try to regenerate the .table file.
4. If, out of laziness, you do not provide an id, the same .gnuplot will be used for different plots, but this is not a problem since the .table will automatically be regenerated for each plot on-the-fly. Note: If you intend to share your files with someone else, always use an id, so that the file can by typeset without having GNUPLOT installed. Also, having unique ids for each plot will improve compilation speed since no external programs need to be called, unless it is really necessary.

When you use plot function{<gnuplot formula>}, the <gnuplot formula> must be given in the gnuplot syntax, whose details are beyond the scope of this manual. Here is the ultra-condensed essence: Use x as the variable and use the C-syntax for normal plots, use t as the variable for parametric plots. Here are some examples:

The following options influence the plot:

• samples=<number> sets the number of samples used in the plot. The default is 25.
• domain=<start>:<end> sets the domain between which the samples are taken. The default is -5:5.
• parametric=<true or false> sets whether the plot is a parametric plot. If true, then t must be used instead of x as the parameter and two comma-separated functions must be given in the <gnuplot formula>. An example is the following:

  \tikz \draw[scale=0.5,domain=-3.141:3.141,smooth]   plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)};

• id=<id> sets the identifier of the current plot. This should be a unique identifier for each plot (though things will also work if it is not, but not as well, see the explanations above). The <id> will be part of a filename, so it should not contain anything fancy like * or $.
• prefix=<prefix> is put before each plot file name. The default is \jobname., but if you have many plots, it might be better to use, say plots/ and have all plots placed in a directory. You have to create the directory yourself.
• raw gnuplot causes the <gnuplot formula> to be passed on to GNUPLOT without setting up the samples or the plot operation. Thus, you could write

  plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)}

  This can be useful for complicated things that need to be passed to GNUPLOT. However, for really complicated situations you should create a special external generating GNUPLOT file and use the file-syntax to include the table “by hand.”

The following styles influence the plot:

• style=every plot This style is installed in each plot, that is, as if you always said

  plot[style=every plot,...]

  This is most useful for globally setting a prefix for all plots by saying:

  \tikzstyle{every plot}=[prefix=plots/]

9.12.4 Placing Marks on the Plot

As we saw already, it is possible to add marks to a plot using the mark option. When this option is used, a copy of the plot mark is placed on each point of the plot. Note that the marks are placed after the whole path has been drawn/filled/shaded. In this respect, they are handled like text nodes.

In detail, the following options govern how marks are drawn:

• mark=<mark mnemonic> Sets the mark to a mnemonic that has previously been defined using the \pgfdeclareplotmark. By default, *, +, and x are available, which draw a filled circle, a plus, and a cross as marks. Many more marks become available when the library pgflibraryplotmarks is loaded. Section 14.3.3 lists the available plot marks.

  One plot mark is special: the ball plot mark is available only it TikZ. The ball color determines the balls’s color. Do not use this option with large number of marks since it will take very long to render in PostScript.

  Option	Effect
  mark=ball

• mark size=<dimension> Sets the size of the plot marks. For circular plot marks, <dimension> is the radius, for other plot marks <dimension> should be about half the width and height.

  This option is not really necessary, since you achieve the same effect by specifying scale=<factor> as a local option, where <factor> is the quotient of the desired size and the default size. However, using mark size is a bit faster and more natural.

• mark options=<options> These options are applied to marks when they are drawn. For example, you can scale (or otherwise transform) the plot mark or set its color.

  \tikz \fill[fill=blue!20]   plot[mark=triangle*,mark options={color=blue,rotate=180}]     file{plots/pgfmanual-sine.table} |- (0,0);

9.12.5 Smooth Plots, Sharp Plots, and Comb Plots

There are different things the plot operation can do with the points it reads from a file or from the inlined list of points. By default, it will connect these points by straight lines. However, you can also use options to change the behavior of plot.

• sharp plot This is the default and causes the points to be connected by straight lines. This option is included only so that you can “switch back” if you “globally” install, say, smooth.
• smooth This option causes the points on the path to be connected using a smooth curve:

  \tikz\draw plot[smooth] file{plots/pgfmanual-sine.table};

  Note that the smoothing algorithm is not very intelligent. You will get the best results if the bending angles are small, that is, less than about 30^o and, even more importantly, if the distances between points are about the same all over the plotting path.

• tension=<value> This option influences how “tight” the smoothing is. A lower value will result in sharper corners, a higher value in more “round” curves. A value of 1 results in a circle if four points at quarter-positions on a circle are given. The default is 0.55. The “correct” value depends on the details of plot.

  \begin{tikzpicture}[smooth cycle]   \draw                 plot[tension=0.2]     coordinates{(0,0) (1,1) (2,0) (1,-1)};   \draw[yshift=-2.25cm] plot[tension=0.5]     coordinates{(0,0) (1,1) (2,0) (1,-1)};   \draw[yshift=-4.5cm]  plot[tension=1]     coordinates{(0,0) (1,1) (2,0) (1,-1)}; \end{tikzpicture}

• smooth cycle This option causes the points on the path to be connected using a closed smooth curve.

  \tikz[scale=0.5]   \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)}         plot               coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle;

• ycomb This option causes the plot operation to interpret the plotting points differently. Instead of connecting them, for each point of the plot a straight line is added to the path from the x-axis to the point, resulting in a sort of “comb” or “bar diagram.”

  \tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table};

  \begin{tikzpicture}[ycomb]   \draw[color=red,line width=6pt]     plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};   \draw[color=red!50,line width=4pt,xshift=3pt]     plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)}; \end{tikzpicture}

• xcomb This option works like ycomb except that the bars are horizontal.

  \tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)};

• polar comb This option causes a line from the origin to the point to be added to the path for each plot point.

  \tikz \draw plot[polar comb,      mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt]    coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)};

• only marks This option causes only marks to be shown; no path segments are added to the actual path. This can be useful for quickly adding some marks to a path.

  \tikz \draw (0,0) sin (1,1) cos (2,0)   plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)};

9.13 The Scoping Operation

When TikZ encounters and opening or a closing brace ({ or }) at some point where a path operation should come, it will open or close a scope. All options that can be applied “locally” will be scoped inside the scope. For example, if you apply a transformation like [xshift=1cm] inside the scoped area, the shifting only applies to the scope. On the other hand, an option like color=red does not have any effect inside a scope since it can only be applied to the path as a whole.

9.14 The Node Operation

You can add nodes to a path using the node operation. Since this operation is quite complex and since the nodes are not really part of the path itself, there is a separate section dealing with nodes, see Section 11.