summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-coordinates.tex531
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}
+
+