summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-paths.tex
blob: 5284f22bb36eb91b557ebc3993cff687344829fb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Constructing Paths}

\subsection{Overview}

The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A
path consists of several parts, each of which is either a closed or
open curve. An open curve has a starting point and an end point and,
in between, consists of several \emph{segments}, each of which is
either a straight line or a Bézier curve. Here is an example of a
path (in red) consisting of two parts, one open, one closed:

\begin{codeexample}[]
\begin{tikzpicture}[scale=2]
  \draw[thick,red]
       (0,0) coordinate (a)
    -- coordinate (ab) (1,.5) coordinate (b)
    .. coordinate (bc) controls +(up:1cm) and +(left:1cm) .. (3,1)  coordinate (c)
       (0,1) -- (2,1) -- coordinate (x) (1,2) -- cycle;

  \draw (a)  node[below] {start part 1}
        (ab) node[below right] {straight segment}
        (b)  node[right] {end first segment}
        (c)  node[right] {end part 1}
        (x)  node[above right]  {part 2 (closed)};
\end{tikzpicture}
\end{codeexample}

A path, by itself, has no ``effect,'' that is, it does not leave any
marks on the page. It is just a set of points on the plane. However,
you can \emph{use} a path in different ways. The most natural actions
are \emph{stroking} (also known as \emph{drawing}) and
\emph{filling}. Stroking can be imagined as picking up a pen of a
certain diameter and ``moving it along the path.'' Filling means that
everything ``inside'' the path is filled with a uniform
color. Naturally, the open parts of a path must first be closed before
a path can be filled.

In \pgfname, there are numerous commands for constructing paths, all
of which start with |\pgfpath|. There are also commands for
\emph{using} paths, though most operations can be performed by calling
|\pgfusepath| with an appropriate parameter.

As a side-effect, the path construction commands keep track of two
bounding boxes. One is the bounding box for the current path, the
other is a bounding box for all paths in the current picture. See
Section~\ref{section-bb} for more details.

Each path construction command extends the current path in some
way. The ``current path'' is a global entity that persists across
\TeX\ groups. Thus, between calls to the path construction commands
you can perform arbitrary computations and even open and closed \TeX\
groups. The current path only gets ``flushed'' when the |\pgfusepath|
command is called (or when the soft-path subsystem is used directly,
see Section~\ref{section-soft-paths}).

\subsection{The Move-To Path Operation}

The most basic operation is the move-to operation. It must be given at
the beginning of paths, though some path construction command (like
|\pgfpathrectangle|) generate move-tos implicitly. A move-to operation
can also be used to start a new part of a path.

\begin{command}{\pgfpathmoveto\marg{coordinate}}
  This command expects a \pgfname-coordinate like |\pgfpointorigin| as
  its parameter. When the current path is empty, this operation will
  start the path at the given \meta{coordinate}. If a path has already
  been partly constructed, this command will end the current part of
  the path and start a new one.
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathlineto{\pgfpoint{1cm}{1cm}}
  \pgfpathlineto{\pgfpoint{2cm}{1cm}}
  \pgfpathlineto{\pgfpoint{3cm}{0.5cm}}
  \pgfpathlineto{\pgfpoint{3cm}{0cm}}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathlineto{\pgfpoint{1cm}{1cm}}
  \pgfpathlineto{\pgfpoint{2cm}{1cm}}
  \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part
  \pgfpathlineto{\pgfpoint{3cm}{0.5cm}}
  \pgfpathlineto{\pgfpoint{3cm}{0cm}}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
  The command will apply the current coordinate transformation matrix
  to \meta{coordinate} before using it.

  The command will update the bounding box of the current path and
  picture, if necessary.
\end{command}


\subsection{The Line-To Path Operation}

\begin{command}{\pgfpathlineto\marg{coordinate}}
  This command extends the current path in a straight line to the
  given \meta{coordinate}. If this command is given at the beginning
  of path without any other path construction command given before (in
  particular without a move-to operation), the \TeX\ file may compile
  without an error message, but a viewer application may display an
  error message when trying to render the picture.
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathlineto{\pgfpoint{1cm}{1cm}}
  \pgfpathlineto{\pgfpoint{2cm}{1cm}}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
  The command will apply the current coordinate transformation matrix
  to \meta{coordinate} before using it.

  The command will update the bounding box of the current path and
  picture, if necessary.
\end{command}


\subsection{The Curve-To Path Operations}

\begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}}
  This command extends the current path with a Bézier curve from the
  last point of the path to  \meta{coordinate}. The \meta{support 1}
  and \meta{support 2} are the first and second support point of the
  Bézier curve. For more information on Bézier curve, please consult a
  standard textbook on computer graphics.

  Like the line-to command, this command may not be the first path
  construction command in a path.
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathcurveto
    {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
  The command will apply the current coordinate transformation matrix
  to \meta{coordinate} before using it.

  The command will update the bounding box of the current path and
  picture, if necessary. However, the bounding box is simply made
  large enough such that it encompasses all of the support points and
  the \meta{coordinate}. This will guarantee that the curve is
  completely inside the bounding box, but the bounding box will
  typically be quite a bit too large. It is not clear (to me) how this
  can be avoided without resorting to ``some serious math'' in order
  to calculate a precise bounding box.
\end{command}

\begin{command}{\pgfpathquadraticcurveto\marg{support}\marg{coordinate}}
  This command works like |\pgfpathcurveto|, only it uses a quadratic
  Bézier curve rather than a cubic one. This means that only one
  support point is needed.
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathquadraticcurveto
    {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
  Internally, the quadratic curve is converted into a cubic
  curve. The only noticeable effect of this is that the points used for
  computing the bounding box are the control points of the converted
  curve rather than \meta{support}. The main effect of this is that
  the bounding box will be a bit tighter than might be expected. In
  particular, \meta{support} will not always be part of the bounding
  box.
\end{command}


There exist two commands to draw only part of a cubic Bézier curve:

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

  This command draws the part of the curve described by $p$, $s_1$,
  $s_2$ and $q$ between the times $t_1$ and $t_2$. A time value of 0
  indicates the point $p$ and a time value of 1 indicates point $q$.
  This command includes a moveto operation to the first point.

\begin{codeexample}[]
\begin{tikzpicture}
  \draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2);
  \pgfpathcurvebetweentime{0.25}{0.9}{\pgfpointxy{0}{0}}{\pgfpointxy{0}{2}}
    {\pgfpointxy{3}{0}}{\pgfpointxy{3}{2}}
  \pgfsetstrokecolor{red}
  \pgfsetstrokeopacity{0.5}
  \pgfsetlinewidth{2pt}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}

\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}}
  This command works like |\pgfpathcurvebetweentime|, except that a
  moveto operation is \emph{not} made to the first point.
\end{command}


\subsection{The Close Path Operation}

\begin{command}{\pgfpathclose}
  This command closes the current part of the path by appending a
  straight line to the start point of the current part. Note that there
  \emph{is} a difference between closing a path and using the line-to
  operation to add a straight line to the start of the current
  path. The difference is demonstrated by the upper corners of the triangles
  in the following example:
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfsetlinewidth{5pt}
  \pgfpathmoveto{\pgfpoint{1cm}{1cm}}
  \pgfpathlineto{\pgfpoint{0cm}{-1cm}}
  \pgfpathlineto{\pgfpoint{1cm}{-1cm}}
  \pgfpathclose
  \pgfpathmoveto{\pgfpoint{2.5cm}{1cm}}
  \pgfpathlineto{\pgfpoint{1.5cm}{-1cm}}
  \pgfpathlineto{\pgfpoint{2.5cm}{-1cm}}
  \pgfpathlineto{\pgfpoint{2.5cm}{1cm}}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
\end{command}


\subsection{Arc, Ellipse and Circle Path Operations}

The path construction commands that we have discussed up to now are
sufficient to create all paths that can be created ``at all.''
However, it is useful to have special commands to create certain
shapes, like circles, that arise often in practice.

In the following, the commands for adding (parts of) (transformed)
circles to a path are described.

