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 | 531 |
1 files changed, 393 insertions, 138 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 6ce31747a18..c10e98f39d5 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 @@ -1,20 +1,63 @@ -% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% Copyright 2006 by Till Tantau % -% This program can be redistributed and/or modified under the terms -% of the LaTeX Project Public License Distributed from CTAN -% archives in directory macros/latex/base/lppl.txt. - +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. \section{Specifying Coordinates} -\subsection{Coordinates and Coordinate Options} +\subsection{Overview} -A \emph{coordinate} is a position in a picture. \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} specified 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. +\end{description} + +Here is an example in which explicit the coordinate systems are +specified explicitly: +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \draw (canvas cs:x=0cm,y=2mm) + -- (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[style=help lines] (0,0) grid (3,2); + \draw (0cm,2mm) -- (30:2cm); +\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 @@ -29,82 +72,205 @@ these options at the beginning in brackets: \end{tikzpicture} \end{codeexample} -\subsection{Simple Coordinates} -The simplest way to specify coordinates is as a comma-separated pair -of \TeX\ dimensions as in |(1cm,2pt)| or |(2cm,\textheight)|. As can -be seen, different units can be mixed. The coordinate specified in -this way means ``1cm to the right and 2pt up from the origin of the -picture.'' You can also write things like |(1cm+2pt,2pt)| since the -|calc| package is used. +\subsection{Coordinate Systems} +\subsubsection{Canvas, XYZ, and Polar Coordinate Systems} -\subsection{Polar Coordinates} +Let us start with the basic coordinate systems. -You can also specify coordinates in polar coordinates. In this case, -you specify an angle and a distance, separated by a colon as in -|(30:1cm)|. The angle must always be given in degrees and should be -between $-360$ and $720$. +\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{itemize} + \itemoption{x}|=|\meta{dimension} Distance by which the coordinate + is to the right of the origin. You can also write things like + |1cm+2pt| since the |calc| package is used. + \itemoption{y}|=|\meta{dimension} Distance by which the coordinate + is above the origin. + \end{itemize} \begin{codeexample}[] -\tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm) - -- (120:1cm) -- (150:1cm) -- (180:1cm); +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + + \fill (canvas cs:x=1cm,y=1.5cm) circle (2pt); + \fill (canvas cs:x=2cm,y=-5mm+2pt) circle (2pt); +\end{tikzpicture} \end{codeexample} -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. + To specify a coordinate in the coordinate system implicitly, you use + two dimensions that are seperated by a comma as in |(0cm,3pt)| or + |(2cm,\textheight)|. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[style=help lines] (0,0) grid (3,2); + \fill (1cm,1.5cm) circle (2pt); + \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(-\frac{1}{\sqrt2} + \textrm{cm},-\frac{1}{\sqrt2}\textrm{cm}\bigr)$. + + To specify the factors by which the vectors should be multiplied + before being added, you use the following three options: + \begin{itemize} + \itemoption{x}|=|\meta{factor} Factor by which the $x$-vector is + multiplied. If this option is not given, |0| is used. + \itemoption{y}|=|\meta{factor} Works like |x|. + \itemoption{z}|=|\meta{factor} Works like |x|. + \end{itemize} +\begin{codeexample}[] +\begin{tikzpicture}[->] + \draw (0,0) -- (xyz cs:x=1); + \draw (0,0) -- (xyz cs:y=1); + \draw (0,0) -- (xyz cs:z=1); +\end{tikzpicture} +\end{codeexample} + This coordinate system can also be selected implicitly. To do so, + you just provide two or three comma-seperated factors (not + dimensions). +\begin{codeexample}[] +\begin{tikzpicture}[->] + \draw (0,0) -- (1,0); + \draw (0,0) -- (0,1,0); + \draw (0,0) -- (0,0,1); +\end{tikzpicture} +\end{codeexample} +\end{coordinatesystem} + + +\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. A degree of zero points to the right, a degree of + 90 upward. + \begin{itemize} + \itemoption{angle}|=|\meta{degrees} The angle of the coordinate. + The angle must always be given in degrees and should be between + $-360$ and $720$. + \itemoption{radius}|=|\meta{dimension} The distance from the origin. + \itemoption{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 specifiying identical |x radius| and |y radius| options. + \itemoption{y radius}|=|\meta{dimension} Works like |x radius|. + \end{itemize} +\begin{codeexample}[] +\tikz \draw (0,0) -- (canvas polar cs:angle=30,radius=1cm); +\end{codeexample} -\subsection{Xy- and Xyz-Coordinates} + The implicit form for canvas polar coodinates is the following: + you specify the angle and the distance, separated by a colon as in + |(30:1cm)|. -You can specify coordinates in \pgfname's $xy$-coordinate system. In -this case, you provide two unit-free numbers, separated by a comma as -in |(2,-3)|. This means ``add twice the current \pgfname\ $x$-vector and -subtract three times the $y$-vector.'' By default, the $x$-vector -points 1cm to the right, the $y$-vector points 1cm upwards, but this -can be changed arbitrarily using the |x| and~|y| graphic options. +\begin{codeexample}[] +\tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm) + -- (120:1cm) -- (150:1cm) -- (180:1cm); +\end{codeexample} -Similarly, you can specify coordinates in the $xyz$-coordinate -system. The only difference to the $xy$-coordinates is that you -specify three numbers separated by commas as in |(1,2,3)|. This is -interpreted as ``once the $x$-vector plus twice the $y$-vector plus -three times the $z$-vector.'' The default $z$-vector points to -$\bigl(-\frac{1}{\sqrt2} -\textrm{cm},-\frac{1}{\sqrt2}\textrm{cm}\bigr)$. Consider the -following example: + 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. +\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 detailedly, + 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ą. + \begin{itemize} + \itemoption{angle}|=|\meta{degrees} The angle of the coordinate + interpreted in the ellipse whose axes are the $x$-vector and the + $y$-vector. + \itemoption{radius}|=|\meta{factor} A factor by which the $x$-vector + and $y$-vector are multiplied prior to forming the ellipse. + \itemoption{x radius}|=|\meta{dimension} A specific factor by which + only the $x$-vector is multiplied. + \itemoption{y radius}|=|\meta{dimension} works like |x radius|. + \end{itemize} +\begin{codeexample}[] +\begin{tikzpicture}[x=1.5cm,y=1cm] + \draw[help lines] (0cm,0cm) grid (3cm,2cm); + + \draw (0,0) -- (xyz polar cs:angle=0,radius=1); + \draw (0,0) -- (xyz polar cs:angle=30,radius=1); + \draw (0,0) -- (xyz polar cs:angle=60,radius=1); + \draw (0,0) -- (xyz polar cs:angle=90,radius=1); + + \draw (xyz polar cs:angle=0,radius=2) + -- (xyz polar cs:angle=30,radius=2) + -- (xyz polar cs:angle=60,radius=2) + -- (xyz polar cs:angle=90,radius=2); + \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. \begin{codeexample}[] -\begin{tikzpicture}[->] - \draw (0,0,0) -- (1,0,0); - \draw (0,0,0) -- (0,1,0); - \draw (0,0,0) -- (0,0,1); -\end{tikzpicture} +\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 x-coordinate involved in the |xyz polar| + coordinates. +\end{coordinatesystem} -\subsection{Node Coordinates} +\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. - - -\subsubsection{Named Anchor Coordinates} - -An \emph{anchor coordinate} is a point in a node that you have -previously defined using the node operation. The syntax is -|(|\meta{node name}|.|\meta{anchor}|)|, where \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. Here is -an example: - +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{itemize} + \itemoption{name}|=|\meta{node name} specifies the node in which you + which 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. + \itemoption{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|}; @@ -112,77 +278,64 @@ an example: \node (circle) at (2,0) [draw] {|class Circle|}; \node (ellipse) at (6,0) [draw] {|class Ellipse|}; - \draw (circle.north) |- (0,1); - \draw (ellipse.north) |- (0,1); - \draw[-open triangle 90] (rect.north) |- (0,1) -| (shape.south); + \draw (node cs:name=circle,anchor=north) |- (0,1); + \draw (node cs:name=ellipse,anchor=north) |- (0,1); + \draw[-open triangle 90] (node cs:name=rect,anchor=north) + |- (0,1) -| (node cs:name=shape,anchor=south); \end{tikzpicture} \end{codeexample} - -Section~\ref{section-the-shapes} explain which anchors are available -for the basic shapes. - - - - -\subsubsection{Angle Anchor Coordinates} - -In addition to the named anchors, it is possible to use the syntax -\meta{node name}|.|\meta{angle} to name a point of the node's -border. This point is the coordinate where a ray shot from the center -in the given angle hits the border. Here is an example: - + \itemoption{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}; \foreach \angle in {-90, -80, ..., 90} - \draw (start.\angle) .. controls +(\angle:1cm) and +(-1,0) .. (2.5,0); + \draw (node cs:name=start,angle=\angle) + .. controls +(\angle:1cm) and +(-1,0) .. (2.5,0); \end{tikzpicture} \end{codeexample} + \end{itemize} - -\subsubsection{Anchor-Free Node Coordinates} - -It is also possible to just ``leave out'' the anchor and have \tikzname\ -calculate an appropriate border position for you. Here is an example: + 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}[fill=blue!20] - \draw[style=help lines] (-1,-2) grid (6,3); - \path (0,0) node(a) [ellipse,rotate=10,draw,fill] {An ellipse} - (3,-1) node(b) [circle,draw,fill] {A circle} - (2,2) node(c) [rectangle,rotate=20,draw,fill] {A rectangle} - (5,2) node(d) [rectangle,rotate=-30,draw,fill] {Another rectangle}; - \draw[thick] (a) -- (b) -- (c) -- (d); - \draw[thick,red,->] (a) |- +(1,3) -| (c) |- (b); - \draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d); +\begin{tikzpicture} + \path (0,0) node(a) [ellipse,rotate=10,draw] {An ellipse} + (3,-1) node(b) [circle,draw] {A circle}; + \draw[thick] (node cs:name=a) -- (node cs:name=b); \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 |--(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 always 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) - (x) -- +(1,1); + (node cs:name=x) -- +(1,1); \end{codeexample} Similarly, in the following examples both control points are $(1,1)$: @@ -190,23 +343,52 @@ 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} - (x) .. controls +(1,1) and +(-1,1) .. (y); + (node cs:name=x) .. controls +(1,1) and +(-1,1) .. + (node cs:name=y); \end{codeexample} - -\subsection{Intersection Coordinates} + 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: +\begin{codeexample}[] +\begin{tikzpicture}[fill=blue!20] + \draw[style=help lines] (-1,-2) grid (6,3); + \path (0,0) node(a) [ellipse,rotate=10,draw,fill] {An ellipse} + (3,-1) node(b) [circle,draw,fill] {A circle} + (2,2) node(c) [rectangle,rotate=20,draw,fill] {A rectangle} + (5,2) node(d) [rectangle,rotate=-30,draw,fill] {Another rectangle}; + \draw[thick] (a.south) -- (b) -- (c) -- (d); + \draw[thick,red,->] (a) |- +(1,3) -| (c) |- (b); + \draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d); +\end{tikzpicture} +\end{codeexample} +\end{coordinatesystem} -\subsubsection{Intersection of Two Lines} + +\subsubsection{Intersection Coordinate Systems} Often you wish to specify a point that is on the -intersection of two lines. The first way to specify such an -intersection is the following: You can use the special syntax -\declare{|(intersection of |\meta{$p_1$}|--|\meta{$p_2$}% - | and |\meta{$q_1$}|--|\meta{$q_2$}|)|}. This will yield the -intersection point of the line going through $p_1$ and $p_2$ and the -line through $q_1$ and $q_2$. If the lines do not meet or if they are -identical and arithmetical overflow error will result. +intersection of two lines. For this, the following coordinate system +is useful: + +\begin{coordinatesystem}{intersection} + To specify the intersection of two line, you provide two lines using + the following two options: + \begin{itemize} + \itemoption{first line}|=(|\meta{first coordinate}|)--(|\meta{second coordinate}|)| + \itemoption{second line}|=(|\meta{first coordinate}|)--(|\meta{second coordinate}|)| + \end{itemize} + Note that you have to write |--| between the coordinate, but this + does not mean that anything is added to the path. This is simply a + special syntax. + + The coordinate specified in this way is the intersection of the two + lines. If the lines do not meet or if they are + identical and arithmetical overflow error will result. \begin{codeexample}[] \begin{tikzpicture} @@ -214,25 +396,46 @@ identical and arithmetical overflow error will result. \draw (0,0) coordinate (A) -- (3,2) coordinate (B) (1,2) -- (3,0); - \fill[red] (intersection of A--B and 1,2--3,0) circle (2pt); + \fill[red] (intersection cs: + first line={(A)--(B)}, + second line={(1,2)--(3,0)}) circle (2pt); \end{tikzpicture} \end{codeexample} -\subsubsection{Intersection of Horizontal and Vertical Lines} + The implicit way of specifying this coordinate system is to write + \declare{|(intersection of |\meta{$p_1$}|--|\meta{$p_2$ + }| and |\meta{$q_1$}|--|\meta{$q_2$}|)|}. Note that there are \emph{no} + parentheses around the $p_i$ and $q_i$. Thus, you would write + |(intersection of A--B and 1,2--3,0)|. +\end{coordinatesystem} A frequent special case of 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 special, -shorter, syntax: You can say either -\declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or -\declare{|(|\meta{q}\verb! -| !\meta{p}|)|}. +through some other point $q$. For this situation there is another +coordinate system. + +\begin{coordinatesystem}{perpendicular} + This coordinate system works the same way as |intersection|, only + the lines are specified differently: + + \begin{itemize} + \itemoption{horizontal line through}|=(|\meta{coordinate}|)| + Specifies that one line is a horizontal line that goes through the + given coordinate. + \itemoption{vertical line through}|=(|\meta{coordinate}|)| + Specifies that the other line is vertical and goes through the + given coordinate. + \end{itemize} -For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield -the same as \verb!(2,4)! (provided the $xy$-coordinate system has not -been modified). + The implicit syntax is to write \declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or + \declare{|(|\meta{q}\verb! -| !\meta{p}|)|}. -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: + For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield + the same as \verb!(2,4)! (provided the $xy$-coordinate system has not + been modified). + + The most useful application of the syntax is to draw a line up to some + point on a vertical or horizontal line. Here is an example: \begin{codeexample}[] \begin{tikzpicture} @@ -247,6 +450,56 @@ point on a vertical or horizontal line. Here is an example: \draw[->] (p2) -- (p2 -| yline); \end{tikzpicture} \end{codeexample} +\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: + +\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. +\begin{codeexample}[] +\makeatletter +\define@key{cylindricalkeys}{angle}{\def\myangle{#1}} +\define@key{cylindricalkeys}{radius}{\def\myradius{#1}} +\define@key{cylindricalkeys}{z}{\def\myz{#1}} +\tikzdeclarecoordinatesystem{cylindrical}% +{% + \setkeys{cylindricalkeys}{#1}% + \pgfpointadd{\pgfpointxyz{0}{0}{\myz}}{\pgfpointpolarxy{\myangle}{\myradius}} +} +\begin{tikzpicture}[z=0.2pt] + \draw [->] (0,0,0) -- (0,0,350); + \foreach \num in {0,10,...,350} + \fill (cylindrical cs:angle=\num,radius=1,z=\num) circle (1pt); +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\tikzaliascoordinatesystem\marg{new name}\marg{old name}} + Creates an alias of \meta{old name}. +\end{command} + @@ -299,3 +552,5 @@ the following example, the curve ``leaves'' at $30^\circ$ and \draw[gray,<-] (3,-1) -- +(60:1cm); \end{tikzpicture} \end{codeexample} + + |