Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-paths.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Syntax for Path Specifications}
12 \label{section-paths}
13
14 A \emph{path} is a series of straight and curved line segments. It is specified
15 following a |\path| command and the specification must follow a special syntax,
16 which is described in the subsections of the present section.
17
18 \begin{command}{\path\meta{specification}|;|}
19 This command is available only inside a |{tikzpicture}| environment.
20
21 The \meta{specification} is a long stream of \emph{path operations}. Most
22 of these path operations tell \tikzname\ how the path is built. For
23 example, when you write |--(0,0)|, you use a \emph{line-to operation} and
24 it means ``continue the path from wherever you are to the origin''.
25
26 At any point where \tikzname\ expects a path operation, you can also give
27 some graphic options, which is a list of options in brackets, such as
28 |[rounded corners]|. These options can have different effects:
29 %
30 \begin{enumerate}
31 \item Some options take ``immediate'' effect and apply to all
32 subsequent path operations on the path. For example, the
33 |rounded corners| option will round all following corners, but not
34 the corners ``before'' and if the |sharp corners| is given later on
35 the path (in a new set of brackets), the rounding effect will end.
36 %
37 \begin{codeexample}[]
38 \tikz \draw (0,0) -- (1,1)
39 [rounded corners] -- (2,0) -- (3,1)
40 [sharp corners] -- (3,0) -- (2,1);
41 \end{codeexample}
42 %
43 Another example are the transformation options, which also apply
44 only to subsequent coordinates.
45 \item The options that have immediate effect can be ``scoped'' by
46 putting part of a path in curly braces. For example, the above
47 example could also be written as follows:
48 %
49 \begin{codeexample}[]
50 \tikz \draw (0,0) -- (1,1)
51 {[rounded corners] -- (2,0) -- (3,1)}
52 -- (3,0) -- (2,1);
53 \end{codeexample}
54 %
55 \item Some options only apply to the path as a whole. For example,
56 the |color=| option for determining the color used for, say,
57 drawing the path always applies to all parts of the path. If
58 several different colors are given for different parts of the
59 path, only the last one (on the outermost scope) ``wins'':
60 %
61 \begin{codeexample}[]
62 \tikz \draw (0,0) -- (1,1)
63 [color=red] -- (2,0) -- (3,1)
64 [color=blue] -- (3,0) -- (2,1);
65 \end{codeexample}
66
67 Most options are of this type. In the above example, we would
68 have had to ``split up'' the path into several |\path| commands:
69 %
70 \begin{codeexample}[]
71 \tikz{\draw (0,0) -- (1,1);
72 \draw [color=red] (1,1) -- (2,0) -- (3,1);
73 \draw [color=blue] (3,1) -- (3,0) -- (2,1);}
74 \end{codeexample}
75 \end{enumerate}
76
77 By default, the |\path| command does ``nothing'' with the path, it just
78 ``throws it away''. Thus, if you write |\path(0,0)--(1,1);|, nothing is
79 drawn in your picture. The only effect is that the area occupied by the
80 picture is (possibly) enlarged so that the path fits inside the area. To
81 actually ``do'' something with the path, an option like |draw| or |fill|
82 must be given somewhere on the path. Commands like |\draw| do this
83 implicitly.
84
85 Finally, it is also possible to give \emph{node specifications} on a path.
86 Such specifications can come at different locations, but they are always
87 allowed when a normal path operation could follow. A node specification
88 starts with |node|. Basically, the effect is to typeset the node's text as
89 normal \TeX\ text and to place it at the ``current location'' on the path.
90 The details are explained in Section~\ref{section-nodes}.
91
92 Note, however, that the nodes are \emph{not} part of the path in any way.
93 Rather, after everything has been done with the path what is specified by
94 the path options (like filling and drawing the path due to a |fill| and a
95 |draw| option somewhere in the \meta{specification}), the nodes are added
96 in a post-processing step.
97
98 \emph{Note:} When scanning for path operations \tikzname\ expands tokens
99 looking for valid path operations. This however implies that these tokens
100 has to be fully expandable up to the point where it results in a valid path
101 operation.
102 \end{command}
103
104 \begin{key}{/tikz/name=\meta{path name}}
105 Assigns a name to the path for reference (specifically, for reference
106 in animations; for reference in intersections, use the |name path|
107 command, which has a different purpose, see the |intersections| library
108 for details). Since the name is a ``high-level'' name (drivers never
109 know of it), you can use spaces, number, letters, or whatever you like
110 when naming a path, but the name may \emph{not} contain any punctuation
111 like a dot, a comma, or a colon.
112 \end{key}
113
114 The following style influences scopes:
115 %
116 \begin{stylekey}{/tikz/every path (initially \normalfont empty)}
117 This style is installed at the beginning of every path. This can be
118 useful for (temporarily) adding, say, the |draw| option to everything
119 in a scope.
120 %
121 \begin{codeexample}[]
122 \begin{tikzpicture}
123 [fill=yellow!80!black, % only sets the color
124 every path/.style={draw}] % all paths are drawn
125 \fill (0,0) rectangle +(1,1);
126 \shade (2,0) rectangle +(1,1);
127 \end{tikzpicture}
128 \end{codeexample}
129 %
130 \end{stylekey}
131
132 \begin{key}{/tikz/insert path=\meta{path}}
133 This key can be used inside an option to add something to the current path.
134 This is mostly useful for defining styles that create graphic contents.
135 This option should be used with care, for instance it should not be used as
136 an argument of, say, a |node|. In the following example, we use a style to
137 add little circles to a path.
138 %
139 \begin{codeexample}[]
140 \tikz [c/.style={insert path={circle[radius=2pt]}}]
141 \draw (0,0) -- (1,1) [c] -- (3,2) [c];
142 \end{codeexample}
143 %
144 The effect is the same as of
145 |(0,0) -- (1,1) circle[radius=2pt] -- (3,2) circle[radius=2pt]|.
146 \end{key}
147
148 The following options are for experts only:
149
150 \begin{key}{/tikz/append after command=\meta{path}}
151 Some of the path commands described in the following sections take optional
152 arguments. For these commands, when you use this key inside these options,
153 the \meta{path} will be inserted \emph{after} the path command is done. For
154 instance, when you give this command in the option list of a node, the
155 \meta{path} will be added after the node. This is used by, for instance,
156 the |label| option to allow you to specify a label in the option list of a
157 node, but have this |label| cause a node to be added after another node.
158 %
159 \begin{codeexample}[]
160 \tikz \draw node [append after command={(foo)--(1,1)},draw] (foo){foo};
161 \end{codeexample}
162 %
163 If this key is called multiple times, the effects accumulate, that is, all
164 of the paths are added in the order to keys were found.
165 \end{key}
166
167 \begin{key}{/tikz/prefix after command=\meta{path}}
168 Works like |append after command|, only the accumulation order is inverse:
169 The \meta{path} is added before any earlier paths added using either
170 |append after command| or |prefix after command|.
171 \end{key}
172
173
174 \subsection{The Move-To Operation}
175
176 The perhaps simplest operation is the move-to operation, which is specified by
177 just giving a coordinate where a path operation is expected.
178
179 \begin{pathoperation}[noindex]{}{\meta{coordinate}}
180 \index{empty@\protect\meta{empty} path operation}%
181 \index{Path operations!empty@\protect\texttt{\meta{empty}}}%
182 The move-to operation normally starts a path at a certain point. This does
183 not cause a line segment to be created, but it specifies the starting point
184 of the next segment. If a path is already under construction, that is, if
185 several segments have already been created, a move-to operation will start
186 a new part of the path that is not connected to any of the previous
187 segments.
188 %
189 \begin{codeexample}[]
190 \begin{tikzpicture}
191 \draw (0,0) --(2,0) (0,1) --(2,1);
192 \end{tikzpicture}
193 \end{codeexample}
194
195 In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to operations
196 are specified: |(0,0)| and |(0,1)|. The other two operations, namely
197 |--(2,0)| and |--(2,1)| are line-to operations, described next.
198 \end{pathoperation}
199
200 There is special coordinate called |current subpath start| that is always at
201 the position of the last move-to operation on the current path.
202 %
203 \begin{codeexample}[]
204 \tikz [line width=2mm]
205 \draw (0,0) -- (1,0) -- (1,1)
206 -- (0,1) -- (current subpath start);
207 \end{codeexample}
208
209 Note how in the above example the path is not closed (as |--cycle| would do).
210 Rather, the line just starts and ends at the origin without being a closed
211 path.
212
213
214 \subsection{The Line-To Operation}
215
216 \subsubsection{Straight Lines}
217
218 \begin{pathoperation}{--}{\meta{coordinate or cycle}}
219 The line-to operation extends the current path from the current point in a
220 straight line to the given \meta{coordinate} (the ``or cycle'' part is
221 explained in a moment). The ``current point'' is the endpoint of the
222 previous drawing operation or the point specified by a prior move-to
223 operation.
224
225 When a line-to operation is used and some path segment has just been
226 constructed, for example by another line-to operation, the two line
227 segments become joined. This means that if they are drawn, the point where
228 they meet is ``joined'' smoothly. To appreciate the difference, consider
229 the following two examples: In the left example, the path consists of two
230 path segments that are not joined, but they happen to share a point, while
231 in the right example a smooth join is shown.
232 %
233 \begin{codeexample}[]
234 \begin{tikzpicture}[line width=10pt]
235 \draw (0,0) --(1,1) (1,1) --(2,0);
236 \draw (3,0) -- (4,1) -- (5,0);
237 \useasboundingbox (0,1.5); % make bounding box higher
238 \end{tikzpicture}
239 \end{codeexample}
240
241 Instead of a coordinate following the two minus signs, you can also use the
242 text |cycle|. This causes the straight line from the current point to go to
243 the last point specified by a move-to operation. Note that this need not be
244 the beginning of the path. Furthermore, a smooth join is created between
245 the first segment created after the last move-to operation and the straight
246 line appended by the cycle operation.
247
248 Consider the following example. In the left example, two triangles are
249 created using three straight lines, but they are not joined at the ends. In
250 the second example cycle operations are used.
251 %
252 \begin{codeexample}[]
253 \begin{tikzpicture}[line width=10pt]
254 \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0);
255 \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle;
256 \useasboundingbox (0,1.5); % make bounding box higher
257 \end{tikzpicture}
258 \end{codeexample}
259 %
260 \end{pathoperation}
261
262 Writing |cycle| instead of a coordinate at the end of a path operation is
263 possible with all path operations that end with a coordinate (such as |--| or
264 |..| or |sin| or |grid|, but not |graph| or |plot|). In all cases, the effect
265 is that the coordinate of the last moveto is used as the coordinate expected by
266 the path operation and that a smooth join is added. (What actually happens that
267 the text |cycle| used with any path operation other than |--| gets replaced by
268 |(current subpath start)--cycle|.)
269
270
271 \subsubsection{Horizontal and Vertical Lines}
272
273 Sometimes you want to connect two points via straight lines that are only
274 horizontal and vertical. For this, you can use two path construction
275 operations.
276
277 {\catcode`\|=12
278 \begin{pathoperation}[noindex]{-|}{\meta{coordinate or cycle}}
279 \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}%
280 \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}%
281 \pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
282 This operation means ``first horizontal, then vertical''.
283 %
284 \begin{codeexample}[]
285 \begin{tikzpicture}
286 \draw (0,0) node(a) [draw] {A} (1,1) node(b) [draw] {B};
287 \draw (a.north) |- (b.west);
288 \draw[color=red] (a.east) -| (2,1.5) -| (b.north);
289 \end{tikzpicture}
290 \end{codeexample}
291 %
292 Instead of a coordinate you can also write \verb!cycle! to close the path:
293 %
294 \begin{codeexample}[]
295 \begin{tikzpicture}[ultra thick]
296 \draw (0,0) -- (1,1) -| cycle;
297 \end{tikzpicture}
298 \end{codeexample}
299 \end{pathoperation}
300
301 \begin{pathoperation}[noindex]{|-}{\meta{coordinate or cycle}}
302 \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}%
303 \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}%
304 \pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
305 This operation means ``first vertical, then horizontal''.
306 \end{pathoperation}
307 }
308
309
310 \subsection{The Curve-To Operation}
311
312 The curve-to operation allows you to extend a path using a Bézier curve.
313
314 \begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y or cycle}}}
315 This operation extends the current path from the current point, let us call
316 it $x$, via a curve to a point~$y$ (if, instead of a coordinate you say
317 |cycle| at the end, $y$ will be the coordinate of the last move-to
318 operation). The curve is a cubic Bézier curve. For such a curve, apart
319 from $y$, you also specify two control points $c$ and $d$. The idea is that
320 the curve starts at $x$, ``heading'' in the direction of~$c$.
321 Mathematically spoken, the tangent of the curve at $x$ goes through $c$.
322 Similarly, the curve ends at $y$, ``coming from'' the other control
323 point,~$d$. The larger the distance between $x$ and~$c$ and between $d$
324 and~$y$, the larger the curve will be.
325
326 If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be equal to
327 $c$.
328 %
329 \begin{codeexample}[]
330 \begin{tikzpicture}
331 \draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0)
332 .. controls (5,0) and (5,1) .. (4,1);
333 \draw[color=gray] (0,0) -- (1,1) -- (4,0) -- (5,0) -- (5,1) -- (4,1);
334 \end{tikzpicture}
335 \end{codeexample}
336
337 \begin{codeexample}[]
338 \begin{tikzpicture}
339 \draw[line width=10pt] (0,0) -- (2,0) .. controls (1,1) .. cycle;
340 \end{tikzpicture}
341 \end{codeexample}
342
343 As with the line-to operation, it makes a difference whether two curves are
344 joined because they resulted from consecutive curve-to or line-to
345 operations, or whether they just happen to have a common (end) point:
346 %
347 \begin{codeexample}[]
348 \begin{tikzpicture}[line width=10pt]
349 \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0);
350 \draw [yshift=-1.5cm]
351 (0,0) -- (1,1) .. controls (1,0) and (2,0) .. (2,0);
352 \end{tikzpicture}
353 \end{codeexample}
354 %
355 \end{pathoperation}
356
357
358 \subsection{The Rectangle Operation}
359
360 A rectangle can obviously be created using four straight lines and a cycle
361 operation. However, since rectangles are needed so often, a special syntax is
362 available for them.
363
364 \begin{pathoperation}{rectangle}{\meta{corner or cycle}}
365 When this operation is used, one corner will be the current point, another
366 corner is given by \meta{corner}, which becomes the new current point.
367 %
368 \begin{codeexample}[]
369 \begin{tikzpicture}
370 \draw (0,0) rectangle (1,1);
371 \draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0);
372 \end{tikzpicture}
373 \end{codeexample}
374
375 Just for consistency, you can also use |cycle| instead of a coordinate, but
376 it is a bit unclear what use this might have.
377 \end{pathoperation}
378
379
380 \subsection{Rounding Corners}
381
382 All of the path construction operations mentioned up to now are influenced by
383 the following option:
384
385 \begin{key}{/tikz/rounded corners=\meta{inset} (default 4pt)}
386 When this option is in force, all corners (places where a line is continued
387 either via line-to or a curve-to operation) are replaced by little arcs so
388 that the corner becomes smooth.
389 %
390 \begin{codeexample}[]
391 \tikz \draw [rounded corners] (0,0) -- (1,1)
392 -- (2,0) .. controls (3,1) .. (4,0);
393 \end{codeexample}
394
395 The \meta{inset} describes how big the corner is. Note that the
396 \meta{inset} is \emph{not} scaled along if you use a scaling option like
397 |scale=2|.
398 %
399 \begin{codeexample}[]
400 \begin{tikzpicture}
401 \draw[color=gray,very thin] (10pt,15pt) circle[radius=10pt];
402 \draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt);
403 \end{tikzpicture}
404 \end{codeexample}
405
406 You can switch the rounded corners on and off ``in the middle of path'' and
407 different corners in the same path can have different corner radii:
408 %
409 \begin{codeexample}[]
410 \begin{tikzpicture}
411 \draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1)
412 [sharp corners] -- (2,0)
413 [rounded corners=5pt] -- cycle;
414 \end{tikzpicture}
415 \end{codeexample}
416
417 Here is a rectangle with rounded corners:
418 %
419 \begin{codeexample}[]
420 \tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex);
421 \end{codeexample}
422
423 You should be aware, that there are several pitfalls when using this
424 option. First, the rounded corner will only be an arc (part of a circle) if
425 the angle is $90^\circ$. In other cases, the rounded corner will still be
426 round, but ``not as nice''.
427
428 Second, if there are very short line segments in a path, the ``rounding''
429 may cause inadvertent effects. In such case it may be necessary to
430 temporarily switch off the rounding using |sharp corners|.
431 \end{key}
432
433 \begin{key}{/tikz/sharp corners}
434 This options switches off any rounding on subsequent corners of the path.
435 \end{key}
436
437
438 \subsection{The Circle and Ellipse Operations}
439
440 Circles and ellipses are common path elements for which there is a special path
441 operation.
442
443 \begin{pathoperation}{circle}{\opt{|[|\meta{options}|]|}}
444 This command adds a circle to the current path where the center of the
445 circle is the current point by default, but you can use the |at| option to
446 change this. The new current point of the path will be (typically just
447 remain) the center of the circle.
448
449 The radius of the circle is specified using the following options:
450 %
451 \begin{key}{/tikz/x radius=\meta{value}}
452 Sets the horizontal radius of the circle (which, when this value is
453 different from the vertical radius, is actually an ellipse). The
454 \meta{value} may either be a dimension or a dimensionless number. In
455 the latter case, the number is interpreted in the $xy$-coordinate
456 system (if the $x$-unit is set to, say, |2cm|, then |x radius=3| will
457 have the same effect as |x radius=6cm|).
458 \end{key}
459 %
460 \begin{key}{/tikz/y radius=\meta{value}}
461 Works like the |x radius|.
462 \end{key}
463 %
464 \begin{key}{/tikz/radius=\meta{value}}
465 Sets the |x radius| and |y radius| simultaneously.
466 \end{key}
467 %
468 \begin{key}{/tikz/at=\meta{coordinate}}
469 If this option is explicitly set inside the \meta{options} (or
470 indirectly via the |every circle| style), the \meta{coordinate} is used
471 as the center of the circle instead of the current point. Setting |at|
472 to some value in an enclosing scope has no effect.
473 \end{key}
474 The \meta{options} may also contain additional options like, say, a
475 |rotate| or |scale|, that will only have an effect on the circle.
476 %
477 \begin{codeexample}[]
478 \begin{tikzpicture}
479 \draw (1,0) circle [radius=1.5];
480 \fill (1,0) circle [x radius=1cm, y radius=5mm, rotate=30];
481 \end{tikzpicture}
482 \end{codeexample}
483
484 It is possible to set the |radius| also in some enclosing scope, in this
485 case the options can be left out (but see the note below on what may
486 follow):
487 %
488 \begin{codeexample}[]
489 \begin{tikzpicture}[radius=2pt]
490 \draw (0,0) circle -- (1,1) circle -- ++(0,1) circle;
491 \end{tikzpicture}
492 \end{codeexample}
493
494 The following style is used with every circle:
495 %
496 \begin{stylekey}{/tikz/every circle}
497 You can use this key to set up, say, a default radius for every circle.
498 The key will also be used with the |ellipse| operation.
499 \end{stylekey}
500
501 In case you feel that the names |radius| and |x radius| are too long for
502 your taste, you can easily created shorter aliases:
503 %
504 \begin{codeexample}[code only]
505 \tikzset{r/.style={radius=#1},rx/.style={x radius=#1},ry/.style={y radius=#1}}
506 \end{codeexample}
507 %
508 You can then say |circle [r=1cm]| or |circle [rx=1,ry=1.5]|. The reason
509 \tikzname\ uses the longer names by default is that it encourages people to
510 write more readable code.
511
512 \emph{Note:} There also exists an older syntax for circles, where the
513 radius of the circle is given in parentheses right after the |circle|
514 command as in |circle (1pt)|. Although this syntax is a bit more succinct,
515 it is harder to understand for readers of the code and the use of
516 parentheses for something other than a coordinate is ill-chosen.
517
518 \tikzname\ will use the following rule to determine whether the old or the
519 normal syntax is used: If |circle| is directly followed by something that
520 (expands to) an opening parenthesis, then the old syntax is used and inside
521 these following parentheses there must be a single number or dimension
522 representing a radius. In all other cases the new syntax is used.
523 \end{pathoperation}
524
525 \begin{pathoperation}{ellipse}{|[|\meta{options}|]|}
526 This command has exactly the same effect as |circle|. The older syntax for
527 this command is |ellipse (|\meta{x radius} |and| \meta{y radius}|)|. As for
528 the |circle| command, this syntax is not as good as the standard syntax.
529 %
530 \begin{codeexample}[]
531 \begin{tikzpicture}
532 \draw [help lines] (0,0) grid (3,2);
533 \draw (1,1) ellipse [x radius=1cm,y radius=.5cm];
534 \end{tikzpicture}
535 \end{codeexample}
536 %
537 \end{pathoperation}
538
539
540 \subsection{The Arc Operation}
541
542 The \emph{arc operation} allows you to add an arc to the current path.
543 %
544 \begin{pathoperation}{arc}{\oarg{options}}
545 The |arc| operation adds a part of an ellipse to the current path. The
546 radii of the ellipse are given by the values of |x radius| and |y radius|,
547 which should be set in the \meta{options}. The arc will start at the
548 current point and will end at the end of the arc. The arc will start and
549 end at angles computed from the three keys |start angle|, |end angle|, and
550 |delta angle|. Normally, the first two keys specify the start and end
551 angle. However, in case one of them is empty, it is computed from the other
552 key plus or minus the |delta angle|. In detail, if |end angle| is empty, it
553 is set to the start angle plus the delta angle. If the start angle is
554 missing, it is set to the end angle minus the delta angle. If all three
555 keys are set, the delta angle is ignored.
556 %
557 \begin{key}{/tikz/start angle=\meta{degrees}}
558 Sets the start angle.
559 \end{key}
560 %
561 \begin{key}{/tikz/end angle=\meta{degrees}}
562 Sets the end angle.
563 \end{key}
564 %
565 \begin{key}{/tikz/delta angle=\meta{degrees}}
566 Sets the delta angle.
567 \end{key}
568
569 \begin{codeexample}[]
570 \begin{tikzpicture}[radius=1cm]
571 \draw (0,0) arc[start angle=180, end angle=90]
572 -- (2,.5) arc[start angle=90, delta angle=-90];
573 \draw (4,0) -- +(30:1cm)
574 arc [start angle=30, delta angle=30] -- cycle;
575 \draw (8,0) arc [start angle=0, end angle=270,
576 x radius=1cm, y radius=5mm] -- cycle;
577 \end{tikzpicture}
578 \end{codeexample}
579
580 \begin{codeexample}[]
581 \begin{tikzpicture}[radius=1cm,delta angle=30]
582 \draw (-1,0) -- +(3.5,0);
583 \draw (1,0) ++(210:2cm) -- +(30:4cm);
584 \draw (1,0) +(0:1cm) arc [start angle=0];
585 \draw (1,0) +(180:1cm) arc [start angle=180];
586 \path (1,0) ++(15:.75cm) node{$\alpha$};
587 \path (1,0) ++(15:-.75cm) node{$\beta$};
588 \end{tikzpicture}
589 \end{codeexample}
590
591 There also exists a shorter syntax for the arc operation, namely |arc|
592 begin directly followed by
593 |(|\meta{start angle}|:|\meta{end angle}|:|\meta{radius}). However, this
594 syntax is harder to read, so the normal syntax should be preferred in
595 general.
596 \end{pathoperation}
597
598
599 \subsection{The Grid Operation}
600
601 You can add a grid to the current path using the |grid| path operation.
602
603 \begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner or cycle}}
604 This operation adds a grid filling a rectangle whose two corners are given
605 by \meta{corner} and by the previous coordinate. (Instead of a coordinate
606 you can also say |cycle| to use the position of the last move-to as the
607 corner coordinate, but it is not very natural to do so.) Thus, the
608 typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, which
609 yields a grid filling the rectangle whose corners are at $(1,1)$ and
610 $(3,3)$. All coordinate transformations apply to the grid.
611 %
612 \begin{codeexample}[]
613 \tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2);
614 \end{codeexample}
615
616 The \meta{options}, which are local to the |grid| operation, can be used to
617 influence the appearance of the grid. The stepping of the grid is governed
618 by the following options:
619 %
620 \begin{key}{/tikz/step=\meta{number or dimension or coordinate} (initially 1cm)}
621 Sets the stepping in both the $x$ and $y$-direction. If a dimension is
622 provided, this is used directly. If a number is provided, this number
623 is interpreted in the $xy$-coordinate system. For example, if you
624 provide the number |2|, then the $x$-step is twice the $x$-vector and
625 the $y$-step is twice the $y$-vector set by the |x=| and |y=| options.
626 Finally, if you provide a coordinate, then the $x$-part of this
627 coordinate will be used as the $x$-step and the $y$-part will be used
628 as the $y$-coordinate.
629 %
630 \begin{codeexample}[]
631 \begin{tikzpicture}[x=.5cm]
632 \draw[thick] (0,0) grid [step=1] (3,2);
633 \draw[red] (0,0) grid [step=.75cm] (3,2);
634 \end{tikzpicture}
635 \begin{tikzpicture}
636 \draw (0,0) circle [radius=1];
637 \draw[blue] (0,0) grid [step=(45:1)] (3,2);
638 \end{tikzpicture}
639 \end{codeexample}
640
641 A complication arises when the $x$- and/or $y$-vector do not point
642 along the axes. Because of this, the actual rule for computing the
643 $x$-step and the $y$-step is the following: As the $x$- and $y$-steps
644 we use the $x$- and $y$-components or the following two vectors: The
645 first vector is either $(\meta{x-grid-step-number},0)$ or
646 $(\meta{x-grid-step-dimension},0\mathrm{pt})$, the second vector is
647 $(0,\meta{y-grid-step-number})$ or
648 $(0\mathrm{pt},\meta{y-grid-step-dimension})$.
649
650 If the $x$-step or $y$-step is $0$ or negative the corresponding lines
651 are not drawn.
652 \end{key}
653
654 \begin{key}{/tikz/xstep=\meta{dimension or number} (initially 1cm)}
655 Sets the stepping in the $x$-direction.
656 %
657 \begin{codeexample}[]
658 \begin{tikzpicture}
659 \draw (0,0) grid [xstep=.5,ystep=.75] (3,2);
660 \draw[ultra thick] (0,0) grid [ystep=0] (3,2);
661 \end{tikzpicture}
662 \end{codeexample}
663 \end{key}
664
665 \begin{key}{/tikz/ystep=\meta{dimension or number} (initially 1cm)}
666 Sets the stepping in the $y$-direction.
667 \end{key}
668
669 It is important to note that the grid is always ``phased'' such that it
670 contains the point $(0,0)$ if that point happens to be inside the
671 rectangle. Thus, the grid does \emph{not} always have an intersection at
672 the corner points; this occurs only if the corner points are multiples of
673 the stepping. Note that due to rounding errors, the ``last'' lines of a
674 grid may be omitted. In this case, you have to add an epsilon to the corner
675 points.
676
677 The following style is useful for drawing grids:
678 %
679 \begin{stylekey}{/tikz/help lines (initially {line width=0.2pt,gray})}
680 This style makes lines ``subdued'' by using thin gray lines for them.
681 However, this style is not installed automatically and you have to say
682 for example:
683 %
684 \begin{codeexample}[]
685 \tikz \draw[help lines] (0,0) grid (3,3);
686 \end{codeexample}
687 \end{stylekey}
688 \end{pathoperation}
689
690
691 \subsection{The Parabola Operation}
692
693 The |parabola| path operation continues the current path with a parabola. A
694 parabola is a (shifted and scaled) curve defined by the equation $f(x) = x^2$
695 and looks like this: \tikz \draw (-1ex,1.5ex) parabola[parabola height=-1.5ex]
696 +(2ex,0ex);.
697
698 \begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend
699 coordinate}}\meta{coordinate or cycle}}
700 This operation adds a parabola through the current point and the given
701 \meta{coordinate} or, if |cycle| is used instead of coordinate at the end,
702 the \meta{coordinate} is set to the position of the last move-to and the
703 path gets closed after the parabola. If the |bend| is given, it specifies
704 where the bend should go; the \meta{options} can also be used to specify
705 where the bend is. By default, the bend is at the old current point.
706 %
707 \begin{codeexample}[]
708 \begin{tikzpicture}
709 \draw (0,0) rectangle (1,1.5)
710 (0,0) parabola (1,1.5);
711 \draw[xshift=1.5cm] (0,0) rectangle (1,1.5)
712 (0,0) parabola[bend at end] (1,1.5);
713 \draw[xshift=3cm] (0,0) rectangle (1,1.5)
714 (0,0) parabola bend (.75,1.75) (1,1.5);
715
716 \draw[yshift=-2cm] (1,1.5) --
717 (0,0) parabola cycle;
718 \end{tikzpicture}
719 \end{codeexample}
720
721 The following options influence parabolas:
722 %
723 \begin{key}{/tikz/bend=\meta{coordinate}}
724 Has the same effect as saying |bend|\meta{coordinate} outside the
725 \meta{options}. The option specifies that the bend of the parabola
726 should be at the given \meta{coordinate}. You have to take care
727 yourself that the bend position is a ``valid'' position; which means
728 that if there is no parabola of the form $f(x) = a x^2 + b x + c$ that
729 goes through the old current point, the given bend, and the new current
730 point, the result will not be a parabola.
731
732 There is one special property of the \meta{coordinate}: When a relative
733 coordinate is given like |+(0,0)|, the position relative to this
734 coordinate is ``flexible''. More precisely, this position lies
735 somewhere on a line from the old current point to the new current
736 point. The exact position depends on the next option.
737 \end{key}
738
739 \begin{key}{/tikz/bend pos=\meta{fraction}}
740 Specifies where the ``previous'' point is relative to which the bend is
741 calculated. The previous point will be at the \meta{fraction}th part of
742 the line from the old current point to the new current point.
743
744 The idea is the following: If you say |bend pos=0| and |bend +(0,0)|,
745 the bend will be at the old current point. If you say |bend pos=1| and
746 |bend +(0,0)|, the bend will be at the new current point. If you say
747 |bend pos=0.5| and |bend +(0,2cm)| the bend will be 2cm above the
748 middle of the line between the start and end point. This is most useful
749 in situations such as the following:
750 %
751 \begin{codeexample}[]
752 \begin{tikzpicture}
753 \draw[help lines] (0,0) grid (3,2);
754 \draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0);
755 \end{tikzpicture}
756 \end{codeexample}
757
758 In the above example, the |bend +(0,2)| essentially means ``a parabola
759 that is 2cm high'' and |+(3,0)| means ``and 3cm wide''. Since this
760 situation arises often, there is a special shortcut option:
761 %
762 \begin{key}{/tikz/parabola height=\meta{dimension}}
763 This option has the same effect as
764 |[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|.
765 %
766 \begin{codeexample}[]
767 \begin{tikzpicture}
768 \draw[help lines] (0,0) grid (3,2);
769 \draw (-1,0) parabola[parabola height=2cm] +(3,0);
770 \end{tikzpicture}
771 \end{codeexample}
772 \end{key}
773 \end{key}
774
775 The following styles are useful shortcuts:
776 %
777 \begin{stylekey}{/tikz/bend at start}
778 This places the bend at the start of a parabola. It is a shortcut for
779 the following options: |bend pos=0,bend={+(0,0)}|.
780 \end{stylekey}
781
782 \begin{stylekey}{/tikz/bend at end}
783 This places the bend at the end of a parabola.
784 \end{stylekey}
785 \end{pathoperation}
786
787
788 \subsection{The Sine and Cosine Operation}
789
790 The |sin| and |cos| operations are similar to the |parabola| operation. They,
791 too, can be used to draw (parts of) a sine or cosine curve.
792
793 \begin{pathoperation}{sin}{\meta{coordinate or cycle}}
794 The effect of |sin| is to draw a scaled and shifted version of a sine curve
795 in the interval $[0,\pi/2]$. The scaling and shifting is done in such a way
796 that the start of the sine curve in the interval is at the old current
797 point and that the end of the curve in the interval is at
798 \meta{coordinate}. Here is an example that should clarify this:
799 %
800 \begin{codeexample}[]
801 \tikz \draw (0,0) rectangle (1,1) (0,0) sin (1,1)
802 (2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1);
803 \end{codeexample}
804 %
805 \end{pathoperation}
806
807 \begin{pathoperation}{cos}{\meta{coordinate or cycle}}
808 This operation works similarly, only a cosine in the interval $[0,\pi/2]$
809 is drawn. By correctly alternating |sin| and |cos| operations, you can
810 create a complete sine or cosine curve:
811 %
812 \begin{codeexample}[]
813 \begin{tikzpicture}[xscale=1.57]
814 \draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1);
815 \draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0);
816 \end{tikzpicture}
817 \end{codeexample}
818 %
819 \end{pathoperation}
820
821 Note that there is no way to (conveniently) draw an interval on a sine or
822 cosine curve whose end points are not multiples of $\pi/2$.
823
824
825 \subsection{The SVG Operation}
826
827 The |svg| operation can be used to extend the current path by a path given in
828 the \textsc{svg} path data syntax. This syntax is described in detail in
829 Section~8.3 of the \textsc{svg 1.1} specification, please consult this
830 specification for details.
831
832 \begin{pathoperation}{svg}{\opt{\oarg{options}}\marg{path data}}
833 This operation adds the path specified in the \meta{path data} in
834 \textsc{svg 1.1 path data} syntax to the current path. Unlike the
835 \textsc{svg}-specification, it \emph{is} permissible that the path data
836 does not start with a move-to command (|m| or |M|), in which case the last
837 point of the current path is used as start point. The optional
838 \meta{options} apply locally to this path operation, typically you will use
839 them to set up, say, some transformations.
840 %
841 \begin{codeexample}[preamble={\usetikzlibrary{svg.path}}]
842 \begin{tikzpicture}
843 \filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10}
844 node [above left] {upper left} -- cycle;
845
846 \draw svg {M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0};
847 \end{tikzpicture}
848 \end{codeexample}
849
850 An \textsc{svg} coordinate like |10 20| is always interpreted as
851 |(10pt,20pt)|, so the basic unit is always points (|pt|). The
852 $xy$-coordinate system is not used. However, you can use scaling to
853 (locally) change the basic unit. For instance, |svg[scale=1cm]| (yes, this
854 works, although some rather evil magic is involved) will cause 1cm to be
855 the basic unit.
856
857 Instead of curly braces, you can also use quotation marks to indicate the
858 start and end of the \textsc{svg} path.
859
860 \emph{Warning:} The arc operations (|a| and |A|) are numerically instable.
861 This means that they will be quite imprecise, except when the angle is a
862 multiple of $90^\circ$ (as is, fortunately, most often the case).
863 \end{pathoperation}
864
865
866 \subsection{The Plot Operation}
867
868 The |plot| operation can be used to append a line or curve to the path that
869 goes through a large number of coordinates. These coordinates are either given
870 in a simple list of coordinates, read from some file, or they are computed on
871 the fly.
872
873 Since the syntax and the behavior of this command are a bit complex, they are
874 described in the separated Section~\ref{section-tikz-plots}.
875
876
877 \subsection{The To Path Operation}
878
879 The |to| operation is used to add a user-defined path from the previous
880 coordinate to the following coordinate. When you write |(a) to (b)|, a straight
881 line is added from |a| to |b|, exactly as if you had written |(a) -- (b)|.
882 However, if you write |(a) to [out=135,in=45] (b)| a curve is added to the
883 path, which leaves at an angle of 135$^\circ$ at |a| and arrives at an angle of
884 45$^\circ$ at |b|. This is because the options |in| and |out| trigger a special
885 path to be used instead of the straight line.
886
887 \begin{pathoperation}{to}{\opt{|[|\meta{options}|]|}
888 \opt{\meta{nodes}} \meta{coordinate or cycle}}
889 This path operation inserts the path currently set via the |to path| option
890 at the current position. The \meta{options} can be used to modify (perhaps
891 implicitly) the |to path| and to set up how the path will be rendered.
892
893 Before the |to path| is inserted, a number of macros are set up that can
894 ``help'' the |to path|. These are |\tikztostart|, |\tikztotarget|, and
895 |\tikztonodes|; they are explained in the following.
896
897 \medskip
898 \textbf{Start and Target Coordinates.}\ \
899 The |to| operation is always followed by a \meta{coordinate}, called the
900 target coordinate, or the text |cycle|, in which case the last move-to is
901 used as a coordinate and the path gets closed. The macro |\tikztotarget| is
902 set to this coordinate (without its parentheses). There is also a
903 \emph{start coordinate}, which is the coordinate preceding the |to|
904 operation. This coordinate can be accessed via the macro |\tikztostart|. In
905 the following example, for the first |to|, the macro |\tikztostart| is
906 |0pt,0pt| and the |\tikztotarget| is |0,2|. For the second |to|, the macro
907 |\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the third,
908 they are set to |a| and |current subpath start|.
909 %
910 \begin{codeexample}[]
911 \begin{tikzpicture}
912 \draw[help lines] (0,0) grid (3,2);
913 \node (a) at (2,2) {a};
914
915 \draw (0,0) to (0,2);
916 \draw[red] (10pt,10pt) to (a);
917 \draw[blue] (3,0) -- (3,2) -- (a) to cycle;
918 \end{tikzpicture}
919 \end{codeexample}
920
921 \medskip
922 \textbf{Nodes on to--paths.}\ \
923 It is possible to add nodes to the paths constructed by a |to| operation.
924 To do so, you specify the nodes between the |to| keyword and the coordinate
925 (if there are options to the |to| operation, these come first). The effect
926 of |(a) to node {x} (b)| (typically) is the same as if you had written
927 |(a) -- node {x} (b)|, namely that the node is placed on the |to|. This can
928 be used to add labels to |to|s:
929 %
930 \begin{codeexample}[]
931 \begin{tikzpicture}
932 \draw (0,0) to node [sloped,above] {x} (3,2);
933
934 \draw (0,0) to[out=90,in=180] node [sloped,above] {x} (3,2);
935 \end{tikzpicture}
936 \end{codeexample}
937
938 Instead of writing the node between the |to| keyword and the target
939 coordinate, you may also use the following keys to create such nodes:
940 %
941 \begin{key}{/tikz/edge node=\meta{node specification}}
942 This key can be used inside the \meta{options} of a |to| path command.
943 It will add the \meta{node specification} to the list of nodes to be
944 placed on the connecting line, just as if you had written the
945 \meta{node specification} directly after the |to| keyword:
946 %
947 \begin{codeexample}[]
948 \begin{tikzpicture}
949 \draw (0,0) to [edge node={node [sloped,above] {x}}] (3,2);
950
951 \draw (0,0) to [out=90,in=180,
952 edge node={node [sloped,above] {x}}] (3,2);
953 \end{tikzpicture}
954 \end{codeexample}
955 %
956 This key is mostly useful to create labels automatically using other
957 keys.
958 \end{key}
959 %
960 \begin{key}{/tikz/edge label=\meta{text}}
961 A shorthand for |edge node={node[auto]{|\meta{text}|}}|.
962 %
963 \begin{codeexample}[]
964 \tikz \draw (0,0) to [edge label=x] (3,2);
965 \end{codeexample}
966 \end{key}
967 %
968 \begin{key}{/tikz/edge label'=\meta{text}}
969 A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|.
970 %
971 \begin{codeexample}[]
972 \tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2);
973 \end{codeexample}
974 \end{key}
975
976 When the |quotes| library is loaded, additional ways of specifying nodes on
977 to--paths become available, see Section~\ref{section-edge-quotes}.
978
979 \medskip
980 \textbf{Styles for to-paths.}\ \
981 In addition to the \meta{options} given after the |to| operation, the
982 following style is also set at the beginning of the to path:
983 %
984 \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
985 This style is installed at the beginning of every to.
986 %
987 \begin{codeexample}[]
988 \tikz[every to/.style={bend left}]
989 \draw (0,0) to (3,2);
990 \end{codeexample}
991 %
992 Note that, as explained below, every to path is implicitly surrounded
993 by curly braces. This means that options like |draw| given in an
994 |every to| do not actually influence the path. You can fix this by
995 using the |append after command| option:
996 %
997 \begin{codeexample}[]
998 \tikz[every to/.style={append after command={[draw,dashed]}}]
999 \draw (0,0) to (3,2);
1000 \end{codeexample}
1001 \end{stylekey}
1002
1003 \medskip
1004 \textbf{Options.}\ \
1005 The \meta{options} given with the |to| allow you to influence the
1006 appearance of the |to path|. Mostly, these options are used to change the
1007 |to path|. This can be used to change the path from a straight line to,
1008 say, a curve.
1009
1010 The path used is set using the following option:
1011 %
1012 \begin{key}{/tikz/to path=\meta{path}}
1013 Whenever a |to| operation is used, the \meta{path} is inserted. More
1014 precisely, the following path is added:
1015 %
1016 \begin{quote}
1017 |{[every to,|\meta{options}|] |\meta{path} |}|
1018 \end{quote}
1019
1020 The \meta{options} are the options given to the |to| operation, the
1021 \meta{path} is the path set by this option |to path|.
1022
1023 Inside the \meta{path}, different macros are used to reference the
1024 from- and to-coordinates. In detail, these are:
1025 %
1026 \begin{itemize}
1027 \item \declareandlabel{\tikztostart} will expand to the
1028 from-coordinate (without the parentheses).
1029 \item \declareandlabel{\tikztotarget} will expand to the
1030 to-coordinate.
1031 \item \declareandlabel{\tikztonodes} will expand to the nodes
1032 between the |to| operation and the coordinate. Furthermore,
1033 these nodes will have the |pos| option set implicitly.
1034 \end{itemize}
1035
1036 Let us have a look at a simple example. The standard straight line for
1037 a |to| is achieved by the following \meta{path}:
1038 %
1039 \begin{quote}
1040 |-- (\tikztotarget) \tikztonodes|
1041 \end{quote}
1042
1043 Indeed, this is the default setting for the path. When we write
1044 |(a) to (b)|, the \meta{path} will expand to |(a) -- (b)|, when we
1045 write
1046 %
1047 \begin{quote}
1048 |(a) to[red] node {x} (b)|
1049 \end{quote}
1050 %
1051 the \meta{path} will expand to
1052 %
1053 \begin{quote}
1054 |(a) -- (b) node[red] {x}|
1055 \end{quote}
1056
1057 It is not possible to specify the path
1058 %
1059 \begin{quote}
1060 |-- \tikztonodes (\tikztotarget)|
1061 \end{quote}
1062 %
1063 since \tikzname\ does not allow one to have a macro after |--| that
1064 expands to a node.
1065
1066 Now let us have a look at how we can modify the \meta{path} sensibly.
1067 The simplest way is to use a curve.
1068 %
1069 \begin{codeexample}[]
1070 \begin{tikzpicture}[to path={
1071 .. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}]
1072
1073 \node (a) at (0,0) {a};
1074 \node (b) at (2,1) {b};
1075 \node (c) at (1,2) {c};
1076
1077 \draw (a) to node {x} (b)
1078 (a) to (c);
1079 \end{tikzpicture}
1080 \end{codeexample}
1081
1082 Here is another example:
1083 %
1084 \begin{codeexample}[]
1085 \tikzset{
1086 my loop/.style={to path={
1087 .. controls +(80:1) and +(100:1) .. (\tikztotarget) \tikztonodes}},
1088 my state/.style={circle,draw}}
1089
1090 \begin{tikzpicture}[shorten >=2pt]
1091 \node [my state] (a) at (210:1) {$q_a$};
1092 \node [my state] (b) at (330:1) {$q_b$};
1093
1094 \draw[->] (a) to node[below] {1} (b)
1095 to [my loop] node[above right] {0} (b);
1096 \end{tikzpicture}
1097 \end{codeexample}
1098
1099 \begin{key}{/tikz/execute at begin to=\meta{code}}
1100 The \meta{code} is executed prior to the |to|. This can be used to
1101 draw one or more additional paths or to do additional computations.
1102 \end{key}
1103
1104 \begin{key}{/tikz/execute at end to=\meta{code}}
1105 Works like the previous option, only this code is executed after
1106 the to path has been added.
1107 % FIXME : provide examples...
1108 \end{key}
1109
1110 \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
1111 This style is installed at the beginning of every to.
1112 \end{stylekey}
1113 \end{key}
1114 \end{pathoperation}
1115
1116 There are a number of predefined |to path|s, see Section~\ref{library-to-paths}
1117 for a reference.
1118
1119
1120 \subsection{The Foreach Operation}
1121
1122 \begin{pathoperation}{foreach}{\meta{variables}\opt{\oarg{options}} |in|
1123 \meta{list} \marg{path commands}}
1124 The |foreach| operation can be used to repeatedly insert the \meta{path
1125 commands} into the current path. Naturally, the \meta{path commands} should
1126 internally reference some of the \meta{variables} so that you do not insert
1127 exactly the same path repeatedly, but rather variations. For historical
1128 reasons, you can also write |\foreach| instead of |foreach|.
1129 %
1130 \begin{codeexample}[]
1131 \tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) };
1132 \end{codeexample}
1133 %
1134 See Section~\ref{section-foreach} for more details on the for-each-command.
1135 \end{pathoperation}
1136
1137
1138 \subsection{The Let Operation}
1139
1140 The \emph{let operation} is the first of a number of path operations that do
1141 not actually extend that path, but have different, mostly local, effects.
1142 It requires the |calc| library, see Section~\ref{tikz-lib-calc}.
1143
1144 \begin{pathoperation}{let}{\meta{assignment}
1145 \opt{|,|\meta{assignment}}%
1146 \opt{|,|\meta{assignment}\dots}\declare{| in |}}
1147 When this path operation is encountered, the \meta{assignment}s are
1148 evaluated, one by one. This will store coordinate and number in
1149 special \emph{registers} (which are local to \tikzname, they have
1150 nothing to do with \TeX\ registers). Subsequently, one can access the
1151 contents of these registers using the macros |\p|, |\x|, |\y|, and
1152 |\n|.
1153
1154 The first kind of permissible \meta{assignment}s have the following form:
1155 %
1156 \begin{quote}
1157 |\n|\meta{number register}|={|\meta{formula}|}|
1158 \end{quote}
1159 %
1160 When an assignment has this form, the \meta{formula} is evaluated using the
1161 |\pgfmathparse| operation. The result is stored in the \meta{number
1162 register}. If the \meta{formula} involves a dimension anywhere (as in
1163 |2*3cm/2|), then the \meta{number register} stores the resulting dimension
1164 with a trailing |pt|. A \meta{number register} can be named arbitrarily
1165 and is a normal \TeX\ parameter to the |\n| macro. Possible names are
1166 |{left corner}|, but also just a single digit like~|5|.
1167
1168 Let us call the path that follows a let operation its \emph{body}. Inside
1169 the body, the |\n| macro can be used to access the register.
1170 %
1171 \begin{command}{\n\marg{number register}}
1172 When this macro is used on the left-hand side of an |=|-sign in a let
1173 operation, it has no effect and is just there for readability. When the
1174 macro is used on the right-hand side of an |=|-sign or in the body of
1175 the let operation, then it expands to the value stored in the
1176 \meta{number register}. This will either be a dimensionless number like
1177 |2.0| or a dimension like |5.6pt|.
1178
1179 For instance, if we say |let \n1={1pt+2pt}, \n2={1+2} in ...|, then
1180 inside the |...| part the macro |\n1| will expand to |3pt| and |\n2|
1181 expands to |3|.
1182 \end{command}
1183
1184 The second kind of \meta{assignments} have the following form:
1185 %
1186 \begin{quote}
1187 |\p|\meta{point register}|=|\meta{coordinate}
1188 \end{quote}
1189 %
1190 Point position registers store a single point, consisting of an $x$-part
1191 and a $y$-part measured in \TeX\ points (|pt|). In particular, point
1192 registers do not store nodes or node names. Here is an example:
1193 %
1194 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1195 \begin{tikzpicture}
1196 \draw [help lines] (0,0) grid (3,2);
1197
1198 \draw let \p{foo} = (1,1), \p2 = (2,0) in
1199 (0,0) -- (\p2) -- (\p{foo});
1200 \end{tikzpicture}
1201 \end{codeexample}
1202
1203 \begin{command}{\p\marg{point register}}
1204 When this macro is used on the left-hand side of an |=|-sign in a let
1205 operation, it has no effect and is just there for readability. When the
1206 macro is used on the right-hand side of an |=|-sign or in the body of
1207 the let operation, then it expands to the $x$-part (measured in \TeX\
1208 points) of the coordinate stored in the \meta{register}, followed, by a
1209 comma, followed by the $y$-part.
1210
1211 For instance, if we say |let \p1=(1pt,1pt+2pt) in ...|, then inside the
1212 |...| part the macro |\p1| will expand to exactly the seven characters
1213 ``1pt,3pt''. This means that you when you write |(\p1)|, this expands
1214 to |(1pt,3pt)|, which is presumably exactly what you intended.
1215 \end{command}
1216 %
1217 \begin{command}{\x\marg{point register}}
1218 This macro expands just to the $x$-part of the point register. If we
1219 say as above, as we did above, |let \p1=(1pt,1pt+2pt) in ...|, then
1220 inside the |...| part the macro |\x1| expands to |1pt|.
1221 \end{command}
1222 %
1223 \begin{command}{\y\marg{point register}}
1224 Works like |\x|, only for the $y$-part.
1225 \end{command}
1226 %
1227 Note that the above macros are available only inside a let operation.
1228
1229 Here is an example where let clauses are used to assemble a coordinate from
1230 the $x$-coordinate of a first point and the $y$-coordinate of a second
1231 point. Naturally, using the \verb!|-! notation, this could be written much
1232 more compactly.
1233 %
1234 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1235 \begin{tikzpicture}
1236 \draw [help lines] (0,0) grid (3,2);
1237
1238 \draw (1,0) coordinate (first point)
1239 -- (3,2) coordinate (second point);
1240
1241 \fill[red] let \p1 = (first point),
1242 \p2 = (second point) in
1243 (\x1,\y2) circle [radius=2pt];
1244 \end{tikzpicture}
1245 \end{codeexample}
1246
1247 Note that the effect of a let operation is local to the body of the let
1248 operation. If you wish to access a computed coordinate outside the body,
1249 you must use a |coordinate| path operation:
1250 %
1251 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1252 \begin{tikzpicture}
1253 \draw [help lines] (0,0) grid (3,2);
1254
1255 \path % let's define some points:
1256 let
1257 \p1 = (1,0),
1258 \p2 = (3,2),
1259 \p{center} = ($ (\p1) !.5! (\p2) $) % center
1260 in
1261 coordinate (p1) at (\p1)
1262 coordinate (p2) at (\p2)
1263 coordinate (center) at (\p{center});
1264
1265 \draw (p1) -- (p2);
1266 \fill[red] (center) circle [radius=2pt];
1267 \end{tikzpicture}
1268 \end{codeexample}
1269
1270 For a more useful application of the let operation, let us draw a circle
1271 that touches a given line:
1272 %
1273 \begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{calc}}]
1274 \begin{tikzpicture}
1275 \draw [help lines] (0,0) grid (3,3);
1276
1277 \coordinate (a) at (rnd,rnd);
1278 \coordinate (b) at (3-rnd,3-rnd);
1279 \draw (a) -- (b);
1280
1281 \node (c) at (1,2) {x};
1282
1283 \draw let \p1 = ($ (a)!(c)!(b) - (c) $),
1284 \n1 = {veclen(\x1,\y1)}
1285 in circle [at=(c), radius=\n1];
1286 \end{tikzpicture}
1287 \end{codeexample}
1288 %
1289 \end{pathoperation}
1290
1291
1292 \subsection{The Scoping Operation}
1293
1294 When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at some
1295 point where a path operation should come, it will open or close a scope. All
1296 options that can be applied ``locally'' will be scoped inside the scope. For
1297 example, if you apply a transformation like |[xshift=1cm]| inside the scoped
1298 area, the shifting only applies to the scope. On the other hand, an option like
1299 |color=red| does not have any effect inside a scope since it can only be
1300 applied to the path as a whole.
1301
1302 Concerning the effect of scopes on relative coordinates, please see
1303 Section~\ref{section-scopes-relative}.
1304
1305
1306 \subsection{The Node and Edge Operations}
1307
1308 The |node| operation adds a so-called node to a path. This operation is special
1309 in the following sense: It does not change the current path in any way. In
1310 other words, this operation is not really a path operation, but has an effect
1311 that is ``external'' to the path. The |edge| operation has similar effect in
1312 that it adds something \emph{after} the main path has been drawn. However, it
1313 works like the |to| operation, that is, it adds a |to| path to the picture
1314 after the main path has been drawn.
1315
1316 Since these operations are quite complex, they are described in the separate
1317 Section~\ref{section-nodes}.
1318
1319
1320 \subsection{The Graph Operation}
1321
1322 The |graph| operation can be used to specify easily how a large number of nodes
1323 are connected. This operation is documented in a separate section, see
1324 Section~\ref{section-library-graphs}.
1325
1326
1327 \subsection{The Pic Operation}
1328
1329 The |pic| operation is used to insert a ``short picture'' (hence the ``short''
1330 name) at the current position of the path. This operation is somewhat similar
1331 to the |node| operation and discussed in detail in Section~\ref{section-pics}.
1332
1333
1334 \subsection{The Attribute Animation Operation}
1335
1336 \begin{pathoperation}{:}{\meta{animation attribute}|=|\marg{options}}
1337 This path operation has the same effect as if you had said:
1338 %
1339 \begin{quote}
1340 |[animate = { myself:|\meta{animate attribute}|=|\marg{options}|} ]|
1341 \end{quote}
1342 %
1343 This causes an animation of \meta{animate attribute} to be added to the
1344 current path, see Section~\ref{section-tikz-animations} for details.
1345 %
1346 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
1347 \tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
1348 \end{codeexample}
1349 %
1350 \end{pathoperation}
1351
1352
1353 \subsection{The PGF-Extra Operation}
1354
1355 In some cases you may need to ``do some calculations or some other stuff''
1356 while a path is constructed. For this, you would like to suspend the
1357 construction of the path and suspend \tikzname's parsing of the path, you would
1358 then like to have some \TeX\ code executed, and would then like to resume the
1359 parsing of the path. This effect can be achieved using the following path
1360 operation |\pgfextra|. Note that this operation should only be used by real
1361 experts and should only be used deep inside clever macros, not on normal paths.
1362
1363 \begin{command}{\pgfextra\marg{code}}
1364 This command may only be used inside a \tikzname\ path. There it is used
1365 like a normal path operation. The construction of the path is temporarily
1366 suspended and the \meta{code} is executed. Then, the path construction is
1367 resumed.
1368 %
1369 \begin{codeexample}[]
1370 \newdimen\mydim
1371 \begin{tikzpicture}
1372 \mydim=1cm
1373 \draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim);
1374 \end{tikzpicture}
1375 \end{codeexample}
1376 %
1377 \end{command}
1378
1379 \begin{command}{\pgfextra \meta{code} \texttt{\char`\\endpgfextra}}
1380 This is an alternative syntax for the |\pgfextra| command. If the code
1381 following |\pgfextra| does not start with a brace, the \meta{code} is
1382 executed until |\endpgfextra| is encountered. What actually happens is that
1383 when |\pgfextra| is not followed by a brace, this completely shuts down the
1384 \tikzname\ parser and |\endpgfextra| is a normal macro that restarts the
1385 parser.
1386 %
1387 \begin{codeexample}[]
1388 \newdimen\mydim
1389 \begin{tikzpicture}
1390 \mydim=1cm
1391 \draw (0pt,\mydim)
1392 \pgfextra \mydim=2cm \endpgfextra -- (0pt,\mydim);
1393 \end{tikzpicture}
1394 \end{codeexample}
1395 %
1396 \end{command}
1397
1398
1399 \subsection{Interacting with the Soft Path subsystem}
1400
1401 During construction \tikzname\ stores the path internally as a \emph{soft
1402 path}. Sometimes it is desirable to save a path during the stage of
1403 construction, restore it elsewhere and continue using it. There are two keys to
1404 facilitate this operation, which are explained below. To learn more about the
1405 soft path subsystem, refer to section~\ref{section-soft-paths}.
1406
1407 \begin{key}{/tikz/save path=\meta{macro}}
1408 Save the current soft path into \meta{macro}.
1409 \end{key}
1410
1411 \begin{key}{/tikz/use path=\meta{macro}}
1412 Set the current path to the soft path stored in \meta{macro}.
1413 \end{key}
1414
1415 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
1416 \begin{tikzpicture}
1417 \path[save path=\pathA,name path=A] (0,1) to [bend left] (1,0);
1418 \path[save path=\pathB,name path=B]
1419 (0,0) .. controls (.33,.1) and (.66,.9) .. (1,1);
1420
1421 \fill[name intersections={of=A and B}] (intersection-1) circle (1pt);
1422
1423 \draw[blue][use path=\pathA];
1424 \draw[red] [use path=\pathB];
1425 \end{tikzpicture}
1426 \end{codeexample}