Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-coordinates.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{Specifying Coordinates}
12
13 \subsection{Overview}
14
15 A \emph{coordinate} is a position on the canvas on which your picture is drawn.
16 \tikzname\ uses a special syntax for specifying coordinates. Coordinates are
17 always put in round brackets. The general syntax is
18 \declare{|(|\opt{|[|\meta{options}|]|}\meta{coordinate specification}|)|}.
19
20 The \meta{coordinate specification} specifies coordinates using one of many
21 different possible \emph{coordinate systems}. Examples are the Cartesian
22 coordinate system or polar coordinates or spherical coordinates. No matter
23 which coordinate system is used, in the end, a specific point on the canvas is
24 represented by the coordinate.
25
26 There are two ways of specifying which coordinate system should be used:
27 %
28 \begin{description}
29 \item[Explicitly] You can specify the coordinate system explicitly. To do
30 so, you give the name of the coordinate system at the beginning,
31 followed by |cs:|, which stands for ``coordinate system'', followed by
32 a specification of the coordinate using the key--value syntax. Thus,
33 the general syntax for \meta{coordinate specification} in the explicit
34 case is |(|\meta{coordinate system}| cs:|\meta{list of key--value pairs
35 specific to the coordinate system}|)|.
36 \item[Implicitly] The explicit specification is often too verbose when
37 numerous coordinates should be given. Because of this, for the
38 coordinate systems that you are likely to use often a special syntax
39 is provided. \tikzname\ will notice when you use a coordinate
40 specified in a special syntax and will choose the correct coordinate
41 system automatically.
42 \end{description}
43
44 Here is an example in which explicit the coordinate systems are specified
45 explicitly:
46 %
47 \begin{codeexample}[]
48 \begin{tikzpicture}
49 \draw[help lines] (0,0) grid (3,2);
50 \draw (canvas cs:x=0cm,y=2mm)
51 -- (canvas polar cs:radius=2cm,angle=30);
52 \end{tikzpicture}
53 \end{codeexample}
54 %
55 In the next example, the coordinate systems are implicit:
56 %
57 \begin{codeexample}[]
58 \begin{tikzpicture}
59 \draw[help lines] (0,0) grid (3,2);
60 \draw (0cm,2mm) -- (30:2cm);
61 \end{tikzpicture}
62 \end{codeexample}
63
64 It is possible to give options that apply only to a single coordinate, although
65 this makes sense for transformation options only. To give transformation
66 options for a single coordinate, give these options at the beginning in
67 brackets:
68 %
69 \begin{codeexample}[]
70 \begin{tikzpicture}
71 \draw[help lines] (0,0) grid (3,2);
72 \draw (0,0) -- (1,1);
73 \draw[red] (0,0) -- ([xshift=3pt] 1,1);
74 \draw (1,0) -- +(30:2cm);
75 \draw[red] (1,0) -- +([shift=(135:5pt)] 30:2cm);
76 \end{tikzpicture}
77 \end{codeexample}
78
79
80 \subsection{Coordinate Systems}
81
82 \subsubsection{Canvas, XYZ, and Polar Coordinate Systems}
83
84 Let us start with the basic coordinate systems.
85
86 \begin{coordinatesystem}{canvas}
87 The simplest way of specifying a coordinate is to use the |canvas|
88 coordinate system. You provide a dimension $d_x$ using the |x=| option and
89 another dimension $d_y$ using the |y=| option. The position on the canvas
90 is located at the position that is $d_x$ to the right and $d_y$ above the
91 origin.
92
93 \begin{key}{/tikz/cs/x=\meta{dimension} (initially 0pt)}
94 Distance by which the coordinate is to the right of the origin. You can
95 also write things like |1cm+2pt| since the mathematical engine is used
96 to evaluate the \meta{dimension}.
97 \end{key}
98
99 \begin{key}{/tikz/cs/y=\meta{dimension} (initially 0pt)}
100 Distance by which the coordinate is above the origin.
101 \end{key}
102
103 \begin{codeexample}[]
104 \begin{tikzpicture}
105 \draw[help lines] (0,0) grid (3,2);
106
107 \fill (canvas cs:x=1cm,y=1.5cm) circle (2pt);
108 \fill (canvas cs:x=2cm,y=-5mm+2pt) circle (2pt);
109 \end{tikzpicture}
110 \end{codeexample}
111
112 To specify a coordinate in the coordinate system implicitly, you use two
113 dimensions that are separated by a comma as in |(0cm,3pt)| or
114 |(2cm,\textheight)|.
115 %
116 \begin{codeexample}[]
117 \begin{tikzpicture}
118 \draw[help lines] (0,0) grid (3,2);
119
120 \fill (1cm,1.5cm) circle (2pt);
121 \fill (2cm,-5mm+2pt) circle (2pt);
122 \end{tikzpicture}
123 \end{codeexample}
124 %
125 \end{coordinatesystem}
126
127 \begin{coordinatesystem}{xyz}
128 The |xyz| coordinate system allows you to specify a point as a multiple of
129 three vectors called the $x$-, $y$-, and $z$-vectors. By default, the
130 $x$-vector points 1cm to the right, the $y$-vector points 1cm upwards, but
131 this can be changed arbitrarily as explained in Section~\ref{section-xyz}.
132 The default $z$-vector points to
133 $\bigl(-3.85\textrm{mm},-3.85\textrm{mm}\bigr)$.
134
135 To specify the factors by which the vectors should be multiplied before
136 being added, you use the following three options:
137 %
138 \begin{key}{/tikz/cs/x=\meta{factor} (initially 0)}
139 Factor by which the $x$-vector is multiplied.
140 \end{key}
141 %
142 \begin{key}{/tikz/cs/y=\meta{factor} (initially 0)}
143 Works like |x|.
144 \end{key}
145 %
146 \begin{key}{/tikz/cs/z=\meta{factor} (initially 0)}
147 Works like |x|.
148 \end{key}
149
150 \begin{codeexample}[]
151 \begin{tikzpicture}[->]
152 \draw (0,0) -- (xyz cs:x=1);
153 \draw (0,0) -- (xyz cs:y=1);
154 \draw (0,0) -- (xyz cs:z=1);
155 \end{tikzpicture}
156 \end{codeexample}
157
158 This coordinate system can also be selected implicitly. To do so, you just
159 provide two or three comma-separated factors (not dimensions).
160 %
161 \begin{codeexample}[]
162 \begin{tikzpicture}[->]
163 \draw (0,0) -- (1,0);
164 \draw (0,0) -- (0,1,0);
165 \draw (0,0) -- (0,0,1);
166 \end{tikzpicture}
167 \end{codeexample}
168 %
169 \end{coordinatesystem}
170
171 \emph{Note:} It is possible to use coordinates like |(1,2cm)|, which are
172 neither |canvas| coordinates nor |xyz| coordinates. The rule is the following:
173 If a coordinate is of the implicit form |(|\meta{x}|,|\meta{y}|)|, then
174 \meta{x} and \meta{y} are checked, independently, whether they have a dimension
175 or whether they are dimensionless. If both have a dimension, the |canvas|
176 coordinate system is used. If both lack a dimension, the |xyz| coordinate
177 system is used. If \meta{x} has a dimension and \meta{y} has not, then the sum
178 of two coordinate |(|\meta{x}|,0pt)| and |(0,|\meta{y}|)| is used. If \meta{y}
179 has a dimension and \meta{x} has not, then the sum of two coordinate
180 |(|\meta{x}|,0)| and |(0pt,|\meta{y}|)| is used.
181
182 \emph{Note furthermore:} An expression like |(2+3cm,0)| does \emph{not} mean
183 the same as |(2cm+3cm,0)|. Instead, if \meta{x} or \meta{y} internally uses a
184 mixture of dimensions and dimensionless values, then all dimensionless values
185 are ``upgraded'' to dimensions by interpreting them as |pt|. So, |2+3cm| is the
186 same dimension as |2pt+3cm|.
187
188 \begin{coordinatesystem}{canvas polar}
189 The |canvas polar| coordinate system allows you to specify polar
190 coordinates. You provide an angle using the |angle=| option and a radius
191 using the |radius=| option. This yields the point on the canvas that is at
192 the given radius distance from the origin at the given degree. An angle of
193 zero degrees to the right, a degree of 90 upward.
194 %
195 \begin{key}{/tikz/cs/angle=\meta{degrees}}
196 The angle of the coordinate. The angle must always be given in degrees.
197 \end{key}
198 %
199 \begin{key}{/tikz/cs/radius=\meta{dimension}}
200 The distance from the origin.
201 \end{key}
202 %
203 \begin{key}{/tikz/cs/x radius=\meta{dimension}}
204 A polar coordinate is, after all, just a point on a circle of the given
205 \meta{radius}. When you provide an $x$-radius and also a $y$-radius,
206 you specify an ellipse instead of a circle. The |radius| option has the
207 same effect as specifying identical |x radius| and |y radius| options.
208 \end{key}
209 %
210 \begin{key}{/tikz/cs/y radius=\meta{dimension}}
211 Works like |x radius|.
212 \end{key}
213 %
214 \begin{codeexample}[]
215 \tikz \draw (0,0) -- (canvas polar cs:angle=30,radius=1cm);
216 \end{codeexample}
217
218 The implicit form for canvas polar coordinates is the following: you
219 specify the angle and the distance, separated by a colon as in |(30:1cm)|.
220 %
221 \begin{codeexample}[]
222 \tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm)
223 -- (120:1cm) -- (150:1cm) -- (180:1cm);
224 \end{codeexample}
225
226 Two different radii are specified by writing |(30:1cm and 2cm)|.
227
228 For the implicit form, instead of an angle given as a number you can also
229 use certain words. For example, |up| is the same as |90|, so that you can
230 write |\tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);| and get
231 \tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);. Apart from |up| you can use
232 |down|, |left|, |right|, |north|, |south|, |west|, |east|, |north east|,
233 |north west|, |south east|, |south west|, all of which have their natural
234 meaning.
235 \end{coordinatesystem}
236
237 \begin{coordinatesystem}{xyz polar}
238 This coordinate system work similarly to the |canvas polar| system.
239 However, the radius and the angle are interpreted in the $xy$-coordinate
240 system, not in the canvas system. More detailed, consider the circle or
241 ellipse whose half axes are given by the current $x$-vector and the current
242 $y$-vector. Then, consider the point that lies at a given angle on this
243 ellipse, where an angle of zero is the same as the $x$-vector and an angle
244 of 90 is the $y$-vector. Finally, multiply the resulting vector by the
245 given radius factor. Voil\`a.
246 %
247 \begin{key}{/tikz/cs/angle=\meta{degrees}}
248 The angle of the coordinate interpreted in the ellipse whose axes are
249 the $x$-vector and the $y$-vector.
250 \end{key}
251 %
252 \begin{key}{/tikz/cs/radius=\meta{factor}}
253 A factor by which the $x$-vector and $y$-vector are multiplied prior to
254 forming the ellipse.
255 \end{key}
256 %
257 \begin{key}{/tikz/cs/x radius=\meta{dimension}}
258 A specific factor by which only the $x$-vector is multiplied.
259 \end{key}
260 %
261 \begin{key}{/tikz/cs/y radius=\meta{dimension}}
262 Works like |x radius|.
263 \end{key}
264 %
265 \begin{codeexample}[]
266 \begin{tikzpicture}[x=1.5cm,y=1cm]
267 \draw[help lines] (0cm,0cm) grid (3cm,2cm);
268
269 \draw (0,0) -- (xyz polar cs:angle=0,radius=1);
270 \draw (0,0) -- (xyz polar cs:angle=30,radius=1);
271 \draw (0,0) -- (xyz polar cs:angle=60,radius=1);
272 \draw (0,0) -- (xyz polar cs:angle=90,radius=1);
273
274 \draw (xyz polar cs:angle=0,radius=2)
275 -- (xyz polar cs:angle=30,radius=2)
276 -- (xyz polar cs:angle=60,radius=2)
277 -- (xyz polar cs:angle=90,radius=2);
278 \end{tikzpicture}
279 \end{codeexample}
280
281 The implicit version of this option is the same as the implicit version of
282 |canvas polar|, only you do not provide a unit.
283
284 \begin{codeexample}[]
285 \tikz[x={(0cm,1cm)},y={(-1cm,0cm)}]
286 \draw (0,0) -- (30:1) -- (60:1) -- (90:1)
287 -- (120:1) -- (150:1) -- (180:1);
288 \end{codeexample}
289 %
290 \end{coordinatesystem}
291
292 \begin{coordinatesystem}{xy polar}
293 This is just an alias for |xyz polar|, which some people might prefer as
294 there is no z-coordinate involved in the |xyz polar| coordinates.
295 \end{coordinatesystem}
296
297
298 \subsubsection{Barycentric Systems}
299 \label{section-barycentric-coordinates}
300
301 In the barycentric coordinate system a point is expressed as the linear
302 combination of multiple vectors. The idea is that you specify vectors $v_1$,
303 $v_2$, \dots, $v_n$ and numbers $\alpha_1$, $\alpha_2$, \dots, $\alpha_n$. Then
304 the barycentric coordinate specified by these vectors and numbers is
305 %
306 \begin{align*}
307 \frac{\alpha_1 v_1 + \alpha_2 v_2 + \cdots + \alpha_n v_n}{\alpha_1
308 + \alpha_2 + \cdots + \alpha_n}
309 \end{align*}
310
311 The |barycentric cs| allows you to specify such coordinates easily.
312
313 \begin{coordinatesystem}{barycentric}
314 For this coordinate system, the \meta{coordinate specification} should be a
315 comma-separated list of expressions of the form \meta{node
316 name}|=|\meta{number}. Note that (currently) the list should not contain
317 any spaces before or after the \meta{node name} (unlike normal key--value
318 pairs).
319
320 The specified coordinate is now computed as follows: Each pair provides one
321 vector and a number. The vector is the |center| anchor of the \meta{node
322 name}. The number is the \meta{number}. Note that (currently) you cannot
323 specify a different anchor, so that in order to use, say, the |north|
324 anchor of a node you first have to create a new coordinate at this north
325 anchor. (Using for instance \texttt{\string\coordinate (mynorth) at
326 (mynode.north);}.)
327 %
328 \begin{codeexample}[]
329 \begin{tikzpicture}
330 \coordinate (content) at (90:3cm);
331 \coordinate (structure) at (210:3cm);
332 \coordinate (form) at (-30:3cm);
333
334 \node [above] at (content) {content oriented};
335 \node [below left] at (structure) {structure oriented};
336 \node [below right] at (form) {form oriented};
337
338 \draw [thick,gray] (content.south) -- (structure.north east) -- (form.north west) -- cycle;
339
340 \small
341 \node at (barycentric cs:content=0.5,structure=0.1 ,form=1) {PostScript};
342 \node at (barycentric cs:content=1 ,structure=0 ,form=0.4) {DVI};
343 \node at (barycentric cs:content=0.5,structure=0.5 ,form=1) {PDF};
344 \node at (barycentric cs:content=0 ,structure=0.25,form=1) {CSS};
345 \node at (barycentric cs:content=0.5,structure=1 ,form=0) {XML};
346 \node at (barycentric cs:content=0.5,structure=1 ,form=0.4) {HTML};
347 \node at (barycentric cs:content=1 ,structure=0.2 ,form=0.8) {\TeX};
348 \node at (barycentric cs:content=1 ,structure=0.6 ,form=0.8) {\LaTeX};
349 \node at (barycentric cs:content=0.8,structure=0.8 ,form=1) {Word};
350 \node at (barycentric cs:content=1 ,structure=0.05,form=0.05) {ASCII};
351 \end{tikzpicture}
352 \end{codeexample}
353 %
354 \end{coordinatesystem}
355
356
357 \subsubsection{Node Coordinate System}
358 \label{section-node-coordinates}
359
360 In \pgfname\ and in \tikzname\ it is quite easy to define a node that you wish
361 to reference at a later point. Once you have defined a node, there are
362 different ways of referencing points of the node. To do so, you use the
363 following coordinate system:
364
365 \begin{coordinatesystem}{node}
366 This coordinate system is used to reference a specific point inside or on
367 the border of a previously defined node. It can be used in different ways,
368 so let us go over them one by one.
369
370 You can use three options to specify which coordinate you mean:
371 %
372 \begin{key}{/tikz/cs/name=\meta{node name}}
373 Specifies the node that you wish to use to specify a coordinate. The
374 \meta{node name} is the name that was previously used to name the node
375 using the |name=|\meta{node name} option or the special node name
376 syntax.
377 \end{key}
378 %
379 \begin{key}{/tikz/anchor=\meta{anchor}}
380 Specifies an anchor of the node. Here is an example:
381 %
382 \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
383 \begin{tikzpicture}[node font=\ttfamily]
384 \node (shape) at (0,2) [draw] {class Shape};
385 \node (rect) at (-2,0) [draw] {class Rectangle};
386 \node (circle) at (2,0) [draw] {class Circle};
387 \node (ellipse) at (6,0) [draw] {class Ellipse};
388
389 \draw (node cs:name=circle,anchor=north) |- (0,1);
390 \draw (node cs:name=ellipse,anchor=north) |- (0,1);
391 \draw [arrows = -{Triangle[open, angle=60:3mm]}]
392 (node cs:name=rect,anchor=north)
393 |- (0,1) -| (node cs:name=shape,anchor=south);
394 \end{tikzpicture}
395 \end{codeexample}
396 \end{key}
397 %
398 \begin{key}{/tikz/cs/angle=\meta{degrees}}
399 It is also possible to provide an angle \emph{instead} of an anchor.
400 This coordinate refers to a point of the node's border where a ray shot
401 from the center in the given angle hits the border. Here is an example:
402 %
403 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
404 \begin{tikzpicture}
405 \node (start) [draw,shape=ellipse] {start};
406 \foreach \angle in {-90, -80, ..., 90}
407 \draw (node cs:name=start,angle=\angle)
408 .. controls +(\angle:1cm) and +(-1,0) .. (2.5,0);
409 \end{tikzpicture}
410 \end{codeexample}
411 \end{key}
412
413 It is possible to provide \emph{neither} the |anchor=| option nor the
414 |angle=| option. In this case, \tikzname\ will calculate an appropriate
415 border position for you. Here is an example:
416 %
417 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
418 \begin{tikzpicture}
419 \path (0,0) node(a) [ellipse,rotate=10,draw] {An ellipse}
420 (3,-1) node(b) [circle,draw] {A circle};
421 \draw[thick] (node cs:name=a) -- (node cs:name=b);
422 \end{tikzpicture}
423 \end{codeexample}
424
425 \tikzname\ will be reasonably clever at determining the border points that
426 you ``mean'', but, naturally, this may fail in some situations. If
427 \tikzname\ fails to determine an appropriate border point, the center will
428 be used instead.
429
430 Automatic computation of anchors works only with the line-to operations
431 |--|, the vertical/horizontal versions \verb!|-! and \verb!-|!, and with
432 the curve-to operation |..|. For other path commands, such as |parabola| or
433 |plot|, the center will be used. If this is not desired, you should give a
434 named anchor or an angle anchor.
435
436 Note that if you use an automatic coordinate for both the start and the end
437 of a line-to, as in |--(node cs:name=b)--|, then \emph{two} border
438 coordinates are computed with a move-to between them. This is usually
439 exactly what you want.
440
441 If you use relative coordinates together with automatic anchor coordinates,
442 the relative coordinates are computed relative to the node's center, not
443 relative to the border point. Here is an example:
444 %
445 \begin{codeexample}[]
446 \tikz \draw (0,0) node(x) [draw] {Text}
447 rectangle (1,1)
448 (node cs:name=x) -- +(1,1);
449 \end{codeexample}
450
451 Similarly, in the following examples both control points are $(1,1)$:
452 %
453 \begin{codeexample}[]
454 \tikz \draw (0,0) node(x) [draw] {X}
455 (2,0) node(y) {Y}
456 (node cs:name=x) .. controls +(1,1) and +(-1,1) ..
457 (node cs:name=y);
458 \end{codeexample}
459
460 The implicit way of specifying the node coordinate system is to simply use
461 the name of the node in parentheses as in |(a)| or to specify a name
462 together with an anchor or an angle separated by a dot as in |(a.north)| or
463 |(a.10)|.
464
465 Here is a more complete example:
466 %
467 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
468 \begin{tikzpicture}[fill=blue!20]
469 \draw[help lines] (-1,-2) grid (6,3);
470 \path (0,0) node(a) [ellipse,rotate=10,draw,fill] {An ellipse}
471 (3,-1) node(b) [circle,draw,fill] {A circle}
472 (2,2) node(c) [rectangle,rotate=20,draw,fill] {A rectangle}
473 (5,2) node(d) [rectangle,rotate=-30,draw,fill] {Another rectangle};
474 \draw[thick] (a.south) -- (b) -- (c) -- (d);
475 \draw[thick,red,->] (a) |- +(1,3) -| (c) |- (b);
476 \draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d);
477 \end{tikzpicture}
478 \end{codeexample}
479 %
480 \end{coordinatesystem}
481
482 % -----------------------------------------------------------------------------
483 % Deprecated:
484 % -----------------------------------------------------------------------------
485 %
486 % \subsubsection{Intersection Coordinate Systems}
487 %
488 % Often you wish to specify a point that is on the
489 % intersection of two lines or shapes. For this, the following
490 % coordinate system is useful:
491 %
492 % \begin{coordinatesystem}{intersection}
493 % First, you must specify two objects that should be
494 % intersected. These ``objects'' can either be lines or the shapes of
495 % nodes. There are two option to specify the first object:
496 % \begin{key}{/tikz/cs/first line={\ttfamily\char`\{}|(|\meta{first
497 % coordinate}|)--(|\meta{second coordinate}|)|{\ttfamily\char`\}}}
498 % Specifies that the first object is a line that goes from
499 % \meta{first coordinate} to meta{second coordinate}.
500 % \end{key}
501 % Note that you have to write |--| between the coordinate, but this
502 % does not mean that anything is added to the path. This is simply a
503 % special syntax.
504 % \begin{key}{/tikz/cs/first node=\meta{node}}
505 % Specifies that the first object is a previously defined node named
506 % \meta{node}.
507 % \end{key}
508 %
509 % To specify the second object, you use one of the following keys:
510 % \begin{key}{/tikz/cs/second line={\ttfamily\char`\{}|(|\meta{first
511 % coordinate}|)--(|\meta{second coordinate}|)|{\ttfamily\char`\}}}
512 % As above.
513 % \end{key}
514 % \begin{key}{/tikz/cs/second node=\meta{node}}
515 % Specifies that the second object is a previously defined node
516 % named \meta{node}.
517 % \end{key}
518 %
519 % Since it is possible that two objects have multiple intersections,
520 % you may need to specify which solution you want:
521 % \begin{key}{/tikz/cs/solution=\meta{number} (initially 1)}
522 % Specifies which solution should be used. Numbering starts with 1.
523 % \end{key}
524 % The coordinate specified in this way is the \meta{number}th
525 % intersection of the two objects. If the objects do not intersect,
526 % an error may occur.
527 %
528 % \begin{codeexample}[]
529 % \begin{tikzpicture}
530 % \draw[help lines] (0,0) grid (3,2);
531 % \draw (0,0) coordinate (A) -- (3,2) coordinate (B)
532 % (1,2) -- (3,0);
533 %
534 % \fill[red] (intersection cs:
535 % first line={(A)--(B)},
536 % second line={(1,2)--(3,0)}) circle (2pt);
537 % \end{tikzpicture}
538 % \end{codeexample}
539 %
540 % The implicit way of specifying this coordinate system is to write
541 % \declare{|(intersection |\opt{\meta{number}}| of |\meta{first
542 % object}%
543 % | and |\meta{second object}|)|}. Here, \meta{first object} either
544 % has the form \meta{$p_1$}|--|\meta{$p_2$} or it is just a node
545 % name. Likewise for \meta{second object}. Note that there are \emph{no}
546 % parentheses around the $p_i$. Thus, you would write
547 % |(intersection of A--B and 1,2--3,0)| for the intersection of the
548 % line through the coordinates |A| and |B| and the line through the
549 % points $(1,2)$ and $(3,0)$. You would write
550 % |(intersection 2 of c_1 and c_2)| for the second
551 % intersection of the node named |c_1| and the node named
552 % |c_2|.
553 %
554 % \tikzname\ needs an explicit algorithm for computing the
555 % intersection of two shapes and such an algorithm is available only
556 % for few shapes. Currently, the following intersection will be
557 % computed correctly:
558 % \begin{itemize}
559 % \item a line and a line
560 % \item a |circle| node and a line (in any order)
561 % \item a |circle| and a |circle|
562 % \end{itemize}
563 % \begin{codeexample}[]
564 % \begin{tikzpicture}[scale=.25]
565 % \coordinate [label=-135:$a$] (a) at ($ (0,0) + (rand,rand) $);
566 % \coordinate [label=45:$b$] (b) at ($ (3,2) + (rand,rand) $);
567 %
568 % \coordinate [label=-135:$u$] (u) at (-1,1);
569 % \coordinate [label=45:$v$] (v) at (6,0);
570 %
571 % \draw (a) -- (b)
572 % (u) -- (v);
573 %
574 % \node (c1) at (a) [draw,circle through=(b)] {};
575 % \node (c2) at (b) [draw,circle through=(a)] {};
576 %
577 % \coordinate [label=135:$c$] (c) at (intersection 2 of c1 and c2);
578 % \coordinate [label=-45:$d$] (d) at (intersection of u--v and c2);
579 % \coordinate [label=135:$e$] (e) at (intersection of u--v and a--b);
580 %
581 % \foreach \p in {a,b,c,d,e,u,v}
582 % \fill [opacity=.5] (\p) circle (8pt);
583 % \end{tikzpicture}
584 % \end{codeexample}
585 % \end{coordinatesystem}
586 % -----------------------------------------------------------------------------
587
588
589 \subsubsection{Tangent Coordinate Systems}
590
591 \begin{coordinatesystem}{tangent}
592 This coordinate system, which is available only when the \tikzname\ library
593 |calc| is loaded, allows you to compute the point that lies tangent to a
594 shape. In detail, consider a \meta{node} and a \meta{point}. Now, draw a
595 straight line from the \meta{point} so that it ``touches'' the \meta{node}
596 (more formally, so that it is \emph{tangent} to this \meta{node}). The
597 point where the line touches the shape is the point referred to by the
598 |tangent| coordinate system.
599
600 The following options may be given:
601 %
602 \begin{key}{/tikz/cs/node=\meta{node}}
603 This key specifies the node on whose border the tangent should lie.
604 \end{key}
605 %
606 \begin{key}{/tikz/cs/point=\meta{point}}
607 This key specifies the point through which the tangent should go.
608 \end{key}
609 %
610 \begin{key}{/tikz/cs/solution=\meta{number}}
611 Specifies which solution should be used if there are more than one.
612 \end{key}
613
614 A special algorithm is needed in order to compute the tangent for a given
615 shape. Currently, tangents can be computed for nodes whose shape is one of
616 the following:
617 %
618 \begin{itemize}
619 \item |coordinate|
620 \item |circle|
621 \end{itemize}
622 %
623 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
624 \begin{tikzpicture}
625 \draw[help lines] (0,0) grid (3,2);
626
627 \coordinate (a) at (3,2);
628
629 \node [circle,draw] (c) at (1,1) [minimum size=40pt] {$c$};
630
631 \draw[red] (a) -- (tangent cs:node=c,point={(a)},solution=1) --
632 (c.center) -- (tangent cs:node=c,point={(a)},solution=2) -- cycle;
633 \end{tikzpicture}
634 \end{codeexample}
635
636 There is no implicit syntax for this coordinate system.
637 \end{coordinatesystem}
638
639
640 \subsubsection{Defining New Coordinate Systems}
641
642 While the set of coordinate systems that \tikzname\ can parse via their special
643 syntax is fixed, it is possible and quite easy to define new explicitly named
644 coordinate systems. For this, the following commands are used:
645
646 \begin{command}{\tikzdeclarecoordinatesystem\marg{name}\marg{code}}
647 This command declares a new coordinate system named \meta{name} that can
648 later on be used by writing |(|\meta{name}| cs:|\meta{arguments}|)|. When
649 \tikzname\ encounters a coordinate specified in this way, the
650 \meta{arguments} are passed to \meta{code} as argument |#1|.
651
652 It is now the job of \meta{code} to make sense of the \meta{arguments}. At
653 the end of \meta{code}, the two \TeX\ dimensions |\pgf@x| and |\pgf@y|
654 should be have the $x$- and $y$-canvas coordinate of the coordinate.
655
656 It is not necessary, but customary, to parse \meta{arguments} using the
657 key--value syntax. However, you can also parse it in any way you like.
658
659 In the following example, a coordinate system |cylindrical| is defined.
660 %
661 \begin{codeexample}[]
662 \makeatletter
663 \define@key{cylindricalkeys}{angle}{\def\myangle{#1}}
664 \define@key{cylindricalkeys}{radius}{\def\myradius{#1}}
665 \define@key{cylindricalkeys}{z}{\def\myz{#1}}
666 \makeatother
667 \tikzdeclarecoordinatesystem{cylindrical}%
668 {%
669 \setkeys{cylindricalkeys}{#1}%
670 \pgfpointadd{\pgfpointxyz{0}{0}{\myz}}{\pgfpointpolarxy{\myangle}{\myradius}}
671 }
672 \begin{tikzpicture}[z=0.2pt]
673 \draw [->] (0,0,0) -- (0,0,350);
674 \foreach \num in {0,10,...,350}
675 \fill (cylindrical cs:angle=\num,radius=1,z=\num) circle (1pt);
676 \end{tikzpicture}
677 \end{codeexample}
678 %
679 \end{command}
680
681 \begin{command}{\tikzaliascoordinatesystem\marg{new name}\marg{old name}}
682 Creates an alias of \meta{old name}.
683 \end{command}
684
685
686 \subsection{Coordinates at Intersections}
687 \label{section-intersection-coordinates}
688
689 You will wish to compute the intersection of two paths. For the special and
690 frequent case of two perpendicular lines, a special coordinate system called
691 |perpendicular| is available. For more general cases, the |intersections|
692 library can be used.
693
694
695 \subsubsection{Intersections of Perpendicular Lines}
696
697 A frequent special case of path intersections is the intersection of a vertical
698 line going through a point $p$ and a horizontal line going through some other
699 point $q$. For this situation there is a useful coordinate system.
700
701 \begin{coordinatesystem}{perpendicular}
702 You can specify the two lines using the following keys:
703
704 \begin{key}{/tikz/cs/horizontal line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
705 Specifies that one line is a horizontal line that goes through the
706 given coordinate.
707 \end{key}
708 %
709 \begin{key}{/tikz/cs/vertical line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
710 Specifies that the other line is vertical and goes through the given
711 coordinate.
712 \end{key}
713
714 However, in almost all cases you should, instead, use the implicit syntax.
715 Here, you write \declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or
716 \declare{|(|\meta{q}\verb! -| !\meta{p}|)|}.
717
718 For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield the
719 same as \verb!(2,4)! (provided the $xy$-co\-or\-di\-nate system has not
720 been modified).
721
722 The most useful application of the syntax is to draw a line up to some
723 point on a vertical or horizontal line. Here is an example:
724 %
725 \begin{codeexample}[]
726 \begin{tikzpicture}
727 \path (30:1cm) node(p1) {$p_1$} (75:1cm) node(p2) {$p_2$};
728
729 \draw (-0.2,0) -- (1.2,0) node(xline)[right] {$q_1$};
730 \draw (2,-0.2) -- (2,1.2) node(yline)[above] {$q_2$};
731
732 \draw[->] (p1) -- (p1 |- xline);
733 \draw[->] (p2) -- (p2 |- xline);
734 \draw[->] (p1) -- (p1 -| yline);
735 \draw[->] (p2) -- (p2 -| yline);
736 \end{tikzpicture}
737 \end{codeexample}
738
739 Note that in \declare{|(|\meta{c}\verb! |- !\meta{d}|)|} the coordinates
740 \meta{c} and \meta{d} are \emph{not} surrounded by parentheses. If they
741 need to be complicated expressions (like a computation using the
742 |$|-syntax), you must surround them with braces; parentheses will then be %$
743 added around them.
744
745 As an example, let us specify a point that lies horizontally at the middle
746 of the line from $A$ to~$B$ and vertically at the middle of the line from
747 $C$ to~$D$:
748 %
749 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
750 \begin{tikzpicture}
751 \node (A) at (0,1) {A};
752 \node (B) at (1,1.5) {B};
753 \node (C) at (2,0) {C};
754 \node (D) at (2.5,-2) {D};
755
756 \draw (A) -- (B) node [midway] {x};
757 \draw (C) -- (D) node [midway] {x};
758
759 \node at ({$(A)!.5!(B)$} -| {$(C)!.5!(D)$}) {X};
760 \end{tikzpicture}
761 \end{codeexample}
762 %
763 \end{coordinatesystem}
764
765
766 \subsubsection{Intersections of Arbitrary Paths}
767
768 \begin{tikzlibrary}{intersections}
769 This library enables the calculation of intersections of two arbitrary
770 paths. However, due to the low accuracy of \TeX, the paths should not be
771 ``too complicated''. In particular, you should not try to intersect paths
772 consisting of lots of very small segments such as plots or decorated paths.
773 \end{tikzlibrary}
774
775 To find the intersections of two paths in \tikzname, they must be ``named''. A
776 ``named path'' is, quite simply, a path that has been named using the following
777 key (note that this is a \emph{different} key from the |name| key, which only
778 attaches a hyperlink target to a path, but does not store the path in a way that
779 is useful for the intersection computation):
780
781 \begin{keylist}{%
782 /tikz/name path=\meta{name},
783 /tikz/name path global=\meta{name}%
784 }
785 The effect of this key is that, after the path has been constructed, just
786 before it is used, it is associated with \meta{name}. For |name path|, this
787 association survives beyond the final semi-colon of the path but not the
788 end of the surrounding scope. For |name path global|, the association will
789 survive beyond any scope as well. Handle with care.
790
791 Any paths created by nodes on the (main) path are ignored, unless this key
792 is explicitly used. If the same \meta{name} is used for the main path and
793 the node path(s), then the paths will be added together and then associated
794 with \meta{name}.
795 \end{keylist}
796
797 To find the intersection of named paths, the following key is used:
798
799 \begin{key}{/tikz/name intersections=\marg{options}}
800 This key changes the key path to |/tikz/intersection| and processes
801 \meta{options}. These options determine, among other things, which paths to
802 use for the intersection. Having processed the options, any intersections
803 are then found. A coordinate is created at each intersection, which by
804 default, will be named |intersection-1|, |intersection-2|, and so on.
805 Optionally, the prefix |intersection| can be changed, and the total number
806 of intersections stored in a \TeX-macro.
807 %
808 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
809 \begin{tikzpicture}[every node/.style={opacity=1, black, above left}]
810 \draw [help lines] grid (3,2);
811 \draw [name path=ellipse] (2,0.5) ellipse (0.75cm and 1cm);
812 \draw [name path=rectangle, rotate=10] (0.5,0.5) rectangle +(2,1);
813 \fill [red, opacity=0.5, name intersections={of=ellipse and rectangle}]
814 (intersection-1) circle (2pt) node {1}
815 (intersection-2) circle (2pt) node {2};
816 \end{tikzpicture}
817 \end{codeexample}
818
819 The following keys can be used in \meta{options}:
820
821 \begin{key}{/tikz/intersection/of=\meta{name path 1}| and |\meta{name path 2}}
822 This key is used to specify the names of the paths to use for the
823 intersection.
824 \end{key}
825
826 \begin{key}{/tikz/intersection/name=\meta{prefix} (initially intersection)}
827 This key specifies the prefix name for the coordinate nodes placed at
828 each intersection.
829 \end{key}
830
831 \begin{key}{/tikz/intersection/total=\meta{macro}}
832 This key means that the total number of intersections found will be
833 stored in \meta{macro}.
834 \end{key}
835
836 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
837 \begin{tikzpicture}
838 \clip (-2,-2) rectangle (2,2);
839 \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1);
840 \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2);
841
842 \fill [name intersections={of=curve 1 and curve 2, name=i, total=\t}]
843 [red, opacity=0.5, every node/.style={above left, black, opacity=1}]
844 \foreach \s in {1,...,\t}{(i-\s) circle (2pt) node {\footnotesize\s}};
845 \end{tikzpicture}
846 \end{codeexample}
847
848 \begin{key}{/tikz/intersection/by=\meta{comma-separated list}}
849 This key allows you to specify a list of names for the intersection
850 coordinates. The intersection coordinates will still be named
851 \meta{prefix}|-|\meta{number}, but additionally the first coordinate
852 will also be named by the first element of the \meta{comma-separated
853 list}. What happens is that the \meta{comma-separated list} is passed
854 to the |\foreach| statement and for \meta{list member} a coordinate is
855 created at the already-named intersection.
856 %
857 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
858 \begin{tikzpicture}
859 \clip (-2,-2) rectangle (2,2);
860 \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1);
861 \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2);
862
863 \fill [name intersections={of=curve 1 and curve 2, by={a,b}}]
864 (a) circle (2pt)
865 (b) circle (2pt);
866 \end{tikzpicture}
867 \end{codeexample}
868
869 You can also use the |...| notation of the |\foreach| statement inside
870 the \meta{comma-separated list}.
871
872 In case an element of the \meta{comma-separated list} starts with
873 options in square brackets, these options are used when the coordinate
874 is created. A coordinate name can still, but need not, follow the
875 options. This makes it easy to add labels to intersections:
876 %
877 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
878 \begin{tikzpicture}
879 \clip (-2,-2) rectangle (2,2);
880 \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1);
881 \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2);
882
883 \fill [name intersections={
884 of=curve 1 and curve 2,
885 by={[label=center:a],[label=center:...],[label=center:i]}}];
886 \end{tikzpicture}
887 \end{codeexample}
888 \end{key}
889
890 \begin{key}{/tikz/intersection/sort by=\meta{path name}}
891 By default, the intersections are simply returned in the order that the
892 intersection algorithm finds them. Unfortunately, this is not
893 necessarily a ``helpful'' ordering. This key can be used to sort the
894 intersections along the path specified by \meta{path name}, which
895 should be one of the paths mentioned in the |/tikz/intersection/of|
896 key.
897 %
898 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
899 \begin{tikzpicture}
900 \clip (-0.5,-0.75) rectangle (3.25,2.25);
901 \foreach \pathname/\shift in {line/0cm, curve/2cm}{
902 \tikzset{xshift=\shift}
903 \draw [->, name path=curve] (1,1.5) .. controls (-1,1) and (2,0.5) .. (0,0);
904 \draw [->, name path=line] (0,-.5) -- (1,2) ;
905 \fill [name intersections={of=line and curve,sort by=\pathname, name=i}]
906 [red, opacity=0.5, every node/.style={left=.25cm, black, opacity=1}]
907 \foreach \s in {1,2,3}{(i-\s) circle (2pt) node {\footnotesize\s}};
908 }
909 \end{tikzpicture}
910 \end{codeexample}
911 \end{key}
912 \end{key}
913
914
915 \subsection{Relative and Incremental Coordinates}
916
917 \subsubsection{Specifying Relative Coordinates}
918
919 You can prefix coordinates by |++| to make them ``relative''. A coordinate such
920 as |++(1cm,0pt)| means ``1cm to the right of the previous position, making this
921 the new current position''. Relative coordinates are often useful in ``local''
922 contexts:
923 %
924 \begin{codeexample}[]
925 \begin{tikzpicture}
926 \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
927 \draw (2,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
928 \draw (1.5,1.5) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
929 \end{tikzpicture}
930 \end{codeexample}
931
932 Instead of |++| you can also use a single |+|. This also specifies a relative
933 coordinate, but it does not ``update'' the current point for subsequent usages
934 of relative coordinates. Thus, you can use this notation to specify numerous
935 points, all relative to the same ``initial'' point:
936
937 \begin{codeexample}[]
938 \begin{tikzpicture}
939 \draw (0,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
940 \draw (2,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
941 \draw (1.5,1.5) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
942 \end{tikzpicture}
943 \end{codeexample}
944
945 There is a special situation, where relative coordinates are interpreted
946 differently. If you use a relative coordinate as a control point of a Bézier
947 curve, the following rule applies: First, a relative first control point is
948 taken relative to the beginning of the curve. Second, a relative second control
949 point is taken relative to the end of the curve. Third, a relative end point of
950 a curve is taken relative to the start of the curve.
951
952 This special behavior makes it easy to specify that a curve should ``leave or
953 arrive from a certain direction'' at the start or end. In the following
954 example, the curve ``leaves'' at $30^\circ$ and ``arrives'' at $60^\circ$:
955 %
956 \begin{codeexample}[]
957 \begin{tikzpicture}
958 \draw (1,0) .. controls +(30:1cm) and +(60:1cm) .. (3,-1);
959 \draw[gray,->] (1,0) -- +(30:1cm);
960 \draw[gray,<-] (3,-1) -- +(60:1cm);
961 \end{tikzpicture}
962 \end{codeexample}
963
964
965 \subsubsection{Rotational Relative Coordinates}
966
967 You may sometimes wish to specify points relative not only to the previous
968 point, but additionally relative to the tangent entering the previous point.
969 For this, the following key is useful:
970
971 \begin{key}{/tikz/turn}
972 This key can be given as an option to a \meta{coordinate} as in the
973 following example:
974 %
975 \begin{codeexample}[]
976 \tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm);
977 \end{codeexample}
978 %
979 The effect of this key is to locally shift the coordinate system so that
980 the last point reached is at the origin and the coordinate system is
981 ``turned'' so that the $x$-axis points in the direction of a tangent
982 entering the last point. This means, in effect, that when you use polar
983 coordinates of the form \meta{relative angle}|:|\meta{distance} together
984 with the |turn| option, you specify a point that lies at \meta{distance}
985 from the last point in the direction of the last tangent entering the last
986 point, but with a rotation of \meta{relative angle}.
987
988 This key also works with curves \dots
989 %
990 \begin{codeexample}[]
991 \tikz [delta angle=30, radius=1cm]
992 \draw (0,0) arc [start angle=0] -- ([turn]0:1cm)
993 arc [start angle=30] -- ([turn]0:1cm)
994 arc [start angle=60] -- ([turn]30:1cm);
995 \end{codeexample}
996 \begin{codeexample}[]
997 \tikz \draw (0,0) to [bend left] (2,1) -- ([turn]0:1cm);
998 \end{codeexample}
999 %
1000 \dots and with plots \dots
1001 %
1002 \begin{codeexample}[]
1003 \tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,0) } -- ([turn]30:1cm);
1004 \end{codeexample}
1005
1006 Although the above examples use polar coordinates with |turn|, you can also
1007 use any normal coordinate. For instance, |([turn]1,1)| will append a line
1008 of length $\sqrt 2$ that is turns by $45^\circ$ relative to the tangent to
1009 the last point.
1010 %
1011 \begin{codeexample}[]
1012 \tikz \draw (0.5,0.5) -| (2,1) -- ([turn]1,1)
1013 .. controls ([turn]0:1cm) .. ([turn]-90:1cm);
1014 \end{codeexample}
1015 %
1016 \end{key}
1017
1018
1019 \subsubsection{Relative Coordinates and Scopes}
1020 \label{section-scopes-relative}
1021
1022 An interesting question is, how do relative coordinates behave in the presence
1023 of scopes? That is, suppose we use curly braces in a path to make part of it
1024 ``local'', how does that affect the current position? On the one hand, the
1025 current position certainly changes since the scope only affects options, not
1026 the path itself. On the other hand, it may be useful to ``temporarily escape''
1027 from the updating of the current point.
1028
1029 Since both interpretations of how the current point and scopes should
1030 ``interact'' are useful, there is a (local!) option that allows you to decide
1031 which you need.
1032
1033 \begin{key}{/tikz/current point is local=\opt{\meta{boolean}} (initially false)}
1034 Normally, the scope path operation has no effect on the current point. That
1035 is, curly braces on a path have no effect on the current position:
1036 %
1037 \begin{codeexample}[]
1038 \begin{tikzpicture}
1039 \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
1040 \draw[red] (2,0) -- ++(1,0) { -- ++(0,1) } -- ++(-1,0);
1041 \end{tikzpicture}
1042 \end{codeexample}
1043 %
1044 If you set this key to |true|, this behavior changes. In this case, at the
1045 end of a group created on a path, the last current position reverts to
1046 whatever value it had at the beginning of the scope. More precisely, when
1047 \tikzname\ encounters |}| on a path, it checks whether at this particular
1048 moment the key is set to |true|. If so, the current position reverts to the
1049 value it had when the matching |{| was read.
1050 %
1051 \begin{codeexample}[]
1052 \begin{tikzpicture}
1053 \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
1054 \draw[red] (2,0) -- ++(1,0)
1055 { [current point is local] -- ++(0,1) } -- ++(-1,0);
1056 \end{tikzpicture}
1057 \end{codeexample}
1058 %
1059 In the above example, we could also have given the option outside the
1060 scope, for instance as a parameter to the whole scope.
1061 \end{key}
1062
1063
1064 \subsection{Coordinate Calculations}
1065 \label{tikz-lib-calc}
1066
1067 \begin{tikzlibrary}{calc}
1068 You need to load this library in order to use the coordinate calculation
1069 functions described in the present section.
1070 \end{tikzlibrary}
1071
1072 It is possible to do some basic calculations that involve coordinates. In
1073 essence, you can add and subtract coordinates, scale them, compute midpoints,
1074 and do projections. For instance, |($(a) + 1/3*(1cm,0)$)| is the coordinate
1075 that is $1/3 \text{cm}$ to the right of the point |a|:
1076 %
1077 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1078 \begin{tikzpicture}
1079 \draw [help lines] (0,0) grid (3,2);
1080
1081 \node (a) at (1,1) {A};
1082 \fill [red] ($(a) + 1/3*(1cm,0)$) circle (2pt);
1083 \end{tikzpicture}
1084 \end{codeexample}
1085
1086
1087 \subsubsection{The General Syntax}
1088
1089 The general syntax is the following:
1090 %
1091 \begin{quote}
1092 \declare{|(|\opt{|[|\meta{options}|]|}|$|\meta{coordinate computation}|$)|}.
1093 \end{quote}
1094
1095 As you can see, the syntax uses the \TeX\ math symbol |$| to %$
1096 indicate that a ``mathematical computation'' is involved. However, the |$| %$
1097 has no other effect, in particular, no mathematical text is typeset.
1098
1099 The \meta{coordinate computation} has the following structure:
1100 %
1101 \begin{enumerate}
1102 \item It starts with
1103 %
1104 \begin{quote}
1105 \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
1106 \end{quote}
1107 \item This is optionally followed by |+| or |-| and then another
1108 %
1109 \begin{quote}
1110 \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
1111 \end{quote}
1112 \item This is once more followed by |+| or |-| and another of the above
1113 modified coordinate; and so on.
1114 \end{enumerate}
1115
1116 In the following, the syntax of factors and of the different modifiers
1117 is explained in detail.
1118
1119
1120 \subsubsection{The Syntax of Factors}
1121
1122 The \meta{factor}s are optional and detected by checking whether the
1123 \meta{coordinate computation} starts with a |(|. Also, after each $\pm$ a
1124 \meta{factor} is present if, and only if, the |+| or |-| sign is not directly
1125 followed by~|(|.
1126
1127 If a \meta{factor} is present, it is evaluated using the |\pgfmathparse| macro.
1128 This means that you can use pretty complicated computations inside a factor. A
1129 \meta{factor} may even contain opening parentheses, which creates a
1130 complication: How does \tikzname\ know where a \meta{factor} ends and where a
1131 coordinate starts? For instance, if the beginning of a \meta{coordinate
1132 computation} is |2*(3+4|\dots, it is not clear whether |3+4| is part of a
1133 \meta{coordinate} or part of a \meta{factor}. Because of this, the following
1134 rule is used: Once it has been determined, that a \meta{factor} is present, in
1135 principle, the \meta{factor} contains everything up to the next occurrence of
1136 |*(|. Note that there is no space between the asterisk and the parenthesis.
1137
1138 It is permissible to put the \meta{factor} in curly braces. This can be used
1139 whenever it is unclear where the \meta{factor} would end.
1140
1141 Here are some examples of coordinate specifications that consist of exactly one
1142 \meta{factor} and one \meta{coordinate}:
1143 %
1144 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1145 \begin{tikzpicture}
1146 \draw [help lines] (0,0) grid (3,2);
1147
1148 \fill [red] ($2*(1,1)$) circle (2pt);
1149 \fill [green] (${1+1}*(1,.5)$) circle (2pt);
1150 \fill [blue] ($cos(0)*sin(90)*(1,1)$) circle (2pt);
1151 \fill [black] (${3*(4-3)}*(1,0.5)$) circle (2pt);
1152 \end{tikzpicture}
1153 \end{codeexample}
1154
1155
1156 \subsubsection{The Syntax of Partway Modifiers}
1157
1158 A \meta{coordinate} can be followed by different \meta{modifiers}. The first
1159 kind of modifier is the \emph{partway modifier}. The syntax (which is loosely
1160 inspired by Uwe Kern's |xcolor| package) is the following:
1161 %
1162 \begin{quote}
1163 \meta{coordinate}\declare{|!|\meta{number}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
1164 \end{quote}
1165 %
1166 One could write for instance
1167 %
1168 \begin{codeexample}[code only]
1169 (1,2)!.75!(3,4)
1170 \end{codeexample}
1171 %
1172 The meaning of this is: ``Use the coordinate that is three quarters on the way
1173 from |(1,2)| to |(3,4)|.'' In general, \meta{coordinate
1174 x}|!|\meta{number}|!|\meta{coordinate y} yields the coordinate $(1 -
1175 \meta{number})\meta{coordinate x} + \meta{number} \meta{coordinate y}$. Note
1176 that this is a bit different from the way the \meta{number} is interpreted in
1177 the |xcolor| package: First, you use a factor between $0$ and $1$, not a
1178 percentage, and, second, as the \meta{number} approaches $1$, we approach the
1179 second coordinate, not the first. It is permissible to use a \meta{number} that
1180 is smaller than $0$ or larger than $1$. The \meta{number} is evaluated using
1181 the |\pgfmathparse| command and, thus, it can involve complicated computations.
1182 %
1183 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1184 \begin{tikzpicture}
1185 \draw [help lines] (0,0) grid (3,2);
1186
1187 \draw (1,0) -- (3,2);
1188
1189 \foreach \i in {0,0.2,0.5,0.9,1}
1190 \node at ($(1,0)!\i!(3,2)$) {\i};
1191 \end{tikzpicture}
1192 \end{codeexample}
1193
1194 The \meta{second coordinate} may be prefixed by an \meta{angle}, separated with
1195 a colon, as in |(1,1)!.5!60:(2,2)|. The general meaning of
1196 \meta{a}|!|\meta{factor}|!|\meta{angle}|:|\meta{b} is: ``First, consider the
1197 line from \meta{a} to \meta{b}. Then rotate this line by \meta{angle}
1198 \emph{around the point \meta{a}}. Then the two endpoints of this line will be
1199 \meta{a} and some point \meta{c}. Use this point \meta{c} for the subsequent
1200 computation, namely the partway computation.''
1201
1202 Here are two examples:
1203 %
1204 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1205 \begin{tikzpicture}
1206 \draw [help lines] (0,0) grid (3,3);
1207
1208 \coordinate (a) at (1,0);
1209 \coordinate (b) at (3,2);
1210
1211 \draw[->] (a) -- (b);
1212
1213 \coordinate (c) at ($ (a)!1! 10:(b) $);
1214
1215 \draw[->,red] (a) -- (c);
1216
1217 \fill ($ (a)!.5! 10:(b) $) circle (2pt);
1218 \end{tikzpicture}
1219 \end{codeexample}
1220
1221 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1222 \begin{tikzpicture}
1223 \draw [help lines] (0,0) grid (4,4);
1224
1225 \foreach \i in {0,0.125,...,2}
1226 \fill ($(2,2) !\i! \i*180:(3,2)$) circle (2pt);
1227 \end{tikzpicture}
1228 \end{codeexample}
1229
1230 You can repeatedly apply modifiers. That is, after any modifier you can add
1231 another (possibly different) modifier.
1232 %
1233 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1234 \begin{tikzpicture}
1235 \draw [help lines] (0,0) grid (3,2);
1236
1237 \draw (0,0) -- (3,2);
1238 \draw[red] ($(0,0)!.3!(3,2)$) -- (3,0);
1239 \fill[red] ($(0,0)!.3!(3,2)!.7!(3,0)$) circle (2pt);
1240 \end{tikzpicture}
1241 \end{codeexample}
1242
1243
1244 \subsubsection{The Syntax of Distance Modifiers}
1245
1246 A \emph{distance modifier} has nearly the same syntax as a partway modifier,
1247 only you use a \meta{dimension} (something like |1cm|) instead of a
1248 \meta{factor} (something like |0.5|):
1249 %
1250 \begin{quote}
1251 \meta{coordinate}\declare{|!|\meta{dimension}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
1252 \end{quote}
1253
1254 When you write \meta{a}|!|\meta{dimension}|!|\meta{b}, this means the
1255 following: Use the point that is distanced \meta{dimension} from \meta{a} on
1256 the straight line from \meta{a} to \meta{b}. Here is an example:
1257 %
1258 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1259 \begin{tikzpicture}
1260 \draw [help lines] (0,0) grid (3,2);
1261
1262 \draw (1,0) -- (3,2);
1263
1264 \foreach \i in {0cm,1cm,15mm}
1265 \node at ($(1,0)!\i!(3,2)$) {\i};
1266 \end{tikzpicture}
1267 \end{codeexample}
1268
1269 As before, if you use a \meta{angle}, the \meta{second coordinate} is rotated
1270 by this much around the \meta{coordinate} before it is used.
1271
1272 The combination of an \meta{angle} of |90| degrees with a distance can be used
1273 to ``offset'' a point relative to a line. Suppose, for instance, that you have
1274 computed a point |(c)| that lies somewhere on a line from |(a)| to~|(b)| and
1275 you now wish to offset this point by |1cm| so that the distance from this
1276 offset point to the line is |1cm|. This can be achieved as follows:
1277 %
1278 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1279 \begin{tikzpicture}
1280 \draw [help lines] (0,0) grid (3,2);
1281
1282 \coordinate (a) at (1,0);
1283 \coordinate (b) at (3,1);
1284
1285 \draw (a) -- (b);
1286
1287 \coordinate (c) at ($ (a)!.25!(b) $);
1288 \coordinate (d) at ($ (c)!1cm!90:(b) $);
1289
1290 \draw [<->] (c) -- (d) node [sloped,midway,above] {1cm};
1291 \end{tikzpicture}
1292 \end{codeexample}
1293
1294
1295 \subsubsection{The Syntax of Projection Modifiers}
1296
1297 The projection modifier is also similar to the above modifiers: It also gives a
1298 point on a line from the \meta{coordinate} to the \meta{second coordinate}.
1299 However, the \meta{number} or \meta{dimension} is replaced by a
1300 \meta{projection coordinate}:
1301 %
1302 \begin{quote}
1303 \meta{coordinate}\declare{|!|\meta{projection coordinate}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
1304 \end{quote}
1305
1306 Here is an example:
1307 %
1308 \begin{codeexample}[code only]
1309 (1,2)!(0,5)!(3,4)
1310 \end{codeexample}
1311
1312 The effect is the following: We project the \meta{projection coordinate}
1313 orthogonally onto the line from \meta{coordinate} to \meta{second coordinate}.
1314 This makes it easy to compute projected points:
1315 %
1316 \begin{codeexample}[preamble={\usetikzlibrary{calc}}]
1317 \begin{tikzpicture}
1318 \draw [help lines] (0,0) grid (3,2);
1319
1320 \coordinate (a) at (0,1);
1321 \coordinate (b) at (3,2);
1322 \coordinate (c) at (2.5,0);
1323
1324 \draw (a) -- (b) -- (c) -- cycle;
1325
1326 \draw[red] (a) -- ($(b)!(a)!(c)$);
1327 \draw[orange] (b) -- ($(a)!(b)!(c)$);
1328 \draw[blue] (c) -- ($(a)!(c)!(b)$);
1329 \end{tikzpicture}
1330 \end{codeexample}