summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-animations.tex
blob: 4d58fa6d79b315afda835c827f2f0d47262299ba (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
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
% Copyright 2015 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{Animations}
\label{section-tikz-animations}

\begin{tikzlibrary}{animations}
    This library must be loaded in order to use animations with \tikzname.
\end{tikzlibrary}


\subsection{Introduction}

An \emph{animation} changes the appearance of some part of a graphic over time.
The archetypical animation is, of course, a \emph{movement} of some part of a
picture, but a change of, say, the opacity of a path is also an animation.
\tikzname\ allows you to specify such animations using special keys and
notations.
%
\begin{codeexample}[width=8cm,animation list={0.7,1.4,2.1,2.8},animation scale=.25]
\begin{tikzpicture}[
    animate/orbit/.style 2 args = {
        myself:shift = {
          along = {
            (0,0) circle [radius=#1]
          } sloped in #2s/10,
          repeats }} ]

 \node :color = {0s = "orange",
                 2s = "red",
                 4s = "orange",
                 repeats}
       {Sun};

  \begin{scope}[animate={orbit={2.5cm}{365}}]
    \node {Earth};
    \node [animate={orbit={1cm}{28}}] {Moon};
  \end{scope}

  \useasboundingbox (-3.8,-3.8) (3.8,3.8);
\end{tikzpicture}
\end{codeexample}

Adding an animation to a \tikzname\ picture is done as follows:
%
\begin{enumerate}
    \item \emph{Before} or \emph{in the options of} the to-be-animated object
        you specify the object together with an \emph{attribute} that you wish
        to animate. Attributes are things like the fill color or the line width
        or the position of the object.
    \item You specify \emph{when} this attribute should have \emph{which}
        values using a so-called \emph{timeline}. This is just a curve that
        specifies for each point in time which value the attribute should have.
    \item You can additionally use further options to configure the animation,
        for instance you can specify that the animation should repeat or that
        it should only start when a certain object is clicked.
\end{enumerate}

As a simple example, let us move a circle within thirty seconds by three
centimeters to the left:
%
\begin{codeexample}[width=2cm]
\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
\end{codeexample}

As can be seen, a special syntax is used in several places: Entries with a
colon such as |:xshift| specify an attribute, values are specified in quotation
marks. This syntax will be explained in more detail later on.


\subsubsection{Animations Change Attributes}

Before we plunge into the details of how animations are specified, it is
important to understand what \tikzname\ actually does when creating an
animation: It does \emph{not} (as all other animation packages do) precompute a
sequence of pictures that are later somehow displayed in rapid succession.
Neither does it insert an external video into the document. Rather, a
\tikzname\ animation is just an ``annotation'' in the output that a certain
attribute of a certain object should change over time in some specific way when
the object is displayed. It is the job of the document viewer application to
actually compute and display the animation. The big advantage of this approach
is that animations neither increase the output file sizes noticeably nor do
they really slow down \TeX: The hard and complicated calculations are done by
the viewer application. The disadvantage is, of course, that a document viewer
application must understand the annotations and actually compute and display
the animations. The \textsc{svg} format is a format for which this is possible,
the popular \textsc{pdf} format is not. For the \textsc{svg} format, there are
actually different possible ways of ``formulating'' the animations (using
\textsc{smil} or \textsc{css} or JavaScript) and they have different advantages
and disadvantages.

To make a long story short: \tikzname\ animations currently work only with
\textsc{svg} output (and use the \textsc{smil} ``flavor'' of describing
animations). In future, it may well happen that other ``flavor'' of describing
animations will be added, but it is very unlikely that \textsc{pdf} will ever
support animations in a useful way.

It is, however, possible to create ``snapshots'' of an animation and insert
these into \textsc{pdf} files (or any other kind of file including \textsc{svg}
files), see Section~\ref{section-anim-snap} for details. Snapshots are also
useful for creating ``printed versions'' of animations and all of the small
sequences of pictures in the manual that are used for showing what an animation
key does have been creating using snapshots.


\subsubsection{Limitations of the Animation System}

There are a certain limitations of the animation system that you should keep in
mind when considering how and when to use it:
%
\begin{enumerate}
    \item As pointed out earlier, animations require a specific output format
        (currently only \textsc{svg} is supported).
    \item It is extremely difficult to animate ``lines between moving nodes''
        correctly. Consider code like |\draw(a)--(b);| where |a| and |b| are
        nodes. Now, when you animate the position of~|(a)|, the line connecting
        |(a)| and |(b)| will, unfortunately, not ``move along'' automatically
        (but it is easy to move the whole group of |(a)|, |(b)|, and the
        connecting ling as whole). You must ``cheat'' and introduce some
        ``virtual'' nodes, which leads to rather complex and bloated code.
    \item Animation are taken into consideration for bounding box computations,
        but only for shifts, not for rotations, scaling, or skewing and also
        possibly not when multiple shifts are active at the same time for the
        same object.
\end{enumerate}


\subsubsection{Concepts: (Graphic) Objects}

During an animation an attribute of a certain ``object'' changes over time. The
term ``object'' is deliberately a bit vague since there are numerous different
``things'' whose attributes can change. In detail, the following objects have
attributes that can be animated:
%
\begin{enumerate}
    \item Nodes, which are created by the |\node| command (and, also,
        internally by commands such as |\graph|). For nodes, different parts of
        the node can be animated separately; for instance, you can animate the
        color of the background path, but also the color of the text, and also
        the color of the foreground path (though most nodes do not have a
        foreground path) and also the color of different text parts (though
        only few nodes have multiple text parts).
    \item Graphic scopes, which are created by numerous command, including the
        |{scope}| environment, the |\scopes| command, but also |\tikz| itself
        creates a graphic scope and so does each node and even each path.
    \item View boxes, which can only be created using the |view| library.
    \item Paths, which you create using the |\path| command or commands like
        |\draw| that call |\path| internally. However, the (usually background)
        path of a node can also be animated. Note that ``animating the path''
        really means that the path itself should change over time; in essence,
        you can ``warp'' a path over time.
\end{enumerate}

In all of these cases, you must either specify the animation inside the
object's options using |animate| or use the |name| key to name the object and,
then, refer to it in an |animate|. For nodes you can, of course, use the
|(|\meta{node name}|)| syntax to name the node. Recall that you must
\emph{always} specify the animation \emph{before} the object is created; it is
not possible to animate an already created object.

There is a special syntax for choosing the object of an animation, see
Section~\ref{section-anim-syntax-obj}, but you can also use the |object| key to
choose them directly, see Section~\ref{section-anim-def-obj}.


\subsubsection{Concepts: Attributes}

In addition to the to-be-animated object, you must also choose an
\emph{attribute} that you wish to animate. Attributes are things like the color
of an object, the position, but also things like the line width. The syntax for
choosing attributes and the list of attributes will be explained in detail
later on.

Most attributes correspond directly to attributes that are directly supported
by the backend driver (\textsc{svg}), but this is not always the case. For
instance, for a node, \tikzname\ differentiates between the fill color, the
draw (stroke) color, and the text color, while \textsc{svg} treats the text
color are a special case of the fill color. \tikzname\ will do some internal
mappings to ensure that you can animate the ``\tikzname\ attributes'' even when
they are not directly supported.

The same syntax that is used for specifying object is also used to specify
attributes, see Section~\ref{section-anim-syntax-obj}, but you could also set
them directly using the |attribute| key see
Section~\ref{section-anim-def-attr}.


\subsubsection{Concepts: Timelines}

Once an object and an attribute have been chosen, a \emph{timeline} needs to be
established. This is, essentially, a curve that specifies for each ``moment in
time'' which value the attribute should have.

A timeline has a \emph{start} and an \emph{end}, but the start need not be the
``moment zero'' (we will come to that) and may even be negative, while the end
may be at infinity. You specify the timeline by specifying for certain points
in time what the value is at that moment; for all other moments the value is
then interpolated. For instance, if you specify that the attribute |:xshift|
(the ``horizontal position'' of the object) is 0\,mm at time 5\,s and 10\,mm at
time 10\,s, then at 7.5\,s it will be 5\,mm and at 9\,s it will be 8\,mm
(assuming a linear interpolation). The resulting optical effect will be that
the object \emph{smoothly moves} by one centimeter to the right over a period
of five seconds, starting five seconds after ``moment zero''.

Now, what is the ``moment zero'', the ``beginning of an animation''? If nothing
else is specified, an animation starts immediately when the graphic is shown
and this is the moment zero relative to which the timeline is measured.
However, it is also possible to change this. In particular, you can specify
that the moment zero is when a particular \emph{event} occurs such as the user
clicking on another object or another animation ending or starting.

The interpolation of values is not always a straightforward affair. Firstly,
for certain kinds of values is not clear how an interpolation should be
computed. How does one interpolate between two paths? Between the colors red
and green? Between the values |"true"| and |"false"|? In these cases, one must
define carefully what the interpolation should be. Secondly, you may wish to
use a non-linear interpolation, which is useful for ``easing'' motions: The
visual effect of the movement specified above is that the object sits still
from moment $0$ for five seconds, then there is an ``infinite acceleration''
causing the object to suddenly move at the speed of 2\,mm per second, then
there is no acceleration at all for five seconds, causing the object to move
for one centimeter, followed by an ``infinite negative acceleration'' that
makes the object come to a full stop. As a viewer you experience these infinite
accelerations as ``unrealistic'', spoiling the effect of watching a (virtual)
physical process. Non-linear interpolations allow you to avoid this effect.

Just as for specifying objects and attributes, there is also a special syntax
for specifying times and values.


\subsection{Creating an Animation}

\subsubsection{The Animate Key}

In order to animate a picture, you create timelines for all objects and
attributes that change during the animation. The key |animate| is used for
creating these timelines.

\begin{key}{/tikz/animate=\meta{animation specification}}
    You must place all specifications of animations inside uses of |animate|.
    You can, and usually should, place the specification of all timelines of a
    single picture inside a single use of this key since it will reset the time
    and the fork time (explained in Section~\ref{section-anim-def-times}). You
    can, however, use this key several times, in principle. Note that if you
    animate the same attribute of the same object in two different uses of
    |animate|, two separate timelines will result (and complicated rules are
    used to determine which one ``wins'' in case they specify conflicting
    values for the attribute at different times).

    The key can be used at all places where a \tikzname\ key is used; typically
    you will use it with a |{scope}| environment, inside the options of a node,
    or directly with the |\tikz| command:
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2}]
\tikz \node [fill, text = white, animate = {
  myself:fill = {0s = "red", 2s = "blue", begin on = click }}] {Click me};
\end{codeexample}
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2}]
\tikz [animate = {a node:fill = {0s = "red", 2s = "blue",
                                 begin on = click}}]
  \node (a node) [fill, text = white] {Click me};
\end{codeexample}

    The details of what, exactly, happens in the \meta{animation specification}
    will be described in the rest of this section. However, basically, an
    \meta{animation specification} is just a sequence of normal \tikzname\
    key--value pairs that get executed with the path prefix |/tikz/animate| and
    with some special syntax handlers installed. In particular, you can define
    styles for this key path and use them. For instance, we can define a
    |shake| animation like this:
    %
\begin{codeexample}[width=4cm]
\tikzset{
  animate/shake/.style = {myself:xshift = { begin on=click,
      0s = "0mm", 50ms = "#1", 150ms = "-#1", 250ms = "#1", 300ms = "0mm" }}}
\tikz \node [fill = blue!20, draw=blue, very thick, circle,
  animate = {shake = 1mm}] {Shake};
\tikz \node [fill = blue!20, draw=blue, very thick, circle,
  animate = {shake = 2mm}] {SHAKE};
\end{codeexample}

    Note that, as stressed earlier, you can only use the |animate| key to
    specify animations for objects that do not yet exist. The node and object
    names mentioned in a specification always refer to ``upcoming'' objects;
    already existing objects of the same name are not influenced.

    You can use the |name| key inside |animate| to ``name'' the animation. Once
    named, you can later reference the animation in other animations; for
    instance, you can say that another animation should start when the present
    animation has ended.
\end{key}


\subsubsection{Timeline Entries}

The ``job'' of the options passed to the |animate| key is to specify the
timelines of the animation of (a part of) a picture. For each object and each
attribute there may or may not be a timeline and, if present, the timeline
consist of sequences of pairs of times and values. Thus, the most basic entity
of an animation specification is a tuple consisting of five parts, which are
selected by five different keys:
%
\begin{itemize}
    \item |object| for selecting the object,
    \item |attribute| for selecting the attribute,
    \item |id| for selecting the timeline id (explained in
        Section~\ref{section-anim-def-id}),
    \item |time| for selecting a time, and
    \item |value| for selecting a value.
\end{itemize}
%
When all of these parts have been set up (using the above keys, which will be
explained in more detail in a moment), you can use the following key to create
an entry:

\begin{key}{/tikz/animate/entry}
    Each time this key is used in the options of |animate|, \tikzname\ checks
    whether the five keys |object|, |attribute|, |id|, |time|, and |value| are
    set. If one of them is not set, nothing happens. (The |id| key is set to
    the value |default| by default, all other keys must be set explicitly.)

    If all of these keys are set, a \emph{time--value} pair is created and
    added to the timeline of attribute of the object. Additionally, all options
    starting with |/tikz/animate/options/|, which also influence the timeline
    like |begin on|, are also added to the timeline of the object--attribute
    pair.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = {
  object = node, attribute = fill, time = 0s, value = red, entry,
  object = node, attribute = fill, time = 2s, value = blue, entry,
  object = node, attribute = fill, begin on = click, entry}]
  \node (node) [fill, text=white] { Click me };
\end{codeexample}
    %
    In the above example, it would not have been necessary the specify the
    object and the attribute in each line, they retain their values unless they
    are overwritten. Thus, we could also have written:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = {
  object = node, attribute = fill, time = 0s, value = red, entry,
                                   time = 2s, value = blue, entry,
                                   begin on = click, entry}]
  \node (node) [fill, text=white] { Click me };
\end{codeexample}
    %
    Note, however, that in both examples we actually add the time--value pair
    $(2\mathrm{s}, \mathrm{blue})$ twice since the |time| and |value| keys also
    retain their settings and, thus, for the third |entry| they have the same
    values as before and a new pair is added. While this superfluous pair is
    not a problem in the example (it has no visual effect), we will see later
    on how such pairs can be avoided by using the |scope| key.

    A sequence of calls of |entry| can freely switch between objects and
    attributes (that is, between timelines), but the times for any given
    timeline must be given in non-decreasing order:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = {
  object = node,  attribute = fill, time = 0s, value = red, entry,
  object = node2, attribute = draw, entry,
  object = node,  attribute = fill, time = 2s, value = blue, entry,
  object = node2, attribute = draw, entry,
  object = node,  attribute = fill, begin on = click, entry,
  object = node2, attribute = draw, begin on = click, entry}] {
  \node (node)  [fill, text=white]            { Node 1 };
  \node (node2) [draw, ultra thick] at (0,-1) { Node 2 };
}
\end{codeexample}
    %
    In the above example, we could not have exchanged the first two lines of
    the |animate| options with the third and fourth line since the values for
    time |0s| must come before the values for time |2s|.
\end{key}

In the following, we have a closer look at the five keys the influence the
|entry| key and then have a look at ways of grouping keys more easily.


\subsubsection{Specifying Objects}
\label{section-anim-def-obj}

You use the |object| key to select the object(s) to which the next use of
|entry| applies. There is also a special syntax for this, which is explained in
Section~\ref{section-anim-syntax-obj}.

\begin{key}{/tikz/animate/object=\meta{list of objects}}
    The \meta{list of objects} is a comma-separated list of strings of the form
    \meta{object}\opt{|.|\meta{type}}. All of the objects in the list are
    selected as to-be-animate object for the next use of the |entry| key. The
    objects referred to by \meta{object} will be the \emph{next} objects with
    the |name| key set to \meta{object}. You can apply the |name| key to nodes
    (where you can also use the special parentheses-syntax and put the name in
    parentheses, it has the same effect), but also to scopes and paths. (The
    |name path| key is not the same as |name|; it is an older key from the
    intersections package and not related.)
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
                                        begin on = click }}] {
  \node (a) [fill, text = white, minimum width=1.5cm] at (0,1cm) {a};
  \node (b) [fill, text = white, minimum width=1.5cm] at (0,5mm) {b};
  \node (c) [fill, text = white, minimum width=1.5cm] at (0,0mm) {c}; }
\end{codeexample}
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
                                        begin on = click },
                   object = c, :fill = {0s = "green", 2s = "blue",
                                        begin on = click } }] {
  \scoped [name = a, yshift=1cm] \fill (0,0) rectangle (1.5cm,2mm);
  \scoped [name = b, yshift=5mm] \fill (0,0) rectangle (1.5cm,2mm);
  \scoped [name = c, yshift=0mm] \fill (0,0) rectangle (1.5cm,2mm); }
\end{codeexample}

    If the \meta{object} name is never used later in the file, no animation is
    created.

    The \meta{object} may also be the special text |myself|. In this case, the
    referenced object is the scope or object to which the |animate| key is
    given. If an object is named |myself| (as in |\node (myself) ...|), you
    cannot reference this node using the |object| key, |myself| \emph{always}
    refers to the object where the |animate| key is given (of course, you can
    animate the node named |myself| by placing the |animate| key inside the
    options of this node; you only cannot ``remotely'' add an animation to it).

    The \meta{object} may be followed by a dot and a \emph{type}. This is need
    in rare cases where you want to animate only a special ``part'' of an
    object that is not accessible in other ways. Normally, \tikzname\ takes
    care of choosing these types automatically, you only need to set these ``if
    you know what you are doing''.
\end{key}


\subsubsection{Specifying Attributes}
\label{section-anim-def-attr}

\begin{key}{/tikz/animate/attribute=\meta{list of attributes}}
    The list of attributes must be a comma-separated list of attribute names.
    The timelines specified later will apply to all of these attributes (and to
    all objects previously selected using |object|). Possible attributes
    include colors, positions, line width, but even the paths themselves. The
    exact list of possible attributes is documented in
    Section~\ref{section-anim-attrs}.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = {attribute = fill, n: = { 0s = "red", 2s = "blue",
                                           begin on = click } }]
  \node (n) [fill, text = white] {The node};
\end{codeexample}
\end{key}


\subsubsection{Specifying IDs}
\label{section-anim-def-id}

\begin{key}{/tikz/animate/id=\meta{id} (initially default)}
    Timelines are use to defined how the values of an attribute of an object
    change over time. In many cases, you will have at most one timeline for
    each object--attribute pair, but, sometimes, you may wish to have more than
    one timeline for the same object and the same attribute. For instance, you
    might have a timeline that specifies a changing |shift| of a node in some
    direction and, at the same time, another timeline that specifies an
    additional |shift| in some other direction(s). The problem is that there is
    only one |shift| attribute and it would be difficult to compute the joint
    effect of the two timelines.

    For this purpose, timelines are actually identified not only by the
    object--attribute pair but, in reality, by the triple consisting of the
    object, the attribute, and the value of this key. We can now specify two
    separate timelines:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = {
  id = 1, n:shift = { 0s = "{(0,0)}", 2s = "{(0,5mm)}", begin on = click },
  id = 2, n:shift = { 0s = "{(0,0)}", 2s = "{(5mm,0)}", begin on = click }
}]
  \node (n) [fill = blue!20, draw=blue, very thick] {The node};
\end{codeexample}

    The default value of |id| is |default|.
\end{key}

Because of the possibility of creating multiple timelines for the same
attribute, it may happen that there is more than one timeline active that is
``trying to modify'' a given attribute. In this case, the following rules are
used to determine, which timeline ``wins'':
%
\begin{enumerate}
    \item If no animation is active at the current time (all animation either
        have not yet started or they have already ended), then the |base| value
        given in the animation encountered last in the code is used. (If there
        are no base values, the attribute is taken from the surrounding scope
        and the animations have ``no effect''.)
    \item If there are several active animations, the one that has started last
        is used and its value is used.
    \item If there are several active animations that have started at the same
        time, the one that comes last in the code is used.
\end{enumerate}

Note that these rules do not apply to transformations of the canvas since these
are always additive (or, phrased differently, they are always all active and
the effects accumulate).


\subsubsection{Specifying Times}
\label{section-anim-def-times}

\begin{key}{/tikz/animate/time=\meta{time}\opt{|later|}}
    Sets the time for the next time--value pair in a call of |entry| to
    \meta{time} plus the current fork time. The text |later| is optional. Both
    ``fork times'' and the optional |later| will be explained in a moment.

    \medskip\textbf{Time Parsing.}
    The \meta{time} is parsed using the command |\pgfparsetime|, which is
    essentially the same as the usual math parser of \tikzname, and the result
    is interpreted as a time in seconds. Thus, a \meta{time} of |2+3| means ``5
    seconds'' and a \meta{time} of |2*(2.1)| means ``4.2 seconds''. (You could
    even specify silly times like |1in|, which results in the time ``72.27
    seconds''. Please do not do that.) The ``essentially''  refers to the fact
    that some extras are installed when the time parser is running:
    %
    \begin{itemize}
        \item The postfix operator |s| is added, which has no effect. Thus,
            when you write |5s| you get the same results as |5|, which is
            exactly 5 seconds as desired.
        \item The postfix operator |ms| is added, which divides a number by
            1000, so |2ms| equals 0.002s.
        \item The postfix operator |min| is added, which multiplies a number by
            60.
        \item The postfix operator |h| is added, which multiplies a number by
            3600.
        \item The infix operator |:| is redefined, so that it multiplies its
            first argument by 60 and adds the second. This implies that |1:20|
            equals 80s and |01:00:00| equals 3600s.
        \item The parsing of octal numbers is switched off to allow things like
            |01:08| for 68s.
    \end{itemize}

    Note that you cannot use the colon syntax for times in things like
    |01:20 = "0"| would (falsely) be interpreted as: ``For the object named |01|
    and its attribute named |20|, do something.'' You can, however, use |01:20|
    in arguments to the |time| key, meaning that you would have to write
    instead: |time = 1:20, "0"|, possibly surround by a |scope|.

    \medskip\textbf{Relative Times.}
    You can suffix a |time| key with ``|later|''. In this case, the \meta{time}
    is interpreted as an offset to the time in the previous use of the time
    key:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :fill = { begin on = click,
    0s = "white",
    500ms later = "red",
    500ms later = "green",  % same as 1s   = "-5mm"
    500ms later = "blue"} % same as 1.5s = "-2.5mm"
  [fill=blue!20, draw=blue, very thick, circle] {Click me};
