The TikZ and PGF Packages
Manual for version 3.1.10

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:

In the next example, the coordinate systems are implicit:

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:

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.

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:

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.

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:

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:

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 \):

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:

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.

13.5 Coordinate Calculations¶

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:

13.5.1 The General Syntax¶

The general syntax is the following:

([⟨options⟩]$⟨coordinate computation⟩$).

As you can see, the syntax uses the TeX 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⟩*⟨coordinate⟩⟨modifiers⟩

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

  ⟨factor⟩*⟨coordinate⟩⟨modifiers⟩

• 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 ⟨factor⟩s 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⟩:

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

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.

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:

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

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:

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:

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:

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: