Debian Codegraph @

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

raw
1 % Copyright 2018 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{Constructing Paths}
12
13 \subsection{Overview}
14
15 The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A path
16 consists of several parts, each of which is either a closed or open curve. An
17 open curve has a starting point and an end point and, in between, consists of
18 several \emph{segments}, each of which is either a straight line or a Bézier
19 curve. Here is an example of a path (in red) consisting of two parts, one open,
20 one closed:
21 %
22 \begin{codeexample}[]
23 \begin{tikzpicture}[scale=2]
24 \draw[thick,red]
25 (0,0) coordinate (a)
26 -- coordinate (ab) (1,.5) coordinate (b)
27 .. coordinate (bc) controls +(up:1cm) and +(left:1cm) .. (3,1) coordinate (c)
28 (0,1) -- (2,1) -- coordinate (x) (1,2) -- cycle;
29
30 \draw (a) node[below] {start part 1}
31 (ab) node[below right] {straight segment}
32 (b) node[right] {end first segment}
33 (c) node[right] {end part 1}
34 (x) node[above right] {part 2 (closed)};
35 \end{tikzpicture}
36 \end{codeexample}
37
38 A path, by itself, has no ``effect'', that is, it does not leave any marks on
39 the page. It is just a set of points on the plane. However, you can \emph{use}
40 a path in different ways. The most natural actions are \emph{stroking} (also
41 known as \emph{drawing}) and \emph{filling}. Stroking can be imagined as
42 picking up a pen of a certain diameter and ``moving it along the path''.
43 Filling means that everything ``inside'' the path is filled with a uniform
44 color. Naturally, the open parts of a path must first be closed before a path
45 can be filled.
46
47 In \pgfname, there are numerous commands for constructing paths, all of which
48 start with |\pgfpath|. There are also commands for \emph{using} paths, though
49 most operations can be performed by calling |\pgfusepath| with an appropriate
50 parameter.
51
52 As a side-effect, the path construction commands keep track of two bounding
53 boxes. One is the bounding box for the current path, the other is a bounding
54 box for all paths in the current picture. See Section~\ref{section-bb} for more
55 details.
56
57 Each path construction command extends the current path in some way. The
58 ``current path'' is a global entity that persists across \TeX\ groups. Thus,
59 between calls to the path construction commands you can perform arbitrary
60 computations and even open and close \TeX\ groups. The current path only gets
61 ``flushed'' when the |\pgfusepath| command is called (or when the soft-path
62 subsystem is used directly, see Section~\ref{section-soft-paths}).
63
64
65 \subsection{The Move-To Path Operation}
66
67 The most basic operation is the move-to operation. It must be given at the
68 beginning of paths, though some path construction command (like
69 |\pgfpathrectangle|) generate move-tos implicitly. A move-to operation can also
70 be used to start a new part of a path.
71
72 \begin{command}{\pgfpathmoveto\marg{coordinate}}
73 This command expects a \pgfname-coordinate like |\pgfpointorigin| as its
74 parameter. When the current path is empty, this operation will start the
75 path at the given \meta{coordinate}. If a path has already been partly
76 constructed, this command will end the current part of the path and start a
77 new one.
78 %
79 \begin{codeexample}[]
80 \begin{pgfpicture}
81 \pgfpathmoveto{\pgfpointorigin}
82 \pgfpathlineto{\pgfpoint{1cm}{1cm}}
83 \pgfpathlineto{\pgfpoint{2cm}{1cm}}
84 \pgfpathlineto{\pgfpoint{3cm}{0.5cm}}
85 \pgfpathlineto{\pgfpoint{3cm}{0cm}}
86 \pgfsetfillcolor{yellow!80!black}
87 \pgfusepath{fill,stroke}
88 \end{pgfpicture}
89 \end{codeexample}
90 %
91 \begin{codeexample}[]
92 \begin{pgfpicture}
93 \pgfpathmoveto{\pgfpointorigin}
94 \pgfpathlineto{\pgfpoint{1cm}{1cm}}
95 \pgfpathlineto{\pgfpoint{2cm}{1cm}}
96 \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part
97 \pgfpathlineto{\pgfpoint{3cm}{0.5cm}}
98 \pgfpathlineto{\pgfpoint{3cm}{0cm}}
99 \pgfsetfillcolor{yellow!80!black}
100 \pgfusepath{fill,stroke}
101 \end{pgfpicture}
102 \end{codeexample}
103 %
104 The command will apply the current coordinate transformation matrix to
105 \meta{coordinate} before using it.
106
107 It will update the bounding box of the current path and picture, if
108 necessary.
109 \end{command}
110
111
112 \subsection{The Line-To Path Operation}
113
114 \begin{command}{\pgfpathlineto\marg{coordinate}}
115 This command extends the current path in a straight line to the given
116 \meta{coordinate}. If this command is given at the beginning of path
117 without any other path construction command given before (in particular
118 without a move-to operation), the \TeX\ file may compile without an error
119 message, but a viewer application may display an error message when trying
120 to render the picture.
121 %
122 \begin{codeexample}[]
123 \begin{pgfpicture}
124 \pgfpathmoveto{\pgfpointorigin}
125 \pgfpathlineto{\pgfpoint{1cm}{1cm}}
126 \pgfpathlineto{\pgfpoint{2cm}{1cm}}
127 \pgfsetfillcolor{yellow!80!black}
128 \pgfusepath{fill,stroke}
129 \end{pgfpicture}
130 \end{codeexample}
131 %
132 The command will apply the current coordinate transformation matrix to
133 \meta{coordinate} before using it.
134
135 It will update the bounding box of the current path and picture, if
136 necessary.
137 \end{command}
138
139
140 \subsection{The Curve-To Path Operations}
141
142 \begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}}
143 This command extends the current path with a Bézier curve from the last
144 point of the path to \meta{coordinate}. The \meta{support 1} and
145 \meta{support 2} are the first and second support point of the Bézier
146 curve. For more information on Bézier curves, please consult a standard
147 textbook on computer graphics.
148
149 Like the line-to command, this command may not be the first path
150 construction command in a path.
151 \begin{codeexample}[]
152 \begin{pgfpicture}
153 \pgfpathmoveto{\pgfpointorigin}
154 \pgfpathcurveto
155 {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}}
156 \pgfsetfillcolor{yellow!80!black}
157 \pgfusepath{fill,stroke}
158 \end{pgfpicture}
159 \end{codeexample}
160 %
161 The command will apply the current coordinate transformation matrix to
162 \meta{coordinate} before using it.
163
164 It will update the bounding box of the current path and picture, if
165 necessary. However, the bounding box is simply made large enough such that
166 it encompasses all of the support points and the \meta{coordinate}. This
167 will guarantee that the curve is completely inside the bounding box, but
168 the bounding box will typically be quite a bit too large. It is not clear
169 (to me) how this can be avoided without resorting to ``some serious math''
170 in order to calculate a precise bounding box.
171 \end{command}
172
173 \begin{command}{\pgfpathquadraticcurveto\marg{support}\marg{coordinate}}
174 This command works like |\pgfpathcurveto|, only it uses a quadratic Bézier
175 curve rather than a cubic one. This means that only one support point is
176 needed.
177 %
178 \begin{codeexample}[]
179 \begin{pgfpicture}
180 \pgfpathmoveto{\pgfpointorigin}
181 \pgfpathquadraticcurveto
182 {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}}
183 \pgfsetfillcolor{yellow!80!black}
184 \pgfusepath{fill,stroke}
185 \end{pgfpicture}
186 \end{codeexample}
187 %
188 Internally, the quadratic curve is converted into a cubic curve. The only
189 noticeable effect of this is that the points used for computing the
190 bounding box are the control points of the converted curve rather than
191 \meta{support}. The main effect of this is that the bounding box will be a
192 bit tighter than might be expected. In particular, \meta{support} will not
193 always be part of the bounding box.
194 \end{command}
195
196 There exist two commands to draw only part of a cubic Bézier curve:
197
198 \begin{command}{\pgfpathcurvebetweentime\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}}
199 This command draws the part of the curve described by $p$, $s_1$, $s_2$ and
200 $q$ between the times $t_1$ and $t_2$. A time value of 0 indicates the
201 point $p$ and a time value of 1 indicates point $q$. This command includes
202 a moveto operation to the first point.
203 %
204 \begin{codeexample}[]
205 \begin{tikzpicture}
206 \draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2);
207 \pgfpathcurvebetweentime{0.25}{0.9}{\pgfpointxy{0}{0}}{\pgfpointxy{0}{2}}
208 {\pgfpointxy{3}{0}}{\pgfpointxy{3}{2}}
209 \pgfsetstrokecolor{red}
210 \pgfsetstrokeopacity{0.5}
211 \pgfsetlinewidth{2pt}
212 \pgfusepath{stroke}
213 \end{tikzpicture}
214 \end{codeexample}
215 %
216 \end{command}
217
218 \begin{command}{\pgfpathcurvebetweentimecontinue\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}}
219 This command works like |\pgfpathcurvebetweentime|, except that a moveto
220 operation is \emph{not} made to the first point.
221 \end{command}
222
223
224 \subsection{The Close Path Operation}
225
226 \begin{command}{\pgfpathclose}
227 This command closes the current part of the path by appending a straight
228 line to the start point of the current part. Note that there \emph{is} a
229 difference between closing a path and using the line-to operation to add a
230 straight line to the start of the current path. The difference is
231 demonstrated by the upper corners of the triangles in the following
232 example:
233 %
234 \begin{codeexample}[]
235 \begin{tikzpicture}
236 \draw[help lines] (0,0) grid (3,2);
237 \pgfsetlinewidth{5pt}
238 \pgfpathmoveto{\pgfpoint{1cm}{1cm}}
239 \pgfpathlineto{\pgfpoint{0cm}{-1cm}}
240 \pgfpathlineto{\pgfpoint{1cm}{-1cm}}
241 \pgfpathclose
242 \pgfpathmoveto{\pgfpoint{2.5cm}{1cm}}
243 \pgfpathlineto{\pgfpoint{1.5cm}{-1cm}}
244 \pgfpathlineto{\pgfpoint{2.5cm}{-1cm}}
245 \pgfpathlineto{\pgfpoint{2.5cm}{1cm}}
246 \pgfusepath{stroke}
247 \end{tikzpicture}
248 \end{codeexample}
249 %
250 \end{command}
251
252
253 \subsection{Arc, Ellipse and Circle Path Operations}
254
255 The path construction commands that we have discussed up to now are sufficient
256 to create all paths that can be created ``at all''. However, it is useful to
257 have special commands to create certain shapes, like circles, that arise often
258 in practice.
259
260 In the following, the commands for adding (parts of) (transformed) circles to a
261 path are described.
262
263 \begin{command}{\pgfpatharc\marg{start angle}\marg{end angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}}
264 This command appends a part of a circle (or an ellipse) to the current
265 path. Imagine the curve between \meta{start angle} and \meta{end angle} on
266 a circle of radius \meta{radius} (if $\meta{start angle} < \meta{end
267 angle}$, the curve goes around the circle counterclockwise, otherwise
268 clockwise). This curve is now moved such that the point where the curve
269 starts is the previous last point of the path. Note that this command will
270 \emph{not} start a new part of the path, which is important for example for
271 filling purposes.
272 %
273 \begin{codeexample}[]
274 \begin{tikzpicture}
275 \draw[help lines] (0,0) grid (3,2);
276 \pgfpathmoveto{\pgfpointorigin}
277 \pgfpathlineto{\pgfpoint{0cm}{1cm}}
278 \pgfpatharc{180}{90}{.5cm}
279 \pgfpathlineto{\pgfpoint{3cm}{1.5cm}}
280 \pgfpatharc{90}{-45}{.5cm}
281 \pgfusepath{fill}
282 \end{tikzpicture}
283 \end{codeexample}
284
285 Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full circle. The
286 ``nearly'' refers to the fact that the circle will not be closed. You can
287 close it using |\pgfpathclose|.
288
289 If the optional \meta{y-radius} is given, the \meta{radius} is the
290 $x$-radius and the \meta{y-radius} the $y$-radius of the ellipse from which
291 the curve is taken:
292 %
293 \begin{codeexample}[]
294 \begin{tikzpicture}
295 \draw[help lines] (0,0) grid (3,2);
296 \pgfpathmoveto{\pgfpointorigin}
297 \pgfpatharc{180}{45}{2cm and 1cm}
298 \pgfusepath{draw}
299 \end{tikzpicture}
300 \end{codeexample}
301
302 The axes of the circle or ellipse from which the arc is ``taken'' always
303 point up and right. However, the current coordinate transformation matrix
304 will have an effect on the arc. This can be used to, say, rotate an arc:
305 %
306 \begin{codeexample}[]
307 \begin{tikzpicture}
308 \draw[help lines] (0,0) grid (3,2);
309 \pgftransformrotate{30}
310 \pgfpathmoveto{\pgfpointorigin}
311 \pgfpatharc{180}{45}{2cm and 1cm}
312 \pgfusepath{draw}
313 \end{tikzpicture}
314 \end{codeexample}
315
316 The command will update the bounding box of the current path and picture,
317 if necessary. Unless rotation or shearing transformations are applied, the
318 bounding box will be tight.
319 \end{command}
320
321 \begin{command}{\pgfpatharcaxes\marg{start angle}\marg{end angle}\marg{first axis}\marg{second axis}}
322 This command is similar to |\pgfpatharc|. The main difference is how the
323 ellipse or circle is specified from which the arc is taken. The two
324 parameters \meta{first axis} and \meta{second axis} are the $0^\circ$-axis
325 and the $90^\circ$-axis of the ellipse from which the path is taken. Thus,
326 |\pgfpatharc{0}{90}{1cm and 2cm}| has the same effect as
327 %
328 \begin{verbatim}
329 \pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}}
330 \end{verbatim}
331 %
332 \begin{codeexample}[]
333 \begin{tikzpicture}
334 \draw[help lines] (0,0) grid (3,2);
335 \draw (0,0) -- (2cm,5mm) (0,0) -- (0cm,1cm);
336
337 \pgfpathmoveto{\pgfpoint{2cm}{5mm}}
338 \pgfpatharcaxes{0}{90}{\pgfpoint{2cm}{5mm}}{\pgfpoint{0cm}{1cm}}
339 \pgfusepath{draw}
340 \end{tikzpicture}
341 \end{codeexample}
342 %
343 \end{command}
344
345 \begin{command}{\pgfpatharcto\marg{x-radius}\marg{y-radius}\marg{rotation} \marg{large arc flag}\marg{counterclockwise flag}\\\marg{target point}}
346 This command (which directly corresponds to the arc-path command of
347 \textsc{svg}) is used to add an arc to the path that starts at the current
348 point and ends at \meta{target point}. This arc is part of an ellipse that
349 is determined in the following way: Imagine an ellipse with radii
350 \meta{x-radius} and \meta{y-radius} that is rotated around its center by
351 \meta{rotation} degrees. When you move this ellipse around in the plane,
352 there will be exactly two positions such that the two current point and the
353 target point lie on the border of the ellipse (excluding pathological
354 cases). The flags \meta{large arc flag} and \meta{clockwise flag} are then
355 used to decide which of these ellipses should be picked and which arc on
356 the picked ellipsis should be used.
357 %
358 \begin{codeexample}[]
359 \begin{tikzpicture}
360 \draw[help lines] (0,0) grid (3,2);
361
362 \pgfpathmoveto{\pgfpoint{0mm}{20mm}}
363 \pgfpatharcto{3cm}{1cm}{0}{0}{0}{\pgfpoint{3cm}{1cm}}
364 \pgfusepath{draw}
365 \end{tikzpicture}
366 \end{codeexample}
367 %
368 Both flags are considered to be false exactly if they evaluate to |0|,
369 otherwise they are true. If the \meta{large arc flag} is true, then the
370 angle spanned by the arc will be greater than $180^\circ$, otherwise it
371 will be less than $180^\circ$. The \meta{clockwise flag} is used to
372 determine which of the two ellipses should be used: if the flag is true,
373 then the arc goes from the current point to the target point in a
374 counterclockwise direction, otherwise in a clockwise fashion.
375 %
376 \begin{codeexample}[]
377 \begin{tikzpicture}
378 \pgfsetlinewidth{2pt}
379 % Flags 0 0: red
380 \pgfsetstrokecolor{red}
381 \pgfpathmoveto{\pgfpointorigin}
382 \pgfpatharcto{20pt}{10pt}{0}{0}{0}{\pgfpoint{20pt}{10pt}}
383 \pgfusepath{stroke}
384 % Flags 0 1: blue
385 \pgfsetstrokecolor{blue}
386 \pgfpathmoveto{\pgfpointorigin}
387 \pgfpatharcto{20pt}{10pt}{0}{0}{1}{\pgfpoint{20pt}{10pt}}
388 \pgfusepath{stroke}
389 % Flags 1 0: orange
390 \pgfsetstrokecolor{orange}
391 \pgfpathmoveto{\pgfpointorigin}
392 \pgfpatharcto{20pt}{10pt}{0}{1}{0}{\pgfpoint{20pt}{10pt}}
393 \pgfusepath{stroke}
394 % Flags 1 1: black
395 \pgfsetstrokecolor{black}
396 \pgfpathmoveto{\pgfpointorigin}
397 \pgfpatharcto{20pt}{10pt}{0}{1}{1}{\pgfpoint{20pt}{10pt}}
398 \pgfusepath{stroke}
399 \end{tikzpicture}
400 \end{codeexample}
401 %
402 \emph{Warning:} The internal computations necessary for this command are
403 numerically very unstable. In particular, the arc will not always really
404 end at the \meta{target coordinate}, but may be off by up to several
405 points. A more precise positioning is currently infeasible due to \TeX's
406 numerical weaknesses. The only case it works quite nicely is when the
407 resulting angle is a multiple of~$90^\circ$.
408 \end{command}
409
410 \begin{command}{\pgfpatharctoprecomputed\marg{center point}\marg{start angle}\marg{end angle}\marg{end point}\\\marg{x-radius}\marg{y-radius}\marg{ratio x-radius/y-radius}\marg{ratio y-radius/x-radius}}
411 A specialized arc operation which is fast and numerically stable, provided
412 a lot of information is given in advance.
413
414 In contrast to |\pgfpatharc|, it explicitly interpolates start and end
415 points.
416
417 In contrast to |\pgfpatharcto|, this routine is numerically stable and
418 quite fast since it relies on a lot of available information.
419 %
420 \begin{codeexample}[]
421 \begin{tikzpicture}
422 \draw[help lines] (0,0) grid (3,2);
423
424 \def\cx{1.5cm}% center x
425 \def\cy{1cm}% center y
426 \def\startangle{0}%
427 \def\endangle{270}%
428 \def\a{1.5cm}% xradius
429 \def\b{0.5cm}% yradius
430 \pgfmathparse{\a/\b}\let\abratio=\pgfmathresult
431 \pgfmathparse{\b/\a}\let\baratio=\pgfmathresult
432 %
433 % start point:
434 \pgfpathmoveto{\pgfpoint{\cx+\a*cos(\startangle)}{\cy+\b*sin(\startangle)}}%
435 \pgfpatharctoprecomputed
436 {\pgfpoint{\cx}{\cy}}
437 {\startangle}
438 {\endangle}
439 {\pgfpoint{\cx+\a*cos(\endangle)}{\cy+\b*sin(\endangle)}}% end point
440 {\a}
441 {\b}
442 {\abratio}
443 {\baratio}
444 \pgfusepath{draw}
445 \end{tikzpicture}
446 \end{codeexample}
447
448 \begin{command}{\pgfpatharctomaxstepsize}
449 The quality of arc approximation taken by |\pgfpatharctoprecomputed| by
450 means of Bézier splines is controlled by a mesh width, which is
451 initially
452
453 |\def\pgfpatharctoprecomputed{45}|.
454
455 The mesh width is provided in (full!) degrees. The smaller the mesh
456 width, the more precise the arc approximation.
457
458 Use an empty value to disable spline approximation (uses a single cubic
459 polynomial for the complete arc).
460
461 The value must be an integer!
462 \end{command}
463 \end{command}
464
465 \begin{command}{\pgfpathellipse\marg{center}\marg{first axis}\marg{second axis}}
466 The effect of this command is to append an ellipse to the current path (if
467 the path is not empty, a new part is started). The ellipse's center will be
468 \meta{center} and \meta{first axis} and \meta{second axis} are the axis
469 \emph{vectors}. The same effect as this command can also be achieved using
470 an appropriate sequence of move-to, arc, and close operations, but this
471 command is easier and faster.
472 %
473 \begin{codeexample}[]
474 \begin{tikzpicture}
475 \draw[help lines] (0,0) grid (3,2);
476 \pgfpathellipse{\pgfpoint{1cm}{0cm}}
477 {\pgfpoint{1.5cm}{0cm}}
478 {\pgfpoint{0cm}{1cm}}
479 \pgfusepath{draw}
480 \color{red}
481 \pgfpathellipse{\pgfpoint{1cm}{0cm}}
482 {\pgfpoint{1cm}{1cm}}
483 {\pgfpoint{-0.5cm}{0.5cm}}
484 \pgfusepath{draw}
485 \end{tikzpicture}
486 \end{codeexample}
487
488 The command will apply coordinate transformations to all coordinates of the
489 ellipse. However, the coordinate transformations are applied only after the
490 ellipse is ``finished conceptually''. Thus, a transformation of 1cm to the
491 right will simply shift the ellipse one centimeter to the right; it will
492 not add 1cm to the $x$-coordinates of the two axis vectors.
493
494 The command will update the bounding box of the current path and picture,
495 if necessary.
496 \end{command}
497
498 \begin{command}{\pgfpathcircle\marg{center}\marg{radius}}
499 A shorthand for |\pgfpathellipse| applied to \meta{center} and the two axis
500 vectors $(\meta{radius},0)$ and $(0,\meta{radius})$.
501 \end{command}
502
503
504 \subsection{Rectangle Path Operations}
505
506 Another shape that arises frequently is the rectangle. Two commands can be used
507 to add a rectangle to the current path. Both commands will start a new part of
508 the path.
509
510 \begin{command}{\pgfpathrectangle\marg{corner}\marg{diagonal vector}}
511 Adds a rectangle to the path whose one corner is \meta{corner} and whose
512 opposite corner is given by $\meta{corner} + \meta{diagonal vector}$.
513 %
514 \begin{codeexample}[]
515 \begin{tikzpicture}
516 \draw[help lines] (0,0) grid (3,2);
517 \pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}}
518 \pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}}
519 \pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}}
520 \pgfusepath{draw}
521 \end{tikzpicture}
522 \end{codeexample}
523 %
524 The command will apply coordinate transformations and update the bounding
525 boxes tightly.
526 \end{command}
527
528 \begin{command}{\pgfpathrectanglecorners\marg{corner}\marg{opposite corner}}
529 Adds a rectangle to the path whose two opposing corners are \meta{corner}
530 and \meta{opposite corner}.
531 %
532 \begin{codeexample}[]
533 \begin{tikzpicture}
534 \draw[help lines] (0,0) grid (3,2);
535 \pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}}
536 \pgfusepath{draw}
537 \end{tikzpicture}
538 \end{codeexample}
539 %
540 The command will apply coordinate transformations and update the bounding
541 boxes tightly.
542 \end{command}
543
544
545 \subsection{The Grid Path Operation}
546
547 \begin{command}{\pgfpathgrid\oarg{options}\marg{first corner}\marg{second corner}}
548 Appends a grid to the current path. That is, a (possibly large) number of
549 parts are added to the path, each part consisting of a single horizontal or
550 vertical straight line segment.
551
552 Conceptually, the origin is part of the grid and the grid is clipped to the
553 rectangle specified by the \meta{first corner} and the \meta{second
554 corner}. However, no clipping occurs (this command just adds parts to the
555 current path) and the points where the lines enter and leave the ``clipping
556 area'' are computed and used to add simple lines to the current path.
557
558 The following keys influence the grid:
559 %
560 \begin{key}{/pgf/stepx=\meta{dimension} (initially 1cm)}
561 The horizontal stepping.
562 \end{key}
563 %
564 \begin{key}{/pgf/stepy=\meta{dimension} (initially 1cm)}
565 The vertical stepping.
566 \end{key}
567 %
568 \begin{key}{/pgf/step=\meta{vector}}
569 Sets the horizontal stepping to the $x$-coordinate of \meta{vector} and
570 the vertical stepping to its $y$-coordinate.
571 \end{key}
572 %
573 \begin{codeexample}[]
574 \begin{pgfpicture}
575 \pgfsetlinewidth{0.8pt}
576 \pgfpathgrid[step={\pgfpoint{1cm}{1cm}}]
577 {\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}}
578 \pgfusepath{stroke}
579 \pgfsetlinewidth{0.4pt}
580 \pgfpathgrid[stepx=1mm,stepy=1mm]
581 {\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}}
582 \pgfusepath{stroke}
583 \end{pgfpicture}
584 \end{codeexample}
585 %
586 The command will apply coordinate transformations and update the bounding
587 boxes. As for ellipses, the transformations are applied to the
588 ``conceptually finished'' grid.
589 %
590 \begin{codeexample}[]
591 \begin{pgfpicture}
592 \pgftransformrotate{10}
593 \pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}}
594 \pgfusepath{stroke}
595 \end{pgfpicture}
596 \end{codeexample}
597 %
598 \end{command}
599
600
601 \subsection{The Parabola Path Operation}
602
603 \begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}}
604 This command appends two half-parabolas to the current path. The first
605 starts at the current point and ends at the current point plus \meta{bend
606 vector}. At this point, it has its bend. The second half parabola starts at
607 that bend point and ends at point that is given by the bend plus \meta{end
608 vector}.
609
610 If you set \meta{end vector} to the null vector, you append only a half
611 parabola that goes from the current point to the bend; by setting
612 \meta{bend vector} to the null vector, you append only a half parabola that
613 goes through the current point and \meta{end vector} and has its bend at
614 the current point.
615
616 It is not possible to use this command to draw a part of a parabola that
617 does not contain the bend.
618 %
619 \begin{codeexample}[]
620 \begin{pgfpicture}
621 % Half-parabola going ``up and right''
622 \pgfpathmoveto{\pgfpointorigin}
623 \pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}}
624 \color{red}
625 \pgfusepath{stroke}
626
627 % Half-parabola going ``down and right''
628 \pgfpathmoveto{\pgfpointorigin}
629 \pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin}
630 \color{blue}
631 \pgfusepath{stroke}
632
633 % Full parabola
634 \pgfpathmoveto{\pgfpoint{-2cm}{2cm}}
635 \pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}}
636 \color{orange}
637 \pgfusepath{stroke}
638 \end{pgfpicture}
639 \end{codeexample}
640 %
641 The command will apply coordinate transformations and update the bounding
642 boxes.
643 \end{command}
644
645
646 \subsection{Sine and Cosine Path Operations}
647
648 Sine and cosine curves often need to be drawn and the following commands may
649 help with this. However, they only allow you to append sine and cosine curves
650 in intervals that are multiples of $\pi/2$.
651
652 \begin{command}{\pgfpathsine\marg{vector}}
653 This command appends a sine curve in the interval $[0,\pi/2]$ to the
654 current path. The sine curve is squeezed or stretched such that the curve
655 starts at the current point and ends at the current point plus
656 \meta{vector}.
657 %
658 \begin{codeexample}[]
659 \begin{tikzpicture}
660 \draw[help lines] (0,0) grid (3,1);
661 \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
662 \pgfpathsine{\pgfpoint{1cm}{1cm}}
663 \pgfusepath{stroke}
664
665 \color{red}
666 \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
667 \pgfpathsine{\pgfpoint{-2cm}{-2cm}}
668 \pgfusepath{stroke}
669 \end{tikzpicture}
670 \end{codeexample}
671 %
672 The command will apply coordinate transformations and update the bounding
673 boxes.
674 \end{command}
675
676 \begin{command}{\pgfpathcosine\marg{vector}}
677 This command appends a cosine curve in the interval $[0,\pi/2]$ to the
678 current path. The curve is squeezed or stretched such that the curve starts
679 at the current point and ends at the current point plus \meta{vector}.
680 Using several sine and cosine operations in sequence allows you to produce
681 a complete sine or cosine curve
682 %
683 \begin{codeexample}[]
684 \begin{pgfpicture}
685 \pgfpathmoveto{\pgfpoint{0cm}{0cm}}
686 \pgfpathsine{\pgfpoint{1cm}{1cm}}
687 \pgfpathcosine{\pgfpoint{1cm}{-1cm}}
688 \pgfpathsine{\pgfpoint{1cm}{-1cm}}
689 \pgfpathcosine{\pgfpoint{1cm}{1cm}}
690 \pgfsetfillcolor{yellow!80!black}
691 \pgfusepath{fill,stroke}
692 \end{pgfpicture}
693 \end{codeexample}
694 %
695 The command will apply coordinate transformations and update the bounding
696 boxes.
697 \end{command}
698
699
700 \subsection{Plot Path Operations}
701
702 There exist several commands for appending plots to a path. These commands are
703 available through the module |plot|. They are documented in
704 Section~\ref{section-plots}.
705
706
707 \subsection{Rounded Corners}
708
709 Normally, when you connect two straight line segments or when you connect two
710 curves that end and start ``at different angles'', you get ``sharp corners''
711 between the lines or curves. In some cases it is desirable to produce ``rounded
712 corners'' instead. Thus, the lines or curves should be shortened a bit and then
713 connected by arcs.
714
715 \pgfname\ offers an easy way to achieve this effect, by calling the following
716 two commands.
717
718 \begin{command}{\pgfsetcornersarced\marg{point}}
719 This command causes all subsequent corners to be replaced by little
720 arcs. The effect of this command lasts till the end of the current
721 \TeX\ scope.
722
723 The \meta{point} dictates how large the corner arc will be. Consider a
724 corner made by two lines $l$ and~$r$ and assume that the line $l$ comes
725 first on the path. The $x$-dimension of the \meta{point} decides by how
726 much the line~$l$ will be shortened, the $y$-dimension of \meta{point}
727 decides by how much the line $r$ will be shortened. Then, the shortened
728 lines are connected by an arc.
729 %
730 \begin{codeexample}[]
731 \begin{tikzpicture}
732 \draw[help lines] (0,0) grid (3,2);
733
734 \pgfsetcornersarced{\pgfpoint{5mm}{5mm}}
735 \pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}
736 \pgfusepath{stroke}
737 \end{tikzpicture}
738 \end{codeexample}
739
740 \begin{codeexample}[]
741 \begin{tikzpicture}
742 \draw[help lines] (0,0) grid (3,2);
743
744 \pgfsetcornersarced{\pgfpoint{10mm}{5mm}}
745 % 10mm entering,
746 % 5mm leaving.
747 \pgfpathmoveto{\pgfpointorigin}
748 \pgfpathlineto{\pgfpoint{0cm}{2cm}}
749 \pgfpathlineto{\pgfpoint{3cm}{2cm}}
750 \pgfpathcurveto
751 {\pgfpoint{3cm}{0cm}}
752 {\pgfpoint{2cm}{0cm}}
753 {\pgfpoint{1cm}{0cm}}
754 \pgfusepath{stroke}
755 \end{tikzpicture}
756 \end{codeexample}
757
758 If the $x$- and $y$-coordinates of \meta{point} are the same and the corner
759 is a right angle, you will get a perfect quarter circle (well, not quite
760 perfect, but perfect up to six decimals). When the angle is not $90^\circ$,
761 you only get a fair approximation.
762
763 More or less ``all'' corners will be rounded, even the corner generated by
764 a |\pgfpathclose| command. (The author is a bit proud of this feature.)
765 %
766 \begin{codeexample}[]
767 \begin{pgfpicture}
768 \pgfsetcornersarced{\pgfpoint{4pt}{4pt}}
769 \pgfpathmoveto{\pgfpointpolar{0}{1cm}}
770 \pgfpathlineto{\pgfpointpolar{72}{1cm}}
771 \pgfpathlineto{\pgfpointpolar{144}{1cm}}
772 \pgfpathlineto{\pgfpointpolar{216}{1cm}}
773 \pgfpathlineto{\pgfpointpolar{288}{1cm}}
774 \pgfpathclose
775 \pgfusepath{stroke}
776 \end{pgfpicture}
777 \end{codeexample}
778
779 To return to normal (unrounded) corners, use
780 |\pgfsetcornersarced{\pgfpointorigin}|.
781
782 Note that the rounding will produce strange and undesirable effects if the
783 lines at the corners are too short. In this case the shortening may cause
784 the lines to ``suddenly extend over the other end'' which is rarely
785 desirable.
786 \end{command}
787
788
789 \subsection{Internal Tracking of Bounding Boxes for Paths and Pictures}
790 \label{section-bb}
791
792 \makeatletter
793
794 The path construction commands keep track of two bounding boxes: One for the
795 current path, which is reset whenever the path is used and thereby flushed, and
796 a bounding box for the current |{pgfpicture}|.
797
798 \begin{command}{\pgfresetboundingbox}
799 Resets the picture's bounding box. The picture will simply forget any
800 previous bounding box updates and start collecting from scratch.
801
802 You can use this together with |\pgfusepath{use as bounding box}| to
803 replace the bounding box by the one of a particular path (ignoring
804 subsequent paths).
805 \end{command}
806
807 The bounding boxes are not accessible by ``normal'' macros. Rather, two sets of
808 four dimension variables are used for this, all of which contain the
809 letter~|@|.
810
811 \begin{textoken}{\pgf@pathminx}
812 The minimum $x$-coordinate ``mentioned'' in the current path. Initially,
813 this is set to $16000$pt.
814 \end{textoken}
815
816 \begin{textoken}{\pgf@pathmaxx}
817 The maximum $x$-coordinate ``mentioned'' in the current path. Initially,
818 this is set to $-16000$pt.
819 \end{textoken}
820
821 \begin{textoken}{\pgf@pathminy}
822 The minimum $y$-coordinate ``mentioned'' in the current path. Initially,
823 this is set to $16000$pt.
824 \end{textoken}
825
826 \begin{textoken}{\pgf@pathmaxy}
827 The maximum $y$-coordinate ``mentioned'' in the current path. Initially,
828 this is set to $-16000$pt.
829 \end{textoken}
830
831 \begin{textoken}{\pgf@picminx}
832 The minimum $x$-coordinate ``mentioned'' in the current picture. Initially,
833 this is set to $16000$pt.
834 \end{textoken}
835
836 \begin{textoken}{\pgf@picmaxx}
837 The maximum $x$-coordinate ``mentioned'' in the current picture. Initially,
838 this is set to $-16000$pt.
839 \end{textoken}
840
841 \begin{textoken}{\pgf@picminy}
842 The minimum $y$-coordinate ``mentioned'' in the current picture. Initially,
843 this is set to $16000$pt.
844 \end{textoken}
845
846 \begin{textoken}{\pgf@picmaxy}
847 The maximum $y$-coordinate ``mentioned'' in the current picture. Initially,
848 this is set to $-16000$pt.
849 \end{textoken}
850
851
852 Each time a path construction command is called, the above variables are
853 (globally) updated. To facilitate this, you can use the following command:
854
855 \begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}}
856 Updates all of the above dimensions in such a way that the point specified
857 by the two arguments is inside both bounding boxes. For the picture's
858 bounding box this updating occurs only if |\ifpgf@relevantforpicturesize|
859 is true, see below.
860 \end{command}
861
862 For the bounding box of the picture it is not always desirable that every path
863 construction command affects this bounding box. For example, if you have just
864 used a clip command, you do not want anything outside the clipping area to
865 affect the bounding box. For this reason, there exists a special ``\TeX\ if''
866 that (locally) decides whether updating should be applied to the picture's
867 bounding box. Clipping will set this if to false, as will certain other
868 commands.
869
870 \begin{command}{\pgf@relevantforpicturesizefalse}
871 Suppresses updating of the picture's bounding box.
872 \end{command}
873
874 \begin{command}{\pgf@relevantforpicturesizetrue}
875 Causes updating of the picture's bounding box.
876 \end{command}