\end{codeexample}

    In reality, the offset is not taken to just any previous use of the |time|
    key, but to the most recent use of this key or of the |resume| key in the
    current local \TeX\ scope. Here is an example:
    %
\begin{codeexample}[code only]
time = 2s,
time = 1s later,    % same as time = 3s
time = 500ms later, % same as time = 3.5s
time = 4s,
time = 1s later,    % same as time = 5s
scope = {           % opens a local scope
  time = 1s later,  % same as time = 6s
  time = 10s
  time = 1s later   % same as time = 11s
},                  % closes the scope, most recent time is 5s once more
time = 2s later     % same as time = 7s
\end{codeexample}

    \medskip\textbf{Fork Times.}
    The time meant by the value \meta{time} passed to the |time| key is not
    used directly. Rather, \tikzname\ adds the current \emph{fork time} to it,
    which is |0s| by default. You can change the fork time using the following
    key:
    %
    \begin{key}{/tikz/animate/fork=\meta{t} (default 0s later)}
        Sets the fork time for the local scope to \meta{t} and sets the current
        time to |0s|. In this scope, when you use ``absolute'' times like |0s|
        or |2s|, you actually refer to later times that have started as
        \meta{t}.

        One application of forks is in the definition of keys that add a
        certain part to a longer animation. Consider for instance the
        definition of a |hilight| key:
        %
\begin{codeexample}[animation list={1.05,1.1,1.15,1.2,2.05,2.1,2.15,2.2}]
\tikz [animate/highlight/.style = {
    scope = { fork = #1,
              :fill = { 0s = "black", 0.1s = "white", 0.2s = "black"} }
  }]
  \node [animate = { myself: = {
            :fill = { 0s = "black", begin on = click },
                      highlight = 1s, highlight = 2s } },
         fill = blue, text=white, very thick, circle] { Click me };
\end{codeexample}
        %
        In the above example, we could also have written |0.1s later| instead
        of |0.2s| and, indeed, the whole style could have been defined using
        only times with |later|, eliminating the need for the |fork| key.
        However, using forks you can specify absolute times for things
        happening in a conceptual ``subprocess'' and also relative times. The
        name |fork| for the key is also borrowed from operating system theory,
        where a ``fork'' is the spawning of an independent process.
    \end{key}

    \medskip\textbf{Remembering and Resuming Times.}
    When you have a complicated animation with a long timeline, you will
    sometimes wish to start some animation when some other animation has
    reached a certain moment; but this moment is only reached through heavy use
    of |later| times and/or forks. In such situations, the following keys are
    useful:
    %
    \begin{key}{/tikz/animate/remember=\meta{macroname}}
        This key stores the current time (the time of the last use of the
        |time| key) globally in the macro \meta{macroname}. This time will
        include the offset of the fork time:
        %
\begin{codeexample}[code only]
time = 2s,
fork = 2s later,    % fork time is now 4s
time = 1s,          % local time is 1s, absolute time is 5s (1s + fork time)
time = 1s later,    % local time is 2s, absolute time is 6s (2s + fork time)
remember = \mytime  % \mytime is now 6s
\end{codeexample}
    \end{key}
    %
    \begin{key}{/tikz/animate/resume=\meta{absolute time}}
        The \meta{absolute time} is evaluated using |\pgfparsetime| and, then,
        the current time is set to the resulting time minus the fork time. When
        the \meta{absolute time} is a macro previously set using |remember|,
        the net effect of this is that we return to the exact ``moment'' in the
        global time line when |remember| was used.
        %
\begin{codeexample}[code only]
fork = 4s,
time = 1s,
remember = \mytime  % \mytime is now 5s
fork = 2s,          % fork time is now 2s, local time is 0s
resume   = \mytime  % fork time is still 2s, local time is 3s
\end{codeexample}
        %
        Using resume you can easily implement a ``join'' operation for forked
        times. You simply remember the times at the ends of the forks and then
        resume the maximum time of these remembered times:
        %
\begin{codeexample}[code only]
scope = {
  fork,
  time = 1s later,
  ...
  remember = \forka
},
scope = {
  fork,
  time = 5s later,
  ...
  remember = \forkb
},
scope = {
  fork,
  time = 2s later,
  ...
  remember = \forkc
},
resume = {max(\forka,\forkb,\forkc)} % "join" the three forks
\end{codeexample}
    \end{key}
\end{key}


\subsubsection{Values}
\label{section-anim-def-values}

\begin{key}{/tikz/animate/value=\meta{value}}
    This key sets the value of the next time--value pair created by |entry| to
    \meta{value}. The syntax of the \meta{value} is not fixed, it depends on
    the type of the attribute. For instance, for an attribute like |opacity|
    the \meta{value} must be an expression that can be evaluated to a number
    between 0 and 1; for the attribute |color| the \meta{value} must, instead,
    be a color; and so on. Take care that when a value contains a comma, you
    must surround it by braces as in |"{(1,1)}"|.

    The allowed texts for the \meta{value} is always the same as the one you
    would pass to the \tikzname\ option of the same name. For instance, since
    the \tikzname\ option |shift| expects a coordinate, you use coordinates as
    \meta{value} with the usual \tikzname\ syntax (including all sorts of
    extensions, the animation system calls the standard \tikzname\ parsing
    routines). The same is true of dimensions, scalar values, colors, and so
    on.

    In addition to the values normally use for setting the attribute, you can
    also (sometimes) use the special text |current value| as \meta{value}. This
    means that the value of the point in the timeline should be whatever the
    value the attribute has at the beginning of the timeline. For instance,
    when you write
    %
\begin{codeexample}[code only]
animate = { obj:color = { 0s = "current value", 2s = "white" } }
\end{codeexample}
    %
    the color of |obj| will change from whatever color it currently has to
    white in two seconds. This is especially useful when several animations are
    triggered by user events and the current color of |obj| cannot be
    determined beforehand.

    There are several limitations on the use of the text |current value|, which
    had to be imposed partly because of the limited support of this feature in
    \textsc{svg}:
    %
    \begin{itemize}
        \item You can use |current value| only with the first time in a
            timeline.
        \item You can only have two times in a timeline that starts with
            |current value|.
        \item You cannot use |current value| for timelines of which you wish to
            take a snapshot.
    \end{itemize}
\end{key}


\subsubsection{Scopes}
\label{section-anim-scopes}

When you specify multiple timelines at the same time, it is often useful and
sometimes even necessary to have keys be set only locally. The following key
makes this easy:

\begin{key}{/tikz/animate/scope=\meta{options}}
    Executed the \meta{options} inside a \TeX\ scope. In particular, all
    settings made inside the scope have no effect after the end of the |scope|.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node [animate = { myself: = { begin on = click,
    scope = { attribute = fill, repeats = 3, 0s = "red", 2s = "red!50" },
    scope = { attribute = draw,              0s = "red", 2s = "red!50" }
  }},
  fill=blue!20, draw=blue, very thick, circle] {Click me};
\end{codeexample}

    Without the use of the |scope| key, the |repeats| key would also affect the
    draw attribute.
\end{key}

While the |scope| key is useful for structuring timeline code, it also keeps
the current time local to the scope, that is, if you use something like
|1s later| after the scope, this will refer to one second after the last use of
|time| \emph{before} the scope. The times set inside the |scope| do not matter.
While this is desirable effect for forks, you may also sometimes wish to
synchronize the local time after the scope with the last time reached in the
scope. The following key makes this easy:

\begin{key}{/tikz/animate/sync=\meta{options}}
    A shorthand for |scope={| \meta{options} |, remember=\temp},resume=\temp|
    where |\temp| is actually an internal name. The effect is that after a
    |sync| the local time just continues as if the scope where not present --
    but regarding everything else the effects are local to the |sync| scope.
\end{key}


\subsection{Syntactic Simplifications}
\label{section-anim-syntax-animate}

In the previous subsection we saw how timelines can be created by specifying
the individual entries of the timelines sequentially. However, most of the time
you will wish to use a simpler syntax that makes it easier to specify
animations. This syntax is only available inside the |animate| key (it is
switched on at the beginning) and consists of three ``parts'': The colon
syntax, the time syntax, and the quote syntax.


\subsubsection{The Colon Syntax I: Specifying Objects and Attributes}
\label{section-anim-syntax-obj}

Inside the \meta{animation specification} passed to the |animate| key, you can
specify an object and an attribute of this object using the following syntax,
whose use is detected by the presence of a colon inside a key:
%
\begin{quote}
  \normalfont
  \opt{\meta{object name(s)}}|:|\opt{\meta{attribute(s)}}
  |={|\meta{options}|}|

  or

  \opt{\meta{object
      name(s)}}|:|\opt{\meta{attribute(s)}}|_|\opt{\meta{id}}
  |={|\meta{options}|}|
\end{quote}
%
In the place to the left of an equal sign, where you would normally use a key,
you can instead place an object name and an attribute separated by a colon.
Additionally, the attribute may be followed by an underscore and an \meta{id},
which identifies the timeline (see Section~\ref{section-anim-def-id}).

Each of these values may be missing, in which case it is not changed from its
previous value.

The effect of the above code is the same as:
%
\begin{quote}
  \normalfont
  |sync = { object = |\meta{objects}|, attribute = |\meta{attribute}|, id = |\meta{id}|, |\meta{options}|, entry }|
\end{quote}
%
although when the object, the attribute, or the id is left empty in the colon
syntax, the corresponding setting will be missing in the above call of |sync|.
Note that because of the |sync| the last time used inside the \meta{options}
will be available afterwards as the last time. Also note that an |entry| is
added at the end, so any settings of keys like |begin| or |repeats| inside the
\meta{options} will get added to the timeline.

Let us now have a look at some examples. First, we set the \meta{object name}
to |mynode| and |othernode| and the \meta{attribute} to |opacity| and to
|color|:
%
\begin{codeexample}[code only]
animate = {
  mynode:opacity    = { 0s = "1",   5s = "0" },
  mynode:color      = { 0s = "red", 5s = "blue" },
  othernode:opacity = { 0s = "1",   5s = "0" },
}
\end{codeexample}

Next, we do the same, but ``in two steps'': First, we set the object to
|my node|, but leave the attribute open and, then, set the attribute, but leave
the object:
%
\begin{codeexample}[code only]
animate = {
  mynode: = {
    :opacity        = { 0s = "1",   5s = "0" },
    :color          = { 0s = "red", 5s = "blue" }
  },
  othernode:opacity = { 0s = "1",   5s = "0" },
}
\end{codeexample}
%
Note how both in  |mynode:| and in |:opacity| and |:color| you must provide the
colon. Its presence signals that an object--attribute pair is being specified;
only now either the object or the attribute is missing.

We can also do it the other way round:
%
\begin{codeexample}[code only]
animate = {
  :opacity = {
    mynode:         = { 0s = "1",   5s = "0" },
    othernode:      = { 0s = "1",   5s = "0" }
  },
  mynode:color      = { 0s = "red", 5s = "blue" }
}
\end{codeexample}
%
Finally, if several objects should get the exact same values, we can also group
them:
%
\begin{codeexample}[code only]
animate = {
  {mynode,othernode}:opacity = { 0s = "1",   5s = "0" },
  mynode:color               = { 0s = "red", 5s = "blue" }
}
\end{codeexample}

As mentioned earlier, all references to objects will be interpreted to future
objects, never to objects already created. Furthermore, also as mentioned
earlier, \tikzname\ allows you to specify |myself| as \meta{object}, which is
interpreted as the scope or node where the |animate| is given (you cannot
animate a node or scope named |myself|, this special name always refers to the
current node). In order to have all attributes refer to the current object, you
write:
%
\begin{codeexample}[code only]
\begin{scope} [animate = {
                 myself: = { % Animate the attribute of the scope
                   :opacity = { ... },
                   :xshift  = { ... }
                 }
               }]
  ...
\end{scope}
\end{codeexample}

The list of permissible attributes is given in
Section~\ref{section-anim-attrs}.


\subsubsection{The Colon Syntax II: Animating Myself}

A frequent use of the |animate| key is for animating attributes of the current
object |myself|. In these cases, it is a bit length to write
%
\begin{codeexample}[code only]
[animate = { myself: = { :some attribute = {...} } } ]
\end{codeexample}
%
\noindent in the options of a node or a scope. For this reason, \tikzname\
allows you to use a special syntax with nodes and scopes:
%
\begin{enumerate}
    \item In a \meta{node specification}, which is everything following a
        |node| command up to the content of the node (which is surrounded by
        curly braces), you can write
        %
        \begin{quote}
            |:some attribute = {|\meta{options}|}|
        \end{quote}
        %
        and this will have the same effect as if you had written
        %
        \begin{quote}
            |[animate = { myself: = { :some attribute = {|\meta{options}|}}}]|
        \end{quote}
        %
        Note that you can use this syntax repeatedly, but each use creates a
        new use of the |animate| key, resulting in a new timeline. In order to
        create complex timelines for several objects, use the |animate| key.
    \item For the commands |\tikz|, |\scoped| and the environments
        |{tikzpicture}| and |{scope}|, when they are followed immediately by
        %
        \begin{quote}
            |:some attribute = {|\meta{options}|}|
        \end{quote}
        %
        then
        %
        \begin{quote}
            |animate = { myself: = { :some attribute = {|\meta{options}|}}}|
        \end{quote}
        %
        is added to the options of the command or scope. Again, you can use the
        syntax repeatedly. Note that when an opening square bracket is
        encountered, this special parsing stops.
\end{enumerate}

Let us have a look at some examples. First, we use the syntax to set the fill
opacity of a node:
%
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node
  :fill opacity = { 0s="1", 2s="0", begin on=click }
  [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
\end{codeexample}
%
Next, we additionally rotate the node:
%
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node
  :fill opacity = { 0s="1", 2s="0", begin on=click }
  :rotate = { 0s="0", 2s="90", begin on=click }
  [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
\end{codeexample}
%
Note that there is no comma between consecutive uses of the colon syntax in
this case. We could have exchanged the order of the options and the uses of the
colon syntax:
%
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node
  :fill opacity = { 0s="1", 2s="0", begin on=click }
  [fill = blue!20, draw = blue, ultra thick, circle]
  :rotate = { 0s="0", 2s="90", begin on=click } {Here!};
\end{codeexample}

We can also use the special syntax with the |\tikz| command itself:
%
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz  :fill opacity = { 0s="1", 2s="0", begin on=click }
       :rotate = { 0s="0", 2s="90", begin on=click }
       [ultra thick]
  \node [fill = blue!20, draw = blue, circle] {Here!};
\end{codeexample}

Note that we could \emph{not} have moved the |[ultra thick]| options before
|:rotate| since the options in square brackets end the special parsing.


\subsubsection{The Time Syntax: Specifying Times}

For each object--attribute pair you must specify the \emph{timeline} of the
attribute. This is a curve that specifies for each ``moment in time'' which
value the attribute should have. In the simplest case, you specify such a
time--value pair as follows:
%
\begin{quote}
    \normalfont
    \meta{time} |="|\meta{value}|"|
\end{quote}

When you specify time--value pairs, you must specify the times in chronological
order (so earlier times come first), but you may specify the same time several
times (this is useful in situations where you have a ``jump'' from one value to
another at a certain moment in time: you first specify the value ``from which
the attribute jumps'' and then you specify the value ``to which the attribute
jumps'' for the same moment).

The above syntax is just a special case of a more general situation. Let us
start with the times. The general syntax for specifying times is as follows:
%
\begin{quote}
    \normalfont
    \meta{time} \opt{|=| \meta{options}}
\end{quote}

Here, \meta{time} is a text that ``looks like a time'', which means that:
%
\begin{enumerate}
    \item It is not a key and does not contain a colon and does not start with
        a quotation mark.
    \item It starts with a digit, a plus or minus sing, a dot, or a
        parenthesis.
\end{enumerate}

If these two things are the case, the above code is transformed to the
following call:
%
\begin{quote}
    \normalfont
    |sync = {time = |\meta{time}|, |\meta{options}|, entry}|
\end{quote}


\subsubsection{The Quote Syntax: Specifying Values}

We saw already in several examples that values are put in quotation marks
(similar to the way this is done in \textsc{xml}). This quote syntax is as
follows:
%
\begin{quote}
    \normalfont
    |"|\meta{value}|"| \opt{|base|} \opt{|=| \meta{options}}
\end{quote}

This syntax is triggered whenever a key starts with a quotation mark%
\footnote{Of catcode 12 for those knowledgeable of such things.} (and note that
when the \meta{value} contains a comma, you have to surround it by curly braces
\emph{inside} the quotation marks as in |"{(1,1)}"|). Then, the following code
is executed:
%
\begin{quote}
    \normalfont
    |sync = {value = |\meta{value}|, |\meta{options}|, entry}|
\end{quote}

This means that when you write |1s = "red"|, what actually happens is that
\tikzname\ executes the following:
%
\begin{codeexample}[code only]
sync = { time = 1s, sync = { value = red, entry }, entry }
\end{codeexample}
%
Note that the second entry has no effect since no value is specified and the
|entry| key only ``takes action'' when both a time and a value have been
specified. Thus, only the innermost |entry| does, indeed, create a time--value
pair as desired.

In addition to the above, if you have added |base| after the closing quote, the
following gets executed before the above |sync|:
%
\begin{quote}
    \normalfont
    |base = {value = |\meta{value}|}|
\end{quote}

This makes it easy to specify base values for timelines.

Interestingly, instead of |1s="red"| you can also write |"red"=1s|. Let us now
have a look at situations where this can be useful.


\subsubsection{Timesheets}

Using the |sync| key or using the three different syntactic constructs
introduced earlier (the color syntax, the time syntax, the value syntax), you
can organize the specification of an animation in different ways. Basically,
the two most useful ways are the following:
%
\begin{enumerate}
    \item You first select an object and an attribute for which you wish to
        establish a timeline and then provide the time--value pairs in a
        sequence:
        %
\begin{codeexample}[code only]
animate = {
  obj:color = {
    0s = "red",
    2s = "blue",
    1s later = "green",
    1s later = "green!50!black",
    10s = "black"
  }
}
\end{codeexample}
        %
        When you specify timelines for several attributes of the same object,
        you can group these together:
        %
\begin{codeexample}[code only]
animate = {
  obj: = {
    :color = { 0s = "red", 2s = "green" },
    :opacity = { 0s = "1", 2s = "0" }
  }
}
\end{codeexample}
        %
        In this way of specifying animations the ``object comes first''.
    \item Alternatively, you can also group the animation by time and, for each
        ``moment'' (known as \emph{keyframes}) you specify which values the
        attributes of the object(s) have:
        %
\begin{codeexample}[code only]
animate = {
  0s = {
    obj:color = "red",
    obj:opacity = "1"
  },
  2s = {
    obj:color = "green",
    obj:opacity = "0"
  }
}
\end{codeexample}
        %
        Naturally, in this case it would have been better to ``move the object
        outside'':
        %
\begin{codeexample}[code only]
animate = {
  obj: = {
    0s = {
      :color = "red",
      :opacity = "1"
    },
    2s = {
      :color = "green",
      :opacity = "0"
    }
  }
}
\end{codeexample}
        %
        When there are several objects involved, we can mix all of these
        approaches:
        %
\begin{codeexample}[code only]
animate = {
  0s = {
    obj: = {
      :color = "red",
      :opacity = "1"
    },
    main node: = {
      :color = "black"
    }
  },
  2s = {
    obj: = {
      :color = "green",
      :opacity = "0"
    },
    main node: = {
      :color = "white"
    }
  }
}
\end{codeexample}
        %
\end{enumerate}


\subsection{The Attributes That Can Be Animated}
\label{section-anim-attrs}

The following \meta{attributes} are permissible (actually, the attribute names
do not include a colon, but since they will almost always be used with the
colon syntax, it makes it easier to identify them):
%
\begin{itemize}
        \itemsep0pt
    \item |:dash phase|
    \item |:dash pattern|
    \item |:dash|
    \item |:draw opacity|
    \item |:draw|
    \item |:fill opacity|
    \item |:fill|
    \item |:line width|
    \item |:opacity|
    \item |:position|
    \item |:path|
    \item |:rotate|
    \item |:scale|
    \item |:stage|
    \item |:text opacity|
    \item |:text|
    \item |:translate|
    \item |:view|
    \item |:visible|
    \item |:xscale|
    \item |:xshift|
    \item |:xskew|
    \item |:xslant|
    \item |:yscale|
    \item |:yshift|
    \item |:yskew|
    \item |:yslant|
\end{itemize}

These attributes are detailed in the following sections, but here is a quick
overview of those that do not have a \tikzname\ key of the same name (and which
thus do not just animate the attribute set using this key):
%
\begin{itemize}
    \item |:shift| allows you to add an animated shifting of the canvas, just
        like \tikzname's |shift| key. However, in conjunction with the |along|
        key, you can also specify the shifting along a path rather than via a
        timeline of coordinates.
    \item |:position| works similar to |:shift|, only the coordinates are not
        relative movements (no ``shifts''), but refer to ``absolute positions''
        in the picture.
    \item |:path| allows you to animate a path (it will morph). The ``values''
        are now paths themselves.
    \item |:view| allows you to animate the view box of a view.
    \item |:visible| decides whether  an object is visible at all.
    \item |:stage| is identical to |:visible|, but when the object is not
        animated, it will be hidden by default.
\end{itemize}


\subsubsection{Animating Color, Opacity, and Visibility}
\label{section-animation-painting}

You can animate the color of the target object of an animation using the
attributes |fill|, |draw|, and |text|. When the target of a color animation is
a scope, you animate the color ``used in this scope'' for filling or stroking.
However, when an object inside the scope has its color set explicitly, this
color overrules the color of the scope.

\begin{tikzanimateattribute}{fill, draw}
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz :fill = {0s = "red", 2s = "blue", begin on = click}
      [text = white, fill = orange ] {
  \node [fill]                   at (0mm,0) {A};
  \node [fill]                   at (5mm,0) {B};
  \node [fill = green!50!black ] at (1cm,0) {C};
}
\end{codeexample}
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{text}
    The |text| attribute only applies to nodes and you need to directly animate
    the |text| attribute of each node individually.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [my anim/.style={ animate = {
           myself:text = {0s = "red", 2s = "blue", begin on = click}}},
       text = white, fill = orange ] {
  \node [fill, my anim] at (0,0) {A};
  \node [fill, my anim] at (1,0) {B};
}
\end{codeexample}
    %
    Unlike the |fill| and |draw| colors, you cannot animate the |text| color
    for scopes:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz [animate = {myself:text = {0s = "red", 2s = "blue",
                                 begin on = click}},
       text = white, fill = orange ] {
  \node [fill] at (0,0) {A};
  \node [fill] at (1,0) {B};
}
\end{codeexample}
    %
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{color}
    The |color| attribute is not really an attribute. Rather, it is a shorthand
    for |{draw,fill,text}|. This means that |color| does not start a separate
    timeline, but continues the |draw| timeline, the |fill| timeline, and the
    |text| timeline.
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{opacity, fill opacity, stroke opacity}
    Similarly to the color, you can also set the opacity used for filling and
    for drawing using the attributes |fill opacity| and |draw opacity|, which
    are exactly the same as the usual \tikzname\ keys of the same names.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :fill opacity = { 0s="1", 2s="0", begin on=click }
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
    Unlike colors, where there is no joint attribute for filling and stroking,
    there is a single |opacity| attribute in addition to the above two
    attributes. If supported by the driver, it treats the graphic object to
    which it is applied as a transparency group. In essence, ``this attribute
    does what you want'' at least in most situations.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :opacity = { 0s="1", 2s="0", begin on=click }
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{visible, stage}
    The difference between the |visible| attribute and an opacity of |0| is
    that an invisible object cannot be clicked and does not need to be
    rendered. The (only) two possible values for this attribute are |false| and
    |true|.
    %
\begin{codeexample}[animation list={1,2,3,4}]
\tikz :visible = {begin on=click, 0s="false", 2s="false"}
  \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\end{codeexample}

    This |stage| attribute is the same as the |visible| attribute, only
    |base="false"| is set by default. This means that the object is \emph{only}
    visible when you explicitly during the time the entries are set to |true|.
    The idea behind the name ``stage'' is that the object is normally ``off
    stage'' and when you explicitly set the ``stage attribute'' to |true| the
    object ``enters'' the stage and ``leaves'' once more when it is no longer
    ``on stage''.
    %
\begin{codeexample}[animation list={-1,0,1,2,3},animation bb={(1.3,-0.7) rectangle (2.7,0.7)}]
\tikz [animate = {example:stage = {
                   begin on = {click, of next=node},
                   0s="true", 2s="true" }}] {
  \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
  \node at (2,0) (example) [fill = blue!20, circle] {Effect};
}
\end{codeexample}
\end{tikzanimateattribute}


\subsubsection{Animating Paths and their Rendering}
\label{section-animation-paths}

The attributes of the appearance of a path that you can animate include the
line width and the dash pattern, the path itself, as well as the arrow tips
attached to the paths. Animating the line width and the dash pattern is easy
since the animation attributes simply have that same names as the properties
that they animate and the syntax for setting is also the same:

\begin{tikzanimateattribute}{line width}
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :line width = { 0s="1pt", 2s="5mm", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
    Note that you must specify number (or expressions that evaluate to numbers)
    as values, you cannot say |thin| or |thick| (these are styles, internally,
    and you also cannot say |line width=thick|).
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{dash, dash phase, dash phase}
    The values for an animation of the dashing are specifications (see the
    |dash| key for details) consisting of a sequence of |on| and |off| numbers.
    In each value of the animation the length of these sequences \emph{must} be
    identical. The interpolation of the values is done for each position of the
    sequences individually, and also on the phase.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :dash = { 0s="on 10pt off 1pt  phase 0pt",
                      2s="on 1pt  off 10pt phase 0pt", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :dash = { 0s="on 1cm off 1pt phase 0pt",
                      2s="on 1cm off 1pt phase 1cm", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}

    This |dash pattern| key allows you to animate the dash phase only. However,
    due to the way dashing is handled by certain drivers, the dash pattern is
    also set, namely to the current dash pattern that is in force when the
    animation is created.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :dash phase = { 0s="0pt", 2s="1cm", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle, dashed] {Click me!};
\end{codeexample}
    %
\end{tikzanimateattribute}

The above attributes ``only'' influence how the path is rendered. You can,
however, also animate the path itself:

\begin{tikzanimateattribute}{path}
    When you animate a path, the values are, of course, paths themselves:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :path = {
        0s = "{(0,-1) .. controls (0,0) and (0,0)   .. (0,1) -- (1,1)}",
        2s = "{(0,-1) .. controls (-1,0) and (-1,0) .. (-1,1) -- (.5,-1)}",
        begin on=click }
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
    There a number of things to keep in mind when you animate a path:
    %
    \begin{itemize}
        \item The path ``values'' are parsed and executed in an especially
            protected scope to ensure that they have only little side effects,
            but you should not do ``fancy things'' on these paths.
        \item As for the dash pattern, you must ensure that all paths in the
            timeline have the same structure (same sequence of path
            construction commands); only the coordinates may differ. In
            particular, you cannot say that the path at |1s| is a rectangle
            using |rectangle| and at |2s| is a circle using |circle|. Instead,
            you would have to ensure that at both times the path consists of
            appropriate Bézier curves (which is cumbersome as the following
            example shows, where we used the fact that a circle consists of
            four Bézier curves):
            %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :path = {
        0s = "{(0,0) circle [radius=1cm]}",
        2s = "{(0,0)
               (1,0) .. controls +(0,0) and +(0,0) .. (0,1)
                     .. controls +(0,0) and +(0,0) .. (-1,0)
                     .. controls +(0,0) and +(0,0) .. (0,-1)
                     .. controls +(0,0) and +(0,0) .. (1,0)
                     -- cycle (0,0)}",
        begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
            %
        \item You must specify arrow tips for an animated path in a special
            way, namely using the |arrows| key for \emph{animations}, not the
            normal |arrows| key (see below).
    \end{itemize}
\end{tikzanimateattribute}

\begin{key}{/tikz/animate/arrows=\meta{arrow spec}}
    This key only has an effect on |:path| animations. It causes the arrow tips
    specified in \meta{arrow spec} to be added to the path during the animation
    (the syntax is the same as for the normal |arrows| key). If you have
    several different animations for a paths, these may contain different arrow
    tips, but each animation must stick to one kind of arrow tips.

    What happens internally when this key is used is the following: The
    specified arrow tips are rendered internally as so-called \emph{markers,}
    which are small graphics that can be placed at the beginning and ends of
    paths and which ``rotate along'' as a path changes. Note that these markers
    are used \emph{only} in the context of animated paths, the arrow tips of
    normal, ``static'' paths are drawn without the use of markers. Normally,
    there is no visual difference between an arrow tip drawn using markers or
    those drawn for static paths, but in rare cases there may be differences.
    You should only add arrows to open path consisting of a single segment with
    sufficiently long first and last segments (so that \tikzname\ can shorten
    these segments correctly when necessary).

    As pointed out earlier, the only way to add arrow tips to a path that is
    animated is using this key, you can \emph{not} say something like
    %
\begin{codeexample}[code only]
\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}" }
  [->] (0,0) -- (1,0);
\end{codeexample}
    %
    This will raise an error since you try to animate a path (|:path = ...|)
    that has normal arrow tips attached (|[->]|).

    Instead, you must specify the arrow tips inside the animation command:
    %
\begin{codeexample}[code only]
\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}", arrows = -> }
  (0,0) -- (1,0);
\end{codeexample}

    However, the above code now has a big shortcoming: While the animation is
    \emph{not} running, \emph{no} arrow tip is shown (the |arrows| key only
    applies to the animation.

    The trick is to use the |base| key. It allows you to install a path as the
    ``base'' path that is used when no animation is running and the arrows
    specified for the animation will also be used for the base. All told, the
    ``correct'' way to specify the animation is the following (note that no
    static path is specified, any specified path would be overruled by the
    |base| path anyway):
    %
\begin{codeexample}[code only]
\draw :path = { 1s = "{(0,0) -- (1,0)}" base, 2s = "{(0,1) -- (1,0)}", arrows = -> };
\end{codeexample}

    Here is an example:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2},animation bb={(-0.1,-0.1) rectangle (1.1,1.1)}]
\tikz [very thick] {
  \node (node) at (-2,0)
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
  \draw :path = {
    0s = "{(0,0) to[out=90, in=180] (.5,1) to[out=0, in=90] (.5,.5)}" base,
    2s = "{(1,0) to[out=180, in=180] (.25,.5) to[out=0, in=180] (1,.5)}",
    arrows = <.<->, begin on = {click, of=node} }; }
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/animate/shorten < = \meta{dimension}}
\end{key}

\begin{key}{/tikz/animate/shorten > = \meta{dimension}}
    For animated paths, just as the key |arrows| has to be passed to the
    animation (to |:path|) instead of to the static path, the keys |shorten >|
    and |shorten <| also have to be passed to the |:path| key.
\end{key}


\subsubsection{Animating Transformations: Relative Transformations}

In order to animate the canvas transformation matrix, you do not animate an
attribute called ``|:transform|''. Rather, there are several attributes that
all manipulate the canvas transformation matrix in different ways. These keys,
taken in appropriate combination, allow you to achieve any particular canvas
transformation matrix. All keys that animate the transformation matrix always
accumulate.

Let us start with the ``standard'' attributes that are also available as keys
in \tikzname:

\begin{tikzanimateattribute}{scale, xscale, yscale}
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :scale = { 0s="1", 2s="0.2", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{rotate}
    The |rotate| key adds an animation of the rotation:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :rotate = { 0s="45", 2s="90", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
    Note that there is no |rotate around| attribute, but you can use the
    |origin| key to change the origin of the rotation.
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{xskew, yskew, xslant, yslant}
    The keys add an animation of the skew (given in degrees) or slant (given as
    in the |xslant| and |yslant| key):
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :xskew = { 0s="0", 2s="45", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :xslant = { 0s="-1", 2s="1", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{xshift, yshift}
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :shift = { 0s="{(0,0)}", 2s="{(5mm,-5mm)}",
                       begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}

\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :xshift = { 0s="0pt", 2s="5mm", begin on=click}
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    %
\end{tikzanimateattribute}

\begin{tikzanimateattribute}{shift}
    This |:shift| attribute can be animated in two ways. First, you can simply
    specify a sequence of coordinates in the same way as you would use the
    |shift| key in \tikzname:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz \node :shift = { 0s = "{(0,0)}", 2s = "{(5mm,-5mm)}",
                       begin on = click }
  [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}

    However, you can also specify the sequence of positions along which the
    shift should occur in a different way, namely by \emph{specifying a path
    along which the object should be moved.} This is often not only more
    natural to do, but also allows you to specify movements along curves.

    \begin{key}{/tikz/animate/options/along=\marg{path}\meta{|sloped| or
        |upright|}\opt{| in|\meta{time}}%
    }
        Use this key with a |:shift| (or a |:position|) to make \tikzname\
        shift the object by the coordinates along the \meta{path}. When this
        key is used, the values may no longer be coordinates, but must be
        fractions of the distance along the path. A value of |"0"| refers to
        the beginning of the path and |"1"| refers to the end:
        %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
  \draw (1,.5) circle [radius=1mm];
  \node :shift = {
            along = {(0,0) circle[radius=5mm]} upright,
            0s="0", 2s=".25", begin on=click }
    at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
    \end{key}

    Following the \meta{path}, which must be put in braces, you must either
    specify |upright| or |sloped|. In the first case, the to-be-animated object
    is moved along the path normally (and stays ``upright''), whereas when you
    use |sloped|, the object will be continuously rotated so that it always
    points along the path.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
  \draw (1,.5) circle [radius=1mm];
  \node :shift = {
            along = {(0,0) circle[radius=5mm]} sloped,
            0s="0", 2s=".25", begin on=click }
    at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}

    In most motion animations that use |along|, you will set the value for |0s|
    to |"0"| and the value for some specific \meta{time} to |"1"|. Because of
    this, you can add |in| \meta{time} after the path, to achieve exactly this
    effect.
\end{tikzanimateattribute}

For the above attributes, it is not immediately clear which coordinate system
should be used for the animation. That is, when you move an object 1cm ``to the
right'', where is ``the right''? By default, movements and transformations like
|:shift| or |:scale| are relative to the \emph{animation coordinate system,}
which defaults to the local coordinate system of the to-be-animated object.
Consider the following example:
%
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
  \node :rotate = { 0s="0", 2s="45", begin on=click}
    at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
Note how the node rotates around its center even though this center is at
position |(1,1)| in the picture's coordinate system. This is because |at (1,1)|
actually only does a shift of the coordinate system and the node is then drawn
at the origin of this shifted coordinate system. Since this shifted coordinate
system becomes the animation coordinate system, the rotation ``around the
origin'' is actually a rotation around the origin of the animation coordinate
system, which is at |(1,1)| in the picture's coordinate system.

Let us, by comparison, do a rotation of a scope surrounding the node where the
origin is not (yet) shifted:
%
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
  \scoped :rotate = { 0s="0", 2s="45", begin on={click, of next=n} }
    \node (n) at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
Now the rotation is really around the origin of the picture.

Most of the time the animation coordinate system will be setup in the way ``you
expect'', but you can modify it using the following keys:

\begin{key}{/tikz/animate/options/origin=\meta{coordinate}}
    Shifts the animation coordinate system by \meta{coordinate}. This has the
    effect that the ``origin'' for scalings and rotations gets shifted by this
    amount. In the following example, the point around which the rotation is
    done is the right border at |(2,1)| since the origin of the animation is at
    |(1,1)| relative to the picture's origin and the |origin| key shifts it one
    centimeter to the right.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
  \node :rotate = { 0s="0", 2s="45", begin on=click,
                    origin = {(1,0)}}
    at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/animate/options/transform=\meta{transformation keys}}
    While the |origin| key does only a shift, the |transform| key allows you to
    add an arbitrary transformation to the animation coordinate system using
    keys like |shift|, |rotate| or even |reset cm| and |cm|. In particular,
    |origin=|\meta{c} has the same effect as |transform| |=|
    |{shift=|\meta{c}|}|. Note that the transformation only influences the
    animation, not the object itself.

    As an example, when you say |transform={scale=2}|, an |:xshift| with a
    value of |"1cm"| will actually shift the object by 2cm. Similarly, after
    you say |transform={rotate=90,scale=2}|, the same |:xshift| of |"1cm"| will
    actually shift the object by 2cm upwards.

    Note that, internally, \tikzname\ has to invert the transformation matrix
    resulting from the \meta{transformation keys} (plus the original animation
    transformation matrix), which can by numerically instable when you use
    ill-conditioned transformations.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
  \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
                    transform = {rotate=-90} }
    at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
  \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
                    transform = {rotate=-45, scale=2} }
    at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
    %
\end{key}


\subsubsection{Animating Transformations: Positioning}

The attributes for specifying transformations and, in particular, the |:shift|
attribute are always expressed in the local animation coordinate system. This
makes it easy to ``shift around a node a little bit'', but makes it hard to
move a node ``from one position to another'' since coordinates need to be
expressed relative to the node's coordinate system, which leads to all sorts of
problems: Suppose you wish to have a node move from $(1,1)$ to $(2,1)$ and then
to $(2,0)$. Now, if the node has already been placed at $(1,1)$ in the usual
manner using |at|, then from the ``node's point of view'' you need to move the
node to $(0,0)$, $(1,0)$, and $(1,-1)$. To make matters worse, when you use
named coordinates as in
%
\begin{codeexample}[code only]
\coordinate(A) at (1,1);
\coordinate(B) at (2,1);
\coordinate(C) at (2,0);
\end{codeexample}
%
and then say that the movement should be from |(A)| to |(B)| to |(C)|, what
should you expect? On the one hand, |(A)| and |(1,1)| should normally be
interchangeable; on the other hand, |(A)| is a specific point in the plane, no
matter from which coordinate system we look at it. It turns out that \tikzname\
will stick to the second interpretation and actually turn |(A)| into |(0,0)|
when it is parsed in the local coordinate system of a node starting at |(A)| --
while |(1,1)| will stay the same.

Because of all these confusing effects, there is another attribute |:position|,
which is similar to a |:shift|, but the coordinates are not interpreted in the
local coordinate system of the node, but in the coordinate system that is in
force when the |animate| key is used. For a node, this is \emph{prior} to the
setup of the node's coordinate system and, thus, usually the picture's
coordinate system.

\begin{tikzanimateattribute}{position}
    Compare the two animations, one with |:position|, one with |:shift|.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
  \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
  \node :position = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
    at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
    %
    Compare this to a shift:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
  \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
  \node :shift = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
    at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
    %
    You can use the |along| key with |:position| in the same way as with
    |:shift|, which is especially useful for specifying that a node ``travels''
    between positions of the canvas:
    %
\begin{codeexample}[animation list={0.5,1,1.5,2}]
\tikz {
  \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
  \draw (1,1) circle [radius=1mm] (1.5,0) circle [radius=1mm];
  \node :position = {
             along = {(1,1) to[bend left] (1.5,0)} sloped in 2s,
             begin on = click }
         at (1,1) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
    %
\end{tikzanimateattribute}


\subsubsection{Animating Transformations: Views}
\label{section-animation-views}

The final method of changing the transformation matrix is to animate a
\emph{view}.

\begin{tikzanimateattribute}{view}
    A view is a canvas transformation that shifts and scales the canvas in such
    a way that a certain rectangle ``matches'' another rectangle: The idea is
    that you ``look through'' a ``window'' (the view) and ``see'' a certain
    area of the canvas. View animation do not allow you to do anything that
    cannot also be done using the |shift| and |scale| keys in combination, but
    it often much more natural to animate which area of a graphic you wish to
    see than to compute and animate a scaling and shift explicitly.

    In order to use a view, you first need to create a view, which is done
    using the |meet| or |slice| keys from the |views| library, see
    Section~\ref{section-library-views}. You can then animate the view using
    the |view| attribute. The values passed to the |entry| key follow the same
    syntax as the views in the view library (though you only animate the
    to-be-viewed rectangle).
    %
\begin{codeexample}[animation list={0.5,1,1.5,2},animation bb={(1.1,-0.9) rectangle (2.9,0.9)}]
\tikz [very thick] {
  \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};

  \draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
  \begin{scope}[view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)},
                animate = {myself:view = {
                    begin on = {click, of=node},
                    0s = "{(0,0) (2,2)}",
                    2s = "{(1,1) (1.5,1.5)}" }}]
    \draw [red] (10mm,10mm) rectangle (15mm,15mm);
    \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
  \end{scope}
}
\end{codeexample}
    %
\end{tikzanimateattribute}


\subsection{Controlling the Timeline}
\label{section-anim-timeline}

We can already specify timelines by giving a sequence of times in
non-decreasing order along with corresponding values. In this section we have a
look at further options that allow us to extend or control the timeline.


\subsubsection{Before and After the Timeline: Value Filling}

When you specify the timeline, you specify it for a certain interval
$[t_1,t_2]$. By default, outside this interval the animation has no effect on
the to-be-animated attribute. The following keys allows you to change this:

\begin{key}{/tikz/animate/base=\meta{options}}
    A ``base'' value is a value that is used for the attribute whenever the
    timeline is \emph{not} active:
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2,2.5}]
\tikz \node [fill = green, text = white] :fill =
    { 1s = "red", 2s = "blue", base = "orange", begin on = click }
  {Click me};
\end{codeexample}

    Syntactically, the |base| key works much like special time syntax: It sets
    up a local |sync| scope and executes the \meta{options} in it and creates
    an |entry|. However, instead of setting the |time| attribute to a time, it
    sets it to a special value that tells \tikzname\ that when the entry is
    created, the current \meta{value} should be used as the |base| value.

    This means that you can write |base = "orange"| as in the above example to
    set the base. However, you can also use the |base| key in other ways; most
    noticeably, you can use it \emph{after} some value:
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2,2.5}]
\tikz \node [fill = green, text = white] :fill =
    { 1s = {"red" = base}, 2s = "blue", begin on = click }
  {Click me};
\end{codeexample}

    Instead of using |base| as a key, you can also add |base| directly after
    the quotes of a value. This is particularly useful for setting up a base
    value that is also used in a timeline:
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2,2.5}]
\tikz \node [fill = green, text = white] :fill =
    { 1s = "red" base, 2s = "blue", begin on = click }
  {Click me};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/animate/options/forever}
    This key causes the timeline to continue ``forever'' after the last time
    with the last value. You can also think of this as having the animation
    ``freeze'' at the end.
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2,2.5}]
\tikz \node :fill = { 1s="red", 2s="blue", forever, begin on=click}
  [fill = green!50!black, text = white] {Click me};
\end{codeexample}
    %
\begin{codeexample}[animation list = {0.5,1,1.5,2,2.5}]
\tikz \node [fill = green!50!black, text = white]
    :fill = { 1s = "red", 2s = "blue", begin on = click }
  {Click me};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/animate/options/freeze}
    An alias for |forever|.
\end{key}


\subsubsection{Beginning and Ending Timelines}
\label{section-anim-begin-end}

The \meta{time} used with the first use of the |entry| key in a timeline is the
start time and the \meta{time} in the last |entry| key is the stop time.
However, this leaves open then question of when the whole timeline is to be
started: The moment the document is opened? When the page is displayed? When
the user scrolls to the to-be-animated object? When some other object is
clicked? The key |begin|, and also the key |end|, allow you to specify answers
to these questions.

\begin{key}{/tikz/animate/options/begin=\meta{time}}
    This key specifies when the ``moment |0s|'' should be relative to the
    moment when the current graphic is first displayed. You can use this key
    multiple times, in this case the timeline is restarted for each of the
    times specified (if it is already running, it will be reset). If no |begin|
    key is given at all, the effect is the same as if |begin=0s| had been
    specified.

    It is permissible to set \meta{time} to a negative value.

    Note that this key has no effect for snapshots.
\end{key}

\begin{key}{/tikz/animate/options/end=\meta{time}}
    This key will truncate the timeline so that it ends \meta{time} after the
    display of the graphic, provided the timeline begins before the specified
    end time. For instance, if you specify a timeline starting at 2\,s and
    ending at 5\,s and you set |begin| to 1\,s and |end| to 4\,s, the timeline
    will run, relative to the moment when the graphic is displayed from 3\,s to
    4\,s.
    %
\begin{codeexample}[]
\tikz \node [fill = green!50!black, text = white]
    :rotate = { 1s = "0", 5s = "90", begin = 2s, end = 4s }
  {Click me};
\end{codeexample}
    %
\end{key}

Instead of specifying the beginning of the timeline relative to the moment to
to-be-animated graphic is displayed, you can also set the ``moment |0s|'' to
the moment a specific \emph{event} happens using the following key:

\begin{key}{/tikz/animate/options/begin on=\meta{options}}
    The \meta{options} will be executed with the path |/pgf/animation/events|
    and will cause a new beginning to be added to the list of possible
    beginnings for the timeline (so the uses of this key accumulate). Each
    ``beginning'' is just another possible ``moment |0s|'' for the timeline.
    For instance, when the \meta{options} are set to |click|, then each time
    the graph is clicked a moment |0s| starts for the timeline.

    Most events are ``caused'' or ``happen to'' some object. For instance, the
    |click| event happens when you click on a certain object. In order to
    specify this object, use the following two keys inside the \meta{options}:
    |of| and |of next|. If neither of these keys are given, the to-be-animated
    object is used.

    \begin{key}{/pgf/animation/events/of=\meta{id}\opt{|.|\meta{type}}}
        This specifies a graphic object id in the same way as the |whom| key,
        also with an optional \meta{type}. This is the object that ``causes''
        the event to happen.

        Unlike the |whom| key, which always refers to a not-yet-existing
        object, this key always refers to an already existing object, namely to
        the most recent use of the \meta{id}. In the following example, the
        referenced object is the node with the label |2| since it is the most
        recently referenced node with \meta{id} |X|.
        %
\begin{codeexample}[width=3cm]
\tikz [very thick] {
  \node (X) at (1,1.2)  [fill = blue!20, draw = blue, circle] {1};
  \node (X) at (1,0.4)  [fill = orange!20, draw = orange, circle] {2};
  \node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}}
               [fill = red!20, draw = red, rectangle] {Anim};
  \node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3};
  \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
\end{codeexample}
    \end{key}

    \begin{key}{/pgf/animation/events/of next=\meta{id}\opt{|.|\meta{type}}}
        This key works like the |of| key, only it refers to a future (actually,
        the next) object with the given \meta{id}, not to a previous one. This,
        in the next example, the referenced node is the one with label |3|.
        %
\begin{codeexample}[width=3cm]
\tikz [very thick] {
  \node (X) at (1,1.2)  [fill = blue!20, draw = blue, circle] {1};
  \node (X) at (1,0.4)  [fill = blue!20, draw = blue, circle] {2};
  \node (node) :rotate = {
                 0s="0", 2s="90", begin on = {click, of next = X}}
               [fill = red!20, draw = red, rectangle] {Anim};
  \node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3};
  \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
\end{codeexample}
    \end{key}

    The following key allows you to specify the event that should cause the
    animation to start:
    %
    \begin{key}{/pgf/animation/events/event=\meta{event name}}
        Specifies the name of the event whose occurrence should start the
        timeline. Which events are supported depends on the device on which the
        animation is displayed, the output format (\textsc{svg} or some other
        format), and the setup of scripts, but here is a list of events
        supported by ``plain \textsc{svg}'': |click|, |focusin|, |focusout|,
        |mousedown|,  |mouseup|, |mouseover|, |mousemove|, |mouseout|, |begin|,
        |end|. However, the following keys make using these events simpler:
        %
        \begin{key}{/pgf/animate/events/click}
            This is a shorthand for |event=click|. This event gets triggered
            when the user clicks on the triggering object with a mouse (or
            something equivalent).
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}}
  [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/mouse down}
            Shorthand for |event=mousedown|. The event gets triggered when the
            user presses a mouse button down on the object.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}}
  [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/mouse up}
            Shorthand for |event=mouseup| and gets triggered, of course, when a
            pressed button is released on the object.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} }
  [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/mouse over}
            Shorthand for |event=mouseover|. The event gets triggered the
            moment the mouse cursor moves over the object.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} }
  [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/mouse move}
            Shorthand for |event=mousemove|. The event gets triggered lots of
            times, namely each time the mouse moves while being ``over'' the
            object.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} }
  [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/mouse out}
            Shorthand for |event=mouseout|. The opposite of |mouse over|:
            triggered when the mouse leaves the object.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} }
  [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/begin}
            Shorthand for |event=begin|. The ``begin'' refers to the beginning
            of another animation, namely the one referenced by |of| or
            |of whom|. This means that the current animation will begin when
            some other animation begins.
            %
\begin{codeexample}[width=2cm]
\tikz \node [animate = {
      myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}},
      myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim}
    },
    fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/end}
            Shorthand for |event=end|. Again, the ``end'' refers to the end of
            another animation, namely the one referenced by |of| or |of whom|.
            This means that the current animation will \emph{begin} when some
            other animation \emph{ends}.
            %
\begin{codeexample}[width=2cm]
\tikz \node [animate = {
    myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}},
    myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim }
  },
  fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
        \end{key}
        %
        \begin{key}{/pgf/animation/events/focus in}
            This is a shorthand for |event=focusin|. This event gets triggered
            when the graphic object gets the focus (this usually makes sense
            only for text input fields).
        \end{key}
        %
        \begin{key}{/pgf/animation/events/focus out}
            This is a shorthand for |event=focusout|.
        \end{key}
    \end{key}

    In addition to the events specified using the generic |event| key, there
    are two further events that take a parameter:
    %
    \begin{key}{/pgf/animation/events/repeat=\meta{number}}
        The event is triggered when a repeating animation has been repeated
        \meta{number} times.
        %
\begin{codeexample}[
  animation list={
    0.333/\frac{1}{3},0.666/\frac{2}{3},1,
    1.333/1\frac{1}{3},1.666/1\frac{2}{3},2,
    2.333/2\frac{1}{3},2.666/2\frac{2}{3},3,
    3.333/2\frac{1}{3},3.666/2\frac{2}{3},4}]
\tikz
  \node [animate = { myself: = {
    :rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim },
                begin snapshot = 2 },
    :xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}},
    fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
    \end{key}

    \begin{key}{/pgf/animation/events/key=\meta{key}}
        The event is triggered when the keyboard key \meta{key} has been
        pressed. For security reasons, a viewer may suppress this.
    \end{key}

    Having specified the event, you can also specify a delay relative to this
    event:

    \begin{key}{/pgf/animation/events/delay=\meta{time}}
        Specifies that the timeline should not start with the event, but,
        rather, be delayed by \meta{time}.
    \end{key}
\end{key}

When you use |begin on| to start an animation when a certain event is
triggered, it is not clear what should happen when the event is triggered
\emph{again}. Should this be ignored completely? Should it only be ignored
while the animation is running? The following key allows you to specify when
should happen:

\begin{key}{/tikz/animate/options/restart=\meta{choice} (default true)}
    You can set \meta{choice} to one of the following:
    %
    \begin{itemize}
        \item |true| means that the animation will restart each time the event
            is triggered. If the animation is already running, it will be reset
            to its beginning.
        \item |false| means that once the animation has started once, it will
            never be restarted.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90",
                        restart = false, begin on = {click}}
    [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
            %
        \item |never| means the same as |false|.
        \item |when not active| means that the animation will restart when the
            event is triggered, but \emph{not} while the animation is running.
            %
\begin{codeexample}[width=2cm]
\tikz \node :rotate = { 0s="0", 2s="90",
                        restart = when not active, begin on = {click}}
    [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
    \end{itemize}
\end{key}

Just like |begin on| specifies when a timeline begins relative to some event,
the |end on| allows you to stop is early when some event happens:

\begin{key}{/tikz/animate/options/end on=\meta{options}}
    Works exactly like |begin on|, one possible end of the timeline is
    specified using the \meta{options}.
\end{key}


\subsubsection{Repeating Timelines and Accumulation}

\begin{key}{/tikz/animate/options/repeats=\meta{specification}}
    Use this key to specify that the timeline animation should repeat at the
    end. The \meta{specification} must consist of two parts, each of which may
    be empty. The first part is one of the following:
    %
    \begin{itemize}
        \item Empty, in which case the timeline repeats forever.
            %
\begin{codeexample}[animation list={1,2,3,4,5}]
\tikz \node :rotate = { 0s = "0", 2s = "90",
                        repeats, begin on = click }
    [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
            %
        \item A \meta{number} (like |2| or |3.25|), in which case the timeline
            repeats \meta{number} times.
            %
\begin{codeexample}[animation list={1,2,3,4,5}]
\tikz \node :rotate = { 0s = "0", 2s = "90",
                        repeats = 1.75, begin on = click }
    [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
            %
        \item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
            which case the timeline repeats however often necessary so that it
            stops exactly after \meta{time}.
            %
\begin{codeexample}[animation list={1,2,3,4,5}]
\tikz \node :rotate = { 0s = "0", 2s = "90",
                        repeats = for 3.5s, begin on = click }
    [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    \end{itemize}
    %
    The second part of the specification must be one of the following:
    %
    \begin{itemize}
        \item Empty, in which case each time the timeline is restarted, the
            attribute's value undergoes the same series of values it did
            previously.
        \item The text |accumulating|. This has the effect that each time the
            timeline is restarted, the last values specified by the timeline is
            \emph{added} to the value from the previous iteration(s). A typical
            example is an animation that shifts a scope by, say, 1\,cm over a
            time of 1\,s. Now, if you repeat this five times, normally the
            scope will shift 1\,cm for 1\,s then ``jump back'', shift again,
            jump back, and so on for five times. In contrast, when the repeats
            are accumulating, the scope will move by 5\,cm over 5\,s in total.
            %
\begin{codeexample}[animation list={1,2,3,4,5}]
\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
                        repeats = accumulating }
    [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
            %
\begin{codeexample}[animation list={1,2,3,4,5}]
\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
                        repeats = for 4s accumulating }
    [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
    \end{itemize}
\end{key}

\begin{key}{/tikz/animate/options/repeat=\meta{specification}}
    An alias for |repeats|.
\end{key}


\subsubsection{Smoothing and Jumping Timelines}
\label{section-anim-smooth}

Your specification of the timeline will consist of a sequence of times along
with values that the attribute should have at these ``key times''. Between
these key times, the attribute's value needs to be interpolated.

Suppose that an animation is supposed to interpolate a attribute's value
between the two values |50| and |100| over a time of 10\,s. The simplest way of
doing so is to do a linear interpolation, where the value as, say, 1\,s is 55,
at 2\,s it is 60, and so on. Unfortunately, the linear interpolation does not
``look'' nice in many cases since the acceleration of a linear interpolation is
zero  during the animation, but infinite at the beginning and at the end; which
looks ``jerky''.

To avoid this, you can specify that the time--attribute curve should not be a
straight line, but rather a curve. You specify this curve using a spline. The
most logical ``coordinate rectangle'' used for this spline in our example would
be |(0s,50)| and |(10s,100)| and we would like to specify something like
%
\begin{codeexample}[code only]
  (0s,50) .. controls (5s,50) and (9s,100) .. (10s,100)
\end{codeexample}
%
This would result in a time--attribute curve where the attribute at |50|
changes slowly at 0\,s and also arrives slowly at |100| at 10\,s, but speeds up
between these values.

We call the first control point |(5s,50)| the ``exit control'' and call
|(9s,100)| the ``entry control'': The first control dictates how quickly or
slowly a time point is left, the second dictates how quickly or slowly we enter
the next one.

The control points are, however, not specified in the coordinate system
indicated above. Rather, the rectangle |(0s,50)| to |(10s, 100)| gets
normalized to |(0,0)| to |(1,1)|. The control point |(5s,50)| would thus become
|(0.5,0)| and |(9s,100)| becomes |(0.9,1)|.

\begin{key}{/tikz/animate/options/exit control=\marg{time fraction}\marg{value fraction}}
    Specifies an exit control using two values as above. The spline from above
    would be specified as follows:
    %
\begin{codeexample}[code only]
exit control={0.5}{0},
entry control={0.9}{1},
0s = "50",
10s = "100"
\end{codeexample}

    Note that the curve specified using exit and entry controls must be
    ``well-behaved'' in the sense that exactly one value must be specified for
    each point in time in the time interval.

    In the next three example, we first specify a ``smooth'' exit from the
    start position, then a smooth arrival at the end position, and, finally
    both.
    %
\begin{codeexample}[animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}}]
\tikz {
  \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
  \node :yshift = { begin on = click,
                    0s = { exit control = {1}{0}, "0cm" },
                    1s = "-5mm",
                    2s = "-10mm" }
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}

\begin{codeexample}[animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}}]
\tikz {
  \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
  \node :yshift = { begin on = click,
                    0s = "0cm",
                    1s = "-5mm",
                    2s = { entry control = {0}{1}, "-10mm" } }
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}

\begin{codeexample}[animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}}]
\tikz {
  \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
  \node :yshift = { begin on = click,
                    0s = { exit control = {1}{0}, "0cm" },
                    1s = "-5mm",
                    2s = { entry control = {0}{1}, "-10mm" } }
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/animate/options/entry control=\marg{time fraction}\marg{value fraction}}
    Works like |exit control|.
\end{key}

\begin{key}{/tikz/animate/options/ease in=\marg{fraction} (default 0.5)}
    A shorthand for |entry control={1-|\meta{fraction}|}{1}|.
\end{key}

\begin{key}{/tikz/animate/options/ease out=\marg{fraction} (default 0.5)}
    A shorthand for |exit control={|\meta{fraction}|}{1}|.
\end{key}

\begin{key}{/tikz/animate/options/ease=\marg{fraction} (default 0.5)}
    A shorthand for |ease in=|\meta{fraction}|, ease out=|\meta{fraction}.

    Note that since for the first time the entry control is ignored and,
    similarly, for the last time the exit control is ignored, using the |ease|
    key with an animation having only two times is particularly easy, since we
    only need to set |ease| once:
    %
\begin{codeexample}[animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}}]
\tikz {
  \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
  \node :yshift = { begin on = click, ease, 0s = "0cm", 2s = "-10mm" }
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
    %
\end{key}

The opposite of having a smooth curve between two values, is to have a ``jump''
from one value to the next. There are two keys for this:

\begin{key}{/tikz/animate/options/stay}
    Specifies that inside the time interval the value ``stays put'' at the
    first value till the end of the interval, where it will jump to the second
    value. This is similar to an exit control where the curve is ``infinitely
    flat''.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2,2.5}]
\tikz {
  \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
  \node :yshift = { begin on = click,
                    0s = "0cm",
                    1s = {stay, "-5mm"},
                    2s = "-10mm" }
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/animate/options/jump}
    Works like the |stay| key, but will cause the value to ``jump to'' the new
    value right at the beginning of the time interval. It is similar to an
    entry control specifying a ``flat'' curve.
    %
\begin{codeexample}[animation list={0.5,1,1.5,2,2.5}]
\tikz {
  \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
  \node :yshift = { begin on = click,
                    0s = "0cm",
                    1s = {jump, "-5mm"},
                    2s = "-10mm" }
    [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
    %
\end{key}


\subsection{Snapshots}
\label{section-anim-snap}

Snapshots are a way of taking a ``photographic snapshot'' of an animation at a
certain time and then insert these into \textsc{pdf} files (or, for that
matter, Postscript files or files in any other format, including \textsc{svg}):
You specify a time like |2s| and then \tikzname\ will compute what the
animation ``would look like after 2s'' and insert the necessary graphics
command for rendering the graphic objects in the correct way. Since this
computation is done by \tikzname\ and since only ``normal'' graphics command
are inserted into the output, snapshots work with all output formats.

Apart from providing a fallback for \textsc{pdf}, snapshots are very useful by
themselves: They make it easy to ``show'' how an animation unfolds on paper.
For this, you simply typeset the same picture with the same animation several
times (using a simple |\foreach| loop), but each time you set a different
snapshot time. This will result in a sequence of pictures that depict the
animation at different points in time and which can then be inserted alongside
each other into the printed document. This approach has been used with the
examples of animations in this manual.
%
\begin{codeexample}[]
\foreach \t in {0.5, 1, 1.5, 2}
  \tikz [make snapshot of = \t]
    \fill :fill = {0s="black", 2s="red"} (0,0) circle [radius = 5mm];
\end{codeexample}

Creating snapshots is done using the following key:

\begin{key}{/tikz/make snapshot of=\meta{time}}
    When this key is used in a \TeX\ scope, animation commands given in the
    scope do not add animation code to the output. Instead, \tikzname\ computes
    the values the attributes of the animation would have at the specified
    \meta{time} and inserts the necessary system layer command to set the
    attribute to the computed values (some care has been taken to make this
    computation match the computations done by viewer applications as best as
    possible).
    %
\begin{codeexample}[]
\tikz [make snapshot of = 1s] {
  \fill :fill = { 0s = "black", 2s = "white" } (0,0) rectangle ++(1,1);
  \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
}
\end{codeexample}

    The moment \meta{time} is best thought of as \meta{time} seconds after the
    ``moment zero'' where all timelines start by default. Now, ``real''
    animation may start at different time through user interaction, which
    clearly makes no sense for snapshots. Nevertheless, you will sometimes wish
    to have more control over when a timeline starts for the purposes of taking
    snapshots. You can use the following key for this:

    \begin{key}{/tikz/animate/options/begin snapshot=\meta{start time}}
        Use this key on a timeline to specify that, only for purposes of taking
        snapshots, the timeline starts at \meta{start time} rather than at
        ``moment zero''. (Think of this as saying that the animation starts
        when a virtual user clicks on the animation and this click occurs
        \meta{start time} seconds after the general ``moment zero'', causing
        the animation to ``lag behind'' by this amount of time.)
        Computationally, for the timeline the \meta{start time} is subtracted
        from the snapshot's \meta{time} when the value needs to be determined:
        %
\begin{codeexample}[]
\tikz [make snapshot of = 1s] {
  \fill :fill = { 0s = "black", 2s = "white",
                  begin snapshot = 1s }        (0,0) rectangle ++(1,1);
  \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
}
\end{codeexample}
    \end{key}

    The computations of the values the animation ``would have'' are done
    entirely by \tikzname, which has the big advantage is that no support from
    the viewer application or the output format is needed -- snapshots work
    with all output formats, not just with \textsc{svg}. However, computations
    done by \tikzname\ are not always very precise and can be slow because of
    \TeX's limitations. In addition, there are some further limitations when it
    comes to \tikzname's computation of snapshot values:
    %
    \begin{itemize}
        \item As mentioned above, except for |begin snapshot|, other commands
            for specifying the beginning or end of a timeline based on user
            interaction make no sense for timelines: The keys |begin|,
            |begin on|, |end|, and |end on| are silently ignored.
        \item The value |current value| for a value is forbidden since this
            value is almost impossible to compute by \tikzname.
        \item Accumulating repeats of a motion are (currently) not supported,
            but should not rely on this.
    \end{itemize}

    When \meta{time} is empty, ``snapshot taking'' is switched off and
    animation commands are inserted once more.
\end{key}

\begin{key}{/tikz/make snapshot after=\meta{time}}
    Works exactly like |make snapshot of|, only the \meta{time} is interpreted
    as $\meta{time} + \epsilon$. This only makes a difference at the end of a
    timeline and when there are two or more values specified for the same time:
    When there are several values specified for time~$t$, a normal snapshot for
    time~$t$ uses the first value given for the attribute. In contrast, this
    command would use the last one given. Similarly, when an animation timeline
    ends at time $t$, a normal snapshot of time $t$ would use the last value of
    the timeline, while this key would not apply the animation at all (it has
    already ended at time $t + \epsilon$).
    %
\begin{codeexample}[]
\tikz [make snapshot of = 2s]
  \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
\tikz [make snapshot after = 2s]
  \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/make snapshot if necessary=\meta{time} (default 0s)}
    This key makes a snapshot of \meta{time} only when the output format does
    not provide support for animations; if the output format supports
    animations (like \textsc{svg}), then the command has no effect and
    animations are created normally.

    This manual is typeset with the following being set once are for all in
    preamble:
    %
\begin{codeexample}[code only]
\tikzset{make snapshot if necessary}
\end{codeexample}

    Because of this setting, in the \textsc{pdf} version of this document, all
    animations are shown at the value they would have at moment~$0s$. In
    contrast, in the \textsc{svg} version, the animations are created normally.

    In both versions, the smaller pictures showing how the animation proceeds
    over time are created using |make snapshot of| for the indicated times.
\end{key}


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: