Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-transformations.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{Coordinate, Canvas, and Nonlinear Transformations}
12
13 \subsection{Overview}
14
15 \pgfname\ offers different ways of scaling, shifting, and rotating (these
16 operations are generally known as \emph{transformations}) graphics: You can
17 apply \emph{coordinate transformations} to all coordinates, you can apply
18 \emph{canvas transformations} to the canvas on which you draw, and you can
19 apply \emph{additional nonlinear transformations}. (The names ``coordinate''
20 and ``canvas'' transformations are not standard, I introduce them only for the
21 purposes of this manual.)
22
23 The differences are the following:
24 %
25 \begin{itemize}
26 \item As the name ``coordinate transformation'' suggests, coordinate
27 transformations apply only to coordinates. For example, when you
28 specify a coordinate like |\pgfpoint{1cm}{2cm}| and you wish to ``use''
29 this coordinate -- for example as an argument to a |\pgfpathmoveto|
30 command -- then the coordinate transformation matrix is applied to the
31 coordinate, resulting in a new coordinate. Continuing the example, if
32 the current coordinate transformation is ``scale by a factor of two'',
33 the coordinate |\pgfpoint{1cm}{2cm}| actually designates the point
34 $(2\mathrm{cm},4\mathrm{cm})$.
35
36 Note that coordinate transformations apply \emph{only} to coordinates.
37 They do not apply to, say, line width or shadings or text.
38 \item The effect of a ``canvas transformation'' like ``scale by a factor of
39 two'' can be imagined as follows: You first draw your picture on a
40 ``rubber canvas'' normally. Then, once you are done, the whole canvas
41 is transformed, in this case stretched by a factor of two. In the
42 resulting image \emph{everything} will be larger: Text, lines,
43 coordinates, and shadings.
44 \item Nonlinear transformations are a special form of coordinate
45 transformations that are, as the name suggests, not linear. The support
46 for nonlinear transformations is quite different from the support for
47 linear coordinate transformations, the main reason being speed: While
48 linear coordinate transformations can be applied very quickly
49 (\pgfname\ does so almost constantly), nonlinear transformations are
50 much harder to apply and also to use. For this reason, nonlinear
51 transformations are implemented in a special module
52 |nonlineartransformations| that has to be loaded explicitly. By
53 default, they are not available.
54 \end{itemize}
55
56 In many cases, it is preferable that you use coordinate transformations and not
57 canvas transformations. When canvas transformations are used, \pgfname\ looses
58 track of the coordinates of nodes and shapes. Also, canvas transformations
59 often cause undesirable effects like changing text size. For these reasons,
60 \pgfname\ makes it easy to setup the coordinate transformation, but a bit
61 harder to change the canvas transformation. Because of the speed penalties
62 caused by nonlinear transformations, they are even harder to set up.
63
64
65 \subsection{Coordinate Transformations}
66 \label{section-linear-coordinate-transformations}
67
68 \subsubsection{How PGF Keeps Track of the Coordinate Transformation Matrix}
69 \label{section-transform-cm}
70
71 \pgfname\ has an internal coordinate transformation matrix. This matrix is
72 applied to coordinates ``in certain situations''. This means that the matrix is
73 not always applied to every coordinate ``no matter what''. Rather, \pgfname\
74 tries to be reasonably smart at when and how this matrix should be applied. The
75 most prominent examples are the path construction commands, which apply the
76 coordinate transformation matrix to their inputs.
77
78 The coordinate transformation matrix consists of four numbers $a$, $b$, $c$,
79 and $d$, and two dimensions $s$ and $t$. When the coordinate transformation
80 matrix is applied to a coordinate $(x,y)$, the new coordinate
81 $(ax+cy+s,bx+dy+t)$ results. For more details on how transformation matrices
82 work in general, please see, for example, the \textsc{pdf} or PostScript
83 reference or a textbook on computer graphics.
84
85 The coordinate transformation matrix is equal to the identity matrix at the
86 beginning. More precisely, $a=1$, $b=0$, $c=0$, $d=1$, $s=0\mathrm{pt}$, and
87 $t=0\mathrm{pt}$.
88
89 The different coordinate transformation commands will modify the matrix by
90 concatenating it with another transformation matrix. This way the effect of
91 applying several transformation commands will \emph{accumulate}.
92
93 The coordinate transformation matrix is local to the current \TeX\ group
94 (unlike the canvas transformation matrix, which is local to the current
95 |{pgfscope}|). Thus, the effect of adding a coordinate transformation to the
96 coordinate transformation matrix will last only till the end of the current
97 \TeX\ group.
98
99
100 \subsubsection{Commands for Relative Coordinate Transformations}
101
102 The following commands add a basic coordinate transformation to the current
103 coordinate transformation matrix. For all commands, the transformation is
104 applied \emph{in addition} to any previous coordinate transformations.
105
106 \begin{command}{\pgftransformshift\marg{point}}
107 Shifts coordinates by \meta{point}.
108 %
109 \begin{codeexample}[]
110 \begin{tikzpicture}
111 \draw[help lines] (0,0) grid (3,2);
112 \draw (0,0) -- (2,1) -- (1,0);
113 \pgftransformshift{\pgfpoint{1cm}{1cm}}
114 \draw[red] (0,0) -- (2,1) -- (1,0);
115 \end{tikzpicture}
116 \end{codeexample}
117 %
118 \end{command}
119
120 \begin{command}{\pgftransformxshift\marg{dimensions}}
121 Shifts coordinates by \meta{dimension} along the $x$-axis.
122 %
123 \begin{codeexample}[]
124 \begin{tikzpicture}
125 \draw[help lines] (0,0) grid (3,2);
126 \draw (0,0) -- (2,1) -- (1,0);
127 \pgftransformxshift{.5cm}
128 \draw[red] (0,0) -- (2,1) -- (1,0);
129 \end{tikzpicture}
130 \end{codeexample}
131 %
132 \end{command}
133
134 \begin{command}{\pgftransformyshift\marg{dimensions}}
135 Like |\pgftransformxshift|, only for the $y$-axis.
136 \end{command}
137
138 \begin{command}{\pgftransformscale\marg{factor}}
139 Scales coordinates by \meta{factor}.
140 %
141 \begin{codeexample}[]
142 \begin{tikzpicture}
143 \draw[help lines] (0,0) grid (3,2);
144 \draw (0,0) -- (2,1) -- (1,0);
145 \pgftransformscale{.75}
146 \draw[red] (0,0) -- (2,1) -- (1,0);
147 \end{tikzpicture}
148 \end{codeexample}
149 %
150 \end{command}
151
152 \begin{command}{\pgftransformxscale\marg{factor}}
153 Scales coordinates by \meta{factor} in the $x$-direction.
154 %
155 \begin{codeexample}[]
156 \begin{tikzpicture}
157 \draw[help lines] (0,0) grid (3,2);
158 \draw (0,0) -- (2,1) -- (1,0);
159 \pgftransformxscale{.75}
160 \draw[red] (0,0) -- (2,1) -- (1,0);
161 \end{tikzpicture}
162 \end{codeexample}
163 %
164 \end{command}
165
166 \begin{command}{\pgftransformyscale\marg{factor}}
167 Like |\pgftransformxscale|, only for the $y$-axis.
168 \end{command}
169
170 \begin{command}{\pgftransformxslant\marg{factor}}
171 Slants coordinates by \meta{factor} in the $x$-direction. Here, a factor of
172 |1| means $45^\circ$.
173 %
174 \begin{codeexample}[]
175 \begin{tikzpicture}
176 \draw[help lines] (0,0) grid (3,2);
177 \draw (0,0) -- (2,1) -- (1,0);
178 \pgftransformxslant{.5}
179 \draw[red] (0,0) -- (2,1) -- (1,0);
180 \end{tikzpicture}
181 \end{codeexample}
182 %
183 \end{command}
184
185 \begin{command}{\pgftransformyslant\marg{factor}}
186 Slants coordinates by \meta{factor} in the $y$-direction.
187 %
188 \begin{codeexample}[]
189 \begin{tikzpicture}
190 \draw[help lines] (0,0) grid (3,2);
191 \draw (0,0) -- (2,1) -- (1,0);
192 \pgftransformyslant{-1}
193 \draw[red] (0,0) -- (2,1) -- (1,0);
194 \end{tikzpicture}
195 \end{codeexample}
196 %
197 \end{command}
198
199
200 \begin{command}{\pgftransformrotate\marg{angles}}
201 Rotates coordinates counterclockwise by \meta{angles} given in degrees.
202 %
203 \begin{codeexample}[]
204 \begin{tikzpicture}
205 \draw[help lines] (0,0) grid (3,2);
206 \draw (0,0) -- (2,1) -- (1,0);
207 \pgftransformrotate{30}
208 \draw[red] (0,0) -- (2,1) -- (1,0);
209 \end{tikzpicture}
210 \end{codeexample}
211 %
212 \end{command}
213
214 \begin{command}{\pgftransformtriangle\marg{a}\marg{b}\marg{c}}
215 This command transforms the coordinate system in such a way that the
216 triangle given by the points \meta{a}, \meta{b} and \meta{c} lies at the
217 coordinates $(0,0)$, $(1\mathrm{pt},0\mathrm{pt})$ and
218 $(0\mathrm{pt},1\mathrm{pt})$.
219 %
220 \begin{codeexample}[]
221 \begin{tikzpicture}
222 \draw[help lines] (0,0) grid (3,2);
223 \pgftransformtriangle
224 {\pgfpoint{1cm}{0cm}}
225 {\pgfpoint{0cm}{2cm}}
226 {\pgfpoint{3cm}{1cm}}
227
228 \draw (0,0) -- (1pt,0pt) -- (0pt,1pt) -- cycle;
229 \end{tikzpicture}
230 \end{codeexample}
231 %
232 \end{command}
233
234 \begin{command}{\pgftransformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{point}}
235 Applies the transformation matrix given by $a$, $b$, $c$, and $d$ and the
236 shift \meta{point} to coordinates (in addition to any previous
237 transformations already in force).
238 %
239 \begin{codeexample}[]
240 \begin{tikzpicture}
241 \draw[help lines] (0,0) grid (3,2);
242 \draw (0,0) -- (2,1) -- (1,0);
243 \pgftransformcm{1}{1}{0}{1}{\pgfpoint{.25cm}{.25cm}}
244 \draw[red] (0,0) -- (2,1) -- (1,0);
245 \end{tikzpicture}
246 \end{codeexample}
247 %
248 \end{command}
249
250 \begin{command}{\pgftransformarrow\marg{start}\marg{end}}
251 Shifts coordinates to the end of the line going from \meta{start} to
252 \meta{end} with the correct rotation.
253 %
254 \begin{codeexample}[]
255 \begin{tikzpicture}
256 \draw[help lines] (0,0) grid (3,2);
257 \draw (0,0) -- (3,1);
258 \pgftransformarrow{\pgfpointorigin}{\pgfpoint{3cm}{1cm}}
259 \pgftext{tip}
260 \end{tikzpicture}
261 \end{codeexample}
262 %
263 \end{command}
264
265 \begin{command}{\pgftransformlineattime\marg{time}\marg{start}\marg{end}}
266 Shifts coordinates by a specific point on a line at a specific time. The
267 point by which the coordinate is shifted is calculated by calling
268 |\pgfpointlineattime|, see Section~\ref{section-pointsattime}.
269
270 In addition to shifting the coordinate, a rotation \emph{may} also be
271 applied. Whether this is the case depends on whether the \TeX\ if
272 |\ifpgfslopedattime| is set to true or not.
273 %
274 \begin{codeexample}[]
275 \begin{tikzpicture}
276 \draw[help lines] (0,0) grid (3,2);
277 \draw (0,0) -- (2,1);
278 \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
279 \pgftext{Hi!}
280 \end{tikzpicture}
281 \end{codeexample}
282 %
283 \begin{codeexample}[]
284 \begin{tikzpicture}
285 \draw[help lines] (0,0) grid (3,2);
286 \draw (0,0) -- (2,1);
287 \pgfslopedattimetrue
288 \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
289 \pgftext{Hi!}
290 \end{tikzpicture}
291 \end{codeexample}
292 %
293 If |\ifpgfslopedattime| is true, another \TeX\ |\if| is important:
294 |\ifpgfallowupsidedowattime|. If this is false, \pgfname\ will ensure that
295 the rotation is done in such a way that text is never ``upside down''.
296
297 There is another \TeX\ |\if| that influences this command. If you set
298 |\ifpgfresetnontranslationattime| to true, then, between shifting the
299 coordinate and (possibly) rotating/sloping the coordinate, the command
300 |\pgftransformresetnontranslations| is called. See the description of this
301 command for details.
302 %
303 \begin{codeexample}[]
304 \begin{tikzpicture}
305 \draw[help lines] (0,0) grid (3,2);
306 \pgftransformscale{1.5}
307 \draw (0,0) -- (2,1);
308 \pgfslopedattimetrue
309 \pgfresetnontranslationattimefalse
310 \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
311 \pgftext{Hi!}
312 \end{tikzpicture}
313 \end{codeexample}
314 %
315 \begin{codeexample}[]
316 \begin{tikzpicture}
317 \draw[help lines] (0,0) grid (3,2);
318 \pgftransformscale{1.5}
319 \draw (0,0) -- (2,1);
320 \pgfslopedattimetrue
321 \pgfresetnontranslationattimetrue
322 \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
323 \pgftext{Hi!}
324 \end{tikzpicture}
325 \end{codeexample}
326 %
327 \end{command}
328
329 \begin{command}{\pgftransformcurveattime\marg{time}\marg{start}\marg{first support}\marg{second support}\marg{end}}
330 Shifts coordinates by a specific point on a curve at a specific time, see
331 Section~\ref{section-pointsattime} once more.
332
333 As for the line-at-time transformation command, |\ifpgfslopedattime|
334 decides whether an additional rotation should be applied. Again, the value
335 of |\ifpgfallowupsidedowattime| is also considered.
336 %
337 \begin{codeexample}[]
338 \begin{tikzpicture}
339 \draw[help lines] (0,0) grid (3,2);
340 \draw (0,0) .. controls (0,2) and (1,2) .. (2,1);
341 \pgftransformcurveattime{.25}{\pgfpointorigin}
342 {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}}
343 \pgftext{Hi!}
344 \end{tikzpicture}
345 \end{codeexample}
346 %
347 \begin{codeexample}[]
348 \begin{tikzpicture}
349 \draw[help lines] (0,0) grid (3,2);
350 \draw (0,0) .. controls (0,2) and (1,2) .. (2,1);
351 \pgfslopedattimetrue
352 \pgftransformcurveattime{.25}{\pgfpointorigin}
353 {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}}
354 \pgftext{Hi!}
355 \end{tikzpicture}
356 \end{codeexample}
357 %
358 The value of |\ifpgfresetnontranslationsattime| is also taken into account.
359 \end{command}
360
361 \begin{command}{\pgftransformarcaxesattime\marg{time
362 $t$}\marg{center}\marg{0-degree axis}\marg{90-degree
363 axis}\marg{start angle}\marg{end angle}%
364 }
365 Shifts coordinates by a specific point on an arc at a specific time, see
366 Section~\ref{section-pointsattime} once more.
367
368 As for the previous commands, |\ifpgfslopedattime| decides whether an
369 additional rotation should be applied and |\ifpgfallowupsidedowattime| is
370 also considered.
371 %
372 \begin{codeexample}[]
373 \begin{tikzpicture}
374 \draw[help lines] (0,0) grid (3,2);
375 \pgfpathmoveto{\pgfpoint{2cm}{1cm}}
376 \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}
377 \pgfusepath{stroke}
378 \pgfslopedattimetrue
379 \pgftransformarcaxesattime{.25}
380 {\pgfpoint{0cm}{1cm}}
381 {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}
382 {0}{60}
383 \pgftext{Hi!}
384 \end{tikzpicture}
385 \end{codeexample}
386 %
387 The value of |\ifpgfresetnontranslationsattime| is also taken into account.
388 \end{command}
389
390 {
391 \let\ifpgfslopedattime=\relax
392 \begin{textoken}{\ifpgfslopedattime}
393 Decides whether the ``at time'' transformation commands also rotate
394 coordinates or not.
395 \end{textoken}
396 }
397 {
398 \let\ifpgfallowupsidedowattime=\relax
399 \begin{textoken}{\ifpgfallowupsidedowattime}
400 Decides whether the ``at time'' transformation commands should allow
401 the rotation be done in such a way that ``upside-down text'' can
402 result.
403 \end{textoken}
404 }
405 {
406 \let\ifpgfresetnontranslationsattime=\relax
407 \begin{textoken}{\ifpgfresetnontranslationsattime}
408 Decides whether the ``at time'' transformation commands should reset
409 the non-translations between shifting and rotating.
410 \end{textoken}
411 }
412
413
414 \subsubsection{Commands for Absolute Coordinate Transformations}
415
416 The coordinate transformation commands introduced up to now are always applied
417 in addition to any previous transformations. In contrast, the commands
418 presented in the following can be used to change the transformation matrix ``in
419 absolute terms''. Note that this is, in general, dangerous and will often
420 produce unexpected effects. You should use these commands only if you really
421 know what you are doing.
422
423 \begin{command}{\pgftransformreset}
424 Resets the coordinate transformation matrix to the identity matrix. Thus,
425 once this command is given no transformations are applied till the end of
426 the scope.
427 %
428 \begin{codeexample}[]
429 \begin{tikzpicture}
430 \draw[help lines] (0,0) grid (3,2);
431 \pgftransformrotate{30}
432 \draw (0,0) -- (2,1) -- (1,0);
433 \pgftransformreset
434 \draw[red] (0,0) -- (2,1) -- (1,0);
435 \end{tikzpicture}
436 \end{codeexample}
437 %
438 \end{command}
439
440 \begin{command}{\pgftransformresetnontranslations}
441 This command sets the $a$, $b$, $c$, and $d$ part of the coordinate
442 transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, the
443 current shifting of the matrix is not modified.
444
445 The effect of this command is that any rotation/scaling/slanting is undone
446 in the current \TeX\ group, but the origin is not ``moved back''.
447
448 This command is mostly useful directly before a |\pgftext| command to
449 ensure that the text is not scaled or rotated.
450 %
451 \begin{codeexample}[]
452 \begin{tikzpicture}
453 \draw[help lines] (0,0) grid (3,2);
454 \pgftransformscale{2}
455 \pgftransformrotate{30}
456 \pgftransformxshift{1cm}
457 {\color{red}\pgftext{rotated}}
458 \pgftransformresetnontranslations
459 \pgftext{shifted only}
460 \end{tikzpicture}
461 \end{codeexample}
462 %
463 \end{command}
464
465 \begin{command}{\pgftransforminvert}
466 Replaces the coordinate transformation matrix by a coordinate
467 transformation matrix that ``exactly undoes the original transformation''.
468 For example, if the original transformation was ``scale by 2 and then shift
469 right by 1cm'' the new one is ``shift left by 1cm and then scale by
470 $1/2$''.
471
472 This command will produce an error if the determinant of the matrix is too
473 small, that is, if the matrix is near-singular.
474 %
475 \begin{codeexample}[]
476 \begin{tikzpicture}
477 \draw[help lines] (0,0) grid (3,2);
478 \pgftransformrotate{30}
479 \draw (0,0) -- (2,1) -- (1,0);
480 \pgftransforminvert
481 \draw[red] (0,0) -- (2,1) -- (1,0);
482 \end{tikzpicture}
483 \end{codeexample}
484 %
485 \end{command}
486
487
488 \subsubsection{Saving and Restoring the Coordinate Transformation Matrix}
489
490 There are two commands for saving and restoring coordinate transformation
491 matrices.
492
493 \begin{command}{\pgfgettransform\marg{macro}}
494 This command will (locally) define \meta{macro} to a representation of the
495 current coordinate transformation matrix. This matrix can later on be
496 reinstalled using |\pgfsettransform|.
497 \end{command}
498
499 \begin{command}{\pgfsettransform\marg{macro}}
500 Reinstalls a coordinate transformation matrix that was previously saved
501 using |\pgfgettransform|.
502 \end{command}
503
504 \begin{command}{\pgfgettransformentries\marg{macro for a}\marg{macro
505 for b}\marg{macro for c}\marg{macro for d}\marg{macro for shift
506 x}\marg{macro for shift y}%
507 }
508 This command is similar to |\pgfgettransform| except that it stores the
509 current coordinate transformation matrix in a set of six macros.
510
511 The matrix can later on be reinstalled using |\pgfsettransformentries|.
512 Furthermore, all these macros (or just a few of them) can be used as
513 arguments for |\pgftransformcm|.
514 \end{command}
515
516 \begin{command}{\pgfsettransformentries\marg{a}\marg{b}\marg{c}\marg{d}\marg{shiftx}\marg{shifty}}
517 Reinstalls a coordinate transformation matrix that was previously saved
518 using the storage command |\pgfgettransformentries|. This command can also
519 be used to replace any previously existing coordinate transformation matrix
520 (it is thus equivalent to |\pgftransformreset| followed by
521 |\pgftransformcm|).
522 \end{command}
523
524
525 \subsubsection{Applying Coordinate Transformation to Points}
526
527 \begin{command}{\pgfpointtransformed\marg{point}}
528 Applies current transformation matrix to \marg{point} $(x,y)$ and returns a
529 transformed point $(ax+cy+s,bx+dy+t)$. Normally, this is done automatically
530 by commands like |\pgfpathlineto| or |\pgfpathmoveto|, but sometimes you
531 may wish to access a transformed point yourself.
532 \end{command}
533
534
535 \subsubsection{Computing Adjustments for Coordinate Transformations}
536 \label{section-adjustment-transformations}
537
538 \begin{command}{\pgftransformationadjustments}
539 This command computes ``adjustments'' for the current transformation matrix
540 so that even when you install a transformation matrix that scales
541 everything by a certain factor, you can still draw something of ``an
542 absolute size''. Suppose for instance that you install a transformation
543 matrix that scales everything by a factor of 4 and you now wish to draw a
544 horizontal line of length 1cm. Then, if you do not reset the transformation
545 matrix, you can draw a line of logical length 2.5mm, which will then get
546 scaled to a line of 1cm. Things get more difficult in case you scale things
547 only, say, vertically. In this case, the adjustment necessary for
548 horizontal lines is different from the one needed for vertical lines.
549
550 This function computes two scaling factors, one for horizontal lines
551 and one for vertical lines, and stores them in the following macros:
552 %
553 \begin{command}{\pgfhorizontaltransformationadjustment}
554 When you scale the length of a horizontal line by this factor in the
555 current transformation, you compensate for the scaling. Formally, it is
556 $1/\|\mathit{transform}(1,0)\|_2$, where $\mathit{transform}$ applies
557 the current transformations matrix to the given number.
558 %
559 \begin{codeexample}[]
560 \begin{tikzpicture}
561 \draw [help lines] (0,0) grid (2,2);
562 \begin{scope}[xscale=2,thick]
563 \draw [red] (1,1) -- ++(1,0);
564
565 \pgftransformationadjustments
566 \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0);
567 \end{scope}
568 \end{tikzpicture}
569 \end{codeexample}
570 %
571 \begin{codeexample}[]
572 \begin{tikzpicture}
573 \draw [help lines] (0,0) grid (2,2);
574 \begin{scope}[xscale=2,thick,rotate=90]
575 \draw [red] (1,1) -- ++(1,0);
576
577 \pgftransformationadjustments
578 \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0);
579 \end{scope}
580 \end{tikzpicture}
581 \end{codeexample}
582 \end{command}
583 %
584 \begin{command}{\pgfverticaltransformationadjustment}
585 $1/\|\mathit{transform}(0,1)\|_2$.
586 \end{command}
587
588 Note that the ``right'' way to draw a line of absolute length 1cm in a
589 transformed coordinate system is to first compute the start point and to
590 then reset the transformation matrix. The transformation adjustments
591 computed here are important only in situations where you cannot do this,
592 for instance when an |outer xsep| must be set.
593 \end{command}
594
595
596 \subsection{Canvas Transformations}
597
598 The canvas transformation matrix is not managed by \pgfname, but by the output
599 format like \pdf\ or PostScript. All that \pgfname\ does is to call appropriate
600 low-level |\pgfsys@| commands to change the canvas transformation matrix.
601
602 Unlike coordinate transformations, canvas transformations apply to
603 ``everything'', including images, text, shadings, line thickness, and so on.
604 The idea is that a canvas transformation really stretches and deforms the
605 canvas after the graphic is finished.
606
607 Unlike coordinate transformations, canvas transformations are local to the
608 current |{pgfscope}|, not to the current \TeX\ group. This is due to the fact
609 that they are managed by the backend driver, not by \TeX\ or \pgfname.
610
611 Unlike the coordinate transformation matrix, it is not possible to ``reset''
612 the canvas transformation matrix. The only way to change it is to concatenate
613 it with another canvas transformation matrix or to end the current
614 |{pgfscope}|.
615
616 Unlike coordinate transformations, \pgfname\ does not ``keep track'' of canvas
617 transformations. In particular, it will not be able to correctly save the
618 coordinates of shapes or nodes when a canvas transformation is used.
619
620
621 \subsubsection{Applying General Canvas Transformations}
622
623 \pgfname\ does not offer many commands for modifying the canvas transformation
624 matrix. Instead, different commands allow you to concatenate the canvas
625 transformation matrix with a coordinate transformation matrix (and there are
626 numerous commands for specifying a coordinate transformation, see the previous
627 section).
628
629 \begin{command}{\pgflowlevelsynccm}
630 This command concatenates the canvas transformation matrix with the current
631 coordinate transformation matrix. Afterward, the coordinate transformation
632 matrix is reset.
633
634 The effect of this command is to ``synchronize'' the coordinate
635 transformation matrix and the canvas transformation matrix. All
636 transformations that were previously applied by the coordinate
637 transformations matrix are now applied by the canvas transformation matrix.
638 %
639 \begin{codeexample}[]
640 \begin{tikzpicture}
641 \draw[help lines] (0,0) grid (3,2);
642 \pgfsetlinewidth{1pt}
643 \pgftransformscale{5}
644 \draw (0,0) -- (0.4,.2);
645 \pgftransformxshift{0.2cm}
646 \pgflowlevelsynccm
647 \draw[red] (0,0) -- (0.4,.2);
648 \end{tikzpicture}
649 \end{codeexample}
650 %
651 \end{command}
652
653 \begin{command}{\pgflowlevel\marg{transformation code}}
654 This command concatenates the canvas transformation matrix with the
655 coordinate transformation specified by \meta{transformation code}.
656 %
657 \begin{codeexample}[]
658 \begin{tikzpicture}
659 \draw[help lines] (0,0) grid (3,2);
660 \pgfsetlinewidth{1pt}
661 \pgflowlevel{\pgftransformscale{5}}
662 \draw (0,0) -- (0.4,.2);
663 \end{tikzpicture}
664 \end{codeexample}
665 %
666 \end{command}
667
668 \begin{command}{\pgflowlevelobj\marg{transformation code}\marg{code}}
669 This command creates a local |{pgfscope}|. Inside this scope,
670 |\pgflowlevel| is first called with the argument \meta{transformation
671 code}, then the \meta{code} is inserted.
672 %
673 \begin{codeexample}[]
674 \begin{tikzpicture}
675 \draw[help lines] (0,0) grid (3,2);
676 \pgfsetlinewidth{1pt}
677 \pgflowlevelobj{\pgftransformscale{5}} {\draw (0,0) -- (0.4,.2);}
678 \pgflowlevelobj{\pgftransformxshift{-1cm}}{\draw (0,0) -- (0.4,.2);}
679 \end{tikzpicture}
680 \end{codeexample}
681 %
682 \end{command}
683
684 \begin{environment}{{pgflowlevelscope}\marg{transformation code}}
685 This environment first surrounds the \meta{environment contents} by a
686 |{pgfscope}|. Then it calls |\pgflowlevel| with the argument
687 \meta{transformation code}.
688 %
689 \begin{codeexample}[]
690 \begin{tikzpicture}
691 \draw[help lines] (0,0) grid (3,2);
692 \pgfsetlinewidth{1pt}
693 \begin{pgflowlevelscope}{\pgftransformscale{5}}
694 \draw (0,0) -- (0.4,.2);
695 \end{pgflowlevelscope}
696 \begin{pgflowlevelscope}{\pgftransformxshift{-1cm}}
697 \draw (0,0) -- (0.4,.2);
698 \end{pgflowlevelscope}
699 \end{tikzpicture}
700 \end{codeexample}
701 %
702 \end{environment}
703
704 \begin{plainenvironment}{{pgflowlevelscope}\marg{transformation code}}
705 Plain \TeX\ version of the environment.
706 \end{plainenvironment}
707
708 \begin{contextenvironment}{{pgflowlevelscope}\marg{transformation code}}
709 Con\TeX t version of the environment.
710 \end{contextenvironment}
711
712
713 \subsubsection{Establishing View Boxes}
714 \label{section-base-view}
715
716 A \emph{view box} is like a ``window'' through which you see a graphic. To
717 establish a view box, you specify a rectangle -- which is the window -- and
718 another rectangle surrounding the to-be-viewed graphic. The graphic will then
719 be rescaled and shifted in such a way that the to-be-viewed rectangle matches
720 the view box's rectangle as well as possible. Note that establishing a view box
721 does, indeed, cause a canvas transformation to be installed.
722
723 View boxes are only seldom needed in normal graphics. Their main application is
724 with animations since you can \emph{animate} the to-be-viewed rectangle. This
725 makes it easy to create animations in which you zoom in, zoom out, and pan a
726 graphic.
727
728 \begin{environment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}}
729 Inside the viewbox scope, the source rectangle (with the two \pgfname\
730 points $ll_1$ and $ur_1$ as corners) will be translated and scaled so that
731 it becomes centered on the target rectangle (with the corners $ll_2$ and
732 $ur_2$) and will, for |meet| as last parameter, be as large as possible so
733 that it fits inside the target and, for |slice|, be as small as possible so
734 that it encompasses the target.
735 %
736 \begin{codeexample}[]
737 \tikz {
738 \draw [red, very thick] (0,0) rectangle (20mm,20mm);
739 \begin{pgfviewboxscope}
740 {\pgfpoint{5mm}{5mm}}{\pgfpoint{25mm}{15mm}} % Source
741 {\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}} % Target
742 {meet}
743 \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
744 \draw [thick] (1,1) circle [radius=8mm] node {Hi};
745 \end{pgfviewboxscope} }
746 \end{codeexample}
747 %
748 \begin{codeexample}[]
749 \tikz {
750 \draw [red, very thick] (0,0) rectangle (20mm,20mm);
751 \begin{pgfviewboxscope}
752 {\pgfpoint{5mm}{5mm}}{\pgfpoint{25mm}{15mm}} % Source
753 {\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}} % Target
754 {slice}
755 \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
756 \draw [thick] (1,1) circle [radius=8mm] node {Hi};
757 \end{pgfviewboxscope} }
758 \end{codeexample}
759 %
760 \end{environment}
761
762 \begin{plainenvironment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}}
763 Plain \TeX\ version of the environment.
764 \end{plainenvironment}
765
766 \begin{contextenvironment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}}
767 Con\TeX t version of the environment.
768 \end{contextenvironment}
769
770
771 \subsection{Nonlinear Transformations}
772 \label{section-nonlinear-transformations}
773
774 In order to use nonlinear transformations, you first have to load the following
775 \pgfname\ module:
776
777 \begin{pgfmodule}{nonlineartransformations}
778 Loads the necessary functionality for nonlinear transformations.
779 \end{pgfmodule}
780
781
782 \subsubsection{Introduction}
783
784 The difference between the coordinate transformations introduced in
785 Section~\ref{section-linear-coordinate-transformations} above to nonlinear
786 transformations is, of course, that the transformations can be nonlinear. An
787 example of a nonlinear transformation is the transformation underlying polar
788 coordinates: A polar coordinate $(r,d)$ gets transformed to the canvas position
789 $(d\cos r,d\sin r)$, which is clearly not a linear transformation.
790
791 Nonlinear transformations work somewhat like the normal linear coordinate
792 transformations in the sense that they apply to coordinate and thereby to the
793 construction of paths, but not to things like text or line width or shadings.
794 (Indeed, it is not possible to apply nonlinear transformations to, say, text.)
795
796 This means that there is a fundamental difference between, on the one hand,
797 calling a function like |\pgfpointpolar| or specifying a coordinate as |(45:2)|
798 in \tikzname\ and, on the other hand, installing the nonlinear transformation
799 ``polar coordinates'' using the command |\pgftransformnonlinear|: In a
800 coordinate like |(45:2)| the user explicitly says ``please evaluate this one
801 coordinate in polar coordinate and then continue in the normal coordinate
802 system with the result''. Otherwise nothing changes and a line between two
803 points specified in this way is still a straight line.
804
805 Things are quite different when we install a polar \emph{transformation} using
806 |\pgftransformnonlinear|. Now, even a seemingly low-level Cartesian coordinate
807 |\pgfqpoint{1pt}{1pt}| will get transformed. Even more drastically, what is
808 specified as a straight line like
809 %
810 \begin{codeexample}[code only]
811 \draw (0,1) -- (1,1);
812 \end{codeexample}
813 %
814 can become curved since \emph{everything} gets transformed.
815
816
817 \subsubsection{Installing Nonlinear Transformation}
818
819 \begin{codeexample}[setup code,hidden]
820 \makeatletter
821 \def\polartransformation{
822 % \pgf@x will contain the radius
823 % \pgf@y will contain the distance
824 \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
825 % pgfmathresultx is now the cosine of radius and
826 % pgfmathresulty is the sine of radius
827 \pgf@x=\pgfmathresultx\pgf@y%
828 \pgf@y=\pgfmathresulty\pgf@y%
829 }
830 \makeatother
831 \end{codeexample}
832
833 \begin{command}{\pgftransformnonlinear\marg{transformation code}}
834 This command adds the \meta{transformation code} to the list of non-linear
835 transformations currently in force. Thus, similar to linear coordinate
836 transformations, each additional call to this function adds another
837 transformation to the current \TeX\ scope and the effect ends at the end of
838 the current scope. In practice, however, you typically will not have more
839 than one active nonlinear transformation.
840
841 The job of the \meta{transformation code} is to map a point~$p$ given in
842 the registers |\pgf@x| and |\pgf@y| to a new coordinate~$f(p)$, which
843 should be returned in |\pgf@x| and |\pgf@y| as well. As an example, suppose
844 we wish to install polar coordinates as the nonlinear transformation. For
845 this, we need a bit of code:
846 %
847 \begin{codeexample}[code only]
848 \def\polartransformation{%
849 % \pgf@x will contain the radius
850 % \pgf@y will contain the distance
851 \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
852 % pgfmathresultx is now the cosine of radius and
853 % pgfmathresulty is the sine of radius
854 \pgf@x=\pgfmathresultx\pgf@y%
855 \pgf@y=\pgfmathresulty\pgf@y%
856 }
857 \end{codeexample}
858 %
859 (In case you wonder why you cannot just call |\pgfpointpolar| at this
860 point: You can, but this function internally uses |\pgf@x| and |\pgf@y| in
861 complicated ways, so you would first have to safe them so some other
862 registers. Also, the above is faster.)
863
864 If we were to call this function again, we would get something funny like
865 ``polar-polar coordinates'', so let's not do this. Let us instead have a
866 look at the effect this call has: Once a nonlinear transformation is
867 installed, all subsequent path constructions are affected by this
868 transformation. In particular, a normal grid now becomes the typical
869 ``polar grid''.
870 %
871 \begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
872 \begin{tikzpicture}
873 \draw [help lines] (0,0) grid (3,2);
874 % Start nonlinear transformation
875 \pgftransformnonlinear{\polartransformation}% see above
876
877 % Draw something with this transformation in force
878 \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
879 \end{tikzpicture}
880 \end{codeexample}
881 %
882 \end{command}
883
884
885 \subsubsection{Applying Nonlinear Transformations to Points}
886
887 \begin{command}{\pgfpointtransformednonlinear\marg{point}}
888 Works like |\pgfpointtransformed|, but also applies the current nonlinear
889 transformation; that is, it first applies the current linear transformation
890 and then the current nonlinear transformations. Note that, just like
891 |\pgfpointtransformed|, you normally do not call this function directly
892 since it is called internally by the path drawing commands.
893 \end{command}
894
895
896 \subsubsection{Applying Nonlinear Transformations to Paths}
897
898 When a nonlinear transformation is installed, the normal path construction
899 commands like |\pgfpathmoveto| get adjusted so that the ``honour'' the
900 nonlinear transformations currently in force. For |\pgfpathmoveto| this is
901 pretty simple: Instead of just applying the linear transformation matrix to the
902 point to which the path should ``jump'' next, we also apply the nonlinear
903 transformation. However, for a command like |\pgfpathlineto|, things are much
904 more difficult: A straight line will no longer be a straight line!
905
906 In order to make straight lines ``bend'', the following changes are in force
907 while a nonlinear transformation is installed:
908 %
909 \begin{enumerate}
910 \item Whenever a straight line between two points $p$ and $q$ should be
911 added to the path, either through |\pgfpathlineto| or through
912 |\pgfpathclose|, we replace this straight line by a ``degenerated
913 curve'' from $p$ to $q$ whose control points are at one third and two
914 third of the distance between $p$ and $q$ on the line between $p$ and
915 $q$. In this way, while nonlinear transformations are in force, we only
916 need to transform curves.
917 \item Next, suppose we wish to transform a curve from $p$ to $q$ with
918 supports $s$ and $t$. For this, we simply apply the nonlinear
919 transformation $f$ to all four points and draw a line with the results.
920 Note that this mapping is actually not quite satisfactory for long
921 lines that are strongly curved:
922 %
923 \begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
924 \begin{tikzpicture}
925 \draw [help lines] (0,0) grid (3,2);
926 {
927 \pgftransformnonlinear{\polartransformation}
928 % The curve with the controls computed by pgf: a nice quarter arc
929 \draw [red] (0,20mm) -- (90pt,20mm);
930 }
931 % Here is the curve with controls just transformed:
932 \draw (0:20mm) .. controls (30pt:20mm) and (60pt:20mm) .. (90pt:20mm);
933 \end{tikzpicture}
934 \end{codeexample}
935 %
936 As the example shows, the control points now lie on the arc; but in
937 reality they should point along the tangents at the start and the end.
938 This is exactly when \pgfname\ does through the computation described
939 above.
940 \item To overcome the effect of the control points being ``off'', it is
941 necessary to split up longer curves into smaller parts, which are drawn
942 individually to increase the accuracy. When such splitting occurs, can
943 be configured using the following command:
944 %
945 \begin{command}{\pgfsettransformnonlinearflatness\marg{dimension} (initially 5pt)}
946 Whenever in a to-be-drawn curve the $L^\infty$-distance (maximum of
947 the distances in $x$- and $y$-directions) between the start of a
948 curve and its first control point or between the first and second
949 control points or between the second control point and the end is
950 more than \meta{distance}, the curve gets split in the middle (more
951 precisely, at time $t= 0.5$) and we draw the two parts individually
952 (for them, splitting may occur again, if the curve is still too
953 long).
954 %
955 \begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
956 \begin{tikzpicture}
957 \draw [help lines] (0,0) grid (3,2);
958 \draw[red] (0:20mm) arc [start angle=0, end angle=90, radius=2cm];
959 {
960 \pgftransformnonlinear{\polartransformation}
961 \pgfsettransformnonlinearflatness{2pt} % very precise
962 \draw (0,20mm) -- (90pt,20mm);
963 }
964 \end{tikzpicture}
965 \end{codeexample}
966 \end{command}
967 \end{enumerate}
968
969
970 \subsubsection{Applying Nonlinear Transformations to Text}
971
972 Earlier, it was pointed that nonlinear transformations do not apply to text.
973 Nevertheless, when you use |\pgftext| or |\pgfnode|, \pgfname\ will do a sort
974 of ``best effort'' to render the text in the nonlinear coordinate system: The
975 point where the text should be shown can obviously be computed easily. When
976 then temporarily reset the nonlinear transformation and, instead, setup a
977 linear transformation that matches the nonlinear transformation at the point
978 where the text should be. Then, the text is shown. This means that if the text
979 is longer, it will not ``follow'' the nonlinear transformation, but near the
980 origin of the text it will look ``correct''. As an example, let us add some
981 text at the grid point of the above example:
982 %
983 \begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
984 \begin{tikzpicture}
985 \draw [help lines] (0,0) grid (3,2);
986 \pgftransformnonlinear{\polartransformation}% see above
987
988 % Draw something with this transformation in force
989 \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
990
991 \foreach \angle in {0,30,60,90}
992 \foreach \dist in {1,2}
993 {
994 \pgftransformshift{\pgfpoint{\angle pt}{\dist cm}}
995 \pgftext{\angle$^\circ$}
996 }
997 \end{tikzpicture}
998 \end{codeexample}
999
1000
1001 \subsubsection{Approximating Nonlinear Transformations Using Linear Transformations}
1002
1003 At any given point, the current nonlinear transformation can be approximated
1004 using a linear transformation. The following two functions allow you to install
1005 such a local approximation:
1006
1007 \begin{command}{\pgfapproximatenonlineartransformation}
1008 This command will do two things:
1009 %
1010 \begin{enumerate}
1011 \item It clears the nonlinear transformations for the rest of the
1012 current \TeX\ scope, so only linear transformations apply.
1013 \item However, before removing the nonlinear transformations, the
1014 linear transformation matrix is modified so that it mimics the
1015 effect the nonlinear transformation had at the origin. That is,
1016 after you call this command, drawing something near the origin will
1017 look almost the same as if you had not called it.
1018 \end{enumerate}
1019 %
1020 \begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
1021 \begin{tikzpicture}
1022 \draw [help lines] (0,0) grid (3,2);
1023 \pgftransformnonlinear{\polartransformation}% see above
1024 \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
1025
1026 \begin{scope}[shift={(45pt,20mm)}]
1027 % Draw something near "origin":
1028 \draw [red] (-10pt,-10pt) -- (10pt,10pt);
1029 \draw [red] (10pt,-10pt) -- (-10pt,10pt);
1030
1031 % Now draw the same, but in the "approximate" coordinate system:
1032 \pgfapproximatenonlineartransformation
1033 \draw [] (-10pt,-10pt) -- (10pt,10pt);
1034 \draw [] (10pt,-10pt) -- (-10pt,10pt);
1035 \pgftext{foo}
1036 \end{scope}
1037 \end{tikzpicture}
1038 \end{codeexample}
1039 %
1040 This command is used by |\pgftext| and |\pgfnode| to transform text when a
1041 nonlinear transformation is in force.
1042 \end{command}
1043
1044 \begin{command}{\pgfapproximatenonlineartranslation}
1045 This command works like the normal approximation command, but it will only
1046 approximate how the origin gets translated, it will not approximate the
1047 rotation, skewing, or scaling that is involved. This is useful for drawing
1048 text at the right position, but without ``mutilating'' the text.
1049 %
1050 \begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
1051 \begin{tikzpicture}
1052 \draw [help lines] (0,0) grid (3,2);
1053 \pgftransformnonlinear{\polartransformation}% see above
1054 \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
1055
1056 \begin{scope}[shift={(45pt,20mm)}]
1057 % Draw something near "origin":
1058 \draw [red] (-10pt,-10pt) -- (10pt,10pt);
1059 \draw [red] (10pt,-10pt) -- (-10pt,10pt);
1060
1061 % Now draw the same, but in the "approximate" coordinate system:
1062 \pgfapproximatenonlineartranslation
1063 \draw [] (-10pt,-10pt) -- (10pt,10pt);
1064 \draw [] (10pt,-10pt) -- (-10pt,10pt);
1065 \pgftext{foo}
1066 \end{scope}
1067 \end{tikzpicture}
1068 \end{codeexample}
1069 %
1070 \end{command}
1071
1072
1073 \subsubsection{Nonlinear Transformation Libraries}
1074 \label{section-library-curvilinear}
1075
1076 \begin{pgflibrary}{curvilinear}
1077 This library defines commands for computing nonlinear transformations
1078 ``along Bézier curves''.
1079 \end{pgflibrary}
1080
1081 Up to now, our running example for a nonlinear transformation was polar
1082 transformation. However, is \pgfname\ nonlinear transformations are
1083 \emph{actually} mainly used for transforming arrow tips; and these need to be
1084 transformed ``along curves''. The |curvilinear| library defines a number of
1085 commands that offer the necessary computations for such transformations.
1086
1087 \begin{command}{\pgfsetcurvilinearbeziercurve\marg{start}\marg{first support}\marg{second support}\marg{end}}
1088 Prior to using any other command from this library, you first call this
1089 function to ``install'' a Bézier curve to which the commands will refer.
1090 This curve will be local to the current \TeX\ scope and you can install
1091 only one curve at a time.
1092
1093 The main job of this command is to store the passed points internally and
1094 to build a lookup table for distance-to-time conversions, see the next
1095 command.
1096 %
1097 \begin{codeexample}[code only]
1098 \pgfsetcurvilinearbeziercurve
1099 {\pgfpointorigin}
1100 {\pgfpoint{1cm}{1cm}}
1101 {\pgfpoint{2cm}{1cm}}
1102 {\pgfpoint{3cm}{0cm}}
1103 \end{codeexample}
1104 %
1105 \end{command}
1106
1107 \begin{command}{\pgfcurvilineardistancetotime\marg{distance}}
1108 This command does a ``distance-to-time-conversion'': It tries to compute a
1109 time $t$, returned in |\pgf@x|, that corresponds to travelling
1110 \meta{distance} along the curve that has last been installed using the
1111 command |\pgfsetcurvilinearbeziercurve|. The distance-to-time-conversion
1112 uses the precomputations done by that command. Note that several
1113 compromises had to be made between speed and accuracy:
1114 %
1115 \begin{itemize}
1116 \item The conversion will be best near the start of the curve.
1117 \item The more ``degenerate'' the curve, the worse the results.
1118 \end{itemize}
1119 \end{command}
1120
1121 \begin{command}{\pgfpointcurvilinearbezierorthogonal\marg{distance}\marg{offset}}
1122 This command computes the following point: Consider the curve last
1123 installed using the command |\pgfsetcurvilinearbeziercurve|. We travel
1124 along this curve by \meta{distance}, arriving at a point $p$. Then, we turn
1125 by $90^\circ$ and travel by \meta{offset} units ``always from the curve'',
1126 arriving at a point $q$. This point $q$ will now be returned in |\pgf@x|
1127 and |\pgf@y|; furthermore, the transformed local coordinate system at point
1128 $q$ will also be returned |\pgf@xa| and the other registers, see
1129 |\pgftransformnonlinear| for details.
1130 %
1131 \makeatletter
1132 \begin{codeexample}[
1133 preamble={\usepgfmodule{nonlineartransformations}
1134 \usetikzlibrary{curvilinear}},
1135 pre=\makeatletter]
1136 \begin{tikzpicture}
1137 \draw [help lines] (0,0) grid (3,2);
1138 {
1139 \pgfsetcurvilinearbeziercurve
1140 {\pgfpoint{0mm}{20mm}}
1141 {\pgfpoint{11mm}{20mm}}
1142 {\pgfpoint{20mm}{11mm}}
1143 {\pgfpoint{20mm}{0mm}}
1144 \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}%
1145 \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
1146 }
1147 \draw[red, very thick]
1148 (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm);
1149 \end{tikzpicture}
1150 \end{codeexample}
1151
1152 \begin{codeexample}[
1153 preamble={\usepgfmodule{nonlineartransformations}
1154 \usetikzlibrary{curvilinear}},
1155 pre=\makeatletter]
1156 \begin{tikzpicture}
1157 \draw [help lines] (0,0) grid (3,2);
1158 {
1159 \pgfsetcurvilinearbeziercurve
1160 {\pgfpoint{0mm}{20mm}}
1161 {\pgfpoint{10mm}{20mm}}
1162 {\pgfpoint{10mm}{10mm}}
1163 {\pgfpoint{20mm}{10mm}}
1164 \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}%
1165 \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
1166 }
1167 \draw[red, very thick]
1168 (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm);
1169 \end{tikzpicture}
1170 \end{codeexample}
1171 %
1172 \end{command}
1173
1174 \begin{command}{\pgfpointcurvilinearbezierpolar\marg{x}\marg{y}}
1175 This command is similar to the previous version, but the transformation is
1176 different: The idea is that a line form $(0,0)$ to $(x,0)$ gets transformed
1177 to the curve from the start of the curve to a point at distance $x$ along
1178 the curve. This is identical to what the ``orthogonal'' transformation
1179 above also does. The difference is that a line from $(0,0)$ to $(0,y)$ gets
1180 still transformed to an initial segment of the curve of a length of $y$,
1181 but now rotated by $90^\circ$. In general, the point $p = (x,y)$ gets
1182 transferred to a point that at distance $|p| = \sqrt{x^2+y^2}$ along the
1183 curve, but rotated by the angle of $p$ relative to the $x$-axis.
1184
1185 All of these computations mainly have the following effect: Two straight
1186 lines from the start of the curve as in a |Straight Barb| arrow tip get
1187 transformed to an initial segment of the curve whose length is the length
1188 of the two lines, but this segment gets rotated by the angle of the two
1189 lines.
1190 %
1191 \makeatletter
1192 \begin{codeexample}[
1193 preamble={\usepgfmodule{nonlineartransformations}
1194 \usetikzlibrary{curvilinear}},
1195 pre=\makeatletter]
1196 \begin{tikzpicture}
1197 \draw [help lines] (0,0) grid (3,2);
1198 {
1199 \pgfsetcurvilinearbeziercurve
1200 {\pgfpoint{0mm}{20mm}}
1201 {\pgfpoint{11mm}{20mm}}
1202 {\pgfpoint{20mm}{11mm}}
1203 {\pgfpoint{20mm}{0mm}}
1204 \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}%
1205 \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
1206 % Add a "barb":
1207 \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt);
1208 }
1209 \draw[red, very thick]
1210 (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm);
1211 \end{tikzpicture}
1212 \end{codeexample}
1213
1214 \begin{codeexample}[
1215 preamble={\usepgfmodule{nonlineartransformations}
1216 \usetikzlibrary{curvilinear}},
1217 pre=\makeatletter]
1218 \begin{tikzpicture}
1219 \draw [help lines] (0,0) grid (3,2);
1220 {
1221 \pgfsetcurvilinearbeziercurve
1222 {\pgfpoint{0mm}{20mm}}
1223 {\pgfpoint{10mm}{20mm}}
1224 {\pgfpoint{10mm}{10mm}}
1225 {\pgfpoint{20mm}{10mm}}
1226 \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}%
1227 \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
1228 % Add a "barb":
1229 \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt);
1230 }
1231 \draw[red, very thick]
1232 (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm);
1233 \end{tikzpicture}
1234 \end{codeexample}
1235 %
1236 \end{command}
1237
1238
1239 %%% Local Variables:
1240 %%% mode: latex
1241 %%% TeX-master: "pgfmanual"
1242 %%% End:
1243
1244 % LocalWords: nonlineartransformations PGF cx dy pdf PostScript pgfscope xstep
1245 % LocalWords: Reinstalls shiftx backend pgflowlevelscope ystep ezier lookup xa
1246 % LocalWords: precomputations