diff options
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 | 452 |
1 files changed, 452 insertions, 0 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 new file mode 100644 index 00000000000..9c1a821e26c --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-points.tex @@ -0,0 +1,452 @@ +% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>. +% +% This program can be redistributed and/or modified under the terms +% of the LaTeX Project Public License Distributed from CTAN +% archives in directory macros/latex/base/lppl.txt. + + +\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|. + +\subsection{Basic Coordinate Commands} + +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. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpoint{1cm}{1cm}} {2pt} + \pgfpathcircle{\pgfpoint{2cm}{5pt}} {2pt} + \pgfpathcircle{\pgfpoint{0pt}{.5in}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointorigin} + Yields the origin. Same as |\pgfpoint{0pt}{0pt}|. +\end{command} + +\begin{command}{\pgfpointpolar\marg{degree}\marg{radius}} + Yields a point location given in polar coordinates. You can specify + the angle only in degrees, radians are not supported, currently. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + + \foreach \angle in {0,10,...,90} + {\pgfpathcircle{\pgfpointpolar{\angle}{1cm}}{2pt}} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + + +\subsection{Coordinates in the Xy- and Xyz-Coordinate Systems} + +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.'' + +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}{\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. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\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. +\begin{codeexample}[] +\begin{pgfpicture} + \pgfsetarrowsend{to} + + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{0}{1}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{0}{1}{0}} + \pgfusepath{stroke} + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpointxyz{1}{0}{0}} + \pgfusepath{stroke} +\end{pgfpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfsetxvec\marg{point}} + 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); + + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} + + \color{red} + \pgfsetxvec{\pgfpoint{0.75cm}{0cm}} + \pgfpathmoveto{\pgfpointxy{1}{0}} + \pgfpathlineto{\pgfpointxy{2}{2}} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfsetyvec\marg{point}} + Works like |\pgfsetyvec|. +\end{command} + +\begin{command}{\pgfsetzvec\marg{point}} + Works like |\pgfsetzvec|. +\end{command} + + + + +\subsection{Building Coordinates From Other Coordinates} + +Many commands allow you to construct a coordinate in terms of other +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$}$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointadd{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointscale\marg{factor}\marg{coordinate}} + Returns the vector $\meta{factor}\meta{coordinate}$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointscale{1.5}{\pgfpoint{1cm}{0cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + +\begin{command}{\pgfpointdiff\marg{start}\marg{end}} + Returns the difference vector $\meta{end} - \meta{start}$. +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathcircle{\pgfpointdiff{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt} + \pgfusepath{fill} +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\begin{command}{\pgfpointnormalised\marg{point}} + This command returns a normalized 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); + \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt} + \pgfpathcircle{\pgfpointscale{20} + {\pgfpointnormalised{\pgfpoint{2cm}{1cm}}}}{2pt} + \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. Imaging 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$. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (3,2); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{2cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,...,1.25} + {\pgftext[at= + \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 removed + 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); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathlineto{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \d in {0pt,20pt,40pt,70pt} + {\pgftext[at= + \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}} +\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é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); + \pgfpathmoveto{\pgfpointorigin} + \pgfpathcurveto + {\pgfpoint{0cm}{2cm}}{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}} + \pgfusepath{stroke} + \foreach \t in {0,0.25,0.5,0.75,1} + {\pgftext[at=\pgfpointcurveattime{\t}{\pgfpointorigin} + {\pgfpoint{0cm}{2cm}} + {\pgfpoint{0cm}{2cm}} + {\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. + +\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. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathrectanglecorners{\pgfpoint{-1cm}{-1.25cm}}{\pgfpoint{1cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderrectangle + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \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. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,1.5); + \pgfpathellipse{\pgfpointorigin}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{1.25cm}} + \pgfusepath{stroke} + + \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt} + \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt} + \pgfusepath{fill} + \color{red} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \pgfpathcircle{\pgfpointborderellipse + {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt} + \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. + +\begin{codeexample}[] +\begin{tikzpicture} + \draw[help lines] (0,0) grid (2,2); + \draw (.5,0) -- (2,2); + \draw (1,2) -- (2,0); + \pgfpathcircle{% + \pgfpointintersectionoflines + {\pgfpointxy{.5}{0}}{\pgfpointxy{2}{2}} + {\pgfpointxy{1}{2}}{\pgfpointxy{2}{0}}} + {2pt} + \pgfusepath{stroke} +\end{tikzpicture} +\end{codeexample} +\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. + +\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. +\end{command} + + + + +\subsection{Internals of How Point Commands Work} + +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. 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 + \pgfpointnormalised{\pgfpoint{1cm}{1cm}} + \global\pgf@x=\pgf@x % make the change of \pgf@x persist past the scope + \global\pgf@y=\pgf@y % make the change of \pgf@y persist past the scope +} +% \pgf@x and \pgf@y are now set correctly, all other variables are +% unchanged +\end{codeexample} + +\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. +\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|: +\begin{codeexample}[code only] +\def\pgfpointadd#1#2{% + \pgf@process{#1}% + \pgf@xa=\pgf@x% + \pgf@ya=\pgf@y% + \pgf@process{#2}% + \advance\pgf@x by\pgf@xa% + \advance\pgf@y by\pgf@ya} +\end{codeexample} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual" +%%% End: |