summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transformations.tex
blob: ef049f3cf36019644a022f1ece22431c90560fb6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
% Copyright 2018 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Transformations}

\pgfname\ has a powerful transformation mechanism that is similar to the
transformation capabilities of \textsc{metafont}. The present section explains
how you can access it in \tikzname.


\subsection{The Different Coordinate Systems}

It is a long process from  a coordinate like, say, $(1,2)$ or
$(1\mathrm{cm},5\mathrm{pt})$, to the position a point is finally placed on the
display or paper. In order to find out where the point should go, it is
constantly ``transformed'', which means that it is mostly shifted around and
possibly rotated, slanted, scaled, and otherwise mutilated.

In detail, (at least) the following transformations are applied to a coordinate
like $(1,2)$ before a point on the screen is chosen:
%
\begin{enumerate}
    \item \pgfname\ interprets a coordinate like $(1,2)$  in its
        $xy$-coordinate system as ``add the current $x$-vector once and the
        current $y$-vector twice to obtain the new point''.
    \item \pgfname\ applies its coordinate transformation matrix to the
        resulting coordinate. This yields the final position of the point
        inside the picture.
    \item The backend driver (like |dvips| or |pdftex|) adds transformation
        commands such that the coordinate is shifted to the correct position in
        \TeX's page coordinate system.
    \item \textsc{pdf} (or PostScript) apply the canvas transformation matrix
        to the point, which can once more change the position on the page.
    \item The viewer application or the printer applies the device
        transformation matrix to transform the coordinate to its final pixel
        coordinate on the screen or paper.
\end{enumerate}

In reality, the process is even more involved, but the above should give the
idea: A point is constantly transformed by changes of the coordinate system.

In \tikzname, you only have access to the first two coordinate systems: The
$xy$-coordinate system and the coordinate transformation matrix (these will be
explained later). \pgfname\ also allows you to change the canvas transformation
matrix, but you have to use commands of the core layer directly to do so and
you ``better know what you are doing'' when you do this. The moment you start
modifying the canvas matrix, \pgfname\ immediately loses track of all
coordinates and shapes, anchors, and bounding box computations will no longer
work.


\subsection{The XY- and XYZ-Coordinate Systems}
\label{section-xyz}

The first and easiest coordinate systems are \pgfname's $xy$- and
$xyz$-coordinate systems. The idea is very simple: Whenever you specify a
coordinate like |(2,3)| this means $2v_x + 3v_y$, where $v_x$ is the current
\emph{$x$-vector} and $v_y$ is the current \emph{$y$-vector}. Similarly, the
coordinate |(1,2,3)| means $v_x + 2v_y + 3v_z$.

Unlike other packages, \pgfname\ does not insist that $v_x$ actually has a
$y$-component of $0$, that is, that it is a horizontal vector. Instead, the
$x$-vector can point anywhere you want. Naturally, \emph{normally} you will
want the $x$-vector to point horizontally.

One undesirable effect of this flexibility is that it is not possible to
provide mixed coordinates as in $(1,2\mathrm{pt})$. Life is hard.

To change the $x$-, $y$-, and $z$-vectors, you can use the following options:

\begin{key}{/tikz/x=\meta{value} (initially 1cm)}
    If \meta{value} is a dimension, the $x$-vector of \pgfname's
    $xyz$-coordinate system is set up to point \meta{value} to the right, that
    is, to $(\meta{value},0pt)$.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw                  (0,0)   -- +(1,0);
  \draw[x=2cm,color=red] (0,0.1) -- +(1,0);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\tikz \draw[x=1.5cm] (0,0) grid (2,2);
\end{codeexample}

    The last example shows that the size of steppings in grids, just like all
    other dimensions, are not affected by the $x$-vector. After all, the
    $x$-vector is only used to determine the coordinate of the upper right
    corner of the grid.

    If \meta{value} is a coordinate, the $x$-vector of \pgfname's
    $xyz$-coordinate system to the specified coordinate. If \meta{value}
    contains a comma, it must be put in braces.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw                            (0,0) -- (1,0);
  \draw[x={(2cm,0.5cm)},color=red] (0,0) -- (1,0);
\end{tikzpicture}
\end{codeexample}

    You can use this, for example, to exchange the meaning of the $x$- and
    $y$-coordinate.
    %
\begin{codeexample}[]
\begin{tikzpicture}[smooth]
  \draw plot coordinates{(1,0) (2,0.5) (3,0) (3,1)};
  \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red]
        plot coordinates{(1,0) (2,0.5) (3,0) (3,1)};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/y=\meta{value} (initially 1cm)}
    Works like the |x=| option, only if \meta{value} is a dimension, the
    resulting vector points to $(0,\meta{value})$.
\end{key}

\begin{key}{/tikz/z=\meta{value} (initially \normalfont$-3.85$mm)}
    Works like the |y=| option, but now a dimension is the point
    $(\meta{value},\meta{value})$.
    %
\begin{codeexample}[]
\begin{tikzpicture}[z=-1cm,->,thick]
  \draw[color=red] (0,0,0) -- (1,0,0);
  \draw[color=blue] (0,0,0) -- (0,1,0);
  \draw[color=orange] (0,0,0) -- (0,0,1);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}


\subsection{Coordinate Transformations}

\pgfname\ and \tikzname\ allow you to specify \emph{coordinate
transformations}. Whenever you specify a coordinate as in |(1,0)| or
|(1cm,1pt)| or |(30:2cm)|, this coordinate is first ``reduced'' to a position
of the form ``$x$ points to the right and $y$ points upwards''. For example,
|(1in,5pt)| is reduced to ``$72\frac{72}{100}$ points to the right and 5 points
upwards'' and |(90:100pt)| means ``0pt to the right and 100 points upwards''.

The next step is to apply the current \emph{coordinate transformation matrix}
to the coordinate. For example, the coordinate transformation matrix might
currently be set such that it adds a certain constant to the $x$ value. Also,
it might be set up such that it, say, exchanges the $x$ and $y$ value. In
general, any ``standard'' transformation like translation, rotation, slanting,
or scaling or any combination thereof is possible. (Internally, \pgfname\ keeps
track of a coordinate transformation matrix very much like the concatenation
matrix used by \textsc{pdf} or PostScript.)
%
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw (0,0) rectangle (1,0.5);
  \begin{scope}[xshift=1cm]
    \draw             [red]    (0,0) rectangle (1,0.5);
    \draw[yshift=1cm] [blue]   (0,0) rectangle (1,0.5);
    \draw[rotate=30]  [orange] (0,0) rectangle (1,0.5);
  \end{scope}
\end{tikzpicture}
\end{codeexample}

The most important aspect of the coordinate transformation matrix is \emph{that
it applies to coordinates only!} In particular, the coordinate transformation
has no effect on things like the line width or the dash pattern or the shading
angle. In certain cases, it is not immediately clear whether the coordinate
transformation matrix \emph{should} apply to a certain dimension. For example,
should the coordinate transformation matrix apply to grids? (It does.) And what
about the size of arced corners? (It does not.) The general rule is: ``If there
is no `coordinate' involved, even `indirectly', the matrix is not applied.''.
However, sometimes, you simply have to try or look it up in the documentation
whether the matrix will be applied.

Setting the matrix cannot be done directly. Rather, all you can do is to
``add'' another transformation to the current matrix. However, all
transformations are local to the current \TeX-group. All transformations are
added using graphic options, which are described below.

Transformations apply immediately when they are encountered ``in the middle of
a path'' and they apply only to the coordinates on the path following the
transformation option.
%
\begin{codeexample}[]
\tikz \draw (0,0) rectangle (1,0.5) [xshift=2cm] (0,0) rectangle (1,0.5);
\end{codeexample}

A final word of warning: You should refrain from using ``aggressive''
transformations like a scaling of a factor of 10\,000. The reason is that all
transformations are done using \TeX, which has a fairly low accuracy.
Furthermore, in certain situations it is necessary that \tikzname\
\emph{inverts} the current transformation matrix and this will fail if the
transformation matrix is badly conditioned or even singular (if you do not know
what singular matrices are, you are blessed).

\begin{key}{/tikz/shift={\ttfamily\char`\{}\meta{coordinate}{\ttfamily\char`\}}}
    Adds the \meta{coordinate} to all coordinates.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                       (0,0) -- (1,1) -- (1,0);
  \draw[shift={(1,1)},blue]   (0,0) -- (1,1) -- (1,0);
  \draw[shift={(30:1cm)},red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/shift only}
    This option does not take any parameter. Its effect is to cancel all
    current transformations except for the shifting. This means that the origin
    will remain where it is, but any rotation around the origin or scaling
    relative to the origin or skewing will no longer have an effect.

    This option is useful in situations where a complicated transformation is
    used to ``get to a position'', but you then wish to draw something
    ``normal'' at this position.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                                      (0,0) -- (1,1) -- (1,0);
  \draw[rotate=30,xshift=2cm,blue]           (0,0) -- (1,1) -- (1,0);
  \draw[rotate=30,xshift=2cm,shift only,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/xshift=\meta{dimension}}
    Adds \meta{dimension} to the $x$ value of all coordinates.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                   (0,0) -- (1,1) -- (1,0);
  \draw[xshift=2cm,blue]  (0,0) -- (1,1) -- (1,0);
  \draw[xshift=-10pt,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/yshift=\meta{dimension}}
    Adds \meta{dimension} to the $y$ value of all coordinates.
\end{key}

\begin{key}{/tikz/scale=\meta{factor}}
    Multiplies all coordinates by the given \meta{factor}. The \meta{factor}
    should not be excessively large in absolute terms or very close to zero.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw               (0,0) -- (1,1) -- (1,0);
  \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0);
  \draw[scale=-1,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/scale around={\ttfamily\char`\{}\meta{factor}|:|\meta{coordinate}{\ttfamily\char`\}}}
    Scales the coordinate system by \meta{factor}, with the ``origin of
    scaling'' centered on \meta{coordinate} rather than the origin.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                             (0,0) -- (1,1) -- (1,0);
  \draw[scale=2,blue]               (0,0) -- (1,1) -- (1,0);
  \draw[scale around={2:(1,1)},red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/xscale=\meta{factor}}
    Multiplies only the $x$-value of all coordinates by the given
    \meta{factor}.
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                (0,0) -- (1,1) -- (1,0);
  \draw[xscale=2,blue] (0,0) -- (1,1) -- (1,0);
  \draw[xscale=-1,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/yscale=\meta{factor}}
    Multiplies only the $y$-value of all coordinates by \meta{factor}.
\end{key}

\begin{key}{/tikz/xslant=\meta{factor}}
    Slants the coordinate horizontally by the given \meta{factor}:
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                (0,0) -- (1,1) -- (1,0);
  \draw[xslant=2,blue] (0,0) -- (1,1) -- (1,0);
  \draw[xslant=-1,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/yslant=\meta{factor}}
    Slants the coordinate vertically by the given \meta{factor}:
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                (0,0) -- (1,1) -- (1,0);
  \draw[yslant=2,blue] (0,0) -- (1,1) -- (1,0);
  \draw[yslant=-1,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/rotate=\meta{degree}}
    Rotates the coordinate system by \meta{degree}:
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                 (0,0) -- (1,1) -- (1,0);
  \draw[rotate=40,blue] (0,0) -- (1,1) -- (1,0);
  \draw[rotate=-20,red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/rotate around={\ttfamily\char`\{}\meta{degree}|:|\meta{coordinate}{\ttfamily\char`\}}}
    Rotates the coordinate system by \meta{degree} around the point
    \meta{coordinate}.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                                (0,0) -- (1,1) -- (1,0);
  \draw[rotate around={40:(1,1)},blue] (0,0) -- (1,1) -- (1,0);
  \draw[rotate around={-20:(1,1)},red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/rotate around x=\meta{angle}}
    This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
    $xyz$-coordinate system so that they are rotated by \meta{angle} around the
    axis corresponding to the $x$-vector. The rotation is applied so that when
    looking towards the origin along this axis, positive angles result in an
    anticlockwise rotation.
    %
\begin{codeexample}[]
\begin{tikzpicture}[>=stealth]
  \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
  \draw [->] (0,0,0) -- (0,2,0) node [at end, left]  {$y$};
  \draw [->] (0,0,0) -- (0,0,2) node [at end, left]  {$z$};

  \draw [red,   rotate around x=0]  (0,0,0) -- (1,1,0) -- (1,0,0);
  \draw [green, rotate around x=45] (0,0,0) -- (1,1,0) -- (1,0,0);
  \draw [blue,  rotate around x=90] (0,0,0) -- (1,1,0) -- (1,0,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/rotate around y=\meta{angle}}
    This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
    $xyz$-coordinate system so that they are rotated by \meta{angle} around
    the axis corresponding to the $y$-vector. The rotation is applied so that
    when looking towards the origin along this axis, positive angles result in
    an anticlockwise rotation.
    %
\begin{codeexample}[]
\begin{tikzpicture}[>=stealth]
  \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
  \draw [->] (0,0,0) -- (0,2,0) node [at end, left]  {$y$};
  \draw [->] (0,0,0) -- (0,0,2) node [at end, left]  {$z$};

  \draw [red,   rotate around y=0]   (0,0,0) -- (1,1,0) -- (1,0,0);
  \draw [green, rotate around y=-45] (0,0,0) -- (1,1,0) -- (1,0,0);
  \draw [blue,  rotate around y=-90] (0,0,0) -- (1,1,0) -- (1,0,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/rotate around z=\meta{angle}}
    This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
    $xyz$-coordinate system so that they are rotated by \meta{angle} around the
    axis corresponding to the $z$-vector. The rotation is applied so that when
    looking towards the origin along this axis, positive angles result in an
    anticlockwise rotation.
    %
\begin{codeexample}[]
\begin{tikzpicture}[>=stealth]
  \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
  \draw [->] (0,0,0) -- (0,2,0) node [at end, left]  {$y$};
  \draw [->] (0,0,0) -- (0,0,2) node [at end, left]  {$z$};

  \draw [red,   rotate around z=0]  (0,0) -- (1,1) -- (1,0);
  \draw [green, rotate around z=45] (0,0) -- (1,1) -- (1,0);
  \draw [blue,  rotate around z=90] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/cm={\ttfamily\char`\{}\meta{$a$}|,|\meta{$b$}|,|\meta{$c$}|,|\meta{$d$}|,|\meta{coordinate}{\ttfamily\char`\}}}
    applies the following transformation to all coordinates: Let $(x,y)$ be the
    coordinate to be transformed and let \meta{coordinate} specify the point
    $(t_x,t_y)$. Then the new coordinate is given by
    $\left(\begin{smallmatrix} a & c \\ b & d\end{smallmatrix}\right)
    \left(\begin{smallmatrix} x \\ y \end{smallmatrix}\right) +
    \left(\begin{smallmatrix} t_x \\ t_y \end{smallmatrix}\right)$.
    Usually, you do not use this option directly.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                             (0,0) -- (1,1) -- (1,0);
  \draw[cm={1,1,0,1,(0,0)},blue]    (0,0) -- (1,1) -- (1,0);
  \draw[cm={0,1,1,0,(1cm,1cm)},red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/reset cm}
    Completely resets the coordinate transformation matrix to the identity
    matrix. This will destroy not only the transformations applied in the
    current scope, but also all transformations inherited from surrounding
    scopes. Do not use this option, unless you really, really know what you are
    doing.
\end{key}


\subsection{Canvas Transformations}

A \emph{canvas transformation}, see
Section~\ref{section-design-transformations} for details, is best thought of as
a transformation in which the drawing canvas is stretched or rotated. Imaging
writing something on a balloon (the canvas) and then blowing air into the
balloon: Not only does the text become larger, the thin lines also become
larger. In particular, if you scale the canvas by a factor of two, all lines
are twice as thick.

Canvas transformations should be used with great care. In most circumstances
you do \emph{not} want line widths to change in a picture as this creates
visual inconsistency.

Just as important, when you use canvas transformations \emph{\pgfname\ loses
track of positions of nodes and of picture sizes} since it does not take the
effect of canvas transformations into account when it computes coordinates of
nodes (do not, however, rely on this; it may change in the future).

Finally, note that a canvas transformation always applies to a path as a whole,
it is not possible (as for coordinate transformations) to use different
transformations in different parts of a path.

In short, you should not use canvas transformations unless you really know what
you are doing.

\begin{key}{/tikz/transform canvas=\meta{options}}
    The \meta{options} should contain coordinate transformations options like
    |scale| or |xshift|. Multiple options can be given, their effects
    accumulate in the usual manner. The effect of these \meta{options}
    (immediately) changes the current canvas transformation matrix. The
    coordinate transformation matrix is not changed. Tracking of the picture
    size is (locally) switched off and the node coordinate will no longer be
    correct.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw                                    (0,0) -- (1,1) -- (1,0);
  \draw[transform canvas={scale=2},blue]   (0,0) -- (1,1) -- (1,0);
  \draw[transform canvas={rotate=180},red] (0,0) -- (1,1) -- (1,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}