\begin{command}{\pgfpatharc\marg{start angle}\marg{end
      angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}}
  This command appends a part of a circle (or an ellipse) to the current
  path. Imaging the curve between \meta{start angle} and \meta{end
    angle} on a circle of radius \meta{radius} (if $\meta{start angle}
  < \meta{end angle}$, the curve goes around the circle
  counterclockwise, otherwise clockwise). This curve is now moved such
  that the point where the curve starts is the previous last point of the
  path. Note that this command will \emph{not} start a new part of the
  path, which is important for example for filling purposes.

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathlineto{\pgfpoint{0cm}{1cm}}
  \pgfpatharc{180}{90}{.5cm}
  \pgfpathlineto{\pgfpoint{3cm}{1.5cm}}
  \pgfpatharc{90}{-45}{.5cm}
  \pgfusepath{fill}
\end{tikzpicture}
\end{codeexample}

  Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full
  circle. The ``nearly'' refers to the fact that the circle will not
  be closed. You can close it using |\pgfpathclose|.

  If the optional \meta{y-radius} is given, the \meta{radius} is the
  $x$-radius and the \meta{y-radius} the $y$-radius of the ellipse
  from which the curve is taken:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpatharc{180}{45}{2cm and 1cm}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}

  The axes of the circle or ellipse from which the arc is ``taken''
  always point up and right. However, the current coordinate
  transformation matrix will have an effect on the arc. This can be
  used to, say, rotate an arc:

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgftransformrotate{30}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpatharc{180}{45}{2cm and 1cm}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}

  The command will update the bounding box of the current path and
  picture, if necessary. Unless rotation or shearing transformations
  are applied, the bounding box will be tight.
\end{command}

\begin{command}{\pgfpatharcaxes\marg{start angle}\marg{end
      angle}\marg{first axis}\marg{second axis}}
  This command is similar to |\pgfpatharc|. The main difference is how
  the ellipse or circle is specified from which the arc is taken. The
  two parameters \meta{first axis} and \meta{second axis} are the
  $0^\circ$-axis and the $90^\circ$-axis of the ellipse from which the
  path is taken. Thus, |\pgfpatharc{0}{90}{1cm and 2cm}| has the same effect
  as
\begin{verbatim}
\pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}}
\end{verbatim}
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw (0,0) -- (2cm,5mm) (0,0) -- (0cm,1cm);

  \pgfpathmoveto{\pgfpoint{2cm}{5mm}}
  \pgfpatharcaxes{0}{90}{\pgfpoint{2cm}{5mm}}{\pgfpoint{0cm}{1cm}}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
\end{command}


\begin{command}{\pgfpatharcto\marg{x-radius}\marg{y-radius}\marg{rotation}
    \marg{large arc flag}\marg{counterclockwise flag}\\\marg{target point}}
  This command (which directly corresponds to the arc-path command of
  \textsc{svg}) is used to add an arc to the path that starts at the
  current point and ends at \meta{target point}. This arc is part of
  an ellipse that is determined in the following way: Imagine an
  ellipse with radii \meta{x-radius} and \meta{y-radius} that is
  rotated around its center by \meta{rotation} degrees. When you move
  this ellipse around in the plane, there will be exactly two
  positions such that the two current point and the target point lie
  on the border of the ellipse (excluding pathological cases). The
  flags \meta{large arc flag} and \meta{clockwise flag} are then used to
  decide which of these ellipses should be picked and which arc on the
  picked ellipsis should be used.
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);

  \pgfpathmoveto{\pgfpoint{0mm}{20mm}}
  \pgfpatharcto{3cm}{1cm}{0}{0}{0}{\pgfpoint{3cm}{1cm}}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
  Both flags are considered to be false exactly if they evaluate to
  |0|, otherwise they are true. If the \meta{large arc flag} is true,
  then the angle spanned by the arc will be greater than $180^\circ$,
  otherwise it will be less than $180^\circ$. The \meta{clockwise
    flag} is used to determine which of the two ellipses should be
  used: if the flag is true, then the arc goes from the current point
  to the target point in a counterclockwise direction, otherwise in a
  clockwise fashion.
