diff options
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.tex | 1183 |
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); |