Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-points.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Specifying Coordinates}
12 \label{section-points}
13
14 \subsection{Overview}
15
16 Most \pgfname\ commands expect you to provide the coordinates of a \emph{point}
17 (also called \emph{coordinate}) inside your picture. Points are always
18 ``local'' to your picture, that is, they never refer to an absolute position on
19 the page, but to a position inside the current |{pgfpicture}| environment. To
20 specify a coordinate you can use commands that start with |\pgfpoint|.
21
22
23 \subsection{Basic Coordinate Commands}
24
25 The following commands are the most basic for specifying a coordinate.
26
27 \begin{command}{\pgfpoint\marg{x coordinate}\marg{y coordinate}}
28 Yields a point location. The coordinates are given as \TeX\ dimensions.
29 %
30 \begin{codeexample}[]
31 \begin{tikzpicture}
32 \draw[help lines] (0,0) grid (3,2);
33 \pgfpathcircle{\pgfpoint{1cm}{1cm}} {2pt}
34 \pgfpathcircle{\pgfpoint{2cm}{5pt}} {2pt}
35 \pgfpathcircle{\pgfpoint{0pt}{.5in}}{2pt}
36 \pgfusepath{fill}
37 \end{tikzpicture}
38 \end{codeexample}
39 %
40 \end{command}
41
42 \begin{command}{\pgfpointorigin}
43 Yields the origin. Same as |\pgfpoint{0pt}{0pt}|.
44 \end{command}
45
46 \begin{command}{\pgfpointpolar\marg{degree}{\ttfamily\char`\{}\meta{radius}\opt{|/|\meta{y-radius}}{\ttfamily\char`\}}}
47 Yields a point location given in polar coordinates. You can specify the
48 angle only in degrees, radians are not supported, currently.
49
50 If the optional \meta{y-radius} is given, the polar coordinate is actually
51 a coordinate on an ellipse whose $x$-radius is given by \meta{radius} and
52 whose $y$-radius is given by \meta{y-radius}.
53 %
54 \begin{codeexample}[]
55 \begin{tikzpicture}
56 \draw[help lines] (0,0) grid (3,2);
57
58 \foreach \angle in {0,10,...,90}
59 {\pgfpathcircle{\pgfpointpolar{\angle}{1cm}}{2pt}}
60 \pgfusepath{fill}
61 \end{tikzpicture}
62 \end{codeexample}
63 %
64 \begin{codeexample}[]
65 \begin{tikzpicture}
66 \draw[help lines] (0,0) grid (3,2);
67
68 \foreach \angle in {0,10,...,90}
69 {\pgfpathcircle{\pgfpointpolar{\angle}{1cm and 2cm}}{2pt}}
70 \pgfusepath{fill}
71 \end{tikzpicture}
72 \end{codeexample}
73 %
74 \end{command}
75
76
77 \subsection{Coordinates in the XY-Coordinate System}
78
79 Coordinates can also be specified as multiples of an $x$-vector and a
80 $y$-vector. Normally, the $x$-vector points one centimeter in the $x$-direction
81 and the $y$-vector points one centimeter in the $y$-direction, but using the
82 commands |\pgfsetxvec| and |\pgfsetyvec| they can be changed. Note that the
83 $x$- and $y$-vector do not necessarily point ``horizontally'' and
84 ``vertically''.
85
86 \begin{command}{\pgfpointxy\marg{$s_x$}\marg{$s_y$}}
87 Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$
88 times the $y$-vector.
89 %
90 \begin{codeexample}[]
91 \begin{tikzpicture}
92 \draw[help lines] (0,0) grid (3,2);
93 \pgfpathmoveto{\pgfpointxy{1}{0}}
94 \pgfpathlineto{\pgfpointxy{2}{2}}
95 \pgfusepath{stroke}
96 \end{tikzpicture}
97 \end{codeexample}
98 %
99 \end{command}
100
101 \begin{command}{\pgfsetxvec\marg{point}}
102 Sets that current $x$-vector for usage in the $xyz$-coordinate system.
103 \example
104 %
105 \begin{codeexample}[]
106 \begin{tikzpicture}
107 \draw[help lines] (0,0) grid (3,2);
108
109 \pgfpathmoveto{\pgfpointxy{1}{0}}
110 \pgfpathlineto{\pgfpointxy{2}{2}}
111 \pgfusepath{stroke}
112
113 \color{red}
114 \pgfsetxvec{\pgfpoint{0.75cm}{0cm}}
115 \pgfpathmoveto{\pgfpointxy{1}{0}}
116 \pgfpathlineto{\pgfpointxy{2}{2}}
117 \pgfusepath{stroke}
118 \end{tikzpicture}
119 \end{codeexample}
120 %
121 \end{command}
122
123 \begin{command}{\pgfsetyvec\marg{point}}
124 Works like |\pgfsetxvec|.
125 \end{command}
126
127 \begin{command}{\pgfpointpolarxy\marg{degree}{\ttfamily\char`\{}\meta{radius}\opt{|/|\meta{y-radius}}{\ttfamily\char`\}}}
128 This command is similar to the |\pgfpointpolar| command, but the
129 \meta{radius} is now a factor to be interpreted in the $xy$-coordinate
130 system. This means that a degree of |0| is the same as the $x$-vector of
131 the $xy$-coordinate system times \meta{radius} and a degree of |90| is the
132 $y$-vector times \meta{radius}. As for |\pgfpointpolar|, a \meta{radius}
133 can also be a pair separated by a slash. In this case, the $x$- and
134 $y$-vectors are multiplied by different factors.
135 %
136 \begin{codeexample}[]
137 \begin{tikzpicture}
138 \draw[help lines] (0,0) grid (3,2);
139
140 \begin{scope}[x={(1cm,-5mm)},y=1.5cm]
141 \foreach \angle in {0,10,...,90}
142 {\pgfpathcircle{\pgfpointpolarxy{\angle}{1}}{2pt}}
143 \pgfusepath{fill}
144 \end{scope}
145 \end{tikzpicture}
146 \end{codeexample}
147 %
148 \end{command}
149
150
151 \subsection{Three Dimensional Coordinates}
152
153 It is also possible to specify a point as a multiple of three vectors, the
154 $x$-, $y$-, and $z$-vector. This is useful for creating simple three
155 dimensional graphics.
156
157 \begin{command}{\pgfpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}}
158 Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$
159 times the $y$-vector plus $s_z$ times the $z$-vector.
160 %
161 \begin{codeexample}[]
162 \begin{pgfpicture}
163 \pgfsetarrowsend{to}
164
165 \pgfpathmoveto{\pgfpointorigin}
166 \pgfpathlineto{\pgfpointxyz{0}{0}{1}}
167 \pgfusepath{stroke}
168 \pgfpathmoveto{\pgfpointorigin}
169 \pgfpathlineto{\pgfpointxyz{0}{1}{0}}
170 \pgfusepath{stroke}
171 \pgfpathmoveto{\pgfpointorigin}
172 \pgfpathlineto{\pgfpointxyz{1}{0}{0}}
173 \pgfusepath{stroke}
174 \end{pgfpicture}
175 \end{codeexample}
176 %
177 \end{command}
178
179 \begin{command}{\pgfsetzvec\marg{point}}
180 Works like |\pgfsetxvec|.
181 \end{command}
182
183 Inside the $xyz$-coordinate system, you can also specify points using spherical
184 and cylindrical coordinates.
185
186 \begin{command}{\pgfpointcylindrical\marg{degree}\marg{radius}\marg{height}}
187 This command yields the same as
188 %
189 \begin{verbatim}
190 \pgfpointadd{\pgfpointpolarxy{degree}{radius}}{\pgfpointxyz{0}{0}{height}}
191 \end{verbatim}
192 %
193 \begin{codeexample}[]
194 \begin{tikzpicture}
195 \draw [->] (0,0) -- (1,0,0) node [right] {$x$};
196 \draw [->] (0,0) -- (0,1,0) node [above] {$y$};
197 \draw [->] (0,0) -- (0,0,1) node [below left] {$z$};
198
199 \pgfpathcircle{\pgfpointcylindrical{80}{1}{.5}}{2pt}
200 \pgfusepath{fill}
201
202 \draw[red] (0,0) -- (0,0,.5) -- +(80:1);
203 \end{tikzpicture}
204 \end{codeexample}
205 %
206 \end{command}
207
208 \begin{command}{\pgfpointspherical\marg{longitude}\marg{latitude}\marg{radius}}
209 This command yields a point ``on the surface of the earth'' specified by
210 the \meta{longitude} and the \meta{latitude}. The radius of the earth is
211 given by \meta{radius}. The equator lies in the $xy$-plane.
212 %
213 \begin{codeexample}[]
214 \begin{tikzpicture}
215 \pgfsetfillcolor{lightgray}
216
217 \foreach \latitude in {-90,-75,...,30}
218 {
219 \foreach \longitude in {0,20,...,360}
220 {
221 \pgfpathmoveto{\pgfpointspherical{\longitude}{\latitude}{1}}
222 \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude}{1}}
223 \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude+15}{1}}
224 \pgfpathlineto{\pgfpointspherical{\longitude}{\latitude+15}{1}}
225 \pgfpathclose
226 }
227 \pgfusepath{fill,stroke}
228 }
229 \end{tikzpicture}
230 \end{codeexample}
231 %
232 \end{command}
233
234
235 \subsection{Building Coordinates From Other Coordinates}
236
237 Many commands allow you to construct a coordinate in terms of other
238 coordinates.
239
240
241 \subsubsection{Basic Manipulations of Coordinates}
242
243 \begin{command}{\pgfpointadd\marg{$v_1$}\marg{$v_2$}}
244 Returns the sum vector $\meta{$v_1$} + \meta{$v_2$}$.
245 %
246 \begin{codeexample}[]
247 \begin{tikzpicture}
248 \draw[help lines] (0,0) grid (3,2);
249 \pgfpathcircle{\pgfpointadd{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt}
250 \pgfusepath{fill}
251 \end{tikzpicture}
252 \end{codeexample}
253 %
254 \end{command}
255
256 \begin{command}{\pgfpointscale\marg{factor}\marg{coordinate}}
257 Returns the vector $\meta{factor}\meta{coordinate}$.
258 %
259 \begin{codeexample}[]
260 \begin{tikzpicture}
261 \draw[help lines] (0,0) grid (3,2);
262 \pgfpathcircle{\pgfpointscale{1.5}{\pgfpoint{1cm}{0cm}}}{2pt}
263 \pgfusepath{fill}
264 \end{tikzpicture}
265 \end{codeexample}
266 %
267 \end{command}
268
269 \begin{command}{\pgfpointdiff\marg{start}\marg{end}}
270 Returns the difference vector $\meta{end} - \meta{start}$.
271 %
272 \begin{codeexample}[]
273 \begin{tikzpicture}
274 \draw[help lines] (0,0) grid (3,2);
275 \pgfpathcircle{\pgfpointdiff{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt}
276 \pgfusepath{fill}
277 \end{tikzpicture}
278 \end{codeexample}
279 %
280 \end{command}
281
282 \begin{command}{\pgfpointnormalised\marg{point}}
283 This command returns a normalised version of \meta{point}, that is, a
284 vector of length 1pt pointing in the direction of \meta{point}. If
285 \meta{point} is the $0$-vector or extremely short, a vector of length 1pt
286 pointing upwards is returned.
287
288 This command is \emph{not} implemented by calculating the length of the
289 vector, but rather by calculating the angle of the vector and then using
290 (something equivalent to) the |\pgfpointpolar| command. This ensures that
291 the point will really have length 1pt, but it is not guaranteed that the
292 vector will \emph{precisely} point in the direction of \meta{point} due to
293 the fact that the polar tables are accurate only up to one degree.
294 Normally, this is not a problem.
295 %
296 \begin{codeexample}[]
297 \begin{tikzpicture}
298 \draw[help lines] (0,0) grid (3,2);
299 \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt}
300 \pgfpathcircle{\pgfpointscale{20}
301 {\pgfpointnormalised{\pgfpoint{2cm}{1cm}}}}{2pt}
302 \pgfusepath{fill}
303 \end{tikzpicture}
304 \end{codeexample}
305 %
306 \end{command}
307
308
309 \subsubsection{Points Traveling along Lines and Curves}
310 \label{section-pointsattime}
311
312 The commands in this section allow you to specify points on a line or a curve.
313 Imagine a point ``traveling'' along a curve from some point $p$ to another
314 point $q$. At time $t=0$ the point is at $p$ and at time $t=1$ it is at $q$ and
315 at time, say, $t=1/2$ it is ``somewhere in the middle''. The exact location at
316 time $t=1/2$ will not necessarily be the ``halfway point'', that is, the point
317 whose distance on the curve from $p$ and $q$ is equal. Rather, the exact
318 location will depend on the ``speed'' at which the point is traveling, which in
319 turn depends on the lengths of the support vectors in a complicated manner. If
320 you are interested in the details, please see a good book on Bézier curves.
321
322 \begin{command}{\pgfpointlineattime\marg{time $t$}\marg{point $p$}\marg{point $q$}}
323 Yields a point that is the $t$th fraction between $p$ and~$q$, that is, $p
324 + t(q-p)$. For $t=1/2$ this is the middle of $p$ and $q$.
325 %
326 \begin{codeexample}[]
327 \begin{tikzpicture}
328 \draw[help lines] (0,0) grid (3,2);
329 \pgfpathmoveto{\pgfpointorigin}
330 \pgfpathlineto{\pgfpoint{2cm}{2cm}}
331 \pgfusepath{stroke}
332 \foreach \t in {0,0.25,...,1.25}
333 {\pgftext[at=
334 \pgfpointlineattime{\t}{\pgfpointorigin}{\pgfpoint{2cm}{2cm}}]{\t}}
335 \end{tikzpicture}
336 \end{codeexample}
337 %
338 \end{command}
339
340 \begin{command}{\pgfpointlineatdistance\marg{distance}\marg{start point}\marg{end point}}
341 Yields a point that is located \meta{distance} many units away from the
342 start point in the direction of the end point. In other words, this is the
343 point that results if we travel \meta{distance} steps from \meta{start
344 point} towards \meta{end point}.
345 %
346 \example
347 %
348 \begin{codeexample}[]
349 \begin{tikzpicture}
350 \draw[help lines] (0,0) grid (3,2);
351 \pgfpathmoveto{\pgfpointorigin}
352 \pgfpathlineto{\pgfpoint{3cm}{2cm}}
353 \pgfusepath{stroke}
354 \foreach \d in {0pt,20pt,40pt,70pt}
355 {\pgftext[at=
356 \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}}
357 \end{tikzpicture}
358 \end{codeexample}
359 %
360 \end{command}
361
362 \begin{command}{\pgfpointarcaxesattime\marg{time $t$}\marg{center}\marg{0-degree axis}\marg{90-degree axis}\marg{start angle}\\\marg{end angle}}
363 Yields a point on the arc between \meta{start angle} and \meta{end angle}
364 on an ellipse whose center is at \meta{center} and whose two principal axes
365 are \meta{0-degree axis} and \meta{90-degree axis}. For $t=0$ the point at
366 the \meta{start angle} is returned and for $t=1$ the point at the \meta{end
367 angle}.
368 %
369 \begin{codeexample}[]
370 \begin{tikzpicture}
371 \draw[help lines] (0,0) grid (3,2);
372 \pgfpathmoveto{\pgfpoint{2cm}{1cm}}
373 \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}
374 \pgfusepath{stroke}
375 \foreach \t in {0,0.25,0.5,0.75,1}
376 {\pgftext[at=\pgfpointarcaxesattime{\t}{\pgfpoint{0cm}{1cm}}
377 {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}{0}{60}]{\t}}
378 \end{tikzpicture}
379 \end{codeexample}
380 %
381 \end{command}
382
383 \begin{command}{\pgfpointcurveattime\marg{time $t$}\marg{point $p$}\marg{point $s_1$}\marg{point $s_2$}\marg{point $q$}}
384 Yields a point that is on the Bézier curve from $p$ to $q$ with the support
385 points $s_1$ and $s_2$. The time $t$ is used to determine the location,
386 where $t=0$ yields $p$ and $t=1$ yields $q$.
387 %
388 \begin{codeexample}[]
389 \begin{tikzpicture}
390 \draw[help lines] (0,0) grid (3,2);
391 \pgfpathmoveto{\pgfpointorigin}
392 \pgfpathcurveto
393 {\pgfpoint{0cm}{2cm}}{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}
394 \pgfusepath{stroke}
395 \foreach \t in {0,0.25,0.5,0.75,1}
396 {\pgftext[at=\pgfpointcurveattime{\t}{\pgfpointorigin}
397 {\pgfpoint{0cm}{2cm}}
398 {\pgfpoint{0cm}{2cm}}
399 {\pgfpoint{3cm}{2cm}}]{\t}}
400 \end{tikzpicture}
401 \end{codeexample}
402 %
403 \end{command}
404
405
406 \subsubsection{Points on Borders of Objects}
407
408 The following commands are useful for specifying a point that lies on the
409 border of special shapes. They are used, for example, by the shape mechanism to
410 determine border points of shapes.
411
412 \begin{command}{\pgfpointborderrectangle\marg{direction point}\marg{corner}}
413 This command returns a point that lies on the intersection of a line
414 starting at the origin and going towards the point \meta{direction point}
415 and a rectangle whose center is in the origin and whose upper right corner
416 is at \meta{corner}.
417
418 The \meta{direction point} should have length ``about 1pt'', but it will be
419 normalized automatically. Nevertheless, the ``nearer'' the length is to
420 1pt, the less rounding errors.
421 %
422 \begin{codeexample}[]
423 \begin{tikzpicture}
424 \draw[help lines] (0,0) grid (2,1.5);
425 \pgfpathrectanglecorners{\pgfpoint{-1cm}{-1.25cm}}{\pgfpoint{1cm}{1.25cm}}
426 \pgfusepath{stroke}
427
428 \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt}
429 \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt}
430 \pgfusepath{fill}
431 \color{red}
432 \pgfpathcircle{\pgfpointborderrectangle
433 {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
434 \pgfpathcircle{\pgfpointborderrectangle
435 {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
436 \pgfusepath{fill}
437 \end{tikzpicture}
438 \end{codeexample}
439 %
440 \end{command}
441
442 \begin{command}{\pgfpointborderellipse\marg{direction point}\marg{corner}}
443 This command works like the corresponding command for rectangles, only this
444 time the \meta{corner} is the corner of the bounding rectangle of an
445 ellipse.
446 %
447 \begin{codeexample}[]
448 \begin{tikzpicture}
449 \draw[help lines] (0,0) grid (2,1.5);
450 \pgfpathellipse{\pgfpointorigin}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{1.25cm}}
451 \pgfusepath{stroke}
452
453 \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt}
454 \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt}
455 \pgfusepath{fill}
456 \color{red}
457 \pgfpathcircle{\pgfpointborderellipse
458 {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
459 \pgfpathcircle{\pgfpointborderellipse
460 {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
461 \pgfusepath{fill}
462 \end{tikzpicture}
463 \end{codeexample}
464 %
465 \end{command}
466
467
468 \subsubsection{Points on the Intersection of Lines}
469
470 \begin{command}{\pgfpointintersectionoflines\marg{$p$}\marg{$q$}\marg{$s$}\marg{$t$}}
471 This command returns the intersection of a line going through $p$ and $q$
472 and a line going through $s$ and $t$. If the lines do not intersection, an
473 arithmetic overflow will occur.
474 %
475 \begin{codeexample}[]
476 \begin{tikzpicture}
477 \draw[help lines] (0,0) grid (2,2);
478 \draw (.5,0) -- (2,2);
479 \draw (1,2) -- (2,0);
480 \pgfpathcircle{%
481 \pgfpointintersectionoflines
482 {\pgfpointxy{.5}{0}}{\pgfpointxy{2}{2}}
483 {\pgfpointxy{1}{2}}{\pgfpointxy{2}{0}}}
484 {2pt}
485 \pgfusepath{stroke}
486 \end{tikzpicture}
487 \end{codeexample}
488 %
489 \end{command}
490
491
492 \subsubsection{Points on the Intersection of Two Circles}
493
494 \begin{command}{\pgfpointintersectionofcircles\marg{$p_1$}\marg{$p_2$}\marg{$r_1$}\marg{$r_2$}\marg{solution}}
495 This command returns the intersection of the two circles centered at $p_1$
496 and $p_2$ with radii $r_1$ and $r_2$. If \meta{solution} is |1|, the first
497 intersection is returned, otherwise the second one is returned.
498 %
499 \begin{codeexample}[]
500 \begin{tikzpicture}
501 \draw[help lines] (0,0) grid (2,2);
502 \draw (0.5,0) circle (1);
503 \draw (1.5,1) circle (.8);
504 \pgfpathcircle{%
505 \pgfpointintersectionofcircles
506 {\pgfpointxy{.5}{0}}{\pgfpointxy{1.5}{1}}
507 {1cm}{0.8cm}{1}}
508 {2pt}
509 \pgfusepath{stroke}
510 \end{tikzpicture}
511 \end{codeexample}
512 %
513 \end{command}
514
515
516 \subsubsection{Points on the Intersection of Two Paths}
517
518 \begin{pgflibrary}{intersections}
519 This library defines the below command and allows you to calculate the
520 intersections of two arbitrary paths. However, due to the low accuracy of
521 \TeX, the paths should not be ``too complicated''. In particular, you
522 should not try to intersect paths consisting of lots of very small segments
523 such as plots or decorated paths.
524 \end{pgflibrary}
525
526 \begin{command}{\pgfintersectionofpaths\marg{path 1}\marg{path 2}}
527 This command finds the intersection points on the paths \meta{path 1} and
528 \meta{path 2}. The number of intersection points (``solutions'') that are
529 found will be stored, and each point can be accessed afterward. The code
530 for \meta{path 1} and \meta{path 2} is executed within a \TeX{} group and
531 so can contain transformations (which will be in addition to any existing
532 transformations). The code should not use the path in any way, unless the
533 path is saved first and restored afterward. \pgfname{} will regard
534 solutions as ``a bit special'', in that the points returned will be
535 ``absolute'' and unaffected by any further transformations.
536 %
537 \begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
538 \begin{pgfpicture}
539 \pgfintersectionofpaths
540 {
541 \pgfpathellipse{\pgfpointxy{0}{0}}{\pgfpointxy{1}{0}}{\pgfpointxy{0}{2}}
542 \pgfgetpath\temppath
543 \pgfusepath{stroke}
544 \pgfsetpath\temppath
545 }
546 {
547 \pgftransformrotate{-30}
548 \pgfpathrectangle{\pgfpointorigin}{\pgfpointxy{2}{2}}
549 \pgfgetpath\temppath
550 \pgfusepath{stroke}
551 \pgfsetpath\temppath
552 }
553 \foreach \s in {1,...,\pgfintersectionsolutions}
554 {\pgfpathcircle{\pgfpointintersectionsolution{\s}}{2pt}}
555 \pgfusepath{stroke}
556 \end{pgfpicture}
557 \end{codeexample}
558
559 \begin{command}{\pgfintersectionsolutions}
560 After using the |\pgfintersectionofpaths| command, this \TeX-macro will
561 indicate the number of solutions found.
562 \end{command}
563
564 \begin{command}{\pgfpointintersectionsolution\marg{number}}
565 After using the |\pgfintersectionofpaths| command, this command will
566 return the point for solution \meta{number} or the origin if this
567 solution was not found. By default, the intersections are simply
568 returned in the order that the intersection algorithm finds them.
569 Unfortunately, this is not necessarily a ``helpful'' ordering. However
570 the following two commands can be used to order the solutions more
571 helpfully.
572 \end{command}
573
574 \let\ifpgfintersectionsortbyfirstpath=\relax
575 \begin{command}{\pgfintersectionsortbyfirstpath}
576 Using this command will mean the solutions will be sorted along
577 \meta{path 1}.
578 \end{command}
579
580 \let\ifpgfintersectionsortbysecondpath=\relax
581 \begin{command}{\pgfintersectionsortbysecondpath}
582 Using this command will mean the solutions will be sorted along
583 \meta{path 2}.
584 \end{command}
585 \end{command}
586
587
588 \subsection{Extracting Coordinates}
589
590 There are two commands that can be used to ``extract'' the $x$- or
591 $y$-coordinate of a coordinate.
592
593 \begin{command}{\pgfextractx\marg{dimension}\marg{point}}
594 Sets the \TeX-\meta{dimension} to the $x$-coordinate of the point.
595 %
596 \begin{codeexample}[code only]
597 \newdimen\mydim
598 \pgfextractx{\mydim}{\pgfpoint{2cm}{4pt}}
599 %% \mydim is now 2cm
600 \end{codeexample}
601 %
602 \end{command}
603
604 \begin{command}{\pgfextracty\marg{dimension}\marg{point}}
605 Like |\pgfextractx|, except for the $y$-coordinate.
606 \end{command}
607
608 \begin{command}{\pgfgetlastxy\marg{macro for $x$}\marg{macro for $y$}}
609 Stores the most recently used $(x,y)$ coordinates into two macros.
610 %
611 \begin{codeexample}[]
612 \pgfpoint{2cm}{4cm}
613 \pgfgetlastxy{\macrox}{\macroy}
614 Macro $x$ is `\macrox' and macro $y$ is `\macroy'.
615 \end{codeexample}
616 %
617 Since $(x,y)$ coordinates are usually assigned globally, it is safe to use
618 this command after path operations.
619 \end{command}
620
621
622 \subsection{Internals of How Point Commands Work}
623 \label{section-internal-pointcmds}
624
625 As a normal user of \pgfname\ you do not need to read this section. It is
626 relevant only if you need to understand how the point commands work internally.
627
628 When a command like |\pgfpoint{1cm}{2pt}| is called, all that happens is that
629 the two \TeX-dimension variables |\pgf@x| and |\pgf@y| are set to |1cm| and
630 |2pt|, respectively. These variables belong to the set of internal \pgfname\
631 registers, see section~\ref{section-internal-registers} for details. A command
632 like |\pgfpathmoveto| that takes a coordinate as parameter will just execute
633 this parameter and then use the values of |\pgf@x| and |\pgf@y| as the
634 coordinates to which it will move the pen on the current path.
635
636 Since commands like |\pgfpointnormalised| modify other variables besides
637 |\pgf@x| and |\pgf@y| during the computation of the final values of |\pgf@x|
638 and |\pgf@y|, it is a good idea to enclose a call of a command like |\pgfpoint|
639 in a \TeX-scope and then make the changes of |\pgf@x| and |\pgf@y| global as in
640 the following example:
641 %
642 \begin{codeexample}[code only]
643 ...
644 { % open scope
645 \pgfpointnormalised{\pgfpoint{1cm}{1cm}}
646 \global\pgf@x=\pgf@x % make the change of \pgf@x persist past the scope
647 \global\pgf@y=\pgf@y % make the change of \pgf@y persist past the scope
648 }
649 % \pgf@x and \pgf@y are now set correctly, all other variables are
650 % unchanged
651 \end{codeexample}
652
653 \makeatletter
654 Since this situation arises very often, the macro |\pgf@process| can
655 be used to perform the above code:
656 %
657 \begin{command}{\pgf@process\marg{code}}
658 Executes the \meta{code} in a scope and then makes |\pgf@x| and |\pgf@y|
659 global.
660 \end{command}
661
662 Note that this macro is used often internally. For this reason, it is not a
663 good idea to keep anything important in the variables |\pgf@x| and |\pgf@y|
664 since they will be overwritten and changed frequently. Instead, intermediate
665 values can be stored in the \TeX-dimensions |\pgf@xa|, |\pgf@xb|, |\pgf@xc| and
666 their |y|-counterparts |\pgf@ya|, |\pgf@yb|, |\pgf@yc|. For example, here is the
667 code of the command |\pgfpointadd|:
668 %
669 \begin{codeexample}[code only]
670 \def\pgfpointadd#1#2{%
671 \pgf@process{#1}%
672 \pgf@xa=\pgf@x%
673 \pgf@ya=\pgf@y%
674 \pgf@process{#2}%
675 \advance\pgf@x by\pgf@xa%
676 \advance\pgf@y by\pgf@ya}
677 \end{codeexample}
678
679
680 %%% Local Variables:
681 %%% mode: latex
682 %%% TeX-master: "pgfmanual"
683 %%% End: