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 | 635 |
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} |