diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
commit | 22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch) | |
tree | 2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex | |
parent | cf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff) |
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex | 449 |
1 files changed, 225 insertions, 224 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex index 833118bdf57..eace57ffde3 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex @@ -9,28 +9,24 @@ \section{Specifying Coordinates} - \label{section-points} \subsection{Overview} -Most \pgfname\ commands expect you to provide the coordinates of a -\emph{point} (also called \emph{coordinate}) inside your -picture. Points are always ``local'' to your picture, that is, they -never refer to an absolute position on the page, but to a position -inside the current |{pgfpicture}| environment. To specify a coordinate -you can use commands that start with |\pgfpoint|. +Most \pgfname\ commands expect you to provide the coordinates of a \emph{point} +(also called \emph{coordinate}) inside your picture. Points are always +``local'' to your picture, that is, they never refer to an absolute position on +the page, but to a position inside the current |{pgfpicture}| environment. To +specify a coordinate you can use commands that start with |\pgfpoint|. \subsection{Basic Coordinate Commands} -The following commands are the most basic for specifying a -coordinate. +The following commands are the most basic for specifying a coordinate. \begin{command}{\pgfpoint\marg{x coordinate}\marg{y coordinate}} - Yields a point location. The coordinates are given as \TeX\ - dimensions. - + Yields a point location. The coordinates are given as \TeX\ dimensions. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -40,19 +36,21 @@ coordinate. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfpointorigin} - Yields the origin. Same as |\pgfpoint{0pt}{0pt}|. + Yields the origin. Same as |\pgfpoint{0pt}{0pt}|. \end{command} \begin{command}{\pgfpointpolar\marg{degree}{\ttfamily\char`\{}\meta{radius}\opt{|/|\meta{y-radius}}{\ttfamily\char`\}}} - Yields a point location given in polar coordinates. You can specify - the angle only in degrees, radians are not supported, currently. + Yields a point location given in polar coordinates. You can specify the + angle only in degrees, radians are not supported, currently. - If the optional \meta{y-radius} is given, the polar coordinate is - actually a coordinate on an ellipse whose $x$-radius is given by - \meta{radius} and whose $y$-radius is given by \meta{y-radius}. + If the optional \meta{y-radius} is given, the polar coordinate is actually + a coordinate on an ellipse whose $x$-radius is given by \meta{radius} and + whose $y$-radius is given by \meta{y-radius}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -62,6 +60,7 @@ coordinate. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -71,23 +70,23 @@ coordinate. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} - \subsection{Coordinates in the XY-Coordinate System} Coordinates can also be specified as multiples of an $x$-vector and a -$y$-vector. Normally, the $x$-vector points one centimeter in the -$x$-direction and the $y$-vector points one centimeter in the -$y$-direction, but using the commands |\pgfsetxvec| and -|\pgfsetyvec| they can be changed. Note that the $x$- and -$y$-vector do not necessarily point ``horizontally'' and -``vertically.'' +$y$-vector. Normally, the $x$-vector points one centimeter in the $x$-direction +and the $y$-vector points one centimeter in the $y$-direction, but using the +commands |\pgfsetxvec| and |\pgfsetyvec| they can be changed. Note that the +$x$- and $y$-vector do not necessarily point ``horizontally'' and +``vertically''. \begin{command}{\pgfpointxy\marg{$s_x$}\marg{$s_y$}} - Yields a point that is situated at $s_x$ times the - $x$-vector plus $s_y$ times the $y$-vector. + Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$ + times the $y$-vector. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -96,13 +95,13 @@ $y$-vector do not necessarily point ``horizontally'' and \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgfsetxvec\marg{point}} - Sets that current $x$-vector for usage in the $xyz$-coordinate - system. - \example + Sets that current $x$-vector for usage in the $xyz$-coordinate system. + \example + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -118,23 +117,22 @@ $y$-vector do not necessarily point ``horizontally'' and \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfsetyvec\marg{point}} - Works like |\pgfsetxvec|. + Works like |\pgfsetxvec|. \end{command} - - \begin{command}{\pgfpointpolarxy\marg{degree}{\ttfamily\char`\{}\meta{radius}\opt{|/|\meta{y-radius}}{\ttfamily\char`\}}} - This command is similar to the |\pgfpointpolar| command, but the - \meta{radius} is now a factor to be interpreted in the - $xy$-coordinate system. This means that a degree of |0| is the same - as the $x$-vector of the $xy$-coordinate system times \meta{radius} - and a degree of |90| is the $y$-vector times \meta{radius}. As for - |\pgfpointpolar|, a \meta{radius} can also be a pair separated by a - slash. In this case, the $x$- and $y$-vectors are multiplied by - different factors. + This command is similar to the |\pgfpointpolar| command, but the + \meta{radius} is now a factor to be interpreted in the $xy$-coordinate + system. This means that a degree of |0| is the same as the $x$-vector of + the $xy$-coordinate system times \meta{radius} and a degree of |90| is the + $y$-vector times \meta{radius}. As for |\pgfpointpolar|, a \meta{radius} + can also be a pair separated by a slash. In this case, the $x$- and + $y$-vectors are multiplied by different factors. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -146,20 +144,20 @@ $y$-vector do not necessarily point ``horizontally'' and \end{scope} \end{tikzpicture} \end{codeexample} + % \end{command} - \subsection{Three Dimensional Coordinates} -It is also possible to specify a point as a multiple of three vectors, -the $x$-, $y$-, and $z$-vector. This is useful for creating simple -three dimensional graphics. +It is also possible to specify a point as a multiple of three vectors, the +$x$-, $y$-, and $z$-vector. This is useful for creating simple three +dimensional graphics. \begin{command}{\pgfpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}} - Yields a point that is situated at $s_x$ times the - $x$-vector plus $s_y$ times the $y$-vector plus $s_z$ times the - $z$-vector. + Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$ + times the $y$-vector plus $s_z$ times the $z$-vector. + % \begin{codeexample}[] \begin{pgfpicture} \pgfsetarrowsend{to} @@ -175,21 +173,23 @@ three dimensional graphics. \pgfusepath{stroke} \end{pgfpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfsetzvec\marg{point}} - Works like |\pgfsetxvec|. + Works like |\pgfsetxvec|. \end{command} -Inside the $xyz$-coordinate system, you can also specify points -using spherical and cylindrical coordinates. - +Inside the $xyz$-coordinate system, you can also specify points using spherical +and cylindrical coordinates. \begin{command}{\pgfpointcylindrical\marg{degree}\marg{radius}\marg{height}} - This command yields the same as + This command yields the same as + % \begin{verbatim} \pgfpointadd{\pgfpointpolarxy{degree}{radius}}{\pgfpointxyz{0}{0}{height}} \end{verbatim} + % \begin{codeexample}[] \begin{tikzpicture} \draw [->] (0,0) -- (1,0,0) node [right] {$x$}; @@ -202,13 +202,14 @@ using spherical and cylindrical coordinates. \draw[red] (0,0) -- (0,0,.5) -- +(80:1); \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfpointspherical\marg{longitude}\marg{latitude}\marg{radius}} - This command yields a point ``on the surface of the earth'' - specified by the \meta{longitude} and the \meta{latitude}. The - radius of the earth is given by \meta{radius}. The equator lies in - the $xy$-plane. + This command yields a point ``on the surface of the earth'' specified by + the \meta{longitude} and the \meta{latitude}. The radius of the earth is + given by \meta{radius}. The equator lies in the $xy$-plane. + % \begin{codeexample}[] \begin{tikzpicture} \pgfsetfillcolor{lightgray} @@ -227,10 +228,10 @@ using spherical and cylindrical coordinates. } \end{tikzpicture} \end{codeexample} + % \end{command} - \subsection{Building Coordinates From Other Coordinates} Many commands allow you to construct a coordinate in terms of other @@ -240,7 +241,8 @@ coordinates. \subsubsection{Basic Manipulations of Coordinates} \begin{command}{\pgfpointadd\marg{$v_1$}\marg{$v_2$}} - Returns the sum vector $\meta{$v_1$} + \meta{$v_2$}$. + Returns the sum vector $\meta{$v_1$} + \meta{$v_2$}$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -248,10 +250,12 @@ coordinates. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfpointscale\marg{factor}\marg{coordinate}} - Returns the vector $\meta{factor}\meta{coordinate}$. + Returns the vector $\meta{factor}\meta{coordinate}$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -259,10 +263,12 @@ coordinates. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfpointdiff\marg{start}\marg{end}} - Returns the difference vector $\meta{end} - \meta{start}$. + Returns the difference vector $\meta{end} - \meta{start}$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -270,23 +276,23 @@ coordinates. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgfpointnormalised\marg{point}} - This command returns a normalised version of \meta{point}, that is, - a vector of length 1pt pointing in the direction of \meta{point}. If - \meta{point} is the $0$-vector or extremely short, a vector of - length 1pt pointing upwards is returned. - - This command is \emph{not} implemented by calculating the length of - the vector, but rather by calculating the angle of the vector and - then using (something equivalent to) the |\pgfpointpolar| - command. This ensures that the point will really have length 1pt, - but it is not guaranteed that the vector will \emph{precisely} point - in the direction of \meta{point} due to the fact that the polar - tables are accurate only up to one degree. Normally, this is not a - problem. + This command returns a normalised version of \meta{point}, that is, a + vector of length 1pt pointing in the direction of \meta{point}. If + \meta{point} is the $0$-vector or extremely short, a vector of length 1pt + pointing upwards is returned. + + This command is \emph{not} implemented by calculating the length of the + vector, but rather by calculating the angle of the vector and then using + (something equivalent to) the |\pgfpointpolar| command. This ensures that + the point will really have length 1pt, but it is not guaranteed that the + vector will \emph{precisely} point in the direction of \meta{point} due to + the fact that the polar tables are accurate only up to one degree. + Normally, this is not a problem. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -296,32 +302,27 @@ coordinates. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} \subsubsection{Points Traveling along Lines and Curves} - \label{section-pointsattime} -The commands in this section allow you to specify points on a line or -a curve. Imagine a point ``traveling'' along a curve from some point -$p$ to another point $q$. At time $t=0$ the point is at $p$ and at -time $t=1$ it is at $q$ and at time, say, $t=1/2$ it is ``somewhere in -the middle.'' The exact location at time $t=1/2$ will not necessarily -be the ``halfway point,'' that is, the point whose distance on the -curve from $p$ and $q$ is equal. Rather, the exact location will -depend on the ``speed'' at which the point is traveling, which in -turn depends on the lengths of the support vectors in a complicated -manner. If you are interested in the details, please see a good book -on B\'ezier curves. - - +The commands in this section allow you to specify points on a line or a curve. +Imagine a point ``traveling'' along a curve from some point $p$ to another +point $q$. At time $t=0$ the point is at $p$ and at time $t=1$ it is at $q$ and +at time, say, $t=1/2$ it is ``somewhere in the middle''. The exact location at +time $t=1/2$ will not necessarily be the ``halfway point'', that is, the point +whose distance on the curve from $p$ and $q$ is equal. Rather, the exact +location will depend on the ``speed'' at which the point is traveling, which in +turn depends on the lengths of the support vectors in a complicated manner. If +you are interested in the details, please see a good book on Bézier curves. \begin{command}{\pgfpointlineattime\marg{time $t$}\marg{point $p$}\marg{point $q$}} - Yields a point that is the $t$th fraction between $p$ - and~$q$, that is, $p + t(q-p)$. For $t=1/2$ this is the middle of - $p$ and $q$. - + Yields a point that is the $t$th fraction between $p$ and~$q$, that is, $p + + t(q-p)$. For $t=1/2$ this is the middle of $p$ and $q$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -333,14 +334,17 @@ on B\'ezier curves. \pgfpointlineattime{\t}{\pgfpointorigin}{\pgfpoint{2cm}{2cm}}]{\t}} \end{tikzpicture} \end{codeexample} + % \end{command} \begin{command}{\pgfpointlineatdistance\marg{distance}\marg{start point}\marg{end point}} - Yields a point that is located \meta{distance} many units away - from the start point in the direction of the end point. In other - words, this is the point that results if we travel \meta{distance} - steps from \meta{start point} towards \meta{end point}. - \example + Yields a point that is located \meta{distance} many units away from the + start point in the direction of the end point. In other words, this is the + point that results if we travel \meta{distance} steps from \meta{start + point} towards \meta{end point}. + % + \example + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -352,17 +356,16 @@ on B\'ezier curves. \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}} \end{tikzpicture} \end{codeexample} + % \end{command} -\begin{command}{\pgfpointarcaxesattime\marg{time - $t$}\marg{center}\marg{0-degree axis}\marg{90-degree - axis}\marg{start angle}\\\marg{end angle}} - Yields a point on the arc between \meta{start angle} and \meta{end - angle} on an ellipse whose center is at \meta{center} and whose - two principal axes are \meta{0-degree axis} and \meta{90-degree - axis}. For $t=0$ the point at the \meta{start angle} is returned - and for $t=1$ the point at the \meta{end angle}. - +\begin{command}{\pgfpointarcaxesattime\marg{time $t$}\marg{center}\marg{0-degree axis}\marg{90-degree axis}\marg{start angle}\\\marg{end angle}} + Yields a point on the arc between \meta{start angle} and \meta{end angle} + on an ellipse whose center is at \meta{center} and whose two principal axes + are \meta{0-degree axis} and \meta{90-degree axis}. For $t=0$ the point at + the \meta{start angle} is returned and for $t=1$ the point at the \meta{end + angle}. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -374,14 +377,14 @@ on B\'ezier curves. {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}{0}{60}]{\t}} \end{tikzpicture} \end{codeexample} + % \end{command} -\begin{command}{\pgfpointcurveattime\marg{time $t$}\marg{point - $p$}\marg{point $s_1$}\marg{point $s_2$}\marg{point $q$}} - Yields a point that is on the B\'ezier curve from $p$ to $q$ with the - support points $s_1$ and $s_2$. The time $t$ is used to determine - the location, where $t=0$ yields $p$ and $t=1$ yields $q$. - +\begin{command}{\pgfpointcurveattime\marg{time $t$}\marg{point $p$}\marg{point $s_1$}\marg{point $s_2$}\marg{point $q$}} + Yields a point that is on the Bézier curve from $p$ to $q$ with the support + points $s_1$ and $s_2$. The time $t$ is used to determine the location, + where $t=0$ yields $p$ and $t=1$ yields $q$. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (3,2); @@ -396,24 +399,26 @@ on B\'ezier curves. {\pgfpoint{3cm}{2cm}}]{\t}} \end{tikzpicture} \end{codeexample} + % \end{command} + \subsubsection{Points on Borders of Objects} -The following commands are useful for specifying a point that lies on -the border of special shapes. They are used, for example, by the shape -mechanism to determine border points of shapes. +The following commands are useful for specifying a point that lies on the +border of special shapes. They are used, for example, by the shape mechanism to +determine border points of shapes. \begin{command}{\pgfpointborderrectangle\marg{direction point}\marg{corner}} - This command returns a point that lies on the intersection of a line - starting at the origin and going towards the point \meta{direction - point} and a rectangle whose center is in the origin and whose - upper right corner is at \meta{corner}. - - The \meta{direction point} should have length ``about 1pt,'' but it - will be normalized automatically. Nevertheless, the ``nearer'' the - length is to 1pt, the less rounding errors. - + This command returns a point that lies on the intersection of a line + starting at the origin and going towards the point \meta{direction point} + and a rectangle whose center is in the origin and whose upper right corner + is at \meta{corner}. + + The \meta{direction point} should have length ``about 1pt'', but it will be + normalized automatically. Nevertheless, the ``nearer'' the length is to + 1pt, the less rounding errors. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,1.5); @@ -431,14 +436,14 @@ mechanism to determine border points of shapes. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} - \begin{command}{\pgfpointborderellipse\marg{direction point}\marg{corner}} - This command works like the corresponding command for rectangles, - only this time the \meta{corner} is the corner of the bounding - rectangle of an ellipse. - + This command works like the corresponding command for rectangles, only this + time the \meta{corner} is the corner of the bounding rectangle of an + ellipse. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,1.5); @@ -456,17 +461,17 @@ mechanism to determine border points of shapes. \pgfusepath{fill} \end{tikzpicture} \end{codeexample} + % \end{command} \subsubsection{Points on the Intersection of Lines} - \begin{command}{\pgfpointintersectionoflines\marg{$p$}\marg{$q$}\marg{$s$}\marg{$t$}} - This command returns the intersection of a line going through $p$ - and $q$ and a line going through $s$ and $t$. If the lines do not - intersection, an arithmetic overflow will occur. - + This command returns the intersection of a line going through $p$ and $q$ + and a line going through $s$ and $t$. If the lines do not intersection, an + arithmetic overflow will occur. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,2); @@ -480,18 +485,17 @@ mechanism to determine border points of shapes. \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} + % \end{command} \subsubsection{Points on the Intersection of Two Circles} - \begin{command}{\pgfpointintersectionofcircles\marg{$p_1$}\marg{$p_2$}\marg{$r_1$}\marg{$r_2$}\marg{solution}} - This command returns the intersection of the two circles centered at - $p_1$ and $p_2$ with radii $r_1$ and $r_2$. If \meta{solution} is - |1|, the first intersection is returned, otherwise the second one is - returned. - + This command returns the intersection of the two circles centered at $p_1$ + and $p_2$ with radii $r_1$ and $r_2$. If \meta{solution} is |1|, the first + intersection is returned, otherwise the second one is returned. + % \begin{codeexample}[] \begin{tikzpicture} \draw[help lines] (0,0) grid (2,2); @@ -505,32 +509,31 @@ mechanism to determine border points of shapes. \pgfusepath{stroke} \end{tikzpicture} \end{codeexample} + % \end{command} -\subsubsection{Points on the Intersection of Two Paths} +\subsubsection{Points on the Intersection of Two Paths} \begin{pgflibrary}{intersections} - This library defines the below command and allows you to calculate - the intersections of two arbitrary paths. However, due to the low accuracy of - \TeX, the paths should not be ``too complicated''. - In particular, you should not try to intersect paths consisting of - lots of very small segments such as plots or decorated paths. + This library defines the below command and allows you to calculate the + intersections of two arbitrary paths. However, due to the low accuracy of + \TeX, the paths should not be ``too complicated''. In particular, you + should not try to intersect paths consisting of lots of very small segments + such as plots or decorated paths. \end{pgflibrary} \begin{command}{\pgfintersectionofpaths\marg{path 1}\marg{path 2}} - This command finds the intersection points on the paths - \meta{path 1} and \meta{path 2}. The number of intersection points - (``solutions'') that are found will be stored, and each point - can be accessed afterward. The code for \meta{path 1} and - \meta{path 2} is executed within a \TeX{} group and so can contain - transformations (which will be in addition to any existing - transformations). The code should not use the path in any way, - unless the path is saved first and restored afterward. - \pgfname{} will regard solutions as ``a bit - special'', in that the points returned will be ``absolute'' and - unaffected by any further transformations. - + This command finds the intersection points on the paths \meta{path 1} and + \meta{path 2}. The number of intersection points (``solutions'') that are + found will be stored, and each point can be accessed afterward. The code + for \meta{path 1} and \meta{path 2} is executed within a \TeX{} group and + so can contain transformations (which will be in addition to any existing + transformations). The code should not use the path in any way, unless the + path is saved first and restored afterward. \pgfname{} will regard + solutions as ``a bit special'', in that the points returned will be + ``absolute'' and unaffected by any further transformations. + % \begin{codeexample}[] \begin{pgfpicture} \pgfintersectionofpaths @@ -553,91 +556,89 @@ mechanism to determine border points of shapes. \end{pgfpicture} \end{codeexample} - \begin{command}{\pgfintersectionsolutions} - After using the |\pgfintersectionofpaths| command, this \TeX-macro - will indicate the number of solutions found. - \end{command} - - \begin{command}{\pgfpointintersectionsolution\marg{number}} - After using the |\pgfintersectionofpaths| command, this command - will return the point for solution \meta{number} or the origin - if this solution was not found. - By default, the intersections are simply returned in the order that - the intersection algorithm finds them. Unfortunately, this is not - necessarily a ``helpful'' ordering. However the following two - commands can be used to order the solutions more helpfully. - \end{command} - -\let\ifpgfintersectionsortbyfirstpath=\relax - \begin{command}{\pgfintersectionsortbyfirstpath} - Using this command will mean the solutions will be sorted along - \meta{path 1}. - \end{command} - -\let\ifpgfintersectionsortbysecondpath=\relax - \begin{command}{\pgfintersectionsortbysecondpath} - Using this command will mean the solutions will be sorted along - \meta{path 2}. - \end{command} - + \begin{command}{\pgfintersectionsolutions} + After using the |\pgfintersectionofpaths| command, this \TeX-macro will + indicate the number of solutions found. + \end{command} + + \begin{command}{\pgfpointintersectionsolution\marg{number}} + After using the |\pgfintersectionofpaths| command, this command will + return the point for solution \meta{number} or the origin if this + solution was not found. By default, the intersections are simply + returned in the order that the intersection algorithm finds them. + Unfortunately, this is not necessarily a ``helpful'' ordering. However + the following two commands can be used to order the solutions more + helpfully. + \end{command} + + \let\ifpgfintersectionsortbyfirstpath=\relax + \begin{command}{\pgfintersectionsortbyfirstpath} + Using this command will mean the solutions will be sorted along + \meta{path 1}. + \end{command} + + \let\ifpgfintersectionsortbysecondpath=\relax + \begin{command}{\pgfintersectionsortbysecondpath} + Using this command will mean the solutions will be sorted along + \meta{path 2}. + \end{command} \end{command} - - \subsection{Extracting Coordinates} There are two commands that can be used to ``extract'' the $x$- or $y$-coordinate of a coordinate. \begin{command}{\pgfextractx\marg{dimension}\marg{point}} - Sets the \TeX-\meta{dimension} to the $x$-coordinate of the point. - + Sets the \TeX-\meta{dimension} to the $x$-coordinate of the point. + % \begin{codeexample}[code only] \newdimen\mydim \pgfextractx{\mydim}{\pgfpoint{2cm}{4pt}} %% \mydim is now 2cm \end{codeexample} + % \end{command} \begin{command}{\pgfextracty\marg{dimension}\marg{point}} - Like |\pgfextractx|, except for the $y$-coordinate. + Like |\pgfextractx|, except for the $y$-coordinate. \end{command} \begin{command}{\pgfgetlastxy\marg{macro for $x$}\marg{macro for $y$}} - Stores the most recently used $(x,y)$ coordinates into two macros. + Stores the most recently used $(x,y)$ coordinates into two macros. + % \begin{codeexample}[] \pgfpoint{2cm}{4cm} \pgfgetlastxy{\macrox}{\macroy} Macro $x$ is `\macrox' and macro $y$ is `\macroy'. \end{codeexample} - Since $(x,y)$ coordinates are usually assigned globally, it is safe to use this command after path operations. + % + Since $(x,y)$ coordinates are usually assigned globally, it is safe to use + this command after path operations. \end{command} - \subsection{Internals of How Point Commands Work} - \label{section-internal-pointcmds} -As a normal user of \pgfname\ you do not need to read this section. It -is relevant only if you need to understand how the point commands work -internally. - -When a command like |\pgfpoint{1cm}{2pt}| is called, all that happens -is that the two \TeX-dimension variables |\pgf@x| and |\pgf@y| are set -to |1cm| and |2pt|, respectively. These variables belong to the set of -internal \pgfname\ registers, see section~\ref{section-internal-registers} -for details. A command like |\pgfpathmoveto| that -takes a coordinate as parameter will just execute this parameter and -then use the values of |\pgf@x| and |\pgf@y| as the coordinates to -which it will move the pen on the current path. - -Since commands like |\pgfpointnormalised| modify other variables -besides |\pgf@x| and |\pgf@y| during the computation of the final values of -|\pgf@x| and |\pgf@y|, it is a good idea to enclose a call of a -command like |\pgfpoint| in a \TeX-scope and then make the changes of -|\pgf@x| and |\pgf@y| global as in the following example: +As a normal user of \pgfname\ you do not need to read this section. It is +relevant only if you need to understand how the point commands work internally. + +When a command like |\pgfpoint{1cm}{2pt}| is called, all that happens is that +the two \TeX-dimension variables |\pgf@x| and |\pgf@y| are set to |1cm| and +|2pt|, respectively. These variables belong to the set of internal \pgfname\ +registers, see section~\ref{section-internal-registers} for details. A command +like |\pgfpathmoveto| that takes a coordinate as parameter will just execute +this parameter and then use the values of |\pgf@x| and |\pgf@y| as the +coordinates to which it will move the pen on the current path. + +Since commands like |\pgfpointnormalised| modify other variables besides +|\pgf@x| and |\pgf@y| during the computation of the final values of |\pgf@x| +and |\pgf@y|, it is a good idea to enclose a call of a command like |\pgfpoint| +in a \TeX-scope and then make the changes of |\pgf@x| and |\pgf@y| global as in +the following example: + % \begin{codeexample}[code only] ... { % open scope @@ -652,18 +653,19 @@ command like |\pgfpoint| in a \TeX-scope and then make the changes of \makeatletter Since this situation arises very often, the macro |\pgf@process| can be used to perform the above code: + % \begin{command}{\pgf@process\marg{code}} - Executes the \meta{code} in a scope and then makes |\pgf@x| and - |\pgf@y| global. + Executes the \meta{code} in a scope and then makes |\pgf@x| and |\pgf@y| + global. \end{command} -Note that this macro is used often internally. For this reason, it is -not a good idea to keep anything important in the variables |\pgf@x| -and |\pgf@y| since they will be overwritten and changed -frequently. Instead, intermediate values can ge stored in the -\TeX-dimensions |\pgf@xa|, |\pgf@xb|, |\pgf@xc| and their -|y|-counterparts |\pgf@ya|, |\pgf@yb|, |pgf@yc|. For example, here is -the code of the command |\pgfpointadd|: +Note that this macro is used often internally. For this reason, it is not a +good idea to keep anything important in the variables |\pgf@x| and |\pgf@y| +since they will be overwritten and changed frequently. Instead, intermediate +values can ge stored in the \TeX-dimensions |\pgf@xa|, |\pgf@xb|, |\pgf@xc| and +their |y|-counterparts |\pgf@ya|, |\pgf@yb|, |pgf@yc|. For example, here is the +code of the command |\pgfpointadd|: +% \begin{codeexample}[code only] \def\pgfpointadd#1#2{% \pgf@process{#1}% @@ -675,7 +677,6 @@ the code of the command |\pgfpointadd|: \end{codeexample} - %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual" |