\begin{codeexample}[]
\begin{tikzpicture}
  \pgfsetlinewidth{2pt}
  % Flags 0 0: red
  \pgfsetstrokecolor{red}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpatharcto{20pt}{10pt}{0}{0}{0}{\pgfpoint{20pt}{10pt}}
  \pgfusepath{stroke}
  % Flags 0 1: blue
  \pgfsetstrokecolor{blue}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpatharcto{20pt}{10pt}{0}{0}{1}{\pgfpoint{20pt}{10pt}}
  \pgfusepath{stroke}
  % Flags 1 0: orange
  \pgfsetstrokecolor{orange}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpatharcto{20pt}{10pt}{0}{1}{0}{\pgfpoint{20pt}{10pt}}
  \pgfusepath{stroke}
  % Flags 1 1: black
  \pgfsetstrokecolor{black}
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpatharcto{20pt}{10pt}{0}{1}{1}{\pgfpoint{20pt}{10pt}}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
  \emph{Warning:} The internal computations necessary for this command
  are numerically very unstable. In particular, the arc will not
  always really end at the \meta{target coordinate}, but may be off by
  up to several points. A more precise positioning is currently
  infeasible due to \TeX's numerical weaknesses. The only case that
  works quite nicely is when the resulting angle is a multiple
  of~$90^\circ$.
\end{command}

\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}}
	A specialized arc operation which is fast and numerically stable, provided a lot of information is given in advance.

	In contrast to |\pgfpatharc|, it explicitly interpolates start- and end points.

	In contrast to |\pgfpatharcto|, this routine is numerically stable and quite fast since it relies on a lot of available information.
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);

  \def\cx{1.5cm}% center x
  \def\cy{1cm}% center y
  \def\startangle{0}%
  \def\endangle{270}%
  \def\a{1.5cm}% xradius
  \def\b{0.5cm}% yradius
  \pgfmathparse{\a/\b}\let\abratio=\pgfmathresult
  \pgfmathparse{\b/\a}\let\baratio=\pgfmathresult
  %
  % start point:
  \pgfpathmoveto{\pgfpoint{\cx+\a*cos(\startangle)}{\cy+\b*sin(\startangle)}}%
  \pgfpatharctoprecomputed
    {\pgfpoint{\cx}{\cy}}
    {\startangle}
    {\endangle}
    {\pgfpoint{\cx+\a*cos(\endangle)}{\cy+\b*sin(\endangle)}}% end point
    {\a}
    {\b}
    {\abratio}
    {\baratio}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}

  	\begin{command}{\pgfpatharctomaxstepsize}
	The quality of arc approximation taken by |\pgfpatharctoprecomputed| by means of Bezier splines is     % TODOsp: Bezier --> Bézier?
	controlled by a mesh width, which is initially

	|\def\pgfpatharctoprecomputed{45}|.

	The mesh width is provided in (full!) degrees. The smaller the mesh
	width, the more precise the arc approximation.

	Use an empty value to disable spline approximation (uses a single
	cubic polynomial for the complete arc).

	The value must be an integer!
	\end{command}
\end{command}

\begin{command}{\pgfpathellipse\marg{center}\marg{first
      axis}\marg{second axis}}
  The effect of this command is to append an ellipse to the current
  path (if the path is not empty, a new part is started). The
  ellipse's center will be \meta{center} and \meta{first axis} and
  \meta{second axis} are the axis \emph{vectors}. The same effect as
  this command can also be achieved using an appropriate sequence of
  move-to, arc, and close operations, but this command is easier and
  faster.

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathellipse{\pgfpoint{1cm}{0cm}}
                 {\pgfpoint{1.5cm}{0cm}}
                 {\pgfpoint{0cm}{1cm}}
  \pgfusepath{draw}
  \color{red}
  \pgfpathellipse{\pgfpoint{1cm}{0cm}}
                 {\pgfpoint{1cm}{1cm}}
                 {\pgfpoint{-0.5cm}{0.5cm}}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}

  The command will apply coordinate transformations to all coordinates
  of the ellipse. However, the coordinate transformations are applied
  only after the ellipse is ``finished conceptually.'' Thus, a
  transformation of 1cm to the right will simply shift the ellipse one
  centimeter to the right; it will not add 1cm to the $x$-coordinates
  of the two axis vectors.

  The command will update the bounding box of the current path and
  picture, if necessary.
\end{command}

\begin{command}{\pgfpathcircle\marg{center}\marg{radius}}
  A shorthand for |\pgfpathellipse| applied to \meta{center} and the
  two axis vectors $(\meta{radius},0)$ and $(0,\meta{radius})$.
\end{command}


\subsection{Rectangle Path Operations}

Another shape that arises frequently is the rectangle. Two commands
can be used to add a rectangle to the current path. Both commands will
start a new part of the path.


\begin{command}{\pgfpathrectangle\marg{corner}\marg{diagonal vector}}
  Adds a rectangle to the path whose one corner is \meta{corner} and
  whose opposite corner is given by $\meta{corner} + \meta{diagonal
    vector}$.

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
  The command will apply coordinate transformations and update the
  bounding boxes tightly.
\end{command}


\begin{command}{\pgfpathrectanglecorners\marg{corner}\marg{opposite corner}}
  Adds a rectangle to the path whose two opposing corners are
  \meta{corner} and \meta{opposite corner}.
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}}
  \pgfusepath{draw}
\end{tikzpicture}
\end{codeexample}
  The command will apply coordinate transformations and update the
  bounding boxes tightly.
\end{command}



\subsection{The Grid Path Operation}

\begin{command}{\pgfpathgrid\oarg{options}\marg{lower left}\marg{upper right}}
  Appends a grid to the current path. That is, a (possibly large)
  number of parts are added to the path, each part consisting of a
  single horizontal or vertical straight line segment.

  Conceptually, the origin is part of the grid and the grid is clipped
  to the rectangle specified by the \meta{lower left} and
  the \meta{upper right} corner. However, no clipping occurs (this
  command just adds parts to the current path). Rather, the points
  where the lines enter and leave the ``clipping area'' are computed
  and used to add simple lines to the current path.

  The following keys influence the grid:
  \begin{key}{/pgf/stepx=\meta{dimension} (initially 1cm)}
    The horizontal stepping.
  \end{key}
  \begin{key}{/pgf/stepy=\meta{dimension} (initially 1cm)}
    The vertical stepping.
  \end{key}
  \begin{key}{/pgf/step=\meta{vector}}
    Sets the horizontal stepping to the $x$-coordinate of
    \meta{vector} and the vertical stepping to its $y$-coordinate.
  \end{key}
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfsetlinewidth{0.8pt}
  \pgfpathgrid[step={\pgfpoint{1cm}{1cm}}]
    {\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}}
  \pgfusepath{stroke}
  \pgfsetlinewidth{0.4pt}
  \pgfpathgrid[stepx=1mm,stepy=1mm]
    {\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
  The command will apply coordinate transformations and update the
  bounding boxes tightly. As for ellipses, the transformations are
  applied to the ``conceptually finished'' grid.
\begin{codeexample}[]
\begin{pgfpicture}
  \pgftransformrotate{10}
  \pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
\end{command}


\subsection{The Parabola Path Operation}

\begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}}
  This command appends two half-parabolas to the  current path. The
  first starts at the current point and ends at the current point plus
  \meta{bend vector}. At his point, it has its bend. The second half
  parabola starts at that bend point and end at point that is given by
  the bend plus \meta{end vector}.

  If you set \meta{end vector} to the null vector, you append only a
  half parabola that goes from the current point to the bend; by
  setting \meta{bend vector} to the null vector, you append only a
  half parabola that goes to current point plus \meta{end vector} and
  has its bend at the current point.

  It is not possible to use this command to draw a part of a parabola
  that does not contain the bend.

\begin{codeexample}[]
\begin{pgfpicture}
  % Half-parabola going ``up and right''
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}}
  \color{red}
  \pgfusepath{stroke}

  % Half-parabola going ``down and right''
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin}
  \color{blue}
  \pgfusepath{stroke}

  % Full parabola
  \pgfpathmoveto{\pgfpoint{-2cm}{2cm}}
  \pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}}
  \color{orange}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}
  The command will apply coordinate transformations and update the
  bounding boxes.
\end{command}


\subsection{Sine and Cosine Path Operations}

Sine and cosine curves often need to be drawn and the following commands
may help with this. However, they only allow you to append sine and
cosine curves in intervals that are multiples of $\pi/2$.

\begin{command}{\pgfpathsine\marg{vector}}
  This command appends a sine curve in the interval $[0,\pi/2]$ to the
  current path. The sine curve is squeezed or stretched such that the
  curve starts at the current point and ends at the current point plus
  \meta{vector}.
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,1);
  \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
  \pgfpathsine{\pgfpoint{1cm}{1cm}}
  \pgfusepath{stroke}

  \color{red}
  \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
  \pgfpathsine{\pgfpoint{-2cm}{-2cm}}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}
  The command will apply coordinate transformations and update the
  bounding boxes.
\end{command}

\begin{command}{\pgfpathcosine\marg{vector}}
  This command appends a cosine curve in the interval $[0,\pi/2]$ to the
  current path. The curve is squeezed or stretched such that the
  curve starts at the current point and ends at the current point plus
  \meta{vector}. Using several sine and cosine operations in sequence
  allows you to produce a complete sine or cosine curve
\begin{codeexample}[]
\begin{pgfpicture}
  \pgfpathmoveto{\pgfpoint{0cm}{0cm}}
  \pgfpathsine{\pgfpoint{1cm}{1cm}}
  \pgfpathcosine{\pgfpoint{1cm}{-1cm}}
  \pgfpathsine{\pgfpoint{1cm}{-1cm}}
  \pgfpathcosine{\pgfpoint{1cm}{1cm}}
  \pgfsetfillcolor{examplefill}
  \pgfusepath{fill,stroke}
\end{pgfpicture}
\end{codeexample}
  The command will apply coordinate transformations and update the
  bounding boxes.
\end{command}



\subsection{Plot Path Operations}

There exist several commands for appending
plots to a path. These
commands are available through the module |plot|. They are
documented in Section~\ref{section-plots}.


\subsection{Rounded Corners}

Normally, when you connect two straight line segments or when you
connect two curves that end and start ``at different angles'' you get
``sharp corners'' between the lines or curves. In some cases it is
desirable to produce ``rounded corners'' instead. Thus, the lines
or curves should be shortened a bit and then connected by arcs.

\pgfname\ offers an easy way to achieve this effect, by calling the
following two commands.

\begin{command}{\pgfsetcornersarced\marg{point}}
  This command causes all subsequent corners to be replaced by little
  arcs. The effect of this command lasts till the end of the current
  \TeX\ scope.

  The \meta{point} dictates how large the corner arc will be. Consider
  a corner made by two lines $l$ and~$r$ and assume that the line $l$
  comes first on the path. The $x$-dimension of the \meta{point}
  decides by how much the line~$l$ will be shortened, the
  $y$-dimension of \meta{point} decides by how much the line $r$ will
  be shortened. Then, the shortened lines are connected by an arc.

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);

  \pgfsetcornersarced{\pgfpoint{5mm}{5mm}}
  \pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);

  \pgfsetcornersarced{\pgfpoint{10mm}{5mm}}
  % 10mm entering,
  % 5mm leaving.
  \pgfpathmoveto{\pgfpointorigin}
  \pgfpathlineto{\pgfpoint{0cm}{2cm}}
  \pgfpathlineto{\pgfpoint{3cm}{2cm}}
  \pgfpathcurveto
    {\pgfpoint{3cm}{0cm}}
    {\pgfpoint{2cm}{0cm}}
    {\pgfpoint{1cm}{0cm}}
  \pgfusepath{stroke}
\end{tikzpicture}
\end{codeexample}

  If the $x$- and $y$-coordinates of \meta{point} are the same and the
  corner is a right angle, you will get a perfect quarter circle
  (well, not quite perfect, but perfect up to six decimals). When the
  angle is not $90^\circ$, you only get a fair approximation.

  More or less ``all'' corners will be rounded, even the corner
  generated by a |\pgfpathclose| command. (The author is a bit proud
  of this feature.)

\begin{codeexample}[]
\begin{pgfpicture}
  \pgfsetcornersarced{\pgfpoint{4pt}{4pt}}
  \pgfpathmoveto{\pgfpointpolar{0}{1cm}}
  \pgfpathlineto{\pgfpointpolar{72}{1cm}}
  \pgfpathlineto{\pgfpointpolar{144}{1cm}}
  \pgfpathlineto{\pgfpointpolar{216}{1cm}}
  \pgfpathlineto{\pgfpointpolar{288}{1cm}}
  \pgfpathclose
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}

  To return to normal (unrounded) corners, use
  |\pgfsetcornersarced{\pgfpointorigin}|.

  Note that the rounding will produce strange and undesirable effects
  if the lines at the corners are too short. In this case the
  shortening may cause the lines to ``suddenly extend over the other
  end'' which is rarely desirable.
\end{command}




\subsection{Internal Tracking of Bounding Boxes for Paths and Pictures}

\label{section-bb}

\makeatletter

The path construction commands keep track of two bounding boxes: One
for the current path, which is reset whenever the path is used and
thereby flushed, and a bounding box for the current |{pgfpicture}|.

\begin{command}{\pgfresetboundingbox}
	Resets the picture's bounding box. The picture will simply forget any previous bounding box updates and start collecting from scratch.
	
	You can use this together with |\pgfusepath{use as bounding box}| to replace the bounding box by the one of a particular path (ignoring subsequent paths).
\end{command}

The bounding boxes are not accessible by ``normal'' macros. Rather,
two sets of four dimension variables are used for this, all of which
contain the letter~|@|.

\begin{textoken}{\pgf@pathminx}
  The minimum $x$-coordinate ``mentioned'' in the current
  path. Initially, this is set to $16000$pt.
\end{textoken}

\begin{textoken}{\pgf@pathmaxx}
  The maximum $x$-coordinate ``mentioned'' in the current
  path. Initially, this is set to $-16000$pt.
\end{textoken}

\begin{textoken}{\pgf@pathminy}
  The minimum $y$-coordinate ``mentioned'' in the current
  path. Initially, this is set to $16000$pt.
\end{textoken}

\begin{textoken}{\pgf@pathmaxy}
  The maximum $y$-coordinate ``mentioned'' in the current
  path. Initially, this is set to $-16000$pt.
\end{textoken}

\begin{textoken}{\pgf@picminx}
  The minimum $x$-coordinate ``mentioned'' in the current
  picture. Initially, this is set to $16000$pt.
\end{textoken}

\begin{textoken}{\pgf@picmaxx}
  The maximum $x$-coordinate ``mentioned'' in the current
  picture. Initially, this is set to $-16000$pt.
\end{textoken}

\begin{textoken}{\pgf@picminy}
  The minimum $y$-coordinate ``mentioned'' in the current
  picture. Initially, this is set to $16000$pt.
\end{textoken}

\begin{textoken}{\pgf@picmaxy}
  The maximum $y$-coordinate ``mentioned'' in the current
  picture. Initially, this is set to $-16000$pt.
\end{textoken}


Each time a path construction command is called, the above variables
are (globally) updated. To facilitate this, you can use the following
command:

\begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}}
  Updates all of the above dimension in such a way that the point
  specified by the two arguments is inside both bounding boxes. For
  the picture's bounding box this updating occurs only if
  |\ifpgf@relevantforpicturesize| is true, see below.
\end{command}

For the bounding box of the picture it is not always desirable that
every path construction command affects this bounding box. For
example, if you have just used a clip command, you do not want anything
outside the clipping area to affect the bounding box. For this reason,
there exists a special ``\TeX\ if'' that (locally) decides whether
updating should be applied to the picture's bounding box. Clipping
will set this if to false, as will certain other commands.

\begin{command}{\pgf@relevantforpicturesizefalse}
  Suppresses updating of the picture's bounding box.
\end{command}

\begin{command}{\pgf@relevantforpicturesizetrue}
  Causes updating of the picture's bounding box.
\end{command}