| 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 |