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.tex635
1 files changed, 550 insertions, 85 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 d877d60e52a..448bd24a029 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
@@ -45,7 +45,7 @@ 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[help lines] (0,0) grid (3,2);
\draw (canvas cs:x=0cm,y=2mm)
-- (canvas polar cs:radius=2cm,angle=30);
\end{tikzpicture}
@@ -53,7 +53,7 @@ specified explicitly:
In the next example, the coordinate systems are implicit:
\begin{codeexample}[]
\begin{tikzpicture}
- \draw[style=help lines] (0,0) grid (3,2);
+ \draw[help lines] (0,0) grid (3,2);
\draw (0cm,2mm) -- (30:2cm);
\end{tikzpicture}
\end{codeexample}
@@ -64,7 +64,7 @@ only. To give transformation options for a single coordinate, give
these options at the beginning in brackets:
\begin{codeexample}[]
\begin{tikzpicture}
- \draw[style=help lines] (0,0) grid (3,2);
+ \draw[help lines] (0,0) grid (3,2);
\draw (0,0) -- (1,1);
\draw[red] (0,0) -- ([xshift=3pt] 1,1);
\draw (1,0) -- +(30:2cm);
@@ -86,16 +86,21 @@ Let us start with the basic coordinate systems.
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{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}
- \draw[style=help lines] (0,0) grid (3,2);
+ \draw[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);
@@ -103,11 +108,11 @@ Let us start with the basic coordinate systems.
\end{codeexample}
To specify a coordinate in the coordinate system implicitly, you use
- two dimensions that are seperated by a comma as in |(0cm,3pt)| or
+ two dimensions that are separated by a comma as in |(0cm,3pt)| or
|(2cm,\textheight)|.
\begin{codeexample}[]
\begin{tikzpicture}
- \draw[style=help lines] (0,0) grid (3,2);
+ \draw[help lines] (0,0) grid (3,2);
\fill (1cm,1.5cm) circle (2pt);
\fill (2cm,-5mm+2pt) circle (2pt);
@@ -127,12 +132,16 @@ Let us start with the basic coordinate systems.
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{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}[->]
\draw (0,0) -- (xyz cs:x=1);
@@ -142,7 +151,7 @@ Let us start with the basic coordinate systems.
\end{codeexample}
This coordinate system can also be selected implicitly. To do so,
- you just provide two or three comma-seperated factors (not
+ you just provide two or three comma-separated factors (not
dimensions).
\begin{codeexample}[]
\begin{tikzpicture}[->]
@@ -153,6 +162,24 @@ Let us start with the basic coordinate systems.
\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|.
\begin{coordinatesystem}{canvas polar}
The |canvas polar| coordinate system allows you to specify
@@ -161,23 +188,29 @@ Let us start with the basic coordinate systems.
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{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 coodinates is the following:
+ 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)|.
@@ -200,23 +233,28 @@ Let us start with the basic coordinate systems.
\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,
+ $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à.
- \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{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);
@@ -245,7 +283,7 @@ Let us start with the basic coordinate systems.
\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|
+ prefer as there is no z-coordinate involved in the |xyz polar|
coordinates.
\end{coordinatesystem}
@@ -263,7 +301,7 @@ vectors and numbers is
+ \alpha_2 + \cdots + \alpha_n}
\end{align*}
-The |barycentric cs| allows you to specifiy such coordiantes easily.
+The |barycentric cs| allows you to specify such coordinates easily.
\begin{coordinatesystem}{barycentric}
For this coordinate system, the \meta{coordinate specification}
@@ -321,13 +359,14 @@ you use the following coordinate system:
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{key}{/tikz/cs/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.
+ \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|};
@@ -341,11 +380,12 @@ you use the following coordinate system:
|- (0,1) -| (node cs:name=shape,anchor=south);
\end{tikzpicture}
\end{codeexample}
- \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:
+ \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};
@@ -354,7 +394,7 @@ you use the following coordinate system:
.. controls +(\angle:1cm) and +(-1,0) .. (2.5,0);
\end{tikzpicture}
\end{codeexample}
- \end{itemize}
+ \end{key}
It is possible to provide \emph{neither} the |anchor=| option nor
the |angle=| option. In this case, \tikzname\ will calculate an
@@ -412,7 +452,7 @@ Similarly, in the following examples both control points are $(1,1)$:
Here is a more complete example:
\begin{codeexample}[]
\begin{tikzpicture}[fill=blue!20]
- \draw[style=help lines] (-1,-2) grid (6,3);
+ \draw[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}
@@ -429,23 +469,44 @@ Similarly, in the following examples both control points are $(1,1)$:
\subsubsection{Intersection Coordinate Systems}
Often you wish to specify a point that is on the
-intersection of two lines. For this, the following coordinate system
-is useful:
+intersection of two lines or shapes. 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}
+ First, you must specify two objects that should be
+ intersected. These ``objects'' can either be lines or the shapes of
+ nodes. There are two option to specify the first object:
+ \begin{key}{/tikz/cs/first line={\ttfamily\char`\{}|(|\meta{first
+ coordinate}|)--(|\meta{second coordinate}|)|{\ttfamily\char`\}}}
+ Specifies that the first object is a line that goes from
+ \meta{first coordinate} to meta{second coordinate}.
+ \end{key}
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{key}{/tikz/cs/first node=\meta{node}}
+ 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`\}}}
+ As above.
+ \end{key}
+ \begin{key}{/tikz/cs/second node=\meta{node}}
+ 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)}
+ Specifies which solution should be used. Numbering starts with 1.
+ \end{key}
+ 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}
@@ -460,10 +521,50 @@ is useful:
\end{codeexample}
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)|.
+ \declare{|(intersection |\opt{\meta{number}}| of |\meta{first
+ object}%
+ | and |\meta{second object}|)|}. Here, \meta{first obejct} either
+ has the form \meta{$p_1$}|--|\meta{$p_2$} or it is just a node
+ name. Likewise for \meta{second object}. Note that there are \emph{no}
+ parentheses around the $p_i$. Thus, you would write
+ |(intersection of A--B and 1,2--3,0)| for the intersection of the
+ line through the coordinates |A| and |B| and the line through the
+ points $(1,2)$ and $(3,0)$. You would write
+ |(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
+ computed correctly:
+ \begin{itemize}
+ \item a line and a line
+ \item a |circle| node and a line (in any order)
+ \item a |circle| and a |circle|
+ \end{itemize}
+\begin{codeexample}[]
+\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}
A frequent special case of intersections is the intersection of a
@@ -475,14 +576,14 @@ coordinate system.
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}
+ \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}
The implicit syntax is to write \declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or
\declare{|(|\meta{q}\verb! -| !\meta{p}|)|}.
@@ -509,6 +610,55 @@ coordinate system.
\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 speicifes 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}
+
+ As for intersection coordinate system, 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);
+
+ \coordinate (a) at (3,2);
+
+ \node [circle,draw] (c) at (1,1) [minimum size=40pt] {$c$};
+
+ \draw[red] (a) -- (tangent cs:node=c,point={(a)},solution=1) --
+ (c.center) -- (tangent cs:node=c,point={(a)},solution=2) -- cycle;
+\end{tikzpicture}
+\end{codeexample}
+
+ There is no implicit syntax for this coordinate system.
+\end{coordinatesystem}
\subsubsection{Defining New Coordinate Systems}
@@ -562,6 +712,9 @@ commands are used:
\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.'' Relative coordinates are often useful in
@@ -589,7 +742,7 @@ notation to specify numerous points, all relative to the same
\end{tikzpicture}
\end{codeexample}
-There is one special situation, where relative coordinates are
+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
@@ -611,3 +764,315 @@ the following example, the curve ``leaves'' at $30^\circ$ and
\end{codeexample}
+\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.
+
+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:
+\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.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
+ \draw[red] (2,0) -- ++(1,0)
+ { [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.
+\end{key}
+
+
+\subsection{Coordinate Calculations}
+
+\begin{tikzlibrary}{calc}
+ 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$cm to the right
+of the point |a|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw [help lines] (0,0) grid (3,2);
+
+ \node (a) at (1,1) {A};
+ \fill [red] ($(a) + 1/3*(1cm,0)$) circle (2pt);
+\end{tikzpicture}
+\end{codeexample}
+
+
+
+\subsubsection{The General Syntax}
+
+The general syntax is the following:
+
+\begin{quote}
+ \declare{|(|\opt{|[|\meta{options}|]|}|$|\meta{coordinate computation}|$)|}.
+\end{quote}
+
+As you can see, the syntax uses the \TeX\ math symbol |$| to %$
+indicate that a ``mathematical computation'' is involved. However, the |$| %$
+has no other effect, in particular, no mathematical text is typeset.
+
+The \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.
+\end{enumerate}
+
+In the following, the syntax of factors and of the different modifiers
+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} is 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);
+
+ \fill [red] ($2*(1,1)$) circle (2pt);
+ \fill [green] (${1+1}*(1,.5)$) circle (2pt);
+ \fill [blue] ($cos(0)*sin(90)*(1,1)$) circle (2pt);
+ \fill [black] (${3*(4-3)}*(1,0.5)$) circle (2pt);
+\end{tikzpicture}
+\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:
+\begin{quote}
+ \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 \meta{numbers} that are 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);
+
+ \draw (1,0) -- (3,2);
+
+ \foreach \i in {0,0.2,0.5,0.9,1}
+ \node at ($(1,0)!\i!(3,2)$) {\i};
+\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.''
+
+Here are two examples:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw [help lines] (0,0) grid (3,3);
+
+ \coordinate (a) at (1,0);
+ \coordinate (b) at (3,2);
+
+ \draw[->] (a) -- (b);
+
+ \coordinate (c) at ($ (a)!1! 10:(b) $);
+
+ \draw[->,red] (a) -- (c);
+
+ \fill ($ (a)!.5! 10:(b) $) circle (2pt);
+\end{tikzpicture}
+\end{codeexample}
+
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw [help lines] (0,0) grid (4,4);
+
+ \foreach \i in {0,0.1,...,2}
+ \fill ($(2,2) !\i! \i*180:(3,2)$) circle (2pt);
+\end{tikzpicture}
+\end{codeexample}
+
+
+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);
+
+ \draw (0,0) -- (3,2);
+ \draw[red] ($(0,0)!.3!(3,2)$) -- (3,0);
+ \fill[red] ($(0,0)!.3!(3,2)!.7!(3,0)$) circle (2pt);
+\end{tikzpicture}
+\end{codeexample}
+
+
+\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|):
+\begin{quote}
+ \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:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \draw [help lines] (0,0) grid (3,2);
+
+ \draw (1,0) -- (3,2);
+
+ \foreach \i in {0cm,1cm,15mm}
+ \node at ($(1,0)!\i!(3,2)$) {\i};
+\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.
+
+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);
+
+ \coordinate (a) at (1,0);
+ \coordinate (b) at (3,1);
+
+ \draw (a) -- (b);
+
+ \coordinate (c) at ($ (a)!.25!(b) $);
+ \coordinate (d) at ($ (c)!1cm!90:(b) $);
+
+ \draw [<->] (c) -- (d) node [sloped,midway,above] {1cm};
+\end{tikzpicture}
+\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
+\meta{projection coordinate}:
+\begin{quote}
+ \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 to 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);
+
+ \coordinate (a) at (0,1);
+ \coordinate (b) at (3,2);
+ \coordinate (c) at (2.5,0);
+
+ \draw (a) -- (b) -- (c) -- cycle;
+
+ \draw[red] (a) -- ($(b)!(a)!(c)$);
+ \draw[orange] (b) -- ($(a)!(b)!(c)$);
+ \draw[blue] (c) -- ($(a)!(c)!(b)$);
+\end{tikzpicture}
+\end{codeexample}