diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
commit | 22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch) | |
tree | 2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex | |
parent | cf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff) |
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex | 1088 |
1 files changed, 576 insertions, 512 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex index 77d63178955..2cd4553dfef 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-transformations.tex @@ -7,117 +7,105 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. + \section{Coordinate, Canvas, and Nonlinear Transformations} \subsection{Overview} -\pgfname\ offers different ways of scaling, shifting, and rotating -(these operations are generally known as \emph{transformations}) -graphics: You can apply \emph{coordinate transformations} to all -coordinates, you can apply \emph{canvas transformations} to the -canvas on which you draw, and you can apply \emph{additional nonlinear - transformations.} (The names ``coordinate'' and ``canvas'' -transformations are not standard, I introduce them only for the -purposes of this manual.) +\pgfname\ offers different ways of scaling, shifting, and rotating (these +operations are generally known as \emph{transformations}) graphics: You can +apply \emph{coordinate transformations} to all coordinates, you can apply +\emph{canvas transformations} to the canvas on which you draw, and you can +apply \emph{additional nonlinear transformations}. (The names ``coordinate'' +and ``canvas'' transformations are not standard, I introduce them only for the +purposes of this manual.) The differences are the following: - +% \begin{itemize} -\item - As the name ``coordinate transformation'' suggests, coordinate - transformations apply only to coordinates. For example, when you - specify a coordinate like |\pgfpoint{1cm}{2cm}| and you wish to - ``use'' this coordinate---for example as an argument to a - |\pgfpathmoveto| command---then the coordinate transformation matrix - is applied to the coordinate, resulting in a new - coordinate. Continuing the example, if the current coordinate - transformation is ``scale by a factor of two,'' the coordinate - |\pgfpoint{1cm}{2cm}| actually designates the point - $(2\mathrm{cm},4\mathrm{cm})$. - - Note that coordinate transformations apply \emph{only} to - coordinates. They do not apply to, say, line width or shadings or - text. -\item - The effect of a ``canvas transformation'' like ``scale by a factor - of two'' can be imagined as follows: You first draw your picture on - a ``rubber canvas'' normally. Then, once you are done, the whole - canvas is transformed, in this case stretched by a factor of - two. In the resulting image \emph{everything} will be larger: Text, - lines, coordinates, and shadings. -\item - Nonlinear transformations are a special form of coordinate - transformations that are, as the name suggests, not linear. The - support for nonlinear transformations is quite different from the - support for linear coordinate transformations, the main reason being - speed: While linear coordinate transformations can be applied very - quickly (\pgfname\ does so almost constantly), nonlinear - transformations are much harder to apply and also to use. For this - reason, nonlinear transformations are implemented in a special - module |nonlineartransformations| that has to be loaded - explicitly. By default, they are not available. + \item As the name ``coordinate transformation'' suggests, coordinate + transformations apply only to coordinates. For example, when you + specify a coordinate like |\pgfpoint{1cm}{2cm}| and you wish to ``use'' + this coordinate -- for example as an argument to a |\pgfpathmoveto| + command -- then the coordinate transformation matrix is applied to the + coordinate, resulting in a new coordinate. Continuing the example, if + the current coordinate transformation is ``scale by a factor of two'', + the coordinate |\pgfpoint{1cm}{2cm}| actually designates the point + $(2\mathrm{cm},4\mathrm{cm})$. + + Note that coordinate transformations apply \emph{only} to coordinates. + They do not apply to, say, line width or shadings or text. + \item The effect of a ``canvas transformation'' like ``scale by a factor of + two'' can be imagined as follows: You first draw your picture on a + ``rubber canvas'' normally. Then, once you are done, the whole canvas + is transformed, in this case stretched by a factor of two. In the + resulting image \emph{everything} will be larger: Text, lines, + coordinates, and shadings. + \item Nonlinear transformations are a special form of coordinate + transformations that are, as the name suggests, not linear. The support + for nonlinear transformations is quite different from the support for + linear coordinate transformations, the main reason being speed: While + linear coordinate transformations can be applied very quickly + (\pgfname\ does so almost constantly), nonlinear transformations are + much harder to apply and also to use. For this reason, nonlinear + transformations are implemented in a special module + |nonlineartransformations| that has to be loaded explicitly. By + default, they are not available. \end{itemize} -In many cases, it is preferable that you use coordinate -transformations and not canvas transformations. When canvas -transformations are used, \pgfname\ looses track of the coordinates of -nodes and shapes. Also, canvas transformations often cause undesirable -effects like changing text size. For these reasons, \pgfname\ makes it -easy to setup the coordinate transformation, but a bit harder to -change the canvas transformation. Because of the speed penalties +In many cases, it is preferable that you use coordinate transformations and not +canvas transformations. When canvas transformations are used, \pgfname\ looses +track of the coordinates of nodes and shapes. Also, canvas transformations +often cause undesirable effects like changing text size. For these reasons, +\pgfname\ makes it easy to setup the coordinate transformation, but a bit +harder to change the canvas transformation. Because of the speed penalties caused by nonlinear transformations, they are even harder to set up. \subsection{Coordinate Transformations} \label{section-linear-coordinate-transformations} -\subsubsection{How PGF Keeps Track of the Coordinate Transformation - Matrix} +\subsubsection{How PGF Keeps Track of the Coordinate Transformation Matrix} \label{section-transform-cm} -\pgfname\ has an internal coordinate transformation matrix. This -matrix is applied to coordinates ``in certain situations.'' This means -that the matrix is not always applied to every coordinate ``no matter -what.'' Rather, \pgfname\ tries to be reasonably smart at when and how -this matrix should be applied. The most prominent examples are the -path construction commands, which apply the coordinate transformation -matrix to their inputs. - -The coordinate transformation matrix consists of four numbers $a$, -$b$, $c$, and $d$, and two dimensions $s$ and $t$. When the coordinate -transformation matrix is applied to a coordinate $(x,y)$, the new -coordinate $(ax+by+s,cx+dy+t)$ results. For more details on how -transformation matrices work in general, please see, for example, the -\textsc{pdf} or PostScript reference or a textbook on computer -graphics. - -The coordinate transformation matrix is equal to the identity matrix -at the beginning. More precisely, $a=1$, $b=0$, $c=0$, $d=1$, -$s=0\mathrm{pt}$, and $t=0\mathrm{pt}$. +\pgfname\ has an internal coordinate transformation matrix. This matrix is +applied to coordinates ``in certain situations''. This means that the matrix is +not always applied to every coordinate ``no matter what''. Rather, \pgfname\ +tries to be reasonably smart at when and how this matrix should be applied. The +most prominent examples are the path construction commands, which apply the +coordinate transformation matrix to their inputs. -The different coordinate transformation commands will modify the -matrix by concatenating it with another transformation matrix. This -way the effect of applying several transformation commands will -\emph{accumulate}. +The coordinate transformation matrix consists of four numbers $a$, $b$, $c$, +and $d$, and two dimensions $s$ and $t$. When the coordinate transformation +matrix is applied to a coordinate $(x,y)$, the new coordinate +$(ax+cy+s,bx+dy+t)$ results. For more details on how transformation matrices +work in general, please see, for example, the \textsc{pdf} or PostScript +reference or a textbook on computer graphics. -The coordinate transformation matrix is local to the current \TeX\ -group (unlike the canvas transformation matrix, which is local to the -current |{pgfscope}|). Thus, the effect of adding a coordinate -transformation to the coordinate transformation matrix will last only -till the end of the current \TeX\ group. +The coordinate transformation matrix is equal to the identity matrix at the +beginning. More precisely, $a=1$, $b=0$, $c=0$, $d=1$, $s=0\mathrm{pt}$, and +$t=0\mathrm{pt}$. +The different coordinate transformation commands will modify the matrix by +concatenating it with another transformation matrix. This way the effect of +applying several transformation commands will \emph{accumulate}. +The coordinate transformation matrix is local to the current \TeX\ group +(unlike the canvas transformation matrix, which is local to the current +|{pgfscope}|). Thus, the effect of adding a coordinate transformation to the +coordinate transformation matrix will last only till the end of the current +\TeX\ group. \subsubsection{Commands for Relative Coordinate Transformations} -The following commands add a basic coordinate transformation to the -current coordinate transformation matrix. For all commands, the -transformation is applied \emph{in addition} to any previous -coordinate transformations. +The following commands add a basic coordinate transformation to the current +coordinate transformation matrix. For all commands, the transformation is +applied \emph{in addition} to any previous coordinate transformations. \begin{command}{\pgftransformshift\marg{point}} - Shifts coordinates by \meta{point}. + Shifts coordinates by \meta{point}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -126,10 +114,12 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgftransformxshift\marg{dimensions}} - Shifts coordinates by \meta{dimension} along the $x$-axis. + Shifts coordinates by \meta{dimension} along the $x$-axis. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -138,14 +128,16 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgftransformyshift\marg{dimensions}} - Like |\pgftransformxshift|, only for the $y$-axis. + Like |\pgftransformxshift|, only for the $y$-axis. \end{command} \begin{command}{\pgftransformscale\marg{factor}} - Scales coordinates by \meta{factor}. + Scales coordinates by \meta{factor}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -154,10 +146,12 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgftransformxscale\marg{factor}} - Scales coordinates by \meta{factor} in the $x$-direction. + Scales coordinates by \meta{factor} in the $x$-direction. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -166,17 +160,17 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformyscale\marg{factor}} - Like |\pgftransformxscale|, only for the $y$-axis. + Like |\pgftransformxscale|, only for the $y$-axis. \end{command} - \begin{command}{\pgftransformxslant\marg{factor}} - Slants coordinates by \meta{factor} in the $x$-direction. Here, a - factor of |1| means $45^\circ$. + Slants coordinates by \meta{factor} in the $x$-direction. Here, a factor of + |1| means $45^\circ$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -185,11 +179,12 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformyslant\marg{factor}} - Slants coordinates by \meta{factor} in the $y$-direction. + Slants coordinates by \meta{factor} in the $y$-direction. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -198,12 +193,13 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformrotate\marg{angles}} - Rotates coordinates counterclockwise by \meta{angles} given in degrees. + Rotates coordinates counterclockwise by \meta{angles} given in degrees. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -212,15 +208,15 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} - - \begin{command}{\pgftransformtriangle\marg{a}\marg{b}\marg{c}} - This command transforms the coordinate system in such a way that the - triangle given by the points \meta{a}, \meta{b} and \meta{c} lies at - the coordinates $(0,0)$, $(1\mathrm{pt},0\mathrm{pt})$ and - $(0\mathrm{pt},1\mathrm{pt})$. + This command transforms the coordinate system in such a way that the + triangle given by the points \meta{a}, \meta{b} and \meta{c} lies at the + coordinates $(0,0)$, $(1\mathrm{pt},0\mathrm{pt})$ and + $(0\mathrm{pt},1\mathrm{pt})$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -228,17 +224,18 @@ coordinate transformations. {\pgfpoint{1cm}{0cm}} {\pgfpoint{0cm}{2cm}} {\pgfpoint{3cm}{1cm}} - + \draw (0,0) -- (1pt,0pt) -- (0pt,1pt) -- cycle; \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{point}} - Applies the transformation matrix given by $a$, $b$, $c$, and $d$ - and the shift \meta{point} to coordinates (in addition to any - previous transformations already in force). + Applies the transformation matrix given by $a$, $b$, $c$, and $d$ and the + shift \meta{point} to coordinates (in addition to any previous + transformations already in force). + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -247,12 +244,13 @@ coordinate transformations. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformarrow\marg{start}\marg{end}} - Shifts coordinates to the end of the line going from \meta{start} - to \meta{end} with the correct rotation. + Shifts coordinates to the end of the line going from \meta{start} to + \meta{end} with the correct rotation. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -261,18 +259,18 @@ coordinate transformations. \pgftext{tip} \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformlineattime\marg{time}\marg{start}\marg{end}} - Shifts coordinates by a specific point on a line at a specific - time. The point by which the coordinate is shifted is calculated by - calling |\pgfpointlineattime|, see - Section~\ref{section-pointsattime}. - - In addition to shifting the coordinate, a rotation \emph{may} also - be applied. Whether this is the case depends on whether the \TeX\ if - |\ifpgfslopedattime| is set to true or not. + Shifts coordinates by a specific point on a line at a specific time. The + point by which the coordinate is shifted is calculated by calling + |\pgfpointlineattime|, see Section~\ref{section-pointsattime}. + + In addition to shifting the coordinate, a rotation \emph{may} also be + applied. Whether this is the case depends on whether the \TeX\ if + |\ifpgfslopedattime| is set to true or not. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -281,6 +279,7 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -290,16 +289,17 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} - If |\ifpgfslopedattime| is true, another \TeX\ |\if| is important: - |\ifpgfallowupsidedowattime|. If this is false, \pgfname\ will - ensure that the rotation is done in such a way that text is never - ``upside down.'' - - There is another \TeX\ |\if| that influences this command. If you set - |\ifpgfresetnontranslationattime| to true, then, between - shifting the coordinate and (possibly) rotating/sloping the - coordinate, the command |\pgftransformresetnontranslations| is - called. See the description of this command for details. + % + If |\ifpgfslopedattime| is true, another \TeX\ |\if| is important: + |\ifpgfallowupsidedowattime|. If this is false, \pgfname\ will ensure that + the rotation is done in such a way that text is never ``upside down''. + + There is another \TeX\ |\if| that influences this command. If you set + |\ifpgfresetnontranslationattime| to true, then, between shifting the + coordinate and (possibly) rotating/sloping the coordinate, the command + |\pgftransformresetnontranslations| is called. See the description of this + command for details. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -311,6 +311,7 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -322,17 +323,17 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} + % \end{command} +\begin{command}{\pgftransformcurveattime\marg{time}\marg{start}\marg{first support}\marg{second support}\marg{end}} + Shifts coordinates by a specific point on a curve at a specific time, see + Section~\ref{section-pointsattime} once more. -\begin{command}{\pgftransformcurveattime\marg{time}\marg{start}\marg{first - support}\marg{second support}\marg{end}} - Shifts coordinates by a specific point on a curve at a specific - time, see Section~\ref{section-pointsattime} once more. - - As for the line-at-time transformation command, |\ifpgfslopedattime| - decides whether an additional rotation should be applied. Again, the - value of |\ifpgfallowupsidedowattime| is also considered. + As for the line-at-time transformation command, |\ifpgfslopedattime| + decides whether an additional rotation should be applied. Again, the value + of |\ifpgfallowupsidedowattime| is also considered. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -342,6 +343,7 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -352,19 +354,21 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} - The value of |\ifpgfresetnontranslationsattime| is also taken into account. + % + The value of |\ifpgfresetnontranslationsattime| is also taken into account. \end{command} - \begin{command}{\pgftransformarcaxesattime\marg{time $t$}\marg{center}\marg{0-degree axis}\marg{90-degree - axis}\marg{start angle}\marg{end angle}} - Shifts coordinates by a specific point on an arc at a specific - time, see Section~\ref{section-pointsattime} once more. - - As for the previous commands, |\ifpgfslopedattime| - decides whether an additional rotation should be applied and - |\ifpgfallowupsidedowattime| is also considered. + axis}\marg{start angle}\marg{end angle}% +} + Shifts coordinates by a specific point on an arc at a specific time, see + Section~\ref{section-pointsattime} once more. + + As for the previous commands, |\ifpgfslopedattime| decides whether an + additional rotation should be applied and |\ifpgfallowupsidedowattime| is + also considered. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -379,47 +383,48 @@ coordinate transformations. \pgftext{Hi!} \end{tikzpicture} \end{codeexample} - The value of |\ifpgfresetnontranslationsattime| is also taken into account. + % + The value of |\ifpgfresetnontranslationsattime| is also taken into account. \end{command} - { - \let\ifpgfslopedattime=\relax - \begin{textoken}{\ifpgfslopedattime} - Decides whether the ``at time'' transformation commands also - rotate coordinates or not. - \end{textoken} + \let\ifpgfslopedattime=\relax + \begin{textoken}{\ifpgfslopedattime} + Decides whether the ``at time'' transformation commands also rotate + coordinates or not. + \end{textoken} } { - \let\ifpgfallowupsidedowattime=\relax - \begin{textoken}{\ifpgfallowupsidedowattime} - Decides whether the ``at time'' transformation commands should - allow the rotation be done in such a way that ``upside-down text'' - can result. - \end{textoken} + \let\ifpgfallowupsidedowattime=\relax + \begin{textoken}{\ifpgfallowupsidedowattime} + Decides whether the ``at time'' transformation commands should allow + the rotation be done in such a way that ``upside-down text'' can + result. + \end{textoken} } { - \let\ifpgfresetnontranslationsattime=\relax - \begin{textoken}{\ifpgfresetnontranslationsattime} - Decides whether the ``at time'' transformation commands should - reset the non-translations between shifting and rotating. - \end{textoken} + \let\ifpgfresetnontranslationsattime=\relax + \begin{textoken}{\ifpgfresetnontranslationsattime} + Decides whether the ``at time'' transformation commands should reset + the non-translations between shifting and rotating. + \end{textoken} } \subsubsection{Commands for Absolute Coordinate Transformations} -The coordinate transformation commands introduced up to now are always -applied in addition to any previous transformations. In contrast, the -commands presented in the following can be used to change the -transformation matrix ``in absolute terms.'' Note that this is, in general, -dangerous and will often produce unexpected effects. You should use -these commands only if you really know what you are doing. +The coordinate transformation commands introduced up to now are always applied +in addition to any previous transformations. In contrast, the commands +presented in the following can be used to change the transformation matrix ``in +absolute terms''. Note that this is, in general, dangerous and will often +produce unexpected effects. You should use these commands only if you really +know what you are doing. \begin{command}{\pgftransformreset} - Resets the coordinate transformation matrix to the identity - matrix. Thus, once this command is given no transformations are - applied till the end of the scope. + Resets the coordinate transformation matrix to the identity matrix. Thus, + once this command is given no transformations are applied till the end of + the scope. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -429,20 +434,20 @@ these commands only if you really know what you are doing. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransformresetnontranslations} - This command sets the $a$, $b$, $c$, and $d$ part of the coordinate - transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, - the current shifting of the matrix is not modified. + This command sets the $a$, $b$, $c$, and $d$ part of the coordinate + transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, the + current shifting of the matrix is not modified. - The effect of this command is that any rotation/scaling/slanting is - undone in the current \TeX\ group, but the origin is not ``moved - back.'' + The effect of this command is that any rotation/scaling/slanting is undone + in the current \TeX\ group, but the origin is not ``moved back''. - This command is mostly useful directly before a |\pgftext| command - to ensure that the text is not scaled or rotated. + This command is mostly useful directly before a |\pgftext| command to + ensure that the text is not scaled or rotated. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -454,18 +459,19 @@ these commands only if you really know what you are doing. \pgftext{shifted only} \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgftransforminvert} - Replaces the coordinate transformation matrix by a coordinate - transformation matrix that ``exactly undoes the original - transformation.'' For example, if the original transformation was - ``scale by 2 and then shift right by 1cm'' the new one is ``shift - left by 1cm and then scale by $1/2$.'' - - This command will produce an error if the determinant of - the matrix is too small, that is, if the matrix is near-singular. + Replaces the coordinate transformation matrix by a coordinate + transformation matrix that ``exactly undoes the original transformation''. + For example, if the original transformation was ``scale by 2 and then shift + right by 1cm'' the new one is ``shift left by 1cm and then scale by + $1/2$''. + + This command will produce an error if the determinant of the matrix is too + small, that is, if the matrix is near-singular. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -475,74 +481,71 @@ these commands only if you really know what you are doing. \draw[red] (0,0) -- (2,1) -- (1,0); \end{tikzpicture} \end{codeexample} + % \end{command} +\subsubsection{Saving and Restoring the Coordinate Transformation Matrix} -\subsubsection{Saving and Restoring the Coordinate Transformation - Matrix} - -There are two commands for saving and restoring coordinate -transformation matrices. +There are two commands for saving and restoring coordinate transformation +matrices. \begin{command}{\pgfgettransform\marg{macro}} - This command will (locally) define \meta{macro} to a representation - of the current coordinate transformation matrix. This matrix can - later on be reinstalled using |\pgfsettransform|. + This command will (locally) define \meta{macro} to a representation of the + current coordinate transformation matrix. This matrix can later on be + reinstalled using |\pgfsettransform|. \end{command} - \begin{command}{\pgfsettransform\marg{macro}} - Reinstalls a coordinate transformation matrix that was previously - saved using |\pgfgettransform|. + Reinstalls a coordinate transformation matrix that was previously saved + using |\pgfgettransform|. \end{command} \begin{command}{\pgfgettransformentries\marg{macro for a}\marg{macro for b}\marg{macro for c}\marg{macro for d}\marg{macro for shift - x}\marg{macro for shift y}} - This command is similar to |\pgfgettransform| except that it stores - the current coordinate transformation matrix in a set of six - macros. - - The matrix can later on be reinstalled using - |\pgfsettransformentries|. Furthermore, all these macros (or just a - few of them) can be used as arguments for |\pgftransformcm|. + x}\marg{macro for shift y}% +} + This command is similar to |\pgfgettransform| except that it stores the + current coordinate transformation matrix in a set of six macros. + + The matrix can later on be reinstalled using |\pgfsettransformentries|. + Furthermore, all these macros (or just a few of them) can be used as + arguments for |\pgftransformcm|. \end{command} \begin{command}{\pgfsettransformentries\marg{a}\marg{b}\marg{c}\marg{d}\marg{shiftx}\marg{shifty}} - Reinstalls a coordinate transformation matrix that was previously - saved using the storage command |\pgfgettransformentries|. This - command can also be used to replace any previously existing - coordinate transformation matrix (it is thus equivalent to - |\pgftransformreset| followed by |\pgftransformcm|). + Reinstalls a coordinate transformation matrix that was previously saved + using the storage command |\pgfgettransformentries|. This command can also + be used to replace any previously existing coordinate transformation matrix + (it is thus equivalent to |\pgftransformreset| followed by + |\pgftransformcm|). \end{command} - \subsubsection{Computing Adjustments for Coordinate Transformations} \label{section-adjustment-transformations} \begin{command}{\pgftransformationadjustments} - This command computes ``adjustments'' for the current transformation - matrix so that even when you install a transformation matrix that - scales everything by a certain factor, you can still draw - something of ``an absolute size.'' Suppose for instance that you - install a transformation matrix that scales everything by a factor - of 4 and you now wish to draw a horizontal line of length 1cm. Then, - if you do not reset the transformation matrix, you can draw a line - of logical length 2.5mm, which will then get scaled to a line of - 1cm. Things get more difficult in case you scale things only, say, - vertically. In this case, the adjustement necessary for horizontal - lines is different from the one needed for vertical lines. - - This function computes two scaling factors, one for horizontal lines - and one for vertical lines, and stores them in the following macros: - \begin{command}{\pgfhorizontaltransformationadjustment} - When you scale the length of a horizontal line by this factor in - the current transformation, you compensate for the - scaling. Formally, it is $1/\|\mathit{transform}(1,0)\|_2$, where - $\mathit{transform}$ applies the current transformations matrix to - the given number. + This command computes ``adjustments'' for the current transformation matrix + so that even when you install a transformation matrix that scales + everything by a certain factor, you can still draw something of ``an + absolute size''. Suppose for instance that you install a transformation + matrix that scales everything by a factor of 4 and you now wish to draw a + horizontal line of length 1cm. Then, if you do not reset the transformation + matrix, you can draw a line of logical length 2.5mm, which will then get + scaled to a line of 1cm. Things get more difficult in case you scale things + only, say, vertically. In this case, the adjustment necessary for + horizontal lines is different from the one needed for vertical lines. + + This function computes two scaling factors, one for horizontal lines + and one for vertical lines, and stores them in the following macros: + % + \begin{command}{\pgfhorizontaltransformationadjustment} + When you scale the length of a horizontal line by this factor in the + current transformation, you compensate for the scaling. Formally, it is + $1/\|\mathit{transform}(1,0)\|_2$, where $\mathit{transform}$ applies + the current transformations matrix to the given number. + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (2,2); @@ -552,8 +555,9 @@ transformation matrices. \pgftransformationadjustments \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0); \end{scope} -\end{tikzpicture} +\end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (2,2); @@ -563,65 +567,65 @@ transformation matrices. \pgftransformationadjustments \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0); \end{scope} -\end{tikzpicture} +\end{tikzpicture} \end{codeexample} - \end{command} - \begin{command}{\pgfverticaltransformationadjustment} - $1/\|\mathit{transform}(0,1)\|_2$. - \end{command} - - Note that the ``right'' way to draw a line of absolute length 1cm in - a transformed coordinate system is to first compute the start point - and to then reset the transformation matrix. The transformation - adjustments computed here are important only in situations where you - cannot do this, for instance when an |outer xsep| must be set. + \end{command} + % + \begin{command}{\pgfverticaltransformationadjustment} + $1/\|\mathit{transform}(0,1)\|_2$. + \end{command} + + Note that the ``right'' way to draw a line of absolute length 1cm in a + transformed coordinate system is to first compute the start point and to + then reset the transformation matrix. The transformation adjustments + computed here are important only in situations where you cannot do this, + for instance when an |outer xsep| must be set. \end{command} \subsection{Canvas Transformations} -The canvas transformation matrix is not managed by \pgfname, but by -the output format like \pdf\ or PostScript. All that \pgfname\ does is -to call appropriate low-level |\pgfsys@| commands to change the canvas -transformation matrix. +The canvas transformation matrix is not managed by \pgfname, but by the output +format like \pdf\ or PostScript. All that \pgfname\ does is to call appropriate +low-level |\pgfsys@| commands to change the canvas transformation matrix. Unlike coordinate transformations, canvas transformations apply to -``everything,'' including images, text, shadings, line thickness, and -so on. The idea is that a canvas transformation really stretches and -deforms the canvas after the graphic is finished. - -Unlike coordinate transformations, canvas transformations are local to -the current |{pgfscope}|, not to the current \TeX\ group. This is due -to the fact that they are managed by the backend driver, not by \TeX\ -or \pgfname. - -Unlike the coordinate transformation matrix, it is not possible to -``reset'' the canvas transformation matrix. The only way to change it -is to concatenate it with another canvas transformation matrix or to -end the current |{pgfscope}|. - -Unlike coordinate transformations, \pgfname\ does not ``keep track'' -of canvas transformations. In particular, it will not be able to -correctly save the coordinates of shapes or nodes when a canvas -transformation is used. - -\pgfname\ does not offer a whole set of special commands for modifying -the canvas transformation matrix. Instead, different commands allow -you to concatenate the canvas transformation matrix with a coordinate -transformation matrix (and there are numerous commands for specifying -a coordinate transformation, see the previous section). +``everything'', including images, text, shadings, line thickness, and so on. +The idea is that a canvas transformation really stretches and deforms the +canvas after the graphic is finished. -\begin{command}{\pgflowlevelsynccm} - This command concatenates the canvas transformation matrix with the - current coordinate transformation matrix. Afterward, the coordinate - transformation matrix is reset. +Unlike coordinate transformations, canvas transformations are local to the +current |{pgfscope}|, not to the current \TeX\ group. This is due to the fact +that they are managed by the backend driver, not by \TeX\ or \pgfname. - The effect of this command is to ``synchronize'' the coordinate - transformation matrix and the canvas transformation matrix. All - transformations that were previously applied by the coordinate - transformations matrix are now applied by the canvas transformation - matrix. +Unlike the coordinate transformation matrix, it is not possible to ``reset'' +the canvas transformation matrix. The only way to change it is to concatenate +it with another canvas transformation matrix or to end the current +|{pgfscope}|. +Unlike coordinate transformations, \pgfname\ does not ``keep track'' of canvas +transformations. In particular, it will not be able to correctly save the +coordinates of shapes or nodes when a canvas transformation is used. + + +\subsubsection{Applying General Canvas Transformations} + +\pgfname\ does not offer many commands for modifying the canvas transformation +matrix. Instead, different commands allow you to concatenate the canvas +transformation matrix with a coordinate transformation matrix (and there are +numerous commands for specifying a coordinate transformation, see the previous +section). + +\begin{command}{\pgflowlevelsynccm} + This command concatenates the canvas transformation matrix with the current + coordinate transformation matrix. Afterward, the coordinate transformation + matrix is reset. + + The effect of this command is to ``synchronize'' the coordinate + transformation matrix and the canvas transformation matrix. All + transformations that were previously applied by the coordinate + transformations matrix are now applied by the canvas transformation matrix. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -633,13 +637,13 @@ a coordinate transformation, see the previous section). \draw[red] (0,0) -- (0.4,.2); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgflowlevel\marg{transformation code}} - This command concatenates the canvas transformation matrix with the - coordinate transformation specified by \meta{transformation code}. - + This command concatenates the canvas transformation matrix with the + coordinate transformation specified by \meta{transformation code}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -648,14 +652,14 @@ a coordinate transformation, see the previous section). \draw (0,0) -- (0.4,.2); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgflowlevelobj\marg{transformation code}\marg{code}} - This command creates a local |{pgfscope}|. Inside this scope, - |\pgflowlevel| is first called with the argument - \meta{transformation code}, then the \meta{code} is inserted. - + This command creates a local |{pgfscope}|. Inside this scope, + |\pgflowlevel| is first called with the argument \meta{transformation + code}, then the \meta{code} is inserted. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -664,14 +668,14 @@ a coordinate transformation, see the previous section). \pgflowlevelobj{\pgftransformxshift{-1cm}}{\draw (0,0) -- (0.4,.2);} \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{environment}{{pgflowlevelscope}\marg{transformation code}} - This environment first surrounds the \meta{environment contents} by - a |{pgfscope}|. Then it calls |\pgflowlevel| with the argument - \meta{transformation code}. - + This environment first surrounds the \meta{environment contents} by a + |{pgfscope}|. Then it calls |\pgflowlevel| with the argument + \meta{transformation code}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -684,63 +688,119 @@ a coordinate transformation, see the previous section). \end{pgflowlevelscope} \end{tikzpicture} \end{codeexample} + % \end{environment} - \begin{plainenvironment}{{pgflowlevelscope}\marg{transformation code}} - Plain \TeX\ version of the environment. + Plain \TeX\ version of the environment. \end{plainenvironment} \begin{contextenvironment}{{pgflowlevelscope}\marg{transformation code}} - Con\TeX t version of the environment. + Con\TeX t version of the environment. +\end{contextenvironment} + + +\subsubsection{Establishing View Boxes} +\label{section-base-view} + +A \emph{view box} is like a ``window'' through which you see a graphic. To +establish a view box, you specify a rectangle -- which is the window -- and +another rectangle surrounding the to-be-viewed graphic. The graphic will then +be rescaled and shifted in such a way that the to-be-viewed rectangle matches +the view box's rectangle as well as possible. Note that establishing a view box +does, indeed, cause a canvas transformation to be installed. + +View boxes are only seldom needed in normal graphics. Their main application is +with animations since you can \emph{animate} the to-be-viewed rectangle. This +makes it easy to create animations in which you zoom in, zoom out, and pan a +graphic. + +\begin{environment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}} + Inside the viewbox scope, the source rectangle (with the two \pgfname\ + points $ll_1$ and $ur_1$ as corners) will be translated and scaled so that + it becomes centered on the target rectangle (with the corners $ll_2$ and + $ur_2$) and will, for |meet| as last parameter, be as large as possible so + that it fits inside the target and, for |slice|, be as small as possible so + that it encompasses the target. + % +\begin{codeexample}[] +\tikz { + \draw [red, very thick] (0,0) rectangle (20mm,20mm); + \begin{pgfviewboxscope} + {\pgfpoint{5mm}{5mm}}{\pgfpoint{25mm}{15mm}} % Source + {\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}} % Target + {meet} + \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm); + \draw [thick] (1,1) circle [radius=8mm] node {Hi}; + \end{pgfviewboxscope} } +\end{codeexample} + % +\begin{codeexample}[] +\tikz { + \draw [red, very thick] (0,0) rectangle (20mm,20mm); + \begin{pgfviewboxscope} + {\pgfpoint{5mm}{5mm}}{\pgfpoint{25mm}{15mm}} % Source + {\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}} % Target + {slice} + \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm); + \draw [thick] (1,1) circle [radius=8mm] node {Hi}; + \end{pgfviewboxscope} } +\end{codeexample} + % +\end{environment} + +\begin{plainenvironment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}} + Plain \TeX\ version of the environment. +\end{plainenvironment} + +\begin{contextenvironment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}} + Con\TeX t version of the environment. \end{contextenvironment} \subsection{Nonlinear Transformations} \label{section-nonlinear-transformations} -In order to use nonlinear transformations, you first have to load the -following \pgfname\ module: + +In order to use nonlinear transformations, you first have to load the following +\pgfname\ module: \begin{pgfmodule}{nonlineartransformations} - Loads the necessary functionality for nonlinear transformations. + Loads the necessary functionality for nonlinear transformations. \end{pgfmodule} \subsubsection{Introduction} The difference between the coordinate transformations introduced in -Section~\ref{section-linear-coordinate-transformations} above to -nonlinear transformations is, of course, that the transformations can -be nonlinear. An example of a nonlinear transformation is the -transformation underlying polar coordinates: A polar coordinate -$(r,d)$ gets transformed to the canvas position $(d\cos r,d\sin r)$, -which is clearly not a linear transformation. - -Nonlinear transformations work somewhat like the normal linear -coordinate transformations in the sense that they apply to coordinate -and thereby to the construction of paths, but not to things like text -or line width or shadings. (Indeed, it is not possible to apply -nonlinear transformations to, say, text.) - -This means that there is a fundamental -difference between, on the one hand, calling a function like -|\pgfpointpolar| or specifying a coordinate as |(45:2)| in \tikzname\ -and, on the other hand, installing the nonlinear transformation +Section~\ref{section-linear-coordinate-transformations} above to nonlinear +transformations is, of course, that the transformations can be nonlinear. An +example of a nonlinear transformation is the transformation underlying polar +coordinates: A polar coordinate $(r,d)$ gets transformed to the canvas position +$(d\cos r,d\sin r)$, which is clearly not a linear transformation. + +Nonlinear transformations work somewhat like the normal linear coordinate +transformations in the sense that they apply to coordinate and thereby to the +construction of paths, but not to things like text or line width or shadings. +(Indeed, it is not possible to apply nonlinear transformations to, say, text.) + +This means that there is a fundamental difference between, on the one hand, +calling a function like |\pgfpointpolar| or specifying a coordinate as |(45:2)| +in \tikzname\ and, on the other hand, installing the nonlinear transformation ``polar coordinates'' using the command |\pgftransformnonlinear|: In a -coordinate like |(45:2)| the user explicitly says ``please evaluate -this one coordinate in polar coordinate and then continue in the -normal coordinate system with the result.'' Otherwise nothing changes -and a line between two points specified in this way is still a -straight line. - -Things are quite different when we install a polar -\emph{transformation} using |\pgftransformnonlinear|. Now, even a -seemingly low-level Cartesian coordinate |\pgfqpoint{1pt}{1pt}| will -get transformed. Even more drastically, what is specified as a -straight line like +coordinate like |(45:2)| the user explicitly says ``please evaluate this one +coordinate in polar coordinate and then continue in the normal coordinate +system with the result''. Otherwise nothing changes and a line between two +points specified in this way is still a straight line. + +Things are quite different when we install a polar \emph{transformation} using +|\pgftransformnonlinear|. Now, even a seemingly low-level Cartesian coordinate +|\pgfqpoint{1pt}{1pt}| will get transformed. Even more drastically, what is +specified as a straight line like +% \begin{codeexample}[code only] \draw (0,1) -- (1,1); \end{codeexample} +% can become curved since \emph{everything} gets transformed. @@ -759,19 +819,19 @@ can become curved since \emph{everything} gets transformed. \makeatother \begin{command}{\pgftransformnonlinear\marg{transformation code}} - This command adds the \meta{transformation code} to the list of non-linear - transformations currently in force. Thus, similar to linear - coordinate transformations, each additional call to this function - adds another transformation to the current \TeX\ scope and the - effect ends at the end of the current scope. In practice, however, - you typically will not have more than one active nonlinear - transformation. - - The job of the \meta{transformation code} is to map a point~$p$ - given in the registers |\pgf@x| and |\pgf@y| to a new - coordinate~$f(p)$, which should be returned in |\pgf@x| and |\pgf@y| - as well. As an example, suppose we wish to install polar coordinates - as the nonlinear transformation. For this, we need a bit of code: + This command adds the \meta{transformation code} to the list of non-linear + transformations currently in force. Thus, similar to linear coordinate + transformations, each additional call to this function adds another + transformation to the current \TeX\ scope and the effect ends at the end of + the current scope. In practice, however, you typically will not have more + than one active nonlinear transformation. + + The job of the \meta{transformation code} is to map a point~$p$ given in + the registers |\pgf@x| and |\pgf@y| to a new coordinate~$f(p)$, which + should be returned in |\pgf@x| and |\pgf@y| as well. As an example, suppose + we wish to install polar coordinates as the nonlinear transformation. For + this, we need a bit of code: + % \begin{codeexample}[code only] \def\polartransformation{% % \pgf@x will contain the radius @@ -783,70 +843,71 @@ can become curved since \emph{everything} gets transformed. \pgf@y=\pgfmathresulty\pgf@y% } \end{codeexample} - (In case you wonder why you cannot just call |\pgfpointpolar| at - this point: You can, but this function internally uses |\pgf@x| - and |\pgf@y| in complicated ways, so you would first have to safe - them so some other registers. Also, the above is faster.) - - If we were to call this function again, we would get something funny - like ``polar-polar coordinates,'' so let's not do this. Let us - instead have a look at the effect this call has: Once a nonlinear - transformation is installed, all subsequent path constructions are - affected by this transformation. In particular, a normal grid now - becomes the typical ``polar grid.'' - + % + (In case you wonder why you cannot just call |\pgfpointpolar| at this + point: You can, but this function internally uses |\pgf@x| and |\pgf@y| in + complicated ways, so you would first have to safe them so some other + registers. Also, the above is faster.) + + If we were to call this function again, we would get something funny like + ``polar-polar coordinates'', so let's not do this. Let us instead have a + look at the effect this call has: Once a nonlinear transformation is + installed, all subsequent path constructions are affected by this + transformation. In particular, a normal grid now becomes the typical + ``polar grid''. + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); % Start nonlinear transformation \pgftransformnonlinear{\polartransformation}% see above - + % Draw something with this transformation in force \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); \end{tikzpicture} \end{codeexample} + % \end{command} \subsubsection{Applying Nonlinear Transformations to Points} \begin{command}{\pgfpointtransformednonlinear\marg{point}} - Works like |\pgfpointtransformed|, but also applies the current - nonlinear transformation; that is, it first applies the current - linear transformation and then the current nonlinear - transformations. Note that, just like |\pgfpointtransformed|, you - normally do not call this function directly since it is called - internally by the path drawing commands. + Works like |\pgfpointtransformed|, but also applies the current nonlinear + transformation; that is, it first applies the current linear transformation + and then the current nonlinear transformations. Note that, just like + |\pgfpointtransformed|, you normally do not call this function directly + since it is called internally by the path drawing commands. \end{command} \subsubsection{Applying Nonlinear Transformations to Paths} -When a nonlinear transformation is installed, the normal path -construction commands like |\pgfpathmoveto| get adjusted so that the -``honour'' the nonlinear transformations currently in force. For -|\pgfpathmoveto| this is pretty simple: Instead of just applying the -linear transformation matrix to the point to which the path should -``jump'' next, we also apply the nonlinear transformation. However, -for a command like |\pgfpathlineto|, things are much more difficult: -A straight line will no longer be a straight line! - -In order to make straight lines ``bend'', the following changes are in -force while a nonlinear transformation is installed: +When a nonlinear transformation is installed, the normal path construction +commands like |\pgfpathmoveto| get adjusted so that the ``honour'' the +nonlinear transformations currently in force. For |\pgfpathmoveto| this is +pretty simple: Instead of just applying the linear transformation matrix to the +point to which the path should ``jump'' next, we also apply the nonlinear +transformation. However, for a command like |\pgfpathlineto|, things are much +more difficult: A straight line will no longer be a straight line! +In order to make straight lines ``bend'', the following changes are in force +while a nonlinear transformation is installed: +% \begin{enumerate} -\item Whenever a straight line between two points $p$ and $q$ should - be added to the path, either through |\pgfpathlineto| or through - |\pgfpathclose|, we replace this straight line by a ``degenerated - curve'' from $p$ to $q$ whose control points are at one third and - two third of the distance between $p$ and $q$ on the line between - $p$ and $q$. In this way, while nonlinear transformations are in - force, we only need to transform curves. -\item Next, suppose we wish to transform a curve from $p$ to $q$ with - supports $s$ and $t$. For this, we simply apply the nonlinear - transformation $f$ to all four points and draw a line with the - results. Note that this mapping is actually not quite satisfactory - for long lines that are strongly curved: + \item Whenever a straight line between two points $p$ and $q$ should be + added to the path, either through |\pgfpathlineto| or through + |\pgfpathclose|, we replace this straight line by a ``degenerated + curve'' from $p$ to $q$ whose control points are at one third and two + third of the distance between $p$ and $q$ on the line between $p$ and + $q$. In this way, while nonlinear transformations are in force, we only + need to transform curves. + \item Next, suppose we wish to transform a curve from $p$ to $q$ with + supports $s$ and $t$. For this, we simply apply the nonlinear + transformation $f$ to all four points and draw a line with the results. + Note that this mapping is actually not quite satisfactory for long + lines that are strongly curved: + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -856,28 +917,29 @@ force while a nonlinear transformation is installed: \draw [red] (0,20mm) -- (90pt,20mm); } % Here is the curve with controls just transformed: - \draw (0:20mm) .. controls (30pt:20mm) and (60pt:20mm) .. (90pt:20mm); + \draw (0:20mm) .. controls (30pt:20mm) and (60pt:20mm) .. (90pt:20mm); \end{tikzpicture} \end{codeexample} - As the example shows, the control points now lie on the arc; but in - reality they should point along the tangents at the start and the - end. This is exactly when \pgfname\ does through the computation - described above. -\item - To overcome the effect of the control points being ``off,'' it is - necessary to split up longer curves into smaller parts, which are - drawn individually to increase the accuracy. When such splitting - occurs, can be configured using the following command: - \begin{command}{\pgfsettransformnonlinearflatness\marg{dimension} - (initially 5pt)} - Whenever in a to-be-drawn curve the $L^\infty$-distance (maximum - of the distances in $x$- and $y$-directions) between the start of - a curve and its first control point or between the first and - second control points or between the second control point and the - end is more than \meta{distance}, the curve gets split in the - middle (more precisely, at time $t= 0.5$) and we draw the two - parts individually (for them, splitting may occur again, if the - curve is still too long). + % + As the example shows, the control points now lie on the arc; but in + reality they should point along the tangents at the start and the end. + This is exactly when \pgfname\ does through the computation described + above. + \item To overcome the effect of the control points being ``off'', it is + necessary to split up longer curves into smaller parts, which are drawn + individually to increase the accuracy. When such splitting occurs, can + be configured using the following command: + % + \begin{command}{\pgfsettransformnonlinearflatness\marg{dimension} (initially 5pt)} + Whenever in a to-be-drawn curve the $L^\infty$-distance (maximum of + the distances in $x$- and $y$-directions) between the start of a + curve and its first control point or between the first and second + control points or between the second control point and the end is + more than \meta{distance}, the curve gets split in the middle (more + precisely, at time $t= 0.5$) and we draw the two parts individually + (for them, splitting may occur again, if the curve is still too + long). + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -889,33 +951,31 @@ force while a nonlinear transformation is installed: } \end{tikzpicture} \end{codeexample} - \end{command} + \end{command} \end{enumerate} \subsubsection{Applying Nonlinear Transformations to Text} -Earlier, it was pointed that nonlinear transformations do not apply -to text. Nevertheless, when you use |\pgftext| or |\pgfnode|, -\pgfname\ will do a sort of ``best effort'' to render the text in -the nonlinear coordinate system: The point where the text should be -shown can obviously be computed easily. When then temporarily reset -the nonlinear transformation and, instead, setup a linear -transformation that matches the nonlinear transformation at the -point where the text should be. Then, the text is shown. This means -that if the text is longer, it will not ``follow'' the nonlinear -transformation, but near the origin of the text it will look -``correct.'' As an example, let us add some text at the grid point -of the above example: - +Earlier, it was pointed that nonlinear transformations do not apply to text. +Nevertheless, when you use |\pgftext| or |\pgfnode|, \pgfname\ will do a sort +of ``best effort'' to render the text in the nonlinear coordinate system: The +point where the text should be shown can obviously be computed easily. When +then temporarily reset the nonlinear transformation and, instead, setup a +linear transformation that matches the nonlinear transformation at the point +where the text should be. Then, the text is shown. This means that if the text +is longer, it will not ``follow'' the nonlinear transformation, but near the +origin of the text it will look ``correct''. As an example, let us add some +text at the grid point of the above example: +% \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); \pgftransformnonlinear{\polartransformation}% see above - + % Draw something with this transformation in force \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm); - + \foreach \angle in {0,30,60,90} \foreach \dist in {1,2} { @@ -928,22 +988,23 @@ of the above example: \subsubsection{Approximating Nonlinear Transformations Using Linear Transformations} -At any given point, the current nonlinear transformation can be -approximated using a linear transformation. The following two -functions allow you to install such a local approximation: +At any given point, the current nonlinear transformation can be approximated +using a linear transformation. The following two functions allow you to install +such a local approximation: \begin{command}{\pgfapproximatenonlineartransformation} - This command will do two things: - \begin{enumerate} - \item It clears the nonlinear transformations for the rest of the - current \TeX\ scope, so only linear transformations apply. - \item However, before removing the nonlinear transformations, the - linear transformation matrix is modified so that it mimics the - effect the nonlinear transformation had at the origin. That is, - after you call this command, drawing something near the origin - will look almost the same as if you had not called it. - \end{enumerate} - + This command will do two things: + % + \begin{enumerate} + \item It clears the nonlinear transformations for the rest of the + current \TeX\ scope, so only linear transformations apply. + \item However, before removing the nonlinear transformations, the + linear transformation matrix is modified so that it mimics the + effect the nonlinear transformation had at the origin. That is, + after you call this command, drawing something near the origin will + look almost the same as if you had not called it. + \end{enumerate} + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -952,27 +1013,28 @@ functions allow you to install such a local approximation: \begin{scope}[shift={(45pt,20mm)}] % Draw something near "origin": - \draw [red] (-10pt,-10pt) -- (10pt,10pt); + \draw [red] (-10pt,-10pt) -- (10pt,10pt); \draw [red] (10pt,-10pt) -- (-10pt,10pt); % Now draw the same, but in the "approximate" coordinate system: \pgfapproximatenonlineartransformation - \draw [] (-10pt,-10pt) -- (10pt,10pt); + \draw [] (-10pt,-10pt) -- (10pt,10pt); \draw [] (10pt,-10pt) -- (-10pt,10pt); \pgftext{foo}; \end{scope} \end{tikzpicture} -\end{codeexample} - This command is used by |\pgftext| and |\pgfnode| to transform text - when a nonlinear transformation is in force. +\end{codeexample} + % + This command is used by |\pgftext| and |\pgfnode| to transform text when a + nonlinear transformation is in force. \end{command} \begin{command}{\pgfapproximatenonlineartranslation} - This command works like the normal approximation command, but it - will only approximate how the origin gets translated, it will not - approximate the rotation, skewing, or scaling that is involved. This - is useful for drawing text at the right position, but without - ``mutilating'' the text. + This command works like the normal approximation command, but it will only + approximate how the origin gets translated, it will not approximate the + rotation, skewing, or scaling that is involved. This is useful for drawing + text at the right position, but without ``mutilating'' the text. + % \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -981,17 +1043,18 @@ functions allow you to install such a local approximation: \begin{scope}[shift={(45pt,20mm)}] % Draw something near "origin": - \draw [red] (-10pt,-10pt) -- (10pt,10pt); + \draw [red] (-10pt,-10pt) -- (10pt,10pt); \draw [red] (10pt,-10pt) -- (-10pt,10pt); % Now draw the same, but in the "approximate" coordinate system: \pgfapproximatenonlineartranslation - \draw [] (-10pt,-10pt) -- (10pt,10pt); + \draw [] (-10pt,-10pt) -- (10pt,10pt); \draw [] (10pt,-10pt) -- (-10pt,10pt); \pgftext{foo}; \end{scope} \end{tikzpicture} -\end{codeexample} +\end{codeexample} + % \end{command} @@ -999,27 +1062,26 @@ functions allow you to install such a local approximation: \label{section-library-curvilinear} \begin{pgflibrary}{curvilinear} - This library defines commands for computing nonlinear - transformations ``along B\'ezier curves''. + This library defines commands for computing nonlinear transformations + ``along Bézier curves''. \end{pgflibrary} -Up to now, our running example for a nonlinear transformation was -polar transformation. However, is \pgfname\ nonlinear transformations -are \emph{actually} mainly used for transforming arrow tips; and these -need to be transformed ``along curves.'' The |curvilinear| library -defines a number of commands that offer the necessary computations for -such transformations. - -\begin{command}{\pgfsetcurvilinearbeziercurve\marg{start}\marg{first - support}\marg{second support}\marg{end}} - Prior to using any other command from this library, you first call - this function to ``install'' a B\'ezier curve to which the commands - will refer. This curve will be local to the current \TeX\ scope and - you can install only one curve at a time. - - The main job of this command is to store the passed points - internally and to build a lookup table for distance-to-time - conversions, see the next command. +Up to now, our running example for a nonlinear transformation was polar +transformation. However, is \pgfname\ nonlinear transformations are +\emph{actually} mainly used for transforming arrow tips; and these need to be +transformed ``along curves''. The |curvilinear| library defines a number of +commands that offer the necessary computations for such transformations. + +\begin{command}{\pgfsetcurvilinearbeziercurve\marg{start}\marg{first support}\marg{second support}\marg{end}} + Prior to using any other command from this library, you first call this + function to ``install'' a Bézier curve to which the commands will refer. + This curve will be local to the current \TeX\ scope and you can install + only one curve at a time. + + The main job of this command is to store the passed points internally and + to build a lookup table for distance-to-time conversions, see the next + command. + % \begin{codeexample}[code only] \pgfsetcurvilinearbeziercurve {\pgfpointorigin} @@ -1027,33 +1089,34 @@ such transformations. {\pgfpoint{2cm}{1cm}} {\pgfpoint{3cm}{0cm}} \end{codeexample} + % \end{command} \begin{command}{\pgfcurvilineardistancetotime\marg{distance}} - This command does a ``distance-to-time-conversion'': It tries to - compute a time $t$, returned in |\pgf@x|, that corresponds to - travelling \meta{distance} along the curve that has last been - installed using the command |\pgfsetcurvilinearbeziercurve|. The distance-to-time-conversion - uses the precomputations done by that command. Note that several - compromises had to be made between speed and accuracy: - \begin{itemize} - \item The conversion will be best near the start of the curve. - \item The more ``degenerate'' the curve, the worse the results. - \end{itemize} + This command does a ``distance-to-time-conversion'': It tries to compute a + time $t$, returned in |\pgf@x|, that corresponds to travelling + \meta{distance} along the curve that has last been installed using the + command |\pgfsetcurvilinearbeziercurve|. The distance-to-time-conversion + uses the precomputations done by that command. Note that several + compromises had to be made between speed and accuracy: + % + \begin{itemize} + \item The conversion will be best near the start of the curve. + \item The more ``degenerate'' the curve, the worse the results. + \end{itemize} \end{command} - \begin{command}{\pgfpointcurvilinearbezierorthogonal\marg{distance}\marg{offset}} - This command computes the following point: Consider the curve - last installed using the command |\pgfsetcurvilinearbeziercurve|. We - travel along this curve by \meta{distance}, arriving at a point - $p$. Then, we turn by $90^\circ$ and travel by \meta{offset} units - ``aways from the curve,'' arriving at a point $q$. This point $q$ - will now be returned in |\pgf@x| and |\pgf@y|; furthermore, the - transformed local coordinate system at point $q$ will also be - returned |\pgf@xa| and the other registers, see - |\pgftransformnonlinear| for details. - \makeatletter + This command computes the following point: Consider the curve last + installed using the command |\pgfsetcurvilinearbeziercurve|. We travel + along this curve by \meta{distance}, arriving at a point $p$. Then, we turn + by $90^\circ$ and travel by \meta{offset} units ``always from the curve'', + arriving at a point $q$. This point $q$ will now be returned in |\pgf@x| + and |\pgf@y|; furthermore, the transformed local coordinate system at point + $q$ will also be returned |\pgf@xa| and the other registers, see + |\pgftransformnonlinear| for details. + % +\makeatletter \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -1087,27 +1150,27 @@ such transformations. (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm); \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgfpointcurvilinearbezierpolar\marg{x}\marg{y}} - This command is similar to the previous version, but the - transformation is different: The idea is that a line form $(0,0)$ to - $(x,0)$ gets transformed to the curve from the start of the curve to - a point at distance $x$ along the curve. This is identical to what - the ``orthogonal'' transformation above also does. The difference is - that a line from $(0,0)$ to $(0,y)$ gets still transformed to an - initial segment of the curve of a length of $y$, but now rotated by - $90^\circ$. In general, the point $p = (x,y)$ gets transferred to a - point that at distance $|p| = \sqrt{x^2+y^2}$ along the curve, but - rotated by the angle of $p$ relative to the $x$-axis. - - All of these computations mainly have the following effect: Two - straight lines from the start of the curve as in a |Straight Barb| - arrow tip get transformed to an initial segment of the curve whose - length is the length of the two lines, but this segment gets rotated - by the angle of the two lines. - \makeatletter + This command is similar to the previous version, but the transformation is + different: The idea is that a line form $(0,0)$ to $(x,0)$ gets transformed + to the curve from the start of the curve to a point at distance $x$ along + the curve. This is identical to what the ``orthogonal'' transformation + above also does. The difference is that a line from $(0,0)$ to $(0,y)$ gets + still transformed to an initial segment of the curve of a length of $y$, + but now rotated by $90^\circ$. In general, the point $p = (x,y)$ gets + transferred to a point that at distance $|p| = \sqrt{x^2+y^2}$ along the + curve, but rotated by the angle of $p$ relative to the $x$-axis. + + All of these computations mainly have the following effect: Two straight + lines from the start of the curve as in a |Straight Barb| arrow tip get + transformed to an initial segment of the curve whose length is the length + of the two lines, but this segment gets rotated by the angle of the two + lines. + % +\makeatletter \begin{codeexample}[] \begin{tikzpicture} \draw [help lines] (0,0) grid (3,2); @@ -1145,13 +1208,14 @@ such transformations. (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm); \end{tikzpicture} \end{codeexample} + % \end{command} -%%% Local Variables: +%%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" -%%% End: +%%% End: % LocalWords: nonlineartransformations PGF cx dy pdf PostScript pgfscope xstep % LocalWords: Reinstalls shiftx backend pgflowlevelscope ystep ezier lookup xa |