summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-paths.tex
blob: 3a3f524eed5ae87c512aaab28cccd98327077eb9 (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
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
% Copyright 2019 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{Syntax for Path Specifications}
\label{section-paths}

A \emph{path} is a series of straight and curved line segments. It is specified
following a |\path| command and the specification must follow a special syntax,
which is described in the subsections of the present section.

\begin{command}{\path\meta{specification}|;|}
    This command is available only inside a |{tikzpicture}| environment.

    The \meta{specification} is a long stream of \emph{path operations}. Most
    of these path operations tell \tikzname\ how the path is built. For
    example, when you write |--(0,0)|, you use a \emph{line-to operation} and
    it means ``continue the path from wherever you are to the origin''.

    At any point where \tikzname\ expects a path operation, you can also give
    some graphic options, which is a list of options in brackets, such as
    |[rounded corners]|. These options can have different effects:
    %
    \begin{enumerate}
        \item Some options take ``immediate'' effect and apply to all
            subsequent path operations on the path. For example, the
            |rounded corners| option will round all following corners, but not
            the corners ``before'' and if the |sharp corners| is given later on
            the path (in a new set of brackets), the rounding effect will end.
            %
\begin{codeexample}[]
\tikz \draw (0,0) -- (1,1)
           [rounded corners] -- (2,0) -- (3,1)
           [sharp corners] -- (3,0) -- (2,1);
\end{codeexample}
            %
            Another example are the transformation options, which also apply
            only to subsequent coordinates.
        \item The options that have immediate effect can be ``scoped'' by
            putting part of a path in curly braces. For example, the above
            example could also be written as follows:
            %
\begin{codeexample}[]
\tikz \draw (0,0) -- (1,1)
           {[rounded corners] -- (2,0) -- (3,1)}
           -- (3,0) -- (2,1);
\end{codeexample}
            %
        \item Some options only apply to the path as a whole. For example,
            the |color=| option for determining the color used for, say,
            drawing the path always applies to all parts of the path. If
            several different colors are given for different parts of the
            path, only the last one (on the outermost scope) ``wins'':
            %
\begin{codeexample}[]
\tikz \draw (0,0) -- (1,1)
           [color=red] -- (2,0) -- (3,1)
           [color=blue] -- (3,0) -- (2,1);
\end{codeexample}

            Most options are of this type. In the above example, we would
            have had to ``split up'' the path into several |\path| commands:
            %
\begin{codeexample}[]
\tikz{\draw (0,0) -- (1,1);
      \draw [color=red] (1,1) -- (2,0) -- (3,1);
      \draw [color=blue] (3,1) -- (3,0) -- (2,1);}
\end{codeexample}
    \end{enumerate}

    By default, the |\path| command does ``nothing'' with the path, it just
    ``throws it away''. Thus, if you write |\path(0,0)--(1,1);|, nothing is
    drawn in your picture. The only effect is that the area occupied by the
    picture is (possibly) enlarged so that the path fits inside the area. To
    actually ``do'' something with the path, an option like |draw| or |fill|
    must be given somewhere on the path. Commands like |\draw| do this
    implicitly.

    Finally, it is also possible to give \emph{node specifications} on a path.
    Such specifications can come at different locations, but they are always
    allowed when a normal path operation could follow. A node specification
    starts with |node|. Basically, the effect is to typeset the node's text as
    normal \TeX\ text and to place it at the ``current location'' on the path.
    The details are explained in Section~\ref{section-nodes}.

    Note, however, that the nodes are \emph{not} part of the path in any way.
    Rather, after everything has been done with the path what is specified by
    the path options (like filling and drawing the path due to a |fill| and a
    |draw| option somewhere in the \meta{specification}), the nodes are added
    in a post-processing step.
\end{command}

\begin{key}{/tikz/name=\meta{path name}}
    Assigns a name to the path for reference (specifically, for reference
    in animations; for reference in intersections, use the |name path|
    command, which has a different purpose, see the |intersections| library
    for details). Since the name is a ``high-level'' name (drivers never
    know of it), you can use spaces, number, letters, or whatever you like
    when naming a path, but the name may \emph{not} contain any punctuation
    like a dot, a comma, or a colon.
\end{key}

The following style influences scopes:
%
\begin{stylekey}{/tikz/every path (initially \normalfont empty)}
    This style is installed at the beginning of every path. This can be
    useful for (temporarily) adding, say, the |draw| option to everything
    in a scope.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  [fill=yellow!80!black,      % only sets the color
   every path/.style={draw}]  % all paths are drawn
  \fill  (0,0) rectangle +(1,1);
  \shade (2,0) rectangle +(1,1);
\end{tikzpicture}
\end{codeexample}
    %
\end{stylekey}

\begin{key}{/tikz/insert path=\meta{path}}
    This key can be used inside an option to add something to the current path.
    This is mostly useful for defining styles that create graphic contents.
    This option should be used with care, for instance it should not be used as
    an argument of, say, a |node|. In the following example, we use a style to
    add little circles to a path.
    %
\begin{codeexample}[]
\tikz [c/.style={insert path={circle[radius=2pt]}}]
  \draw (0,0) -- (1,1) [c] -- (3,2) [c];
\end{codeexample}
    %
     The effect is the same as of
    |(0,0) -- (1,1) circle[radius=2pt] -- (3,2) circle[radius=2pt]|.
\end{key}

The following options are for experts only:

\begin{key}{/tikz/append after command=\meta{path}}
    Some of the path commands described in the following sections take optional
    arguments. For these commands, when you use this key inside these options,
    the \meta{path} will be inserted \emph{after} the path command is done. For
    instance, when you give this command in the option list of a node, the
    \meta{path} will be added after the node. This is used by, for instance,
    the |label| option to allow you to specify a label in the option list of a
    node, but have this |label| cause a node to be added after another node.
    %
\begin{codeexample}[]
\tikz \draw node [append after command={(foo)--(1,1)},draw] (foo){foo};
\end{codeexample}
    %
    If this key is called multiple times, the effects accumulate, that is, all
    of the paths are added in the order to keys were found.
\end{key}

\begin{key}{/tikz/prefix after command=\meta{path}}
    Works like |append after command|, only the accumulation order is inverse:
    The \meta{path} is added before any earlier paths added using either
    |append after command| or |prefix after command|.
\end{key}


\subsection{The Move-To Operation}

The perhaps simplest operation is the move-to operation, which is specified by
just giving a coordinate where a path operation is expected.

\begin{pathoperation}[noindex]{}{\meta{coordinate}}
        \index{empty@\protect\meta{empty} path operation}%
        \index{Path operations!empty@\protect\texttt{\meta{empty}}}%
    The move-to operation normally starts a path at a certain point. This does
    not cause a line segment to be created, but it specifies the starting point
    of the next segment. If a path is already under construction, that is, if
    several segments have already been created, a move-to operation will start
    a new part of the path that is not connected to any of the previous
    segments.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) --(2,0) (0,1) --(2,1);
\end{tikzpicture}
\end{codeexample}

    In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to operations
    are specified: |(0,0)| and |(0,1)|. The other two operations, namely
    |--(2,0)| and |--(2,1)| are line-to operations, described next.
\end{pathoperation}

There is special coordinate called |current subpath start| that is always at
the position of the last move-to operation on the current path.
%
\begin{codeexample}[]
\tikz [line width=2mm]
  \draw (0,0) -- (1,0) -- (1,1)
        -- (0,1) -- (current subpath start);
\end{codeexample}

Note how in the above example the path is not closed (as |--cycle| would do).
Rather, the line just starts and ends at the origin without being a closed
path.


\subsection{The Line-To Operation}

\subsubsection{Straight Lines}

\begin{pathoperation}{--}{\meta{coordinate or cycle}}
    The line-to operation extends the current path from the current point in a
    straight line to the given \meta{coordinate} (the ``or cycle'' part is
    explained in a moment). The ``current point'' is the endpoint of the
    previous drawing operation or the point specified by a prior move-to
    operation.

    When a line-to operation is used and some path segment has just been
    constructed, for example by another line-to operation, the two line
    segments become joined. This means that if they are drawn, the point where
    they meet is ``joined'' smoothly. To appreciate the difference, consider
    the following two examples: In the left example, the path consists of two
    path segments that are not joined, but they happen to share a point, while
    in the right example a smooth join is shown.
    %
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
  \draw (0,0) --(1,1)  (1,1) --(2,0);
  \draw (3,0) -- (4,1) -- (5,0);
  \useasboundingbox (0,1.5); % make bounding box higher
\end{tikzpicture}
\end{codeexample}

    Instead of a coordinate following the two minus signs, you can also use the
    text |cycle|. This causes the straight line from the current point to go to
    the last point specified by a move-to operation. Note that this need not be
    the beginning of the path. Furthermore, a smooth join is created between
    the first segment created after the last move-to operation and the straight
    line appended by the cycle operation.

    Consider the following example. In the left example, two triangles are
    created using three straight lines, but they are not joined at the ends. In
    the second example cycle operations are used.
    %
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
  \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0);
  \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle;
  \useasboundingbox (0,1.5); % make bounding box higher
\end{tikzpicture}
\end{codeexample}
    %
\end{pathoperation}

Writing |cycle| instead of a coordinate at the end of a path operation is
possible with all path operations that end with a coordinate (such as |--| or
|..| or |sin| or |grid|, but not |graph| or |plot|). In all cases, the effect
is that the coordinate of the last moveto is used as the coordinate expected by
the path operation and that a smooth join is added. (What actually happens that
the text |cycle| used with any path operation other than |--| gets replaced by
|(current subpath start)--cycle|.)


\subsubsection{Horizontal and Vertical Lines}

Sometimes you want to connect two points via straight lines that are only
horizontal and vertical. For this, you can use two path construction
operations.

{\catcode`\|=12
\begin{pathoperation}[noindex]{-|}{\meta{coordinate or cycle}}
    \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}%
    \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}%
    \pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
    This operation means ``first horizontal, then vertical''.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) node(a) [draw] {A}  (1,1) node(b) [draw] {B};
  \draw (a.north) |- (b.west);
  \draw[color=red] (a.east) -| (2,1.5) -| (b.north);
\end{tikzpicture}
\end{codeexample}
    %
    Instead of a coordinate you can also write \verb!cycle! to close the path:
    %
\begin{codeexample}[]
\begin{tikzpicture}[ultra thick]
  \draw (0,0) -- (1,1) -| cycle;
\end{tikzpicture}
\end{codeexample}
\end{pathoperation}

\begin{pathoperation}[noindex]{|-}{\meta{coordinate or cycle}}
    \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}%
    \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}%
    \pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
    This operations means ``first vertical, then horizontal''.
\end{pathoperation}
}


\subsection{The Curve-To Operation}

The curve-to operation allows you to extend a path using a Bézier curve.

\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y or cycle}}}
    This operation extends the current path from the current point, let us call
    it $x$, via a curve to a point~$y$ (if, instead of a coordinate you say
    |cycle| at the end, $y$ will be the coordinate of the last move-to
    operation). The curve is a cubic Bézier curve. For such a curve, apart
    from $y$, you also specify two control points $c$ and $d$. The idea is that
    the curve starts at $x$, ``heading'' in the direction of~$c$.
    Mathematically spoken, the tangent of the curve at $x$ goes through $c$.
    Similarly, the curve ends at $y$, ``coming from'' the other control
    point,~$d$. The larger the distance between $x$ and~$c$ and between $d$
    and~$y$, the larger the curve will be.

    If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be equal to
    $c$.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0)
                               .. controls (5,0) and (5,1) .. (4,1);
  \draw[color=gray] (0,0) -- (1,1) -- (4,0) -- (5,0) -- (5,1) -- (4,1);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \draw[line width=10pt] (0,0) -- (2,0) .. controls (1,1) .. cycle;
\end{tikzpicture}
\end{codeexample}

    As with the line-to operation, it makes a difference whether two curves are
    joined because they resulted from consecutive curve-to or line-to
    operations, or whether they just happen to have a common (end) point:
    %
\begin{codeexample}[]
\begin{tikzpicture}[line width=10pt]
  \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0);
  \draw [yshift=-1.5cm]
        (0,0) -- (1,1)       .. controls (1,0) and (2,0) .. (2,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{pathoperation}


\subsection{The Rectangle Operation}

A rectangle can obviously be created using four straight lines and a cycle
operation. However, since rectangles are needed so often, a special syntax is
available for them.

\begin{pathoperation}{rectangle}{\meta{corner or cycle}}
    When this operation is used, one corner will be the current point, another
    corner is given by \meta{corner}, which becomes the new current point.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) rectangle (1,1);
  \draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0);
\end{tikzpicture}
\end{codeexample}

    Just for consistency, you can also use |cycle| instead of a coordinate, but
    it is a bit unclear what use this might have.
\end{pathoperation}


\subsection{Rounding Corners}

All of the path construction operations mentioned up to now are influenced by
the following option:

\begin{key}{/tikz/rounded corners=\meta{inset} (default 4pt)}
    When this option is in force, all corners (places where a line is continued
    either via line-to or a curve-to operation) are replaced by little arcs so
    that the corner becomes smooth.
    %
\begin{codeexample}[]
\tikz \draw [rounded corners] (0,0) -- (1,1)
           -- (2,0) .. controls (3,1) .. (4,0);
\end{codeexample}

    The \meta{inset} describes how big the corner is. Note that the
    \meta{inset} is \emph{not} scaled along if you use a scaling option like
    |scale=2|.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[color=gray,very thin] (10pt,15pt) circle[radius=10pt];
  \draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt);
\end{tikzpicture}
\end{codeexample}

    You can switch the rounded corners on and off ``in the middle of path'' and
    different corners in the same path can have different corner radii:
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1)
                     [sharp corners] -- (2,0)
               [rounded corners=5pt] -- cycle;
\end{tikzpicture}
\end{codeexample}

    Here is a rectangle with rounded corners:
    %
\begin{codeexample}[]
\tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex);
\end{codeexample}

    You should be aware, that there are several pitfalls when using this
    option. First, the rounded corner will only be an arc (part of a circle) if
    the angle is $90^\circ$. In other cases, the rounded corner will still be
    round, but ``not as nice''.

    Second, if there are very short line segments in a path, the ``rounding''
    may cause inadvertent effects. In such case it may be necessary to
    temporarily switch off the rounding using |sharp corners|.
\end{key}

\begin{key}{/tikz/sharp corners}
    This options switches off any rounding on subsequent corners of the path.
\end{key}


\subsection{The Circle and Ellipse Operations}

Circles and ellipses are common path elements for which there is a special path
operation.

\begin{pathoperation}{circle}{\opt{|[|\meta{options}|]|}}
    This command adds a circle to the current path where the center of the
    circle is the current point by default, but you can use the |at| option to
    change this. The new current point of the path will be (typically just
    remain) the center of the circle.

    The radius of the circle is specified using the following options:
    %
    \begin{key}{/tikz/x radius=\meta{value}}
        Sets the horizontal radius of the circle (which, when this value is
        different form the vertical radius, is actually an ellipse). The
        \meta{value} may either be a dimension or a dimensionless number. In
        the latter case, the number is interpreted in the $xy$-coordinate
        system (if the $x$-unit is set to, say, |2cm|, then |x radius=3| will
        have the same effect as |x radius=6cm|).
    \end{key}
    %
    \begin{key}{/tikz/y radius=\meta{value}}
        Works like the |x radius|.
    \end{key}
    %
    \begin{key}{/tikz/radius=\meta{value}}
        Sets the |x radius| and |y radius| simultaneously.
    \end{key}
    %
    \begin{key}{/tikz/at=\meta{coordinate}}
        If this option is explicitly set inside the \meta{options} (or
        indirectly via the |every circle| style), the \meta{coordinate} is used
        as the center of the circle instead of the current point. Setting |at|
        to some value in an enclosing scope has no effect.
    \end{key}
    The \meta{options} may also contain additional options like, say, a
    |rotate| or |scale|, that will only have an effect on the circle.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (1,0) circle [radius=1.5];
  \fill (1,0) circle [x radius=1cm, y radius=5mm, rotate=30];
\end{tikzpicture}
\end{codeexample}

    It is possible to set the |radius| also in some enclosing scope, in this
    case the options can be left out (but see the note below on what may
    follow):
    %
\begin{codeexample}[]
\begin{tikzpicture}[radius=2pt]
  \draw (0,0) circle -- (1,1) circle -- ++(0,1) circle;
\end{tikzpicture}
\end{codeexample}

    The following style is used with every circle:
    %
    \begin{stylekey}{/tikz/every circle}
        You can use this key to set up, say, a default radius for every circle.
        The key will also be used with the |ellipse| operation.
    \end{stylekey}

    In case you feel that the names |radius| and |x radius| are too long for
    your taste, you can easily created shorter aliases:
    %
\begin{codeexample}[code only]
\tikzset{r/.style={radius=#1},rx/.style={x radius=#1},ry/.style={y radius=#1}}
\end{codeexample}
    %
    You can then say |circle [r=1cm]| or |circle [rx=1,ry=1.5]|. The reason
    \tikzname\ uses the longer names by default is that it encourages people to
    write more readable code.

    \emph{Note:} There also exists an older syntax for circles, where the
    radius of the circle is given in parentheses right after the |circle|
    command as in |circle (1pt)|. Although this syntax is a bit more succinct,
    it is harder to understand for readers of the code and the use of
    parentheses for something other than a coordinate is ill-chosen.

    \tikzname\ will use the following rule to determine whether the old or the
    normal syntax is used: If |circle| is directly followed by something that
    (expands to) an opening parenthesis, then the old syntax is used and inside
    these following parentheses there must be a single number or dimension
    representing a radius. In all other cases the new syntax is used.
\end{pathoperation}

\begin{pathoperation}{ellipse}{|[|\meta{options}|]|}
    This command has exactly the same effect as |circle|. The older syntax for
    this command is |ellipse (|\meta{x radius} |and| \meta{y radius}|)|. As for
    the |circle| command, this syntax is not as good as the standard syntax.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);
  \draw (1,1) ellipse [x radius=1cm,y radius=.5cm];
\end{tikzpicture}
\end{codeexample}
    %
\end{pathoperation}


\subsection{The Arc Operation}

The \emph{arc operation} allows you to add an arc to the current path.
%
\begin{pathoperation}{arc}{\oarg{options}}
    The |arc| operation adds a part of an ellipse to the current path. The
    radii of the ellipse are given by the values of |x radius| and |y radius|,
    which should be set in the \meta{options}. The arc will start at   the
    current point and will end at the end of the arc. The arc  will start and
    end at angles computed from the three keys |start angle|, |end angle|, and
    |delta angle|. Normally, the first two keys specify the start and end
    angle. However, in case one of them is empty, it is computed from the other
    key plus or minus the |delta angle|. In detail, if |end angle| is empty, it
    is set to the start angle plus the delta angle. If the start angle is
    missing, it is set to the end angle minus the delta angle. If all three
    keys are set, the delta angle is ignored.
    %
    \begin{key}{/tikz/start angle=\meta{degrees}}
        Sets the start angle.
    \end{key}
    %
    \begin{key}{/tikz/end angle=\meta{degrees}}
        Sets the end angle.
    \end{key}
    %
    \begin{key}{/tikz/delta angle=\meta{degrees}}
        Sets the delta angle.
    \end{key}

\begin{codeexample}[]
\begin{tikzpicture}[radius=1cm]
  \draw (0,0)  arc[start angle=180, end angle=90]
     -- (2,.5) arc[start angle=90,  delta angle=-90];
  \draw (4,0) -- +(30:1cm)
              arc [start angle=30,  delta angle=30] -- cycle;
  \draw (8,0) arc [start angle=0,   end angle=270,
                   x radius=1cm, y radius=5mm] -- cycle;
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}[radius=1cm,delta angle=30]
  \draw (-1,0) -- +(3.5,0);
  \draw (1,0) ++(210:2cm) -- +(30:4cm);
  \draw (1,0) +(0:1cm) arc [start angle=0];
  \draw (1,0) +(180:1cm) arc [start angle=180];
  \path (1,0) ++(15:.75cm) node{$\alpha$};
  \path (1,0) ++(15:-.75cm) node{$\beta$};
\end{tikzpicture}
\end{codeexample}

    There also exists a shorter syntax for the arc operation, namely |arc|
    begin directly followed by
    |(|\meta{start angle}|:|\meta{end angle}|:|\meta{radius}). However, this
    syntax is harder to read, so the normal syntax should be preferred in
    general.
\end{pathoperation}


\subsection{The Grid Operation}

You can add a grid to the current path using the |grid| path operation.

\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner or cycle}}
    This operations adds a grid filling a rectangle whose two corners are given
    by \meta{corner} and by the previous coordinate. (Instead of a coordinate
    you can also say |cycle| to use the position of the last move-to as the
    corner coordinate, but it not very natural to do so.) corner Thus, the
    typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, which
    yields a grid filling the rectangle whose corners are at $(1,1)$ and
    $(3,3)$. All coordinate transformations apply to the grid.
    %
\begin{codeexample}[]
\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2);
\end{codeexample}

    The \meta{options}, which are local to the |grid| operation, can be used to
    influence the appearance of the grid. The stepping of the grid is governed
    by the following options:
    %
    \begin{key}{/tikz/step=\meta{number or dimension or coordinate} (initially 1cm)}
        Sets the stepping in both the $x$ and $y$-direction. If a dimension is
        provided, this is used directly. If a number is provided, this number
        is interpreted in the $xy$-coordinate system. For example, if you
        provide the number |2|, then the $x$-step is twice the $x$-vector and
        the $y$-step is twice the $y$-vector set by the |x=| and |y=| options.
        Finally, if you provide a coordinate, then the $x$-part of this
        coordinate will be used as the $x$-step and the $y$-part will be used
        as the $y$-coordinate.
        %
\begin{codeexample}[]
\begin{tikzpicture}[x=.5cm]
  \draw[thick] (0,0) grid [step=1]     (3,2);
  \draw[red]   (0,0) grid [step=.75cm] (3,2);
\end{tikzpicture}
\begin{tikzpicture}
  \draw        (0,0) circle [radius=1];
  \draw[blue]  (0,0) grid [step=(45:1)] (3,2);
\end{tikzpicture}
\end{codeexample}

        A complication arises when the $x$- and/or $y$-vector do not point
        along the axes. Because of this, the actual rule for computing the
        $x$-step and the $y$-step is the following: As the $x$- and $y$-steps
        we use the $x$- and $y$-components or the following two vectors: The
        first vector is either $(\meta{x-grid-step-number},0)$ or
        $(\meta{x-grid-step-dimension},0\mathrm{pt})$, the second vector is
        $(0,\meta{y-grid-step-number})$ or
        $(0\mathrm{pt},\meta{y-grid-step-dimension})$.

        If the $x$-step or $y$-step is $0$ or negative the corresponding lines
        are not drawn.
    \end{key}

    \begin{key}{/tikz/xstep=\meta{dimension or number} (initially 1cm)}
        Sets the stepping in the $x$-direction.
        %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) grid [xstep=.5,ystep=.75] (3,2);
  \draw[ultra thick] (0,0) grid [ystep=0] (3,2);
\end{tikzpicture}
\end{codeexample}
    \end{key}

    \begin{key}{/tikz/ystep=\meta{dimension or number} (initially 1cm)}
        Sets the stepping in the $y$-direction.
    \end{key}

    It is important to note that the grid is always ``phased'' such that it
    contains the point $(0,0)$ if that point happens to be inside the
    rectangle. Thus, the grid does \emph{not} always have an intersection at
    the corner points; this occurs only if the corner points are multiples of
    the stepping. Note that due to rounding errors, the ``last'' lines of a
    grid may be omitted. In this case, you have to add an epsilon to the corner
    points.

    The following style is useful for drawing grids:
    %
    \begin{stylekey}{/tikz/help lines (initially {line width=0.2pt,gray})}
        This style makes lines ``subdued'' by using thin gray lines for them.
        However, this style is not installed automatically and you have to say
        for example:
        %
\begin{codeexample}[]
\tikz \draw[help lines] (0,0) grid (3,3);
\end{codeexample}
    \end{stylekey}
\end{pathoperation}


\subsection{The Parabola Operation}

The |parabola| path operation continues the current path with a parabola. A
parabola is a (shifted and scaled) curve defined by the equation $f(x) = x^2$
and looks like this: \tikz \draw (-1ex,1.5ex) parabola[parabola height=-1.5ex]
+(2ex,0ex);.

\begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend
        coordinate}}\meta{coordinate or cycle}}
    This operation adds a parabola through the current point and the given
    \meta{coordinate} or, if |cycle| is used instead of coordinate at the end,
    the \meta{coordinate} is set to the position of the last move-to and the
    path gets closed after the parabola. If the |bend| is given, it specifies
    where the bend should go; the \meta{options} can also be used to specify
    where the bend is. By default, the bend is at the old current point.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw                (0,0) rectangle                (1,1.5)
                       (0,0) parabola                 (1,1.5);
  \draw[xshift=1.5cm]  (0,0) rectangle                (1,1.5)
                       (0,0) parabola[bend at end]    (1,1.5);
  \draw[xshift=3cm]    (0,0) rectangle                (1,1.5)
                       (0,0) parabola bend (.75,1.75) (1,1.5);

  \draw[yshift=-2cm]   (1,1.5) --
                       (0,0) parabola                 cycle;
\end{tikzpicture}
\end{codeexample}

    The following options influence parabolas:
    %
    \begin{key}{/tikz/bend=\meta{coordinate}}
        Has the same effect as saying |bend|\meta{coordinate} outside the
        \meta{options}. The option specifies that the bend of the parabola
        should be at the given \meta{coordinate}. You have to take care
        yourself that the bend position is a ``valid'' position; which means
        that if there is no parabola of the form $f(x) = a x^2 + b x + c$ that
        goes through the old current point, the given bend, and the new current
        point, the result will not be a parabola.

        There is one special property of the \meta{coordinate}: When a relative
        coordinate is given like |+(0,0)|, the position relative to this
        coordinate is ``flexible''. More precisely, this position lies
        somewhere on a line from the old current point to the new current
        point. The exact position depends on the next option.
    \end{key}

    \begin{key}{/tikz/bend pos=\meta{fraction}}
        Specifies where the ``previous'' point is relative to which the bend is
        calculated. The previous point will be at the \meta{fraction}th part of
        the line from the old current point to the new current point.

        The idea is the following: If you say |bend pos=0| and |bend +(0,0)|,
        the bend will be at the old current point. If you say |bend pos=1| and
        |bend +(0,0)|, the bend will be at the new current point. If you say
        |bend pos=0.5| and |bend +(0,2cm)| the bend will be 2cm above the
        middle of the line between the start and end point. This is most useful
        in situations such as the following:
        %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0);
\end{tikzpicture}
\end{codeexample}

        In the above example, the |bend +(0,2)| essentially means ``a parabola
        that is 2cm high'' and |+(3,0)| means ``and 3cm wide''. Since this
        situation arises often, there is a special shortcut option:
        %
        \begin{key}{/tikz/parabola height=\meta{dimension}}
            This option has the same effect as
            |[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|.
            %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \draw (-1,0) parabola[parabola height=2cm] +(3,0);
\end{tikzpicture}
\end{codeexample}
        \end{key}
    \end{key}

    The following styles are useful shortcuts:
    %
    \begin{stylekey}{/tikz/bend at start}
        This places the bend at the start of a parabola. It is a shortcut for
        the following options: |bend pos=0,bend={+(0,0)}|.
    \end{stylekey}

    \begin{stylekey}{/tikz/bend at end}
        This places the bend at the end of a parabola.
    \end{stylekey}
\end{pathoperation}


\subsection{The Sine and Cosine Operation}

The |sin| and |cos| operations are similar to the |parabola| operation. They,
too, can be used to draw (parts of) a sine or cosine curve.

\begin{pathoperation}{sin}{\meta{coordinate or cycle}}
    The effect of |sin| is to draw a scaled and shifted version of a sine curve
    in the interval $[0,\pi/2]$. The scaling and shifting is done in such a way
    that the start of the sine curve in the interval is at the old current
    point and that the end of the curve in the interval is at
    \meta{coordinate}. Here is an example that should clarify this:
    %
\begin{codeexample}[]
\tikz \draw (0,0) rectangle (1,1)     (0,0) sin (1,1)
            (2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1);
\end{codeexample}
    %
\end{pathoperation}

\begin{pathoperation}{cos}{\meta{coordinate or cycle}}
    This operation works similarly, only a cosine in the interval $[0,\pi/2]$
    is drawn. By correctly alternating |sin| and |cos| operations, you can
    create a complete sine or cosine curve:
    %
\begin{codeexample}[]
\begin{tikzpicture}[xscale=1.57]
  \draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1);
  \draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0);
\end{tikzpicture}
\end{codeexample}
    %
\end{pathoperation}

Note that there is no way to (conveniently) draw an interval on a sine or
cosine curve whose end points are not multiples of $\pi/2$.


\subsection{The SVG Operation}

The |svg| operation can be used to extend the current path by a path given in
the \textsc{svg} path data syntax. This syntax is described in detail in
Section~8.3 of the \textsc{svg 1.1} specification, please consult this
specification for details.

\begin{pathoperation}{svg}{\opt{\oarg{options}}\marg{path data}}
    This operation adds the path specified in the \meta{path data} in
    \textsc{svg 1.1 path data} syntax to the current path. Unlike the
    \textsc{svg}-specification, it \emph{is} permissible that the path data
    does not start with a move-to command (|m| or |M|), in which case the last
    point of the current path is used as start point. The optional
    \meta{options} apply locally to this path operation, typically you will use
    them to set up, say, some transformations.
    %
\begin{codeexample}[preamble={\usetikzlibrary{svg.path}}]
\begin{tikzpicture}
  \filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10}
    node [above left] {upper left} -- cycle;

  \draw svg {M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0};
\end{tikzpicture}
\end{codeexample}

    An \textsc{svg} coordinate like |10 20| is always interpreted as
    |(10pt,20pt)|, so the basic unit is always points (|pt|). The
    $xy$-coordinate system is not used. However, you can use scaling to
    (locally) change the basic unit. For instance, |svg[scale=1cm]| (yes, this
    works, although some rather evil magic is involved) will cause 1cm to be
    the basic unit.

    Instead of curly braces, you can also use quotation marks to indicate the
    start and end of the \textsc{svg} path.

    \emph{Warning:} The arc operations (|a| and |A|) are  numerically instable.
    This means that they will be quite imprecise, except when the angle is a
    multiple of $90^\circ$ (as is, fortunately, most often the case).
\end{pathoperation}


\subsection{The Plot Operation}

The |plot| operation can be used to append a line or curve to the path that
goes through a large number of coordinates. These coordinates are either given
in a simple list of coordinates, read from some file, or they are computed on
the fly.

Since the syntax and the behavior of this command are a bit complex, they are
described in the separated Section~\ref{section-tikz-plots}.


\subsection{The To Path Operation}

The |to| operation is used to add a user-defined path from the previous
coordinate to the following coordinate. When you write |(a) to (b)|, a straight
line is added from |a| to |b|, exactly as if you had written |(a) -- (b)|.
However, if you write |(a) to [out=135,in=45] (b)| a curve is added to the
path, which leaves at an angle of 135$^\circ$ at |a| and arrives at an angle of
45$^\circ$ at |b|. This is because the options |in| and |out| trigger a special
path to be used instead of the straight line.

\begin{pathoperation}{to}{\opt{|[|\meta{options}|]|}
        \opt{\meta{nodes}} \meta{coordinate or cycle}}
    This path operation inserts the path currently set via the |to path| option
    at the current position. The \meta{options} can be used to modify (perhaps
    implicitly) the |to path| and to set up how the path will be rendered.

    Before the |to path| is inserted, a number of macros are set up that can
    ``help'' the |to path|. These are |\tikztostart|, |\tikztotarget|, and
    |\tikztonodes|; they are explained in the following.

    \medskip
    \textbf{Start and Target Coordinates.}\ \
    The |to| operation is always followed by a \meta{coordinate}, called the
    target coordinate, or the text |cycle|, in which case the last move-to is
    used as a coordinate and the path gets closed. The macro |\tikztotarget| is
    set to this coordinate (without its parentheses). There is also a
    \emph{start coordinate}, which is the coordinate preceding the |to|
    operation. This coordinate can be accessed via the macro |\tikztostart|. In
    the following example, for the first |to|, the macro |\tikztostart| is
    |0pt,0pt| and the |\tikztotarget| is |0,2|. For the second |to|, the macro
    |\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the third,
    they are set to |a| and |current subpath start|.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw[help lines] (0,0) grid (3,2);
  \node       (a)         at (2,2) {a};

  \draw       (0,0)       to (0,2);
  \draw[red]  (10pt,10pt) to (a);
  \draw[blue] (3,0) -- (3,2) -- (a) to cycle;
\end{tikzpicture}
\end{codeexample}

    \medskip
    \textbf{Nodes on to--paths.}\ \
    It is possible to add nodes to the paths constructed by a |to| operation.
    To do so, you specify the nodes between the |to| keyword and the coordinate
    (if there are options to the |to| operation, these come first). The effect
    of |(a) to node {x} (b)| (typically) is the same as if you had written
    |(a) -- node {x} (b)|, namely that the node is placed on the |to|. This can
    be used to add labels to |to|s:
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) to node [sloped,above] {x} (3,2);

  \draw (0,0) to[out=90,in=180] node [sloped,above] {x} (3,2);
\end{tikzpicture}
\end{codeexample}

    Instead of writing the node between the |to| keyword and the target
    coordinate, you may also use the following keys to create such nodes:
    %
    \begin{key}{/tikz/edge node=\meta{node specification}}
        This key can be used inside the \meta{options} of a |to| path command.
        It will add the \meta{node specification} to the list of nodes to be
        placed on the connecting line, just as if you had written the
        \meta{node specification} directly after the |to| keyword:
        %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) to [edge node={node [sloped,above] {x}}] (3,2);

  \draw (0,0) to [out=90,in=180,
                  edge node={node [sloped,above] {x}}] (3,2);
\end{tikzpicture}
\end{codeexample}
        %
        This key is mostly useful to create labels automatically using other
        keys.
    \end{key}
    %
    \begin{key}{/tikz/edge label=\meta{text}}
        A shorthand for |edge node={node[auto]{|\meta{text}|}}|.
        %
\begin{codeexample}[]
\tikz \draw (0,0) to [edge label=x] (3,2);
\end{codeexample}
    \end{key}
    %
    \begin{key}{/tikz/edge label'=\meta{text}}
        A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|.
        %
\begin{codeexample}[]
\tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2);
\end{codeexample}
    \end{key}

    When the |quotes| library is loaded, additional ways of specifying nodes on
    to--paths become available, see Section~\ref{section-edge-quotes}.

    \medskip
    \textbf{Styles for to-paths.}\ \
    In addition to the \meta{options} given after the |to| operation, the
    following style is also set at the beginning of the to path:
    %
    \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
        This style is installed at the beginning of every to.
        %
\begin{codeexample}[]
\tikz[every to/.style={bend left}]
  \draw (0,0) to (3,2);
\end{codeexample}
        %
        Note that, as explained below, every to path is implicitly surrounded
        by curly braces. This means that options like |draw| given in an
        |every to| do not actually influence the path. You can fix this by
        using the |append after command| option:
        %
\begin{codeexample}[]
\tikz[every to/.style={append after command={[draw,dashed]}}]
  \draw (0,0) to (3,2);
\end{codeexample}
    \end{stylekey}

    \medskip
    \textbf{Options.}\ \
    The \meta{options} given with the |to| allow you to influence the
    appearance of the |to path|. Mostly, these options are used to change the
    |to path|. This can be used to change the path from a straight line to,
    say, a curve.

    The path used is set using the following option:
    %
    \begin{key}{/tikz/to path=\meta{path}}
        Whenever a |to| operation is used, the \meta{path} is inserted. More
        precisely, the following path is added:
        %
        \begin{quote}
            |{[every to,|\meta{options}|] |\meta{path} |}|
        \end{quote}

        The \meta{options} are the options given to the |to| operation, the
        \meta{path} is the path set by this option |to path|.

        Inside the \meta{path}, different macros are used to reference the
        from- and to-coordinates. In detail, these are:
        %
        \begin{itemize}
            \item \declareandlabel{\tikztostart} will expand to the
                from-coordinate (without the parentheses).
            \item \declareandlabel{\tikztotarget} will expand to the
                to-coordinate.
            \item \declareandlabel{\tikztonodes} will expand to the nodes
                between the |to| operation and the coordinate. Furthermore,
                these nodes will have the |pos| option set implicitly.
        \end{itemize}

        Let us have a look at a simple example. The standard straight line for
        a |to| is achieved by the following \meta{path}:
        %
        \begin{quote}
            |-- (\tikztotarget) \tikztonodes|
        \end{quote}

        Indeed, this is the default setting for the path. When we write
        |(a) to (b)|, the \meta{path} will expand to |(a) -- (b)|, when we
        write
        %
        \begin{quote}
            |(a) to[red] node {x} (b)|
        \end{quote}
        %
        the \meta{path} will expand to
        %
        \begin{quote}
            |(a) -- (b) node[red] {x}|
        \end{quote}

        It is not possible to specify the path
        %
        \begin{quote}
            |-- \tikztonodes (\tikztotarget)|
        \end{quote}
        %
        since \tikzname\ does not allow one to have a macro after |--| that
        expands to a node.

        Now let us have a look at how we can modify the \meta{path} sensibly.
        The simplest way is to use a curve.
        %
\begin{codeexample}[]
\begin{tikzpicture}[to path={
    .. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}]

  \node (a) at (0,0) {a};
  \node (b) at (2,1) {b};
  \node (c) at (1,2) {c};

  \draw (a) to node {x} (b)
        (a) to          (c);
\end{tikzpicture}
\end{codeexample}

        Here is another example:
        %
\begin{codeexample}[]
\tikzset{
  my loop/.style={to path={
    .. controls +(80:1) and +(100:1) .. (\tikztotarget) \tikztonodes}},
  my state/.style={circle,draw}}

\begin{tikzpicture}[shorten >=2pt]
  \node [my state] (a) at (210:1) {$q_a$};
  \node [my state] (b) at (330:1) {$q_b$};

  \draw[->] (a) to           node[below]       {1} (b)
                to [my loop] node[above right] {0} (b);
\end{tikzpicture}
\end{codeexample}

        \begin{key}{/tikz/execute at begin to=\meta{code}}
            The \meta{code} is executed prior to the |to|. This can be used to
            draw one or more additional paths or to do additional computations.
        \end{key}

        \begin{key}{/tikz/execute at end to=\meta{code}}
            Works like the previous option, only this code is executed after
            the to path has been added.
            % FIXME : provide examples...
        \end{key}

        \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
            This style is installed at the beginning of every to.
        \end{stylekey}
    \end{key}
\end{pathoperation}

There are a number of predefined |to path|s, see Section~\ref{library-to-paths}
for a reference.


\subsection{The Foreach Operation}

\begin{pathoperation}{foreach}{\meta{variables}\opt{\oarg{options}} |in|
        \marg{path commands}}
    The |foreach| operation can be used to repeatedly insert the \meta{path
    commands} into the current path. Naturally, the \meta{path commands} should
    internally reference some of the \meta{variables} so that you do not insert
    exactly the same path repeatedly, but rather variations. For historical
    reasons, you can also write |\foreach| instead of |foreach|.
    %
\begin{codeexample}[]
\tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) };
\end{codeexample}
    %
    See Section~\ref{section-foreach} for more details on the for-each-command.
\end{pathoperation}


\subsection{The Let Operation}

The \emph{let operation} is the first of a number of path operations that do
not actually extend that path, but have different, mostly local, effects.
It requires the |calc| library, see Section~\ref{tikz-lib-calc}.

\begin{pathoperation}{let}{\meta{assignment}
        \opt{|,|\meta{assignment}}%
        \opt{|,|\meta{assignment}\dots}\declare{| in |}}
    When this path operation is encountered, the \meta{assignment}s are
    evaluated, one by one. This will store coordinate and number in
    special \emph{registers} (which are local to \tikzname, they have
    nothing to do with \TeX\ registers). Subsequently, one can access the
    contents of these registers using the macros |\p|, |\x|, |\y|, and
    |\n|.

    The first kind of permissible \meta{assignment}s have the following form:
    %
    \begin{quote}
        |\n|\meta{number register}|={|\meta{formula}|}|
    \end{quote}
    %
    When an assignment has this form, the \meta{formula} is evaluated using the
    |\pgfmathparse| operation. The result is stored in the \meta{number
    register}. If the \meta{formula} involves a dimension anywhere (as in
    |2*3cm/2|), then the \meta{number register} stores the resulting dimension
    with a trailing |pt|.  A \meta{number register} can be named arbitrarily
    and is a normal \TeX\ parameter to the |\n| macro. Possible names are
    |{left corner}|, but also just a single digit like~|5|.

    Let us call the path that follows a let operation its \emph{body}. Inside
    the body, the |\n| macro can be used to access the register.
    %
    \begin{command}{\n\marg{number register}}
        When this macro is used on the left-hand side of an |=|-sign in a let
        operation, it has no effect and is just there for readability. When the
        macro is used on the right-hand side of an |=|-sign or in the body of
        the let operation, then it expands to the value stored in the
        \meta{number register}. This will either be a dimensionless number like
        |2.0| or a dimension like |5.6pt|.

        For instance, if we say |let \n1={1pt+2pt}, \n2={1+2} in ...|, then
        inside the |...| part the macro |\n1| will expand to |3pt| and |\n2|
        expands to |3|.
    \end{command}

    The second kind of \meta{assignments} have the following form:
    %
    \begin{quote}
        |\p|\meta{point register}|=|\meta{coordinate}
    \end{quote}
    %
    Point position registers store a single point, consisting of an $x$-part
    and a $y$-part measured in \TeX\ points (|pt|). In particular, point
    registers do not store nodes or node names. Here is an example:
    %
\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);

  \draw let \p{foo} = (1,1), \p2 = (2,0) in
          (0,0) -- (\p2) -- (\p{foo});
\end{tikzpicture}
\end{codeexample}

    \begin{command}{\p\marg{point register}}
        When this macro is used on the left-hand side of an |=|-sign in a let
        operation, it has no effect and is just there for readability. When the
        macro is used on the right-hand side of an |=|-sign or in the body of
        the let operation, then it expands to the $x$-part (measured in \TeX\
        points) of the coordinate stored in the \meta{register}, followed, by a
        comma, followed by the $y$-part.

        For instance, if we say |let \p1=(1pt,1pt+2pt) in ...|, then inside the
        |...| part the macro |\p1| will expand to exactly the seven characters
        ``1pt,3pt''. This means that you when you write |(\p1)|, this expands
        to |(1pt,3pt)|, which is presumably exactly what you intended.
    \end{command}
    %
    \begin{command}{\x\marg{point register}}
        This macro expands just to the $x$-part of the point register. If we
        say as above, as we did above, |let \p1=(1pt,1pt+2pt) in ...|, then
        inside the |...| part the macro |\x1| expands to |1pt|.
    \end{command}
    %
    \begin{command}{\y\marg{point register}}
        Works like |\x|, only for the $y$-part.
    \end{command}
    %
    Note that the above macros are available only inside a let operation.

    Here is an example where let clauses are used to assemble a coordinate from
    the $x$-coordinate of a first point and the $y$-coordinate of a second
    point. Naturally, using the \verb!|-! notation, this could be written much
    more compactly.
    %
\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);

  \draw    (1,0) coordinate (first point)
        -- (3,2) coordinate (second point);

  \fill[red] let \p1 = (first point),
                 \p2 = (second point) in
               (\x1,\y2) circle [radius=2pt];
\end{tikzpicture}
\end{codeexample}

    Note that the effect of a let operation is local to the body of the let
    operation. If you wish to access a computed coordinate outside the body,
    you must use a |coordinate| path operation:
    %
\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);

  \path % let's define some points:
    let
      \p1        = (1,0),
      \p2        = (3,2),
      \p{center} = ($ (\p1) !.5! (\p2) $) % center
    in
      coordinate (p1) at (\p1)
      coordinate (p2) at (\p2)
      coordinate (center) at (\p{center});

  \draw (p1) -- (p2);
  \fill[red] (center) circle [radius=2pt];
\end{tikzpicture}
\end{codeexample}

    For a more useful application of the let operation, let us draw a circle
    that touches a given line:
    %
\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{calc}}]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,3);

  \coordinate (a) at (rnd,rnd);
  \coordinate (b) at (3-rnd,3-rnd);
  \draw (a) -- (b);

  \node (c) at (1,2) {x};

  \draw let \p1 = ($ (a)!(c)!(b) - (c) $),
            \n1 = {veclen(\x1,\y1)}
        in circle [at=(c), radius=\n1];
\end{tikzpicture}
\end{codeexample}
    %
\end{pathoperation}


\subsection{The Scoping Operation}

When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at some
point where a path operation should come, it will open or close a scope. All
options that can be applied ``locally'' will be scoped inside the scope. For
example, if you apply a transformation like |[xshift=1cm]| inside the scoped
area, the shifting only applies to the scope. On the other hand, an option like
|color=red| does not have any effect inside a scope since it can only be
applied to the path as a whole.

Concerning the effect of scopes on relative coordinates, please see
Section~\ref{section-scopes-relative}.


\subsection{The Node and Edge Operations}

The |node| operation adds a so-called node to a path. This operation is special
in the following sense: It does not change the current path in any way. In
other words, this operation is not really a path operation, but has an effect
that is ``external'' to the path. The |edge| operation has similar effect in
that it adds something \emph{after} the main path has been drawn. However, it
works like the |to| operation, that is, it adds a |to| path to the picture
after the main path has been drawn.

Since these operations are quite complex, they are described in the separate
Section~\ref{section-nodes}.


\subsection{The Graph Operation}

The |graph| operation can be used to specify easily how a large number of nodes
are connected. This operation is documented in a separate section, see
Section~\ref{section-library-graphs}.


\subsection{The Pic Operation}

The |pic| operation is used to insert a ``short picture'' (hence the ``short''
name) at the current position of the path. This operation is somewhat similar
to the |node| operation and discussed in detail in Section~\ref{section-pics}.


\subsection{The Attribute Animation Operation}

\begin{pathoperation}{:}{\meta{animation attribute}|=|\marg{options}}
    This path operation has the same effect as if you had said:
    %
    \begin{quote}
        |[animate = { myself:|\meta{animate attribute}|=|\marg{options}|} ]|
    \end{quote}
    %
    This causes an animation of \meta{animate attribute} to be added to the
    current path, see Section~\ref{section-tikz-animations} for details.
    %
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
\end{codeexample}
    %
\end{pathoperation}


\subsection{The PGF-Extra Operation}

In some cases you may need to ``do some calculations or some other stuff''
while a path is constructed. For this, you would like to suspend the
construction of the path and suspend \tikzname's parsing of the path, you would
then like to have some \TeX\ code executed, and would then like to resume the
parsing of the path. This effect can be achieved using the following path
operation |\pgfextra|. Note that this operation should only be used by real
experts and should only be used deep inside clever macros, not on normal paths.

\begin{command}{\pgfextra\marg{code}}
    This command may only be used inside a \tikzname\ path. There it is used
    like a normal path operation. The construction of the path is temporarily
    suspended and the \meta{code} is executed. Then, the path construction is
    resumed.
    %
\begin{codeexample}[]
\newdimen\mydim
\begin{tikzpicture}
  \mydim=1cm
  \draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim);
\end{tikzpicture}
\end{codeexample}
    %
\end{command}

\begin{command}{\pgfextra \meta{code} \texttt{\char`\\endpgfextra}}
    This is an alternative syntax for the |\pgfextra| command. If the code
    following |\pgfextra| does not start with a brace, the \meta{code} is
    executed until |\endpgfextra| is encountered. What actually happens is that
    when |\pgfextra| is not followed by a brace, this completely shuts down the
    \tikzname\ parser and |\endpgfextra| is a normal macro that restarts the
    parser.
    %
\begin{codeexample}[]
\newdimen\mydim
\begin{tikzpicture}
  \mydim=1cm
  \draw (0pt,\mydim)
    \pgfextra \mydim=2cm \endpgfextra -- (0pt,\mydim);
\end{tikzpicture}
\end{codeexample}
    %
\end{command}


\subsection{Interacting with the Soft Path subsystem}

During construction \tikzname\ stores the path internally as a \emph{soft
path}. Sometimes it is desirable to save a path during the stage of
construction, restore it elsewhere and continue using it. There are two keys to
facilitate this operation, which are explained below. To learn more about the
soft path subsystem, refer to section~\ref{section-soft-paths}.

\begin{key}{/tikz/save path=\meta{macro}}
    Save the current soft path into \meta{macro}.
\end{key}

\begin{key}{/tikz/use path=\meta{macro}}
    Set the current path to the soft path stored in \meta{macro}.
\end{key}

\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
\begin{tikzpicture}
  \path[save path=\pathA,name path=A] (0,1) to [bend left] (1,0);
  \path[save path=\pathB,name path=B]
    (0,0) .. controls (.33,.1) and (.66,.9) .. (1,1);

  \fill[name intersections={of=A and B}] (intersection-1) circle (1pt);

  \draw[blue][use path=\pathA];
  \draw[red] [use path=\pathB];
\end{tikzpicture}
\end{codeexample}