Debian Codegraph @

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

raw
1 % Copyright 2018 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{Transformations}
12
13 \pgfname\ has a powerful transformation mechanism that is similar to the
14 transformation capabilities of \textsc{metafont}. The present section explains
15 how you can access it in \tikzname.
16
17
18 \subsection{The Different Coordinate Systems}
19
20 It is a long process from a coordinate like, say, $(1,2)$ or
21 $(1\mathrm{cm},5\mathrm{pt})$, to the position a point is finally placed on the
22 display or paper. In order to find out where the point should go, it is
23 constantly ``transformed'', which means that it is mostly shifted around and
24 possibly rotated, slanted, scaled, and otherwise mutilated.
25
26 In detail, (at least) the following transformations are applied to a coordinate
27 like $(1,2)$ before a point on the screen is chosen:
28 %
29 \begin{enumerate}
30 \item \pgfname\ interprets a coordinate like $(1,2)$ in its
31 $xy$-coordinate system as ``add the current $x$-vector once and the
32 current $y$-vector twice to obtain the new point''.
33 \item \pgfname\ applies its coordinate transformation matrix to the
34 resulting coordinate. This yields the final position of the point
35 inside the picture.
36 \item The backend driver (like |dvips| or |pdftex|) adds transformation
37 commands such that the coordinate is shifted to the correct position in
38 \TeX's page coordinate system.
39 \item \textsc{pdf} (or PostScript) apply the canvas transformation matrix
40 to the point, which can once more change the position on the page.
41 \item The viewer application or the printer applies the device
42 transformation matrix to transform the coordinate to its final pixel
43 coordinate on the screen or paper.
44 \end{enumerate}
45
46 In reality, the process is even more involved, but the above should give the
47 idea: A point is constantly transformed by changes of the coordinate system.
48
49 In \tikzname, you only have access to the first two coordinate systems: The
50 $xy$-coordinate system and the coordinate transformation matrix (these will be
51 explained later). \pgfname\ also allows you to change the canvas transformation
52 matrix, but you have to use commands of the core layer directly to do so and
53 you ``better know what you are doing'' when you do this. The moment you start
54 modifying the canvas matrix, \pgfname\ immediately loses track of all
55 coordinates and shapes, anchors, and bounding box computations will no longer
56 work.
57
58
59 \subsection{The XY- and XYZ-Coordinate Systems}
60 \label{section-xyz}
61
62 The first and easiest coordinate systems are \pgfname's $xy$- and
63 $xyz$-coordinate systems. The idea is very simple: Whenever you specify a
64 coordinate like |(2,3)| this means $2v_x + 3v_y$, where $v_x$ is the current
65 \emph{$x$-vector} and $v_y$ is the current \emph{$y$-vector}. Similarly, the
66 coordinate |(1,2,3)| means $v_x + 2v_y + 3v_z$.
67
68 Unlike other packages, \pgfname\ does not insist that $v_x$ actually has a
69 $y$-component of $0$, that is, that it is a horizontal vector. Instead, the
70 $x$-vector can point anywhere you want. Naturally, \emph{normally} you will
71 want the $x$-vector to point horizontally.
72
73 One undesirable effect of this flexibility is that it is not possible to
74 provide mixed coordinates as in $(1,2\mathrm{pt})$. Life is hard.
75
76 To change the $x$-, $y$-, and $z$-vectors, you can use the following options:
77
78 \begin{key}{/tikz/x=\meta{value} (initially 1cm)}
79 If \meta{value} is a dimension, the $x$-vector of \pgfname's
80 $xyz$-coordinate system is set up to point \meta{value} to the right, that
81 is, to $(\meta{value},0pt)$.
82 %
83 \begin{codeexample}[]
84 \begin{tikzpicture}
85 \draw (0,0) -- +(1,0);
86 \draw[x=2cm,color=red] (0,0.1) -- +(1,0);
87 \end{tikzpicture}
88 \end{codeexample}
89
90 \begin{codeexample}[]
91 \tikz \draw[x=1.5cm] (0,0) grid (2,2);
92 \end{codeexample}
93
94 The last example shows that the size of steppings in grids, just like all
95 other dimensions, are not affected by the $x$-vector. After all, the
96 $x$-vector is only used to determine the coordinate of the upper right
97 corner of the grid.
98
99 If \meta{value} is a coordinate, the $x$-vector of \pgfname's
100 $xyz$-coordinate system is set to the specified coordinate. If \meta{value}
101 contains a comma, it must be put in braces.
102 %
103 \begin{codeexample}[]
104 \begin{tikzpicture}
105 \draw (0,0) -- (1,0);
106 \draw[x={(2cm,0.5cm)},color=red] (0,0) -- (1,0);
107 \end{tikzpicture}
108 \end{codeexample}
109
110 You can use this, for example, to exchange the meaning of the $x$- and
111 $y$-coordinate.
112 %
113 \begin{codeexample}[]
114 \begin{tikzpicture}[smooth]
115 \draw plot coordinates{(1,0) (2,0.5) (3,0) (3,1)};
116 \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red]
117 plot coordinates{(1,0) (2,0.5) (3,0) (3,1)};
118 \end{tikzpicture}
119 \end{codeexample}
120 %
121 \end{key}
122
123 \begin{key}{/tikz/y=\meta{value} (initially 1cm)}
124 Works like the |x=| option, only if \meta{value} is a dimension, the
125 resulting vector points to $(0,\meta{value})$.
126 \end{key}
127
128 \begin{key}{/tikz/z=\meta{value} (initially \normalfont$-3.85$mm)}
129 Works like the |y=| option, but now a dimension is the point
130 $(\meta{value},\meta{value})$.
131 %
132 \begin{codeexample}[]
133 \begin{tikzpicture}[z=-1cm,->,thick]
134 \draw[color=red] (0,0,0) -- (1,0,0);
135 \draw[color=blue] (0,0,0) -- (0,1,0);
136 \draw[color=orange] (0,0,0) -- (0,0,1);
137 \end{tikzpicture}
138 \end{codeexample}
139 %
140 \end{key}
141
142
143 \subsection{Coordinate Transformations}
144
145 \pgfname\ and \tikzname\ allow you to specify \emph{coordinate
146 transformations}. Whenever you specify a coordinate as in |(1,0)| or
147 |(1cm,1pt)| or |(30:2cm)|, this coordinate is first ``reduced'' to a position
148 of the form ``$x$ points to the right and $y$ points upwards''. For example,
149 |(1in,5pt)| is reduced to ``$72\frac{27}{100}$ points to the right and 5 points
150 upwards'' and |(90:100pt)| means ``0pt to the right and 100 points upwards''.
151
152 The next step is to apply the current \emph{coordinate transformation matrix}
153 to the coordinate. For example, the coordinate transformation matrix might
154 currently be set such that it adds a certain constant to the $x$ value. Also,
155 it might be set up such that it, say, exchanges the $x$ and $y$ value. In
156 general, any ``standard'' transformation like translation, rotation, slanting,
157 or scaling or any combination thereof is possible. (Internally, \pgfname\ keeps
158 track of a coordinate transformation matrix very much like the concatenation
159 matrix used by \textsc{pdf} or PostScript.)
160 %
161 \begin{codeexample}[]
162 \begin{tikzpicture}
163 \draw[help lines] (0,0) grid (3,2);
164 \draw (0,0) rectangle (1,0.5);
165 \begin{scope}[xshift=1cm]
166 \draw [red] (0,0) rectangle (1,0.5);
167 \draw[yshift=1cm] [blue] (0,0) rectangle (1,0.5);
168 \draw[rotate=30] [orange] (0,0) rectangle (1,0.5);
169 \end{scope}
170 \end{tikzpicture}
171 \end{codeexample}
172
173 The most important aspect of the coordinate transformation matrix is \emph{that
174 it applies to coordinates only!} In particular, the coordinate transformation
175 has no effect on things like the line width or the dash pattern or the shading
176 angle. In certain cases, it is not immediately clear whether the coordinate
177 transformation matrix \emph{should} apply to a certain dimension. For example,
178 should the coordinate transformation matrix apply to grids? (It does.) And what
179 about the size of arced corners? (It does not.) The general rule is: ``If there
180 is no `coordinate' involved, even `indirectly', the matrix is not applied.''.
181 However, sometimes, you simply have to try or look it up in the documentation
182 whether the matrix will be applied.
183
184 Setting the matrix cannot be done directly. Rather, all you can do is to
185 ``add'' another transformation to the current matrix. However, all
186 transformations are local to the current \TeX-group. All transformations are
187 added using graphic options, which are described below.
188
189 Transformations apply immediately when they are encountered ``in the middle of
190 a path'' and they apply only to the coordinates on the path following the
191 transformation option.
192 %
193 \begin{codeexample}[]
194 \tikz \draw (0,0) rectangle (1,0.5) [xshift=2cm] (0,0) rectangle (1,0.5);
195 \end{codeexample}
196
197 A final word of warning: You should refrain from using ``aggressive''
198 transformations like a scaling of a factor of 10\,000. The reason is that all
199 transformations are done using \TeX, which has a fairly low accuracy.
200 Furthermore, in certain situations it is necessary that \tikzname\
201 \emph{inverts} the current transformation matrix and this will fail if the
202 transformation matrix is badly conditioned or even singular (if you do not know
203 what singular matrices are, you are blessed).
204
205 \begin{key}{/tikz/shift={\ttfamily\char`\{}\meta{coordinate}{\ttfamily\char`\}}}
206 Adds the \meta{coordinate} to all coordinates.
207 %
208 \begin{codeexample}[]
209 \begin{tikzpicture}
210 \draw[help lines] (0,0) grid (3,2);
211 \draw (0,0) -- (1,1) -- (1,0);
212 \draw[shift={(1,1)},blue] (0,0) -- (1,1) -- (1,0);
213 \draw[shift={(30:1cm)},red] (0,0) -- (1,1) -- (1,0);
214 \end{tikzpicture}
215 \end{codeexample}
216 %
217 \end{key}
218
219 \begin{key}{/tikz/shift only}
220 This option does not take any parameter. Its effect is to cancel all
221 current transformations except for the shifting. This means that the origin
222 will remain where it is, but any rotation around the origin or scaling
223 relative to the origin or skewing will no longer have an effect.
224
225 This option is useful in situations where a complicated transformation is
226 used to ``get to a position'', but you then wish to draw something
227 ``normal'' at this position.
228 %
229 \begin{codeexample}[]
230 \begin{tikzpicture}
231 \draw[help lines] (0,0) grid (3,2);
232 \draw (0,0) -- (1,1) -- (1,0);
233 \draw[rotate=30,xshift=2cm,blue] (0,0) -- (1,1) -- (1,0);
234 \draw[rotate=30,xshift=2cm,shift only,red] (0,0) -- (1,1) -- (1,0);
235 \end{tikzpicture}
236 \end{codeexample}
237 %
238 \end{key}
239
240 \begin{key}{/tikz/xshift=\meta{dimension}}
241 Adds \meta{dimension} to the $x$ value of all coordinates.
242 %
243 \begin{codeexample}[]
244 \begin{tikzpicture}
245 \draw[help lines] (0,0) grid (3,2);
246 \draw (0,0) -- (1,1) -- (1,0);
247 \draw[xshift=2cm,blue] (0,0) -- (1,1) -- (1,0);
248 \draw[xshift=-10pt,red] (0,0) -- (1,1) -- (1,0);
249 \end{tikzpicture}
250 \end{codeexample}
251 %
252 \end{key}
253
254 \begin{key}{/tikz/yshift=\meta{dimension}}
255 Adds \meta{dimension} to the $y$ value of all coordinates.
256 \end{key}
257
258 \begin{key}{/tikz/scale=\meta{factor}}
259 Multiplies all coordinates by the given \meta{factor}. The \meta{factor}
260 should not be excessively large in absolute terms or very close to zero.
261 %
262 \begin{codeexample}[]
263 \begin{tikzpicture}
264 \draw[help lines] (0,0) grid (3,2);
265 \draw (0,0) -- (1,1) -- (1,0);
266 \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0);
267 \draw[scale=-1,red] (0,0) -- (1,1) -- (1,0);
268 \end{tikzpicture}
269 \end{codeexample}
270 %
271 \end{key}
272
273 \begin{key}{/tikz/scale around={\ttfamily\char`\{}\meta{factor}|:|\meta{coordinate}{\ttfamily\char`\}}}
274 Scales the coordinate system by \meta{factor}, with the ``origin of
275 scaling'' centered on \meta{coordinate} rather than the origin.
276 %
277 \begin{codeexample}[]
278 \begin{tikzpicture}
279 \draw[help lines] (0,0) grid (3,2);
280 \draw (0,0) -- (1,1) -- (1,0);
281 \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0);
282 \draw[scale around={2:(1,1)},red] (0,0) -- (1,1) -- (1,0);
283 \end{tikzpicture}
284 \end{codeexample}
285 %
286 \end{key}
287
288 \begin{key}{/tikz/xscale=\meta{factor}}
289 Multiplies only the $x$-value of all coordinates by the given
290 \meta{factor}.
291 \begin{codeexample}[]
292 \begin{tikzpicture}
293 \draw[help lines] (0,0) grid (3,2);
294 \draw (0,0) -- (1,1) -- (1,0);
295 \draw[xscale=2,blue] (0,0) -- (1,1) -- (1,0);
296 \draw[xscale=-1,red] (0,0) -- (1,1) -- (1,0);
297 \end{tikzpicture}
298 \end{codeexample}
299 %
300 \end{key}
301
302 \begin{key}{/tikz/yscale=\meta{factor}}
303 Multiplies only the $y$-value of all coordinates by \meta{factor}.
304 \end{key}
305
306 \begin{key}{/tikz/xslant=\meta{factor}}
307 Slants the coordinate horizontally by the given \meta{factor}:
308 %
309 \begin{codeexample}[]
310 \begin{tikzpicture}
311 \draw[help lines] (0,0) grid (3,2);
312 \draw (0,0) -- (1,1) -- (1,0);
313 \draw[xslant=2,blue] (0,0) -- (1,1) -- (1,0);
314 \draw[xslant=-1,red] (0,0) -- (1,1) -- (1,0);
315 \end{tikzpicture}
316 \end{codeexample}
317 %
318 \end{key}
319
320 \begin{key}{/tikz/yslant=\meta{factor}}
321 Slants the coordinate vertically by the given \meta{factor}:
322 %
323 \begin{codeexample}[]
324 \begin{tikzpicture}
325 \draw[help lines] (0,0) grid (3,2);
326 \draw (0,0) -- (1,1) -- (1,0);
327 \draw[yslant=2,blue] (0,0) -- (1,1) -- (1,0);
328 \draw[yslant=-1,red] (0,0) -- (1,1) -- (1,0);
329 \end{tikzpicture}
330 \end{codeexample}
331 %
332 \end{key}
333
334 \begin{key}{/tikz/rotate=\meta{degree}}
335 Rotates the coordinate system by \meta{degree}:
336 %
337 \begin{codeexample}[]
338 \begin{tikzpicture}
339 \draw[help lines] (0,0) grid (3,2);
340 \draw (0,0) -- (1,1) -- (1,0);
341 \draw[rotate=40,blue] (0,0) -- (1,1) -- (1,0);
342 \draw[rotate=-20,red] (0,0) -- (1,1) -- (1,0);
343 \end{tikzpicture}
344 \end{codeexample}
345 %
346 \end{key}
347
348 \begin{key}{/tikz/rotate around={\ttfamily\char`\{}\meta{degree}|:|\meta{coordinate}{\ttfamily\char`\}}}
349 Rotates the coordinate system by \meta{degree} around the point
350 \meta{coordinate}.
351 %
352 \begin{codeexample}[]
353 \begin{tikzpicture}
354 \draw[help lines] (0,0) grid (3,2);
355 \draw (0,0) -- (1,1) -- (1,0);
356 \draw[rotate around={40:(1,1)},blue] (0,0) -- (1,1) -- (1,0);
357 \draw[rotate around={-20:(1,1)},red] (0,0) -- (1,1) -- (1,0);
358 \end{tikzpicture}
359 \end{codeexample}
360 %
361 \end{key}
362
363 \begin{key}{/tikz/rotate around x=\meta{angle}}
364 This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
365 $xyz$-coordinate system so that they are rotated by \meta{angle} around the
366 axis corresponding to the $x$-vector. The rotation is applied so that when
367 looking towards the origin along this axis, positive angles result in an
368 anticlockwise rotation.
369 %
370 \begin{codeexample}[]
371 \begin{tikzpicture}[>=stealth]
372 \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
373 \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$};
374 \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$};
375
376 \draw [red, rotate around x=0] (0,0,0) -- (1,1,0) -- (1,0,0);
377 \draw [green, rotate around x=45] (0,0,0) -- (1,1,0) -- (1,0,0);
378 \draw [blue, rotate around x=90] (0,0,0) -- (1,1,0) -- (1,0,0);
379 \end{tikzpicture}
380 \end{codeexample}
381 %
382 \end{key}
383
384 \begin{key}{/tikz/rotate around y=\meta{angle}}
385 This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
386 $xyz$-coordinate system so that they are rotated by \meta{angle} around
387 the axis corresponding to the $y$-vector. The rotation is applied so that
388 when looking towards the origin along this axis, positive angles result in
389 an anticlockwise rotation.
390 %
391 \begin{codeexample}[]
392 \begin{tikzpicture}[>=stealth]
393 \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
394 \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$};
395 \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$};
396
397 \draw [red, rotate around y=0] (0,0,0) -- (1,1,0) -- (1,0,0);
398 \draw [green, rotate around y=-45] (0,0,0) -- (1,1,0) -- (1,0,0);
399 \draw [blue, rotate around y=-90] (0,0,0) -- (1,1,0) -- (1,0,0);
400 \end{tikzpicture}
401 \end{codeexample}
402 %
403 \end{key}
404
405 \begin{key}{/tikz/rotate around z=\meta{angle}}
406 This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
407 $xyz$-coordinate system so that they are rotated by \meta{angle} around the
408 axis corresponding to the $z$-vector. The rotation is applied so that when
409 looking towards the origin along this axis, positive angles result in an
410 anticlockwise rotation.
411 %
412 \begin{codeexample}[]
413 \begin{tikzpicture}[>=stealth]
414 \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
415 \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$};
416 \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$};
417
418 \draw [red, rotate around z=0] (0,0) -- (1,1) -- (1,0);
419 \draw [green, rotate around z=45] (0,0) -- (1,1) -- (1,0);
420 \draw [blue, rotate around z=90] (0,0) -- (1,1) -- (1,0);
421 \end{tikzpicture}
422 \end{codeexample}
423 %
424 \end{key}
425
426 \begin{key}{/tikz/cm={\ttfamily\char`\{}\meta{$a$}|,|\meta{$b$}|,|\meta{$c$}|,|\meta{$d$}|,|\meta{coordinate}{\ttfamily\char`\}}}
427 applies the following transformation to all coordinates: Let $(x,y)$ be the
428 coordinate to be transformed and let \meta{coordinate} specify the point
429 $(t_x,t_y)$. Then the new coordinate is given by
430 $\left(\begin{smallmatrix} a & c \\ b & d\end{smallmatrix}\right)
431 \left(\begin{smallmatrix} x \\ y \end{smallmatrix}\right) +
432 \left(\begin{smallmatrix} t_x \\ t_y \end{smallmatrix}\right)$.
433 Usually, you do not use this option directly.
434 %
435 \begin{codeexample}[]
436 \begin{tikzpicture}
437 \draw[help lines] (0,0) grid (3,2);
438 \draw (0,0) -- (1,1) -- (1,0);
439 \draw[cm={1,1,0,1,(0,0)},blue] (0,0) -- (1,1) -- (1,0);
440 \draw[cm={0,1,1,0,(1cm,1cm)},red] (0,0) -- (1,1) -- (1,0);
441 \end{tikzpicture}
442 \end{codeexample}
443 %
444 \end{key}
445
446 \begin{key}{/tikz/reset cm}
447 Completely resets the coordinate transformation matrix to the identity
448 matrix. This will destroy not only the transformations applied in the
449 current scope, but also all transformations inherited from surrounding
450 scopes. Do not use this option, unless you really, really know what you are
451 doing.
452 \end{key}
453
454
455 \subsection{Canvas Transformations}
456
457 A \emph{canvas transformation}, see
458 Section~\ref{section-design-transformations} for details, is best thought of as
459 a transformation in which the drawing canvas is stretched or rotated. Imaging
460 writing something on a balloon (the canvas) and then blowing air into the
461 balloon: Not only does the text become larger, the thin lines also become
462 larger. In particular, if you scale the canvas by a factor of two, all lines
463 are twice as thick.
464
465 Canvas transformations should be used with great care. In most circumstances
466 you do \emph{not} want line widths to change in a picture as this creates
467 visual inconsistency.
468
469 Just as important, when you use canvas transformations \emph{\pgfname\ loses
470 track of positions of nodes and of picture sizes} since it does not take the
471 effect of canvas transformations into account when it computes coordinates of
472 nodes (do not, however, rely on this; it may change in the future).
473
474 Finally, note that a canvas transformation always applies to a path as a whole,
475 it is not possible (as for coordinate transformations) to use different
476 transformations in different parts of a path.
477
478 In short, you should not use canvas transformations unless you really know what
479 you are doing.
480
481 \begin{key}{/tikz/transform canvas=\meta{options}}
482 The \meta{options} should contain coordinate transformations options like
483 |scale| or |xshift|. Multiple options can be given, their effects
484 accumulate in the usual manner. The effect of these \meta{options}
485 (immediately) changes the current canvas transformation matrix. The
486 coordinate transformation matrix is not changed. Tracking of the picture
487 size is (locally) switched off and the node coordinate will no longer be
488 correct.
489 %
490 \begin{codeexample}[]
491 \begin{tikzpicture}
492 \draw[help lines] (0,0) grid (3,2);
493 \draw (0,0) -- (1,1) -- (1,0);
494 \draw[transform canvas={scale=2},blue] (0,0) -- (1,1) -- (1,0);
495 \draw[transform canvas={rotate=180},red] (0,0) -- (1,1) -- (1,0);
496 \end{tikzpicture}
497 \end{codeexample}
498 %
499 \end{key}