summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex1183
1 files changed, 598 insertions, 585 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
index 154533e680c..8ffafad7f54 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
@@ -7,42 +7,43 @@
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
-\section{Specifying Coordinates}
+\section{Specifying Coordinates}
\subsection{Overview}
-A \emph{coordinate} is a position on the canvas on which your picture
-is drawn. \tikzname\ uses a special syntax for specifying
-coordinates. Coordinates are always put in round brackets. The general
-syntax is
+A \emph{coordinate} is a position on the canvas on which your picture is drawn.
+\tikzname\ uses a special syntax for specifying coordinates. Coordinates are
+always put in round brackets. The general syntax is
\declare{|(|\opt{|[|\meta{options}|]|}\meta{coordinate specification}|)|}.
-The \meta{coordinate specification} specifies coordinates using one of
-many different possible \emph{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.
+The \meta{coordinate specification} specifies coordinates using one of many
+different possible \emph{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:
+%
\begin{description}
-\item[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 \meta{coordinate specification}
- in the explicit case is |(|\meta{coordinate system}| cs:|\meta{list
- of key-value pairs specific to the coordinate system}|)|.
-\item[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. \tikzname\ will notice when you use a coordinate
- specified in a special syntax and will choose the correct coordinate
- system automatically.
+ \item[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 \meta{coordinate specification} in the explicit
+ case is |(|\meta{coordinate system}| cs:|\meta{list of key--value pairs
+ specific to the coordinate system}|)|.
+ \item[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. \tikzname\ will notice when you use a coordinate
+ specified in a special syntax and will choose the correct coordinate
+ system automatically.
\end{description}
-Here is an example in which explicit the coordinate systems are
-specified explicitly:
+Here is an example in which explicit the coordinate systems are specified
+explicitly:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -50,7 +51,9 @@ specified explicitly:
-- (canvas polar cs:radius=2cm,angle=30);
\end{tikzpicture}
\end{codeexample}
+%
In the next example, the coordinate systems are implicit:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -58,10 +61,11 @@ In the next example, the coordinate systems are implicit:
\end{tikzpicture}
\end{codeexample}
-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:
+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:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -80,23 +84,21 @@ these options at the beginning in brackets:
Let us start with the basic coordinate systems.
\begin{coordinatesystem}{canvas}
- The simplest way of specifying a coordinate is to use the |canvas|
- coordinate system. You provide a dimension $d_x$ using the |x=|
- option and another dimension $d_y$ using the |y=| option. The position on
- the canvas is located at the position that is $d_x$ to the right and
- $d_y$ above the origin.
-
- \begin{key}{/tikz/cs/x=\meta{dimension} (initially 0pt)}
- Distance by which the coordinate
- is to the right of the origin. You can also write things like
- |1cm+2pt| since the mathematical engine is used to evaluate the
- \meta{dimension}.
- \end{key}
-
- \begin{key}{/tikz/cs/y=\meta{dimension} (initially 0pt)}
- Distance by which the coordinate
- is above the origin.
- \end{key}
+ The simplest way of specifying a coordinate is to use the |canvas|
+ coordinate system. You provide a dimension $d_x$ using the |x=| option and
+ another dimension $d_y$ using the |y=| option. The position on the canvas
+ is located at the position that is $d_x$ to the right and $d_y$ above the
+ origin.
+
+ \begin{key}{/tikz/cs/x=\meta{dimension} (initially 0pt)}
+ Distance by which the coordinate is to the right of the origin. You can
+ also write things like |1cm+2pt| since the mathematical engine is used
+ to evaluate the \meta{dimension}.
+ \end{key}
+
+ \begin{key}{/tikz/cs/y=\meta{dimension} (initially 0pt)}
+ Distance by which the coordinate is above the origin.
+ \end{key}
\begin{codeexample}[]
\begin{tikzpicture}
@@ -107,9 +109,10 @@ Let us start with the basic coordinate systems.
\end{tikzpicture}
\end{codeexample}
- To specify a coordinate in the coordinate system implicitly, you use
- two dimensions that are separated by a comma as in |(0cm,3pt)| or
- |(2cm,\textheight)|.
+ To specify a coordinate in the coordinate system implicitly, you use two
+ dimensions that are separated by a comma as in |(0cm,3pt)| or
+ |(2cm,\textheight)|.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -118,28 +121,31 @@ Let us start with the basic coordinate systems.
\fill (2cm,-5mm+2pt) circle (2pt);
\end{tikzpicture}
\end{codeexample}
+ %
\end{coordinatesystem}
-
\begin{coordinatesystem}{xyz}
- The |xyz| coordinate system allows you to specify a point as a
- multiple of three vectors called the $x$-, $y$-, and
- $z$-vectors. By default, the $x$-vector points 1cm to the right,
- the $y$-vector points 1cm upwards, but this can be changed
- arbitrarily as explained in Section~\ref{section-xyz}. The default
- $z$-vector points to $\bigl(-3.85\textrm{mm},-3.85\textrm{mm}\bigr)$.
-
- To specify the factors by which the vectors should be multiplied
- before being added, you use the following three options:
- \begin{key}{/tikz/cs/x=\meta{factor} (initially 0)}
- Factor by which the $x$-vector is multiplied.
- \end{key}
- \begin{key}{/tikz/cs/y=\meta{factor} (initially 0)}
- Works like |x|.
- \end{key}
- \begin{key}{/tikz/cs/z=\meta{factor} (initially 0)}
- Works like |x|.
- \end{key}
+ The |xyz| coordinate system allows you to specify a point as a multiple of
+ three vectors called the $x$-, $y$-, and $z$-vectors. By default, the
+ $x$-vector points 1cm to the right, the $y$-vector points 1cm upwards, but
+ this can be changed arbitrarily as explained in Section~\ref{section-xyz}.
+ The default $z$-vector points to
+ $\bigl(-3.85\textrm{mm},-3.85\textrm{mm}\bigr)$.
+
+ To specify the factors by which the vectors should be multiplied before
+ being added, you use the following three options:
+ %
+ \begin{key}{/tikz/cs/x=\meta{factor} (initially 0)}
+ Factor by which the $x$-vector is multiplied.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/y=\meta{factor} (initially 0)}
+ Works like |x|.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/z=\meta{factor} (initially 0)}
+ Works like |x|.
+ \end{key}
\begin{codeexample}[]
\begin{tikzpicture}[->]
@@ -149,9 +155,9 @@ Let us start with the basic coordinate systems.
\end{tikzpicture}
\end{codeexample}
- This coordinate system can also be selected implicitly. To do so,
- you just provide two or three comma-separated factors (not
- dimensions).
+ This coordinate system can also be selected implicitly. To do so, you just
+ provide two or three comma-separated factors (not dimensions).
+ %
\begin{codeexample}[]
\begin{tikzpicture}[->]
\draw (0,0) -- (1,0);
@@ -159,101 +165,104 @@ Let us start with the basic coordinate systems.
\draw (0,0) -- (0,0,1);
\end{tikzpicture}
\end{codeexample}
+ %
\end{coordinatesystem}
-\emph{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
-|(|\meta{x}|,|\meta{y}|)|, then \meta{x} and \meta{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 \meta{x} has a dimension and \meta{y} has not, then the
-sum of two coordinate |(|\meta{x}|,0pt)| and |(0,|\meta{y}|)| is
-used. If \meta{y} has a dimension and \meta{x} has not, then the sum
-of two coordinate |(|\meta{x}|,0)| and |(0pt,|\meta{y}|)| is used.
-
-\emph{Note furthermore:} An expression like |(2+3cm,0)| does
-\emph{not} mean the same as |(2cm+3cm,0)|. Instead, if \meta{x} or
-\meta{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|.
+\emph{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 |(|\meta{x}|,|\meta{y}|)|, then
+\meta{x} and \meta{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 \meta{x} has a dimension and \meta{y} has not, then the sum
+of two coordinate |(|\meta{x}|,0pt)| and |(0,|\meta{y}|)| is used. If \meta{y}
+has a dimension and \meta{x} has not, then the sum of two coordinate
+|(|\meta{x}|,0)| and |(0pt,|\meta{y}|)| is used.
+
+\emph{Note furthermore:} An expression like |(2+3cm,0)| does \emph{not} mean
+the same as |(2cm+3cm,0)|. Instead, if \meta{x} or \meta{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|.
\begin{coordinatesystem}{canvas polar}
- The |canvas polar| coordinate system allows you to specify
- polar coordinates. You provide an angle using the |angle=| option
- and a radius using the |radius=| option. This yields the point on
- the canvas that is at the given radius distance from the origin at
- the given degree. An angle of zero degrees to the right, a degree of
- 90 upward.
- \begin{key}{/tikz/cs/angle=\meta{degrees}}
- The angle of the coordinate.
- The angle must always be given in degrees and should be between
- $-360$ and $720$.
- \end{key}
- \begin{key}{/tikz/cs/radius=\meta{dimension}}
- The distance from the origin.
- \end{key}
- \begin{key}{/tikz/cs/x radius=\meta{dimension}}
- A polar coordinate is,
- after all, just a point on a circle of the given \meta{radius}. When
- you provide an $x$-radius and also a $y$-radius, you specify an
- ellipse instead of a circle. The |radius| option has the same effect
- as specifying identical |x radius| and |y radius| options.
- \end{key}
- \begin{key}{/tikz/cs/y radius=\meta{dimension}}
- Works like |x radius|.
- \end{key}
+ The |canvas polar| coordinate system allows you to specify polar
+ coordinates. You provide an angle using the |angle=| option and a radius
+ using the |radius=| option. This yields the point on the canvas that is at
+ the given radius distance from the origin at the given degree. An angle of
+ zero degrees to the right, a degree of 90 upward.
+ %
+ \begin{key}{/tikz/cs/angle=\meta{degrees}}
+ The angle of the coordinate. The angle must always be given in degrees
+ and should be between $-360$ and $720$.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/radius=\meta{dimension}}
+ The distance from the origin.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/x radius=\meta{dimension}}
+ A polar coordinate is, after all, just a point on a circle of the given
+ \meta{radius}. When you provide an $x$-radius and also a $y$-radius,
+ you specify an ellipse instead of a circle. The |radius| option has the
+ same effect as specifying identical |x radius| and |y radius| options.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/y radius=\meta{dimension}}
+ Works like |x radius|.
+ \end{key}
+ %
\begin{codeexample}[]
\tikz \draw (0,0) -- (canvas polar cs:angle=30,radius=1cm);
\end{codeexample}
- The implicit form for canvas polar coordinates is the following:
- you specify the angle and the distance, separated by a colon as in
- |(30:1cm)|.
-
+ The implicit form for canvas polar coordinates is the following: you
+ specify the angle and the distance, separated by a colon as in |(30:1cm)|.
+ %
\begin{codeexample}[]
\tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm)
-- (120:1cm) -- (150:1cm) -- (180:1cm);
\end{codeexample}
- Two different radii are specified by writing |(30:1cm and 2cm)|.
+ Two different radii are specified by writing |(30:1cm and 2cm)|.
- For the implicit form, instead of an angle given as a number you can
- also use certain words. For example, |up| is the same as |90|, so
- that you can write |\tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);|
- and get \tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);. Apart from |up|
- you can use |down|, |left|, |right|, |north|, |south|, |west|, |east|,
- |north east|, |north west|, |south east|, |south west|, all of which
- have their natural meaning.
+ For the implicit form, instead of an angle given as a number you can also
+ use certain words. For example, |up| is the same as |90|, so that you can
+ write |\tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);| and get
+ \tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);. Apart from |up| you can use
+ |down|, |left|, |right|, |north|, |south|, |west|, |east|, |north east|,
+ |north west|, |south east|, |south west|, all of which have their natural
+ meaning.
\end{coordinatesystem}
\begin{coordinatesystem}{xyz polar}
- This coordinate system work similarly to the |canvas polar|
- system. However, the radius and the angle are interpreted in the
- $xy$-coordinate system, not in the canvas system. More detailed,
- consider the circle or ellipse whose half axes are given by the
- current $x$-vector and the current $y$-vector. Then, consider the
- point that lies at a given angle on this ellipse, where an angle of
- zero is the same as the $x$-vector and an angle of 90 is the
- $y$-vector. Finally, multiply the resulting vector by the given
- radius factor. Voil\`a.
- \begin{key}{/tikz/cs/angle=\meta{degrees}}
- The angle of the coordinate
- interpreted in the ellipse whose axes are the $x$-vector and the
- $y$-vector.
- \end{key}
- \begin{key}{/tikz/cs/radius=\meta{factor}}
- A factor by which the $x$-vector
- and $y$-vector are multiplied prior to forming the ellipse.
- \end{key}
- \begin{key}{/tikz/cs/x radius=\meta{dimension}} A specific factor by
- which only the $x$-vector is multiplied.
- \end{key}
- \begin{key}{/tikz/cs/y radius=\meta{dimension}}
- Works like |x radius|.
- \end{key}
+ This coordinate system work similarly to the |canvas polar| system.
+ However, the radius and the angle are interpreted in the $xy$-coordinate
+ system, not in the canvas system. More detailed, consider the circle or
+ ellipse whose half axes are given by the current $x$-vector and the current
+ $y$-vector. Then, consider the point that lies at a given angle on this
+ ellipse, where an angle of zero is the same as the $x$-vector and an angle
+ of 90 is the $y$-vector. Finally, multiply the resulting vector by the
+ given radius factor. Voil\`a.
+ %
+ \begin{key}{/tikz/cs/angle=\meta{degrees}}
+ The angle of the coordinate interpreted in the ellipse whose axes are
+ the $x$-vector and the $y$-vector.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/radius=\meta{factor}}
+ A factor by which the $x$-vector and $y$-vector are multiplied prior to
+ forming the ellipse.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/x radius=\meta{dimension}}
+ A specific factor by which only the $x$-vector is multiplied.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/y radius=\meta{dimension}}
+ Works like |x radius|.
+ \end{key}
+ %
\begin{codeexample}[]
\begin{tikzpicture}[x=1.5cm,y=1cm]
\draw[help lines] (0cm,0cm) grid (3cm,2cm);
@@ -270,53 +279,53 @@ by interpreting them as |pt|. So, |2+3cm| is the same dimension as
\end{tikzpicture}
\end{codeexample}
- The implicit version of this option is the same as the implicit
- version of |canvas polar|, only you do not provide a unit.
+ The implicit version of this option is the same as the implicit version of
+ |canvas polar|, only you do not provide a unit.
\begin{codeexample}[]
\tikz[x={(0cm,1cm)},y={(-1cm,0cm)}]
\draw (0,0) -- (30:1) -- (60:1) -- (90:1)
-- (120:1) -- (150:1) -- (180:1);
\end{codeexample}
+ %
\end{coordinatesystem}
\begin{coordinatesystem}{xy polar}
- This is just an alias for |xyz polar|, which some people might
- prefer as there is no z-coordinate involved in the |xyz polar|
- coordinates.
+ This is just an alias for |xyz polar|, which some people might prefer as
+ there is no z-coordinate involved in the |xyz polar| coordinates.
\end{coordinatesystem}
\subsubsection{Barycentric Systems}
\label{section-barycentric-coordinates}
-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$, \dots, $v_n$ and numbers $\alpha_1$, $\alpha_2$,
-\dots, $\alpha_n$. Then the barycentric coordinate specified by these
-vectors and numbers is
+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$, \dots, $v_n$ and numbers $\alpha_1$, $\alpha_2$, \dots, $\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}
+ \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.
\begin{coordinatesystem}{barycentric}
- For this coordinate system, the \meta{coordinate specification}
- should be a comma-separated list of expressions of the form
- \meta{node name}|=|\meta{number}. Note that (currently) the list
- should not contain any spaces before or after the \meta{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 \meta{node name}. The number is the \meta{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
- \texttt{\string\coordinate (mynorth) at (mynode.north);}.)
-
+ For this coordinate system, the \meta{coordinate specification} should be a
+ comma-separated list of expressions of the form \meta{node
+ name}|=|\meta{number}. Note that (currently) the list should not contain
+ any spaces before or after the \meta{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 \meta{node
+ name}. The number is the \meta{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 \texttt{\string\coordinate (mynorth) at
+ (mynode.north);}.)
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\coordinate (content) at (90:3cm);
@@ -342,30 +351,35 @@ The |barycentric cs| allows you to specify such coordinates easily.
\node at (barycentric cs:content=1 ,structure=0.05,form=0.05) {ASCII};
\end{tikzpicture}
\end{codeexample}
+ %
\end{coordinatesystem}
+
\subsubsection{Node Coordinate System}
\label{section-node-coordinates}
-In \pgfname\ and in \tikzname\ 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:
+In \pgfname\ and in \tikzname\ 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:
\begin{coordinatesystem}{node}
- This coordinate system is used to reference a specific point inside
- or on the border of a previously defined node. It can be used in
- different ways, so let us go over them one by one.
-
- You can use three options to specify which coordinate you mean:
- \begin{key}{/tikz/cs/name=\meta{node name}}
- Specifies the node that you wish to use to specify a coordinate.
- The \meta{node name} is
- the name that was previously used to name the node using the
- |name=|\meta{node name} option or the special node name syntax.
- \end{key}
- \begin{key}{/tikz/anchor=\meta{anchor}}
- Specifies an anchor of the node. Here is an example:
+ This coordinate system is used to reference a specific point inside or on
+ the border of a previously defined node. It can be used in different ways,
+ so let us go over them one by one.
+
+ You can use three options to specify which coordinate you mean:
+ %
+ \begin{key}{/tikz/cs/name=\meta{node name}}
+ Specifies the node that you wish to use to specify a coordinate. The
+ \meta{node name} is the name that was previously used to name the node
+ using the |name=|\meta{node name} option or the special node name
+ syntax.
+ \end{key}
+ %
+ \begin{key}{/tikz/anchor=\meta{anchor}}
+ Specifies an anchor of the node. Here is an example:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\node (shape) at (0,2) [draw] {|class Shape|};
@@ -380,12 +394,13 @@ you use the following coordinate system:
|- (0,1) -| (node cs:name=shape,anchor=south);
\end{tikzpicture}
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/cs/angle=\meta{degrees}}
- It is also possible to provide an angle \emph{instead} of an
- anchor. This coordinate refers to a point of the node's
- border where a ray shot from the center
- in the given angle hits the border. Here is an example:
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/angle=\meta{degrees}}
+ It is also possible to provide an angle \emph{instead} of an anchor.
+ This coordinate refers to a point of the node's border where a ray shot
+ from the center in the given angle hits the border. Here is an example:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\node (start) [draw,shape=ellipse] {start};
@@ -394,12 +409,12 @@ you use the following coordinate system:
.. controls +(\angle:1cm) and +(-1,0) .. (2.5,0);
\end{tikzpicture}
\end{codeexample}
- \end{key}
-
- It is possible to provide \emph{neither} the |anchor=| option nor
- the |angle=| option. In this case, \tikzname\ will calculate an
- appropriate border position for you. Here is an example:
+ \end{key}
+ It is possible to provide \emph{neither} the |anchor=| option nor the
+ |angle=| option. In this case, \tikzname\ will calculate an appropriate
+ border position for you. Here is an example:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\path (0,0) node(a) [ellipse,rotate=10,draw] {An ellipse}
@@ -408,35 +423,34 @@ you use the following coordinate system:
\end{tikzpicture}
\end{codeexample}
- \tikzname\ will be reasonably clever at determining the border points that
- you ``mean,'' but, naturally, this may fail in some situations. If
- \tikzname\ fails to determine an appropriate border point, the center will
- be used instead.
-
- Automatic computation of anchors works only with the line-to operations
- |--|, the vertical/horizontal versions \verb!|-! and \verb!-|!, and
- with the curve-to operation |..|. For other path commands, such as
- |parabola| or |plot|, the center will be used. If this is not desired,
- you should give a named anchor or an angle anchor.
-
- Note that if you use an automatic coordinate for both the start and
- the end of a line-to, as in |--(node cs:name=b)--|, then \emph{two}
- border coordinates are computed with a move-to between them. This
- is usually exactly what you want.
-
- If you use relative coordinates together with automatic anchor
- coordinates, the relative coordinates are computed relative to
- the node's center, not relative to the border point. Here is an
- example:
-
+ \tikzname\ will be reasonably clever at determining the border points that
+ you ``mean'', but, naturally, this may fail in some situations. If
+ \tikzname\ fails to determine an appropriate border point, the center will
+ be used instead.
+
+ Automatic computation of anchors works only with the line-to operations
+ |--|, the vertical/horizontal versions \verb!|-! and \verb!-|!, and with
+ the curve-to operation |..|. For other path commands, such as |parabola| or
+ |plot|, the center will be used. If this is not desired, you should give a
+ named anchor or an angle anchor.
+
+ Note that if you use an automatic coordinate for both the start and the end
+ of a line-to, as in |--(node cs:name=b)--|, then \emph{two} border
+ coordinates are computed with a move-to between them. This is usually
+ exactly what you want.
+
+ If you use relative coordinates together with automatic anchor coordinates,
+ the relative coordinates are computed relative to the node's center, not
+ relative to the border point. Here is an example:
+ %
\begin{codeexample}[]
\tikz \draw (0,0) node(x) [draw] {Text}
rectangle (1,1)
(node cs:name=x) -- +(1,1);
\end{codeexample}
-Similarly, in the following examples both control points are $(1,1)$:
-
+ Similarly, in the following examples both control points are $(1,1)$:
+ %
\begin{codeexample}[]
\tikz \draw (0,0) node(x) [draw] {X}
(2,0) node(y) {Y}
@@ -444,12 +458,13 @@ Similarly, in the following examples both control points are $(1,1)$:
(node cs:name=y);
\end{codeexample}
- The implicit way of specifying the node coordinate system is to
- simply use the name of the node in parentheses as in |(a)| or to
- specify a name together with an anchor or an angle separated by a
- dot as in |(a.north)| or |(a.10)|.
+ The implicit way of specifying the node coordinate system is to simply use
+ the name of the node in parentheses as in |(a)| or to specify a name
+ together with an anchor or an angle separated by a dot as in |(a.north)| or
+ |(a.10)|.
- Here is a more complete example:
+ Here is a more complete example:
+ %
\begin{codeexample}[]
\begin{tikzpicture}[fill=blue!20]
\draw[help lines] (-1,-2) grid (6,3);
@@ -462,17 +477,19 @@ Similarly, in the following examples both control points are $(1,1)$:
\draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d);
\end{tikzpicture}
\end{codeexample}
+ %
\end{coordinatesystem}
-
+% -----------------------------------------------------------------------------
% Deprecated:
-
+% -----------------------------------------------------------------------------
+%
% \subsubsection{Intersection Coordinate Systems}
-
+%
% Often you wish to specify a point that is on the
% intersection of two lines or shapes. For this, the following
% coordinate system is useful:
-
+%
% \begin{coordinatesystem}{intersection}
% First, you must specify two objects that should be
% intersected. These ``objects'' can either be lines or the shapes of
@@ -489,7 +506,7 @@ Similarly, in the following examples both control points are $(1,1)$:
% Specifies that the first object is a previously defined node named
% \meta{node}.
% \end{key}
-
+%
% To specify the second object, you use one of the following keys:
% \begin{key}{/tikz/cs/second line={\ttfamily\char`\{}|(|\meta{first
% coordinate}|)--(|\meta{second coordinate}|)|{\ttfamily\char`\}}}
@@ -499,7 +516,7 @@ Similarly, in the following examples both control points are $(1,1)$:
% Specifies that the second object is a previously defined node
% named \meta{node}.
% \end{key}
-
+%
% Since it is possible that two objects have multiple intersections,
% you may need to specify which solution you want:
% \begin{key}{/tikz/cs/solution=\meta{number} (initially 1)}
@@ -508,19 +525,19 @@ Similarly, in the following examples both control points are $(1,1)$:
% The coordinate specified in this way is the \meta{number}th
% intersection of the two objects. If the objects do not intersect,
% an error may occur.
-
+%
% \begin{codeexample}[]
% \begin{tikzpicture}
% \draw[help lines] (0,0) grid (3,2);
% \draw (0,0) coordinate (A) -- (3,2) coordinate (B)
% (1,2) -- (3,0);
-
+%
% \fill[red] (intersection cs:
% first line={(A)--(B)},
% second line={(1,2)--(3,0)}) circle (2pt);
% \end{tikzpicture}
% \end{codeexample}
-
+%
% The implicit way of specifying this coordinate system is to write
% \declare{|(intersection |\opt{\meta{number}}| of |\meta{first
% object}%
@@ -534,7 +551,7 @@ Similarly, in the following examples both control points are $(1,1)$:
% |(intersection 2 of c_1 and c_2)| for the second
% intersection of the node named |c_1| and the node named
% |c_2|.
-
+%
% \tikzname\ needs an explicit algorithm for computing the
% intersection of two shapes and such an algorithm is available only
% for few shapes. Currently, the following intersection will be
@@ -548,59 +565,62 @@ Similarly, in the following examples both control points are $(1,1)$:
% \begin{tikzpicture}[scale=.25]
% \coordinate [label=-135:$a$] (a) at ($ (0,0) + (rand,rand) $);
% \coordinate [label=45:$b$] (b) at ($ (3,2) + (rand,rand) $);
-
+%
% \coordinate [label=-135:$u$] (u) at (-1,1);
% \coordinate [label=45:$v$] (v) at (6,0);
-
+%
% \draw (a) -- (b)
% (u) -- (v);
-
+%
% \node (c1) at (a) [draw,circle through=(b)] {};
% \node (c2) at (b) [draw,circle through=(a)] {};
-
+%
% \coordinate [label=135:$c$] (c) at (intersection 2 of c1 and c2);
% \coordinate [label=-45:$d$] (d) at (intersection of u--v and c2);
% \coordinate [label=135:$e$] (e) at (intersection of u--v and a--b);
-
+%
% \foreach \p in {a,b,c,d,e,u,v}
% \fill [opacity=.5] (\p) circle (8pt);
% \end{tikzpicture}
% \end{codeexample}
% \end{coordinatesystem}
+% -----------------------------------------------------------------------------
\subsubsection{Tangent Coordinate Systems}
\begin{coordinatesystem}{tangent}
- This coordinate system, which is available only when the \tikzname\
- library |calc| is loaded, allows you to compute the point that lies
- tangent to a shape. In detail, consider a \meta{node} and a
- \meta{point}. Now, draw a straight line from the \meta{point} so
- that it ``touches'' the \meta{node} (more formally, so that it is
- \emph{tangent} to this \meta{node}). The point where the line
- touches the shape is the point referred to by the |tangent|
- coordinate system.
-
- The following options may be given:
- \begin{key}{/tikz/cs/node=\meta{node}}
- This key specifies the node on whose border the tangent should
- lie.
- \end{key}
- \begin{key}{/tikz/cs/point=\meta{point}}
- This key specifies the point through which the tangent should go.
- \end{key}
- \begin{key}{/tikz/cs/solution=\meta{number}}
- Specifies which solution should be used if there are more than one.
- \end{key}
-
- A special algorithm is needed in order to compute the tangent for a
- given shape. Currently, tangents can be computed for nodes whose
- shape is one of the following:
- \begin{itemize}
- \item |coordinate|
- \item |circle|
- \end{itemize}
-
+ This coordinate system, which is available only when the \tikzname\ library
+ |calc| is loaded, allows you to compute the point that lies tangent to a
+ shape. In detail, consider a \meta{node} and a \meta{point}. Now, draw a
+ straight line from the \meta{point} so that it ``touches'' the \meta{node}
+ (more formally, so that it is \emph{tangent} to this \meta{node}). The
+ point where the line touches the shape is the point referred to by the
+ |tangent| coordinate system.
+
+ The following options may be given:
+ %
+ \begin{key}{/tikz/cs/node=\meta{node}}
+ This key specifies the node on whose border the tangent should lie.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/point=\meta{point}}
+ This key specifies the point through which the tangent should go.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/solution=\meta{number}}
+ Specifies which solution should be used if there are more than one.
+ \end{key}
+
+ A special algorithm is needed in order to compute the tangent for a given
+ shape. Currently, tangents can be computed for nodes whose shape is one of
+ the following:
+ %
+ \begin{itemize}
+ \item |coordinate|
+ \item |circle|
+ \end{itemize}
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw[help lines] (0,0) grid (3,2);
@@ -614,36 +634,31 @@ Similarly, in the following examples both control points are $(1,1)$:
\end{tikzpicture}
\end{codeexample}
- There is no implicit syntax for this coordinate system.
+ There is no implicit syntax for this coordinate system.
\end{coordinatesystem}
-
\subsubsection{Defining New Coordinate Systems}
-While the set of coordinate systems that \tikzname\ 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:
+While the set of coordinate systems that \tikzname\ 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:
\begin{command}{\tikzdeclarecoordinatesystem\marg{name}\marg{code}}
- This command declares a new coordinate system named \meta{name} that
- can later on be used by writing
- |(|\meta{name}| cs:|\meta{arguments}|)|. When \tikzname\ encounters a coordinate
- specified in this way, the \meta{arguments} are passed to
- \meta{code} as argument |#1|.
-
- It is now the job of \meta{code} to make sense of the
- \meta{arguments}. At the end of \meta{code}, the two \TeX\ 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 \meta{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.
+ This command declares a new coordinate system named \meta{name} that can
+ later on be used by writing |(|\meta{name}| cs:|\meta{arguments}|)|. When
+ \tikzname\ encounters a coordinate specified in this way, the
+ \meta{arguments} are passed to \meta{code} as argument |#1|.
+
+ It is now the job of \meta{code} to make sense of the \meta{arguments}. At
+ the end of \meta{code}, the two \TeX\ 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 \meta{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.
+ %
\begin{codeexample}[]
\makeatletter
\define@key{cylindricalkeys}{angle}{\def\myangle{#1}}
@@ -660,53 +675,53 @@ commands are used:
\fill (cylindrical cs:angle=\num,radius=1,z=\num) circle (1pt);
\end{tikzpicture}
\end{codeexample}
+ %
\end{command}
\begin{command}{\tikzaliascoordinatesystem\marg{new name}\marg{old name}}
- Creates an alias of \meta{old name}.
+ Creates an alias of \meta{old name}.
\end{command}
-
\subsection{Coordinates at Intersections}
\label{section-intersection-coordinates}
-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 |intersection| library can be used.
+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 |intersection|
+library can be used.
\subsubsection{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.
+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.
\begin{coordinatesystem}{perpendicular}
- You can specify the two lines using the following keys:
-
- \begin{key}{/tikz/cs/horizontal line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
- Specifies that one line is a horizontal line that goes through the
- given coordinate.
- \end{key}
- \begin{key}{/tikz/cs/vertical line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
- Specifies that the other line is vertical and goes through the
- given coordinate.
- \end{key}
-
- However, in almost all cases you should, instead, use the implicit
- syntax. Here, you write \declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or
- \declare{|(|\meta{q}\verb! -| !\meta{p}|)|}.
-
- For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield
- the same as \verb!(2,4)! (provided the $xy$-co\-or\-di\-nate 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:
-
+ You can specify the two lines using the following keys:
+
+ \begin{key}{/tikz/cs/horizontal line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
+ Specifies that one line is a horizontal line that goes through the
+ given coordinate.
+ \end{key}
+ %
+ \begin{key}{/tikz/cs/vertical line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
+ Specifies that the other line is vertical and goes through the given
+ coordinate.
+ \end{key}
+
+ However, in almost all cases you should, instead, use the implicit syntax.
+ Here, you write \declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or
+ \declare{|(|\meta{q}\verb! -| !\meta{p}|)|}.
+
+ For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield the
+ same as \verb!(2,4)! (provided the $xy$-co\-or\-di\-nate 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:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\path (30:1cm) node(p1) {$p_1$} (75:1cm) node(p2) {$p_2$};
@@ -721,16 +736,16 @@ coordinate system.
\end{tikzpicture}
\end{codeexample}
- Note that in \declare{|(|\meta{c}\verb! |- !\meta{d}|)|} the
- coordinates \meta{c} and \meta{d} are \emph{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.
+ Note that in \declare{|(|\meta{c}\verb! |- !\meta{d}|)|} the coordinates
+ \meta{c} and \meta{d} are \emph{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$:
+ 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$:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\node (A) at (0,1) {A};
@@ -742,52 +757,54 @@ coordinate system.
\draw (C) -- (D) node [midway] {x};
\node at ({$(A)!.5!(B)$} -| {$(C)!.5!(D)$}) {X};
-\end{tikzpicture}
+\end{tikzpicture}
\end{codeexample}
+ %
\end{coordinatesystem}
\subsubsection{Intersections of Arbitrary Paths}
\begin{tikzlibrary}{intersections}
- This library enables the calculation of intersections of
- two arbitrary paths. However, due to the low accuracy of
- \TeX, the paths should not be ``too complicated''.
- In particular, you should not try to intersect paths consisting of
- lots of very small segments such as plots or decorated paths.
+ This library enables the calculation of intersections of two arbitrary
+ paths. However, due to the low accuracy of \TeX, the paths should not be
+ ``too complicated''. In particular, you should not try to intersect paths
+ consisting of lots of very small segments such as plots or decorated paths.
\end{tikzlibrary}
-To find the intersections of two paths in \tikzname, they must be
-``named''. A ``named path'' is, quite simply, a path that has been
-named using the following key:
+To find the intersections of two paths in \tikzname, 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 \emph{different} key from the |name| key, which only
+attaches a hyperlink target to a path, but does not store the path in a way the
+is useful for the intersection computation):
\begin{keylist}{%
- /tikz/name path=\meta{name},
- /tikz/name path global=\meta{name}}
- The effect of this key is that, after the path has been constructed,
- just before it is used, it is associated with \meta{name}. For |name path|,
- this association survives beyond the final semi-colon of the path
- but not the end of the surrounding scope. For |name path global|, the association
- will survive beyond any scope as well. Handle with care.
-
- Any paths created by nodes on the (main) path are ignored, unless
- this key is explicitly used. If the same \meta{name} is used for the
- main path and the node path(s), then the paths will be added
- together and then associated with \meta{name}.
+ /tikz/name path=\meta{name},
+ /tikz/name path global=\meta{name}%
+}
+ The effect of this key is that, after the path has been constructed, just
+ before it is used, it is associated with \meta{name}. For |name path|, this
+ association survives beyond the final semi-colon of the path but not the
+ end of the surrounding scope. For |name path global|, the association will
+ survive beyond any scope as well. Handle with care.
+
+ Any paths created by nodes on the (main) path are ignored, unless this key
+ is explicitly used. If the same \meta{name} is used for the main path and
+ the node path(s), then the paths will be added together and then associated
+ with \meta{name}.
\end{keylist}
To find the intersection of named paths, the following key is used:
\begin{key}{/tikz/name intersections=\marg{options}}
- This key changes the key path to |/tikz/intersection| and processes
- \meta{options}. These options determine, among other things,
- which paths to use for the intersection. Having processed the
- options, any intersections are then found. A coordinate is created
- at each intersection, which by default, will be named
- |intersection-1|, |intersection-2|, and so on.
- Optionally, the prefix |intersection| can be changed, and the
- total number of intersections stored in a \TeX-macro.
-
+ This key changes the key path to |/tikz/intersection| and processes
+ \meta{options}. These options determine, among other things, which paths to
+ use for the intersection. Having processed the options, any intersections
+ are then found. A coordinate is created at each intersection, which by
+ default, will be named |intersection-1|, |intersection-2|, and so on.
+ Optionally, the prefix |intersection| can be changed, and the total number
+ of intersections stored in a \TeX-macro.
+ %
\begin{codeexample}[]
\begin{tikzpicture}[every node/.style={opacity=1, black, above left}]
\draw [help lines] grid (3,2);
@@ -799,22 +816,22 @@ To find the intersection of named paths, the following key is used:
\end{tikzpicture}
\end{codeexample}
-The following keys can be used in \meta{options}:
+ The following keys can be used in \meta{options}:
-\begin{key}{/tikz/intersection/of=\meta{name path 1}| and |\meta{name path 2}}
- This key is used to specify the names of the paths to use for
- the intersection.
-\end{key}
+ \begin{key}{/tikz/intersection/of=\meta{name path 1}| and |\meta{name path 2}}
+ This key is used to specify the names of the paths to use for the
+ intersection.
+ \end{key}
-\begin{key}{/tikz/intersection/name=\meta{prefix} (initially intersection)}
- This key specifies the prefix name for the coordinate nodes placed
- at each intersection.
-\end{key}
+ \begin{key}{/tikz/intersection/name=\meta{prefix} (initially intersection)}
+ This key specifies the prefix name for the coordinate nodes placed at
+ each intersection.
+ \end{key}
-\begin{key}{/tikz/intersection/total=\meta{macro}}
- This key means that the total number of intersections found
- will be stored in \meta{macro}.
-\end{key}
+ \begin{key}{/tikz/intersection/total=\meta{macro}}
+ This key means that the total number of intersections found will be
+ stored in \meta{macro}.
+ \end{key}
\begin{codeexample}[]
\begin{tikzpicture}
@@ -828,16 +845,15 @@ The following keys can be used in \meta{options}:
\end{tikzpicture}
\end{codeexample}
-
- \begin{key}{/tikz/intersection/by=\meta{comma-separated list}}
- This key allows you to specify a list of names for the intersection
- coordinates. The intersection coordinates will still be named
- \meta{prefix}|-|\meta{number}, but additionally the first
- coordinate will also be named by the first element of the
- \meta{comma-separated list}. What happens is that the
- \meta{comma-separated list} is passed to the |\foreach| statement
- and for \meta{list member} a coordinate is created at the
- already-named intersection.
+ \begin{key}{/tikz/intersection/by=\meta{comma-separated list}}
+ This key allows you to specify a list of names for the intersection
+ coordinates. The intersection coordinates will still be named
+ \meta{prefix}|-|\meta{number}, but additionally the first coordinate
+ will also be named by the first element of the \meta{comma-separated
+ list}. What happens is that the \meta{comma-separated list} is passed
+ to the |\foreach| statement and for \meta{list member} a coordinate is
+ created at the already-named intersection.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\clip (-2,-2) rectangle (2,2);
@@ -850,14 +866,14 @@ The following keys can be used in \meta{options}:
\end{tikzpicture}
\end{codeexample}
- You can also use the |...| notation of the |\foreach| statement
- inside the \meta{comma-separated list}.
+ You can also use the |...| notation of the |\foreach| statement inside
+ the \meta{comma-separated list}.
- In case an element of the \meta{comma-separated list} starts with
- options in square brackets, these options are used when the
- coordinate is created. A coordinate name can still, but need not,
- follow the options. This
- makes it easy to add labels to intersections:
+ In case an element of the \meta{comma-separated list} starts with
+ options in square brackets, these options are used when the coordinate
+ is created. A coordinate name can still, but need not, follow the
+ options. This makes it easy to add labels to intersections:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\clip (-2,-2) rectangle (2,2);
@@ -869,16 +885,16 @@ The following keys can be used in \meta{options}:
by={[label=center:a],[label=center:...],[label=center:i]}}];
\end{tikzpicture}
\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/intersection/sort by=\meta{path name}}
-By default, the intersections are simply returned in the order that
-the intersection algorithm finds them. Unfortunately, this is not
-necessarily a ``helpful'' ordering. This key can be used to sort
-the intersections along the path specified by \meta{path name},
-which should be one of the paths mentioned in the
-|/tikz/intersection/of| key.
-
+ \end{key}
+
+ \begin{key}{/tikz/intersection/sort by=\meta{path name}}
+ By default, the intersections are simply returned in the order that the
+ intersection algorithm finds them. Unfortunately, this is not
+ necessarily a ``helpful'' ordering. This key can be used to sort the
+ intersections along the path specified by \meta{path name}, which
+ should be one of the paths mentioned in the |/tikz/intersection/of|
+ key.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\clip (-0.5,-0.75) rectangle (3.25,2.25);
@@ -892,23 +908,19 @@ which should be one of the paths mentioned in the
}
\end{tikzpicture}
\end{codeexample}
-
- \end{key}
+ \end{key}
\end{key}
-
-
\subsection{Relative and Incremental Coordinates}
-
\subsubsection{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:
-
+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:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
@@ -917,11 +929,10 @@ coordinates are often useful in ``local'' contexts:
\end{tikzpicture}
\end{codeexample}
-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:
+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:
\begin{codeexample}[]
\begin{tikzpicture}
@@ -931,19 +942,17 @@ notation to specify numerous points, all relative to the same
\end{tikzpicture}
\end{codeexample}
-There is a special situation, where relative coordinates are
-interpreted differently. If you use a relative coordinate as a control
-point of a B\'ezier 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$:
+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$:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw (1,0) .. controls +(30:1cm) and +(60:1cm) .. (3,-1);
@@ -955,27 +964,29 @@ the following example, the curve ``leaves'' at $30^\circ$ and
\subsubsection{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:
+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:
\begin{key}{/tikz/turn}
- This key can be given as an option to a \meta{coordinate} as in the
- following example:
+ This key can be given as an option to a \meta{coordinate} as in the
+ following example:
+ %
\begin{codeexample}[]
-\tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm);
+\tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm);
\end{codeexample}
- 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 \meta{relative
- angle}|:|\meta{distance} together with the |turn| option, you
- specify a point that lies at \meta{distance} from the last point in
- the direction of the last tangent entering the last point, but with
- a rotation of \meta{relative angle}.
-
- This key also works with curves \dots
+ %
+ 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 \meta{relative angle}|:|\meta{distance} together
+ with the |turn| option, you specify a point that lies at \meta{distance}
+ from the last point in the direction of the last tangent entering the last
+ point, but with a rotation of \meta{relative angle}.
+
+ This key also works with curves \dots
+ %
\begin{codeexample}[]
\tikz [delta angle=30, radius=1cm]
\draw (0,0) arc [start angle=0] -- ([turn]0:1cm)
@@ -985,55 +996,58 @@ previous point. For this, the following key is useful:
\begin{codeexample}[]
\tikz \draw (0,0) to [bend left] (2,1) -- ([turn]0:1cm);
\end{codeexample}
-
- \dots and with plots \dots
+ %
+ \dots and with plots \dots
+ %
\begin{codeexample}[]
\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,0) } -- ([turn]30:1cm);
\end{codeexample}
- 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.
+ 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.
+ %
\begin{codeexample}[]
\tikz \draw (0.5,0.5) -| (2,1) -- ([turn]1,1)
.. controls ([turn]0:1cm) .. ([turn]-90:1cm);
\end{codeexample}
+ %
\end{key}
\subsubsection{Relative Coordinates and Scopes}
\label{section-scopes-relative}
-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.
+
+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.
-
-\begin{key}{/tikz/current point is local=\opt{\meta{boolean}} (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:
+``interact'' are useful, there is a (local!) option that allows you to decide
+which you need.
+
+\begin{key}{/tikz/current point is local=\opt{\meta{boolean}} (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:
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
\draw[red] (2,0) -- ++(1,0) { -- ++(0,1) } -- ++(-1,0);
\end{tikzpicture}
\end{codeexample}
- If you set this key to |true|, this behaviour 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 \tikzname\ 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 is had when the matching
- |{| was read.
+ %
+ If you set this key to |true|, this behaviour 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
+ \tikzname\ 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 is had when the matching |{| was read.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
@@ -1041,8 +1055,9 @@ decide which you need.
{ [current point is local] -- ++(0,1) } -- ++(-1,0);
\end{tikzpicture}
\end{codeexample}
- In the above example, we could also have given the option outside
- the scope, for instance as a parameter to the whole scope.
+ %
+ In the above example, we could also have given the option outside the
+ scope, for instance as a parameter to the whole scope.
\end{key}
@@ -1050,16 +1065,15 @@ decide which you need.
\label{tikz-lib-calc}
\begin{tikzlibrary}{calc}
- You need to load this library in order to use the coordinate
- calculation functions described in the present section.
+ You need to load this library in order to use the coordinate calculation
+ functions described in the present section.
\end{tikzlibrary}
-
-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|:
+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|:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1070,13 +1084,12 @@ of the point |a|:
\end{codeexample}
-
\subsubsection{The General Syntax}
The general syntax is the following:
-
+%
\begin{quote}
- \declare{|(|\opt{|[|\meta{options}|]|}|$|\meta{coordinate computation}|$)|}.
+ \declare{|(|\opt{|[|\meta{options}|]|}|$|\meta{coordinate computation}|$)|}.
\end{quote}
As you can see, the syntax uses the \TeX\ math symbol |$| to %$
@@ -1084,20 +1097,20 @@ indicate that a ``mathematical computation'' is involved. However, the |$| %$
has no other effect, in particular, no mathematical text is typeset.
The \meta{coordinate computation} has the following structure:
+%
\begin{enumerate}
-\item
- It starts with
- \begin{quote}
- \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
- \end{quote}
-\item
- This is optionally followed by |+| or |-| and then another
- \begin{quote}
- \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
- \end{quote}
-\item
- This is once more followed by |+| or |-| and another of the above
- modified coordinate; and so on.
+ \item It starts with
+ %
+ \begin{quote}
+ \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
+ \end{quote}
+ \item This is optionally followed by |+| or |-| and then another
+ %
+ \begin{quote}
+ \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
+ \end{quote}
+ \item This is once more followed by |+| or |-| and another of the above
+ modified coordinate; and so on.
\end{enumerate}
In the following, the syntax of factors and of the different modifiers
@@ -1106,29 +1119,28 @@ is explained in detail.
\subsubsection{The Syntax of Factors}
-The \meta{factor}s are optional and detected
-by checking whether the \meta{coordinate computation} starts with a
-|(|. Also, after each $\pm$ a \meta{factor} is present if, and only
-if, the |+| or |-| sign is not directly followed by~|(|.
-
-If a \meta{factor} is present, it is evaluated using the
-|\pgfmathparse| macro. This means that you can use pretty complicated
-computations inside a factor. A \meta{factor} may even contain opening
-parentheses, which creates a complication: How does \tikzname\ know
-where a \meta{factor} ends and where a coordinate starts? For
-instance, if the beginning of a \meta{coordinate computation} is
-|2*(3+4|\dots, it is not clear whether |3+4| is part of a
-\meta{coordinate} or part of a \meta{factor}. Because of this, the
-following rule is used: Once it has been determined, that a
-\meta{factor} is present, in principle, the \meta{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 \meta{factor} in curly braces. This can
-be used whenever it is unclear where the \meta{factor} would end.
-
-Here are some examples of coordinate specifications that consist of
-exactly one \meta{factor} and one \meta{coordinate}:
+The \meta{factor}s are optional and detected by checking whether the
+\meta{coordinate computation} starts with a |(|. Also, after each $\pm$ a
+\meta{factor} is present if, and only if, the |+| or |-| sign is not directly
+followed by~|(|.
+
+If a \meta{factor} is present, it is evaluated using the |\pgfmathparse| macro.
+This means that you can use pretty complicated computations inside a factor. A
+\meta{factor} may even contain opening parentheses, which creates a
+complication: How does \tikzname\ know where a \meta{factor} ends and where a
+coordinate starts? For instance, if the beginning of a \meta{coordinate
+computation} is |2*(3+4|\dots, it is not clear whether |3+4| is part of a
+\meta{coordinate} or part of a \meta{factor}. Because of this, the following
+rule is used: Once it has been determined, that a \meta{factor} is present, in
+principle, the \meta{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 \meta{factor} in curly braces. This can be used
+whenever it is unclear where the \meta{factor} would end.
+
+Here are some examples of coordinate specifications that consist of exactly one
+\meta{factor} and one \meta{coordinate}:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1141,33 +1153,33 @@ exactly one \meta{factor} and one \meta{coordinate}:
\end{codeexample}
-
\subsubsection{The Syntax of Partway Modifiers}
-A \meta{coordinate} can be followed by different \meta{modifiers}. The
-first kind of modifier is the \emph{partway modifier}. The syntax
-(which is loosely inspired by Uwe Kern's |xcolor| package) is the
-following:
+A \meta{coordinate} can be followed by different \meta{modifiers}. The first
+kind of modifier is the \emph{partway modifier}. The syntax (which is loosely
+inspired by Uwe Kern's |xcolor| package) is the following:
+%
\begin{quote}
- \meta{coordinate}\declare{|!|\meta{number}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
+ \meta{coordinate}\declare{|!|\meta{number}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
\end{quote}
+%
One could write for instance
+%
\begin{codeexample}[code only]
(1,2)!.75!(3,4)
\end{codeexample}
-The meaning of this is: ``Use the coordinate that is three quarters on
-the way from |(1,2)| to |(3,4)|.'' In general, \meta{coordinate
- x}|!|\meta{number}|!|\meta{coordinate y} yields the coordinate
-$(1-\meta{number})\meta{coordinate x} + \meta{number} \meta{coordinate
- y}$. Note that this is a bit different from the way the
-\meta{number} is interpreted in the |xcolor| package: First, you use a
-factor between $0$ and $1$, not a percentage, and, second, as the
-\meta{number} approaches $1$, we approach the second coordinate, not
-the first. It is permissible to use a \meta{number} that is smaller
-than $0$ or larger than $1$. The \meta{number} is evaluated using the
-|\pgfmathparse| command and, thus, it can involve complicated
-computations.
-
+%
+The meaning of this is: ``Use the coordinate that is three quarters on the way
+from |(1,2)| to |(3,4)|.'' In general, \meta{coordinate
+x}|!|\meta{number}|!|\meta{coordinate y} yields the coordinate $(1 -
+\meta{number})\meta{coordinate x} + \meta{number} \meta{coordinate y}$. Note
+that this is a bit different from the way the \meta{number} is interpreted in
+the |xcolor| package: First, you use a factor between $0$ and $1$, not a
+percentage, and, second, as the \meta{number} approaches $1$, we approach the
+second coordinate, not the first. It is permissible to use a \meta{number} that
+is smaller than $0$ or larger than $1$. The \meta{number} is evaluated using
+the |\pgfmathparse| command and, thus, it can involve complicated computations.
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1179,16 +1191,16 @@ computations.
\end{tikzpicture}
\end{codeexample}
-The \meta{second coordinate} may be prefixed by an \meta{angle},
-separated with a colon, as in |(1,1)!.5!60:(2,2)|. The general meaning
-of \meta{a}|!|\meta{factor}|!|\meta{angle}|:|\meta{b} is ``First,
-consider the line from \meta{a} to \meta{b}. Then rotate this line by
-\meta{angle} \emph{around the point \meta{a}}. Then the two endpoints
-of this line will be \meta{a} and some point \meta{c}. Use this point
-\meta{c} for the subsequent computation, namely the partway
-computation.''
+The \meta{second coordinate} may be prefixed by an \meta{angle}, separated with
+a colon, as in |(1,1)!.5!60:(2,2)|. The general meaning of
+\meta{a}|!|\meta{factor}|!|\meta{angle}|:|\meta{b} is: ``First, consider the
+line from \meta{a} to \meta{b}. Then rotate this line by \meta{angle}
+\emph{around the point \meta{a}}. Then the two endpoints of this line will be
+\meta{a} and some point \meta{c}. Use this point \meta{c} for the subsequent
+computation, namely the partway computation.''
Here are two examples:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,3);
@@ -1206,7 +1218,6 @@ Here are two examples:
\end{tikzpicture}
\end{codeexample}
-
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (4,4);
@@ -1216,10 +1227,9 @@ Here are two examples:
\end{tikzpicture}
\end{codeexample}
-
-You can repeatedly apply modifiers. That is, after any modifier
-you can add another (possibly different) modifier.
-
+You can repeatedly apply modifiers. That is, after any modifier you can add
+another (possibly different) modifier.
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1233,16 +1243,18 @@ you can add another (possibly different) modifier.
\subsubsection{The Syntax of Distance Modifiers}
-A \emph{distance modifier} has nearly the same syntax as a partway
-modifier, only you use a \meta{dimension} (something like |1cm|)
-instead of a \meta{factor} (something like |0.5|):
+A \emph{distance modifier} has nearly the same syntax as a partway modifier,
+only you use a \meta{dimension} (something like |1cm|) instead of a
+\meta{factor} (something like |0.5|):
+%
\begin{quote}
- \meta{coordinate}\declare{|!|\meta{dimension}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
+ \meta{coordinate}\declare{|!|\meta{dimension}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
\end{quote}
When you write \meta{a}|!|\meta{dimension}|!|\meta{b}, this means the
-following: Use the point that is distanced \meta{dimension} from
-\meta{a} on the straight line from \meta{a} to \meta{b}. Here is an example:
+following: Use the point that is distanced \meta{dimension} from \meta{a} on
+the straight line from \meta{a} to \meta{b}. Here is an example:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1254,15 +1266,15 @@ following: Use the point that is distanced \meta{dimension} from
\end{tikzpicture}
\end{codeexample}
-As before, if you use a \meta{angle}, the \meta{second coordinate} is
-rotated by this much around the \meta{coordinate} before it is used.
+As before, if you use a \meta{angle}, the \meta{second coordinate} is rotated
+by this much around the \meta{coordinate} before it is used.
-The combination of an \meta{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:
+The combination of an \meta{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:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);
@@ -1280,26 +1292,27 @@ a line from |(a)| to~|(b)| and you now wish to offset this point by
\end{codeexample}
-
\subsubsection{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 \meta{coordinate} to the \meta{second
- coordinate}. However, the \meta{number} or \meta{dimension} is replaced by a
+The projection modifier is also similar to the above modifiers: It also gives a
+point on a line from the \meta{coordinate} to the \meta{second coordinate}.
+However, the \meta{number} or \meta{dimension} is replaced by a
\meta{projection coordinate}:
+%
\begin{quote}
- \meta{coordinate}\declare{|!|\meta{projection coordinate}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
+ \meta{coordinate}\declare{|!|\meta{projection coordinate}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
\end{quote}
Here is an example:
+%
\begin{codeexample}[code only]
(1,2)!(0,5)!(3,4)
\end{codeexample}
-The effect is the following: We project the \meta{projection
- coordinate} orthogonally onto the line from \meta{coordinate} to
-\meta{second coordinate}. This makes it easy to compute projected
-points:
+The effect is the following: We project the \meta{projection coordinate}
+orthogonally onto the line from \meta{coordinate} to \meta{second coordinate}.
+This makes it easy to compute projected points:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] (0,0) grid (3,2);