PGF/TikZ Manual | PGFplots | TikZ Editor

TikZ and PGF Manual

TikZ

13 Specifying Coordinates

13.1 Overview

A coordinate is a position on the canvas on which your picture is drawn. TikZ uses a special syntax for specifying coordinates. Coordinates are always put in round brackets. The general syntax is ([options]coordinate specification).

The coordinate specification specifies coordinates using one of many different possible coordinate systems. Examples are the Cartesian coordinate system or polar coordinates or spherical coordinates. No matter which coordinate system is used, in the end, a specific point on the canvas is represented by the coordinate.

There are two ways of specifying which coordinate system should be used:

Explicitly

You can specify the coordinate system explicitly. To do so, you give the name of the coordinate system at the beginning, followed by cs:, which stands for “coordinate system”, followed by a specification of the coordinate using the key–value syntax. Thus, the general syntax for coordinate specification in the explicit case is (coordinate system cs:list of key–value pairs specific to the coordinate system).

Implicitly

The explicit specification is often too verbose when numerous coordinates should be given. Because of this, for the coordinate systems that you are likely to use often a special syntax is provided. TikZ will notice when you use a coordinate specified in a special syntax and will choose the correct coordinate system automatically.

Here is an example in which explicit the coordinate systems are specified explicitly:

(-tikz- diagram)


\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\draw (canvas cs:x=0cm,y=2mm)
-- (canvas polar cs:radius=2cm,angle=30);
\end{tikzpicture}

In the next example, the coordinate systems are implicit:

(-tikz- diagram)


\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\draw (0cm,2mm) -- (30:2cm);
\end{tikzpicture}

It is possible to give options that apply only to a single coordinate, although this makes sense for transformation options only. To give transformation options for a single coordinate, give these options at the beginning in brackets:

(-tikz- diagram)


\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
\draw (0,0) -- (1,1);
\draw[red] (0,0) -- ([xshift=3pt] 1,1);
\draw (1,0) -- +(30:2cm);
\draw[red] (1,0) -- +([shift=(135:5pt)] 30:2cm);
\end{tikzpicture}
13.2 Coordinate Systems
13.2.1 Canvas, XYZ, and Polar Coordinate Systems

Let us start with the basic coordinate systems.

Note: It is possible to use coordinates like (1,2cm), which are neither canvas coordinates nor xyz coordinates. The rule is the following: If a coordinate is of the implicit form (x,y), then x and y are checked, independently, whether they have a dimension or whether they are dimensionless. If both have a dimension, the canvas coordinate system is used. If both lack a dimension, the xyz coordinate system is used. If x has a dimension and y has not, then the sum of two coordinate (x,0pt) and (0,y) is used. If y has a dimension and x has not, then the sum of two coordinate (x,0) and (0pt,y) is used.

Note furthermore: An expression like (2+3cm,0) does not mean the same as (2cm+3cm,0). Instead, if x or y internally uses a mixture of dimensions and dimensionless values, then all dimensionless values are “upgraded” to dimensions by interpreting them as pt. So, 2+3cm is the same dimension as 2pt+3cm.

13.2.2 Barycentric Systems

In the barycentric coordinate system a point is expressed as the linear combination of multiple vectors. The idea is that you specify vectors \(v_1\), \(v_2\), …, \(v_n\) and numbers \(\alpha _1\), \(\alpha _2\), …, \(\alpha _n\). Then the barycentric coordinate specified by these vectors and numbers is

\begin{align*} \frac {\alpha _1 v_1 + \alpha _2 v_2 + \cdots + \alpha _n v_n}{\alpha _1 + \alpha _2 + \cdots + \alpha _n} \end{align*}

The barycentric cs allows you to specify such coordinates easily.

  • Coordinate system barycentric

  • For this coordinate system, the coordinate specification should be a comma-separated list of expressions of the form node name=number. Note that (currently) the list should not contain any spaces before or after the node name (unlike normal key–value pairs).

    The specified coordinate is now computed as follows: Each pair provides one vector and a number. The vector is the center anchor of the node name. The number is the number. Note that (currently) you cannot specify a different anchor, so that in order to use, say, the north anchor of a node you first have to create a new coordinate at this north anchor. (Using for instance \coordinate(mynorth) at (mynode.north);.)

    (-tikz- diagram)


    \begin{tikzpicture}
    \coordinate (content) at (90:3cm);
    \coordinate (structure) at (210:3cm);
    \coordinate (form) at (-30:3cm);

    \node [above] at (content) {content oriented};
    \node [below left] at (structure) {structure oriented};
    \node [below right] at (form) {form oriented};

    \draw [thick,gray] (content.south) -- (structure.north east) -- (form.north west) -- cycle;

    \small
    \node at (barycentric cs:content=0.5,structure=0.1 ,form=1) {PostScript};
    \node at (barycentric cs:content=1 ,structure=0 ,form=0.4) {DVI};
    \node at (barycentric cs:content=0.5,structure=0.5 ,form=1) {PDF};
    \node at (barycentric cs:content=0 ,structure=0.25,form=1) {CSS};
    \node at (barycentric cs:content=0.5,structure=1 ,form=0) {XML};
    \node at (barycentric cs:content=0.5,structure=1 ,form=0.4) {HTML};
    \node at (barycentric cs:content=1 ,structure=0.2 ,form=0.8) {\TeX};
    \node at (barycentric cs:content=1 ,structure=0.6 ,form=0.8) {\LaTeX};
    \node at (barycentric cs:content=0.8,structure=0.8 ,form=1) {Word};
    \node at (barycentric cs:content=1 ,structure=0.05,form=0.05) {ASCII};
    \end{tikzpicture}
13.2.3 Node Coordinate System

In pgf and in TikZ it is quite easy to define a node that you wish to reference at a later point. Once you have defined a node, there are different ways of referencing points of the node. To do so, you use the following coordinate system:

13.2.4 Tangent Coordinate Systems
13.2.5 Defining New Coordinate Systems

While the set of coordinate systems that TikZ can parse via their special syntax is fixed, it is possible and quite easy to define new explicitly named coordinate systems. For this, the following commands are used:

  • \tikzdeclarecoordinatesystem{name}{code}

  • This command declares a new coordinate system named name that can later on be used by writing (name cs:arguments). When TikZ encounters a coordinate specified in this way, the arguments are passed to code as argument #1.

    It is now the job of code to make sense of the arguments. At the end of code, the two dimensions \pgf@x and \pgf@y should be have the \(x\)- and \(y\)-canvas coordinate of the coordinate.

    It is not necessary, but customary, to parse arguments using the key–value syntax. However, you can also parse it in any way you like.

    In the following example, a coordinate system cylindrical is defined.

    (-tikz- diagram)


    \makeatletter
    \define@key{cylindricalkeys}{angle}{\def\myangle{#1}}
    \define@key{cylindricalkeys}{radius}{\def\myradius{#1}}
    \define@key{cylindricalkeys}{z}{\def\myz{#1}}
    \makeatother
    \tikzdeclarecoordinatesystem{cylindrical}%
    {%
    \setkeys{cylindricalkeys}{#1}%
    \pgfpointadd{\pgfpointxyz{0}{0}{\myz}}{\pgfpointpolarxy{\myangle}{\myradius}}
    }
    \begin{tikzpicture}[z=0.2pt]
    \draw [->] (0,0,0) -- (0,0,350);
    \foreach \num in {0,10,...,350}
    \fill (cylindrical cs:angle=\num,radius=1,z=\num) circle [radius=1pt];
    \end{tikzpicture}
  • \tikzaliascoordinatesystem{new name}{old name}

  • Creates an alias of old name.

13.3 Coordinates at Intersections

You will wish to compute the intersection of two paths. For the special and frequent case of two perpendicular lines, a special coordinate system called perpendicular is available. For more general cases, the intersections library can be used.

13.3.1 Intersections of Perpendicular Lines

A frequent special case of path intersections is the intersection of a vertical line going through a point \(p\) and a horizontal line going through some other point \(q\). For this situation there is a useful coordinate system.

  • Coordinate system perpendicular

  • You can specify the two lines using the following keys:

    • /tikz/cs/vertical line through={(coordinate)}(no default)

    • Specifies that the other line is vertical and goes through the given coordinate.

    However, in almost all cases you should, instead, use the implicit syntax. Here, you write (p |- q) or (q -| p).

    For example, (2,1 |- 3,4) and (3,4 -| 2,1) both yield the same as (2,4) (provided the \(xy\)-coordinate system has not been modified).

    The most useful application of the syntax is to draw a line up to some point on a vertical or horizontal line. Here is an example:

    (-tikz- diagram)


    \begin{tikzpicture}
    \path (30:1cm) node(p1) {$p_1$} (75:1cm) node(p2) {$p_2$};

    \draw (-0.2,0) -- (1.2,0) node(xline)[right] {$q_1$};
    \draw (2,-0.2) -- (2,1.2) node(yline)[above] {$q_2$};

    \draw[->] (p1) -- (p1 |- xline);
    \draw[->] (p2) -- (p2 |- xline);
    \draw[->] (p1) -- (p1 -| yline);
    \draw[->] (p2) -- (p2 -| yline);
    \end{tikzpicture}

    Note that in (c |- d) the coordinates c and d are not surrounded by parentheses. If they need to be complicated expressions (like a computation using the $-syntax), you must surround them with braces; parentheses will then be added around them.

    As an example, let us specify a point that lies horizontally at the middle of the line from \(A\) to \(B\) and vertically at the middle of the line from \(C\) to \(D\):

    (-tikz- diagram)

    \usetikzlibrary {calc}
    \begin{tikzpicture}
    \node (A) at (0,1) {A};
    \node (B) at (1,1.5) {B};
    \node (C) at (2,0) {C};
    \node (D) at (2.5,-2) {D};

    \draw (A) -- (B) node [midway] {x};
    \draw (C) -- (D) node [midway] {x};

    \node at ({$(A)!.5!(B)$} -| {$(C)!.5!(D)$}) {X};
    \end{tikzpicture}
13.3.2 Intersections of Arbitrary Paths

To find the intersections of two paths in TikZ, they must be “named”. A “named path” is, quite simply, a path that has been named using the following key (note that this is a different key from the name key, which only attaches a hyperlink target to a path, but does not store the path in a way that is useful for the intersection computation):

To find the intersection of named paths, the following key is used:

13.4 Relative and Incremental Coordinates
13.4.1 Specifying Relative Coordinates

You can prefix coordinates by ++ to make them “relative”. A coordinate such as ++(1cm,0pt) means “1cm to the right of the previous position, making this the new current position”. Relative coordinates are often useful in “local” contexts:

(-tikz- diagram)


\begin{tikzpicture}
\draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
\draw (2,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
\draw (1.5,1.5) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
\end{tikzpicture}

Instead of ++ you can also use a single +. This also specifies a relative coordinate, but it does not “update” the current point for subsequent usages of relative coordinates. Thus, you can use this notation to specify numerous points, all relative to the same “initial” point:

(-tikz- diagram)


\begin{tikzpicture}
\draw (0,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
\draw (2,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
\draw (1.5,1.5) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
\end{tikzpicture}

There is a special situation, where relative coordinates are interpreted differently. If you use a relative coordinate as a control point of a Bézier curve, the following rule applies: First, a relative first control point is taken relative to the beginning of the curve. Second, a relative second control point is taken relative to the end of the curve. Third, a relative end point of a curve is taken relative to the start of the curve.

This special behavior makes it easy to specify that a curve should “leave or arrive from a certain direction” at the start or end. In the following example, the curve “leaves” at \(30^\circ \) and “arrives” at \(60^\circ \):

(-tikz- diagram)


\begin{tikzpicture}
\draw (1,0) .. controls +(30:1cm) and +(60:1cm) .. (3,-1);
\draw[gray,->] (1,0) -- +(30:1cm);
\draw[gray,<-] (3,-1) -- +(60:1cm);
\end{tikzpicture}
13.4.2 Rotational Relative Coordinates

You may sometimes wish to specify points relative not only to the previous point, but additionally relative to the tangent entering the previous point. For this, the following key is useful:

  • /tikz/turn(no value)

  • This key can be given as an option to a coordinate as in the following example:

    (-tikz- diagram)


    \tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm);

    The effect of this key is to locally shift the coordinate system so that the last point reached is at the origin and the coordinate system is “turned” so that the \(x\)-axis points in the direction of a tangent entering the last point. This means, in effect, that when you use polar coordinates of the form relative angle:distance together with the turn option, you specify a point that lies at distance from the last point in the direction of the last tangent entering the last point, but with a rotation of relative angle.

    This key also works with curves …

    (-tikz- diagram)


    \tikz [delta angle=30, radius=1cm]
    \draw (0,0) arc [start angle=0] -- ([turn]0:1cm)
    arc [start angle=30] -- ([turn]0:1cm)
    arc [start angle=60] -- ([turn]30:1cm);

    (-tikz- diagram)


    \tikz \draw (0,0) to [bend left] (2,1) -- ([turn]0:1cm);

    …and with plots …

    (-tikz- diagram)


    \tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,0) } -- ([turn]30:1cm);

    Although the above examples use polar coordinates with turn, you can also use any normal coordinate. For instance, ([turn]1,1) will append a line of length \(\sqrt 2\) that is turns by \(45^\circ \) relative to the tangent to the last point.

    (-tikz- diagram)


    \tikz \draw (0.5,0.5) -| (2,1) -- ([turn]1,1)
    .. controls ([turn]0:1cm) .. ([turn]-90:1cm);
13.4.3 Relative Coordinates and Scopes

An interesting question is, how do relative coordinates behave in the presence of scopes? That is, suppose we use curly braces in a path to make part of it “local”, how does that affect the current position? On the one hand, the current position certainly changes since the scope only affects options, not the path itself. On the other hand, it may be useful to “temporarily escape” from the updating of the current point.

Since both interpretations of how the current point and scopes should “interact” are useful, there is a (local!) option that allows you to decide which you need.

  • /tikz/current point is local=boolean (no default, initially false)

  • Normally, the scope path operation has no effect on the current point. That is, curly braces on a path have no effect on the current position:

    (-tikz- diagram)


    \begin{tikzpicture}
    \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
    \draw[red] (2,0) -- ++(1,0) { -- ++(0,1) } -- ++(-1,0);
    \end{tikzpicture}

    If you set this key to true, this behavior changes. In this case, at the end of a group created on a path, the last current position reverts to whatever value it had at the beginning of the scope. More precisely, when TikZ encounters } on a path, it checks whether at this particular moment the key is set to true. If so, the current position reverts to the value it had when the matching { was read.

    (-tikz- diagram)


    \begin{tikzpicture}
    \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
    \draw[red] (2,0) -- ++(1,0)
    { [current point is local] -- ++(0,1) } -- ++(-1,0);
    \end{tikzpicture}

    In the above example, we could also have given the option outside the scope, for instance as a parameter to the whole scope.

13.5 Coordinate Calculations
  • TikZ Library calc

  • \usetikzlibrary{calc} % and plain
    \usetikzlibrary[calc] % Cont

    You need to load this library in order to use the coordinate calculation functions described in the present section.

It is possible to do some basic calculations that involve coordinates. In essence, you can add and subtract coordinates, scale them, compute midpoints, and do projections. For instance, ($(a) + 1/3*(1cm,0)$) is the coordinate that is \(1/3 \text {cm}\) to the right of the point a:

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\node (a) at (1,1) {A};
\fill [red] ($(a) + 1/3*(1cm,0)$) circle [radius=2pt];
\end{tikzpicture}
13.5.1 The General Syntax

The general syntax is the following:

([options]$coordinate computation$).

As you can see, the syntax uses the math symbol $ to indicate that a “mathematical computation” is involved. However, the $ has no other effect, in particular, no mathematical text is typeset.

The coordinate computation has the following structure:

  • 1. It starts with

    factor*coordinatemodifiers

  • 2. This is optionally followed by + or - and then another

    factor*coordinatemodifiers

  • 3. This is once more followed by + or - and another of the above modified coordinate; and so on.

In the following, the syntax of factors and of the different modifiers is explained in detail.

13.5.2 The Syntax of Factors

The factors are optional and detected by checking whether the coordinate computation starts with a (. Also, after each \(\pm \) a factor is present if, and only if, the + or - sign is not directly followed by (.

If a factor is present, it is evaluated using the \pgfmathparse macro. This means that you can use pretty complicated computations inside a factor. A factor may even contain opening parentheses, which creates a complication: How does TikZ know where a factor ends and where a coordinate starts? For instance, if the beginning of a coordinate computation is 2*(3+4…, it is not clear whether 3+4 is part of a coordinate or part of a factor. Because of this, the following rule is used: Once it has been determined, that a factor is present, in principle, the factor contains everything up to the next occurrence of *(. Note that there is no space between the asterisk and the parenthesis.

It is permissible to put the factor in curly braces. This can be used whenever it is unclear where the factor would end.

Here are some examples of coordinate specifications that consist of exactly one factor and one coordinate:

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\fill [red] ($2*(1,1)$) circle [radius=2pt];
\fill [green] (${1+1}*(1,.5)$) circle [radius=2pt];
\fill [blue] ($cos(0)*sin(90)*(1,1)$) circle [radius=2pt];
\fill [black] (${3*(4-3)}*(1,0.5)$) circle [radius=2pt];
\end{tikzpicture}
13.5.3 The Syntax of Partway Modifiers

A coordinate can be followed by different modifiers. The first kind of modifier is the partway modifier. The syntax (which is loosely inspired by Uwe Kern’s xcolor package) is the following:

coordinate!number!angle:second coordinate

One could write for instance


(1,2)!.75!(3,4)

The meaning of this is: “Use the coordinate that is three quarters on the way from (1,2) to (3,4).” In general, coordinate x!number!coordinate y yields the coordinate \((1 - \textit {number})\textit {coordinate x} + \textit {number} \textit {coordinate y}\). Note that this is a bit different from the way the number is interpreted in the xcolor package: First, you use a factor between \(0\) and \(1\), not a percentage, and, second, as the number approaches \(1\), we approach the second coordinate, not the first. It is permissible to use a number that is smaller than \(0\) or larger than \(1\). The number is evaluated using the \pgfmathparse command and, thus, it can involve complicated computations.

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\draw (1,0) -- (3,2);

\foreach \i in {0,0.2,0.5,0.9,1}
\node at ($(1,0)!\i!(3,2)$) {\i};
\end{tikzpicture}

The second coordinate may be prefixed by an angle, separated with a colon, as in (1,1)!.5!60:(2,2). The general meaning of a!factor!angle:b is: “First, consider the line from a to b. Then rotate this line by angle around the point a. Then the two endpoints of this line will be a and some point c. Use this point c for the subsequent computation, namely the partway computation.”

Here are two examples:

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,3);

\coordinate (a) at (1,0);
\coordinate (b) at (3,2);

\draw[->] (a) -- (b);

\coordinate (c) at ($ (a)!1! 10:(b) $);

\draw[->,red] (a) -- (c);

\fill ($ (a)!.5! 10:(b) $) circle [radius=2pt];
\end{tikzpicture}

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (4,4);

\foreach \i in {0,0.125,...,2}
\fill ($(2,2) !\i! \i*180:(3,2)$) circle [radius=2pt];
\end{tikzpicture}

You can repeatedly apply modifiers. That is, after any modifier you can add another (possibly different) modifier.

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\draw (0,0) -- (3,2);
\draw[red] ($(0,0)!.3!(3,2)$) -- (3,0);
\fill[red] ($(0,0)!.3!(3,2)!.7!(3,0)$) circle [radius=2pt];
\end{tikzpicture}
13.5.4 The Syntax of Distance Modifiers

A distance modifier has nearly the same syntax as a partway modifier, only you use a dimension (something like 1cm) instead of a factor (something like 0.5):

coordinate!dimension!angle:second coordinate

When you write a!dimension!b, this means the following: Use the point that is distanced dimension from a on the straight line from a to b. Here is an example:

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\draw (1,0) -- (3,2);

\foreach \i in {0cm,1cm,15mm}
\node at ($(1,0)!\i!(3,2)$) {\i};
\end{tikzpicture}

As before, if you use a angle, the second coordinate is rotated by this much around the coordinate before it is used.

The combination of an angle of 90 degrees with a distance can be used to “offset” a point relative to a line. Suppose, for instance, that you have computed a point (c) that lies somewhere on a line from (a) to (b) and you now wish to offset this point by 1cm so that the distance from this offset point to the line is 1cm. This can be achieved as follows:

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\coordinate (a) at (1,0);
\coordinate (b) at (3,1);

\draw (a) -- (b);

\coordinate (c) at ($ (a)!.25!(b) $);
\coordinate (d) at ($ (c)!1cm!90:(b) $);

\draw [<->] (c) -- (d) node [sloped,midway,above] {1cm};
\end{tikzpicture}
13.5.5 The Syntax of Projection Modifiers

The projection modifier is also similar to the above modifiers: It also gives a point on a line from the coordinate to the second coordinate. However, the number or dimension is replaced by a projection coordinate:

coordinate!projection coordinate!angle:second coordinate

Here is an example:


(1,2)!(0,5)!(3,4)

The effect is the following: We project the projection coordinate orthogonally onto the line from coordinate to second coordinate. This makes it easy to compute projected points:

(-tikz- diagram)

\usetikzlibrary {calc}
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);

\coordinate (a) at (0,1);
\coordinate (b) at (3,2);
\coordinate (c) at (2.5,0);

\draw (a) -- (b) -- (c) -- cycle;

\draw[red] (a) -- ($(b)!(a)!(c)$);
\draw[orange] (b) -- ($(a)!(b)!(c)$);
\draw[blue] (c) -- ($(a)!(c)!(b)$);
\end{tikzpicture}