The TikZ and PGF Packages
Manual for version 3.1.10

The Basic Layer

108 Coordinate, Canvas, and Nonlinear Transformations¶

108.1 Overview¶

pgf offers different ways of scaling, shifting, and rotating (these operations are generally known as transformations) graphics: You can apply coordinate transformations to all coordinates, you can apply canvas transformations to the canvas on which you draw, and you can apply 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:

• • 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 only to coordinates. They do not apply to, say, line width or shadings or text.

• • 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 everything will be larger: Text, lines, coordinates, and shadings.

• • 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 (pgf 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.

In many cases, it is preferable that you use coordinate transformations and not canvas transformations. When canvas transformations are used, pgf looses track of the coordinates of nodes and shapes. Also, canvas transformations often cause undesirable effects like changing text size. For these reasons, pgf 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.

108.2 Coordinate Transformations¶

108.2.1 How PGF Keeps Track of the Coordinate Transformation Matrix¶

pgf 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, pgf 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+cy+s,bx+dy+t)\) results. For more details on how transformation matrices work in general, please see, for example, the 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}\).

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

108.2.2 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 in addition to any previous coordinate transformations.

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

108.2.4 Saving and Restoring the Coordinate Transformation Matrix¶

There are two commands for saving and restoring coordinate transformation matrices.

108.2.5 Applying Coordinate Transformation to Points¶

108.2.6 Computing Adjustments for Coordinate Transformations¶

108.3 Canvas Transformations¶

The canvas transformation matrix is not managed by pgf, but by the output format like pdf or PostScript. All that pgf 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 pgf.

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, pgf 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.

108.3.1 Applying General Canvas Transformations¶

pgf 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).

108.3.2 Establishing View Boxes¶

A 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 animate the to-be-viewed rectangle. This makes it easy to create animations in which you zoom in, zoom out, and pan a graphic.

108.4 Nonlinear Transformations¶

In order to use nonlinear transformations, you first have to load the following pgf module:

108.4.1 Introduction¶

The difference between the coordinate transformations introduced in Section 108.2 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 TikZ 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 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

can become curved since everything gets transformed.

108.4.2 Installing Nonlinear Transformation¶

108.4.3 Applying Nonlinear Transformations to Points¶

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

• 1. 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.

• 2. 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:

  

  copy \usepgfmodule {nonlineartransformations}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
{
\pgftransformnonlinear{\polartransformation}
% The curve with the controls computed by pgf: a nice quarter arc
\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);
\end{tikzpicture}


  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 pgf does through the computation described above.

• 3. 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:

  \pgfsettransformnonlinearflatness{⟨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 ⟨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).

  

  copy \usepgfmodule {nonlineartransformations}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
\draw[red] (0:20mm) arc [start angle=0, end angle=90, radius=2cm];
{
\pgftransformnonlinear{\polartransformation}
\pgfsettransformnonlinearflatness{2pt} % very precise
\draw (0,20mm) -- (90pt,20mm);
}
\end{tikzpicture}


108.4.5 Applying Nonlinear Transformations to Text¶

Earlier, it was pointed that nonlinear transformations do not apply to text. Nevertheless, when you use \pgftext or \pgfnode, pgf 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:

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

108.4.7 Nonlinear Transformation Libraries¶

Up to now, our running example for a nonlinear transformation was polar transformation. However, is pgf nonlinear transformations are 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.