TikZ and PGF Manual

TikZ

26 Animations¶

26.1 Introduction¶

An animation changes the appearance of some part of a graphic over time. The archetypical animation is, of course, a movement of some part of a picture, but a change of, say, the opacity of a path is also an animation. TikZ allows you to specify such animations using special keys and notations.

Adding an animation to a TikZ picture is done as follows:

• 1. Before or in the options of the to-be-animated object you specify the object together with an attribute that you wish to animate. Attributes are things like the fill color or the line width or the position of the object.

• 2. You specify when this attribute should have which values using a so-called timeline. This is just a curve that specifies for each point in time which value the attribute should have.

• 3. 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.

As a simple example, let us move a circle within thirty seconds by three centimeters to the left:

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.

26.1.1 Animations Change Attributes¶

Before we plunge into the details of how animations are specified, it is important to understand what TikZ actually does when creating an animation: It does 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 TikZ 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 svg format is a format for which this is possible, the popular pdf format is not. For the svg format, there are actually different possible ways of “formulating” the animations (using smil or css or JavaScript) and they have different advantages and disadvantages.

To make a long story short: TikZ animations currently work only with svg output (and use the 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 pdf will ever support animations in a useful way.

It is, however, possible to create “snapshots” of an animation and insert these into pdf files (or any other kind of file including svg files), see Section 26.6 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.

26.1.2 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:

• 1. As pointed out earlier, animations require a specific output format (currently only svg is supported).

• 2. 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 line as whole). You must “cheat” and introduce some “virtual” nodes, which leads to rather complex and bloated code.

• 3. Animations 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.

26.1.3 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:

• 1. 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).

• 2. 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.

• 3. View boxes, which can only be created using the views library.

• 4. 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.

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 (⟨node name⟩) syntax to name the node. Recall that you must always specify the animation 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 26.3.1, but you can also use the object key to choose them directly, see Section 26.2.3.

26.1.4 Concepts: Attributes¶

In addition to the to-be-animated object, you must also choose an 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 (svg), but this is not always the case. For instance, for a node, TikZ differentiates between the fill color, the draw (stroke) color, and the text color, while svg treats the text color are a special case of the fill color. TikZ will do some internal mappings to ensure that you can animate the “TikZ 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 26.3.1, but you could also set them directly using the attribute key see Section 26.2.4.

26.1.5 Concepts: Timelines¶

Once an object and an attribute have been chosen, a 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 start and an 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 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 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.

26.2 Creating an Animation¶

26.2.1 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.

26.2.2 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:

• • object for selecting the object,

• • attribute for selecting the attribute,

• • id for selecting the timeline id (explained in Section 26.2.5),

• • time for selecting a time, and

• • value for selecting a value.

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:

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.

26.2.3 Specifying Objects¶

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 26.3.1.

26.2.4 Specifying Attributes¶

26.2.5 Specifying IDs¶

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”:

• 1. 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”.)

• 2. If there are several active animations, the one that has started last is used and its value is used.

• 3. If there are several active animations that have started at the same time, the one that comes last in the code is used.

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).

26.2.6 Specifying Times¶

26.2.7 Values¶

26.2.8 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:

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 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:

26.3 Syntactic Simplifications¶

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.

26.3.1 The Colon Syntax I: Specifying Objects and Attributes¶

Inside the ⟨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:

⟨object name(s)⟩:⟨attribute(s)⟩ ={⟨options⟩}

or

⟨object name(s)⟩:⟨attribute(s)⟩_⟨id⟩ ={⟨options⟩}

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 ⟨id⟩, which identifies the timeline (see Section 26.2.5).

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:

sync = { object = ⟨objects⟩, attribute = ⟨attribute⟩, id = ⟨id⟩, ⟨options⟩, entry }

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 ⟨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 ⟨options⟩ will get added to the timeline.

Let us now have a look at some examples. First, we set the ⟨object name⟩ to mynode and othernode and the ⟨attribute⟩ to opacity and to color:

Next, we do the same, but “in two steps”: First, we set the object to mynode, but leave the attribute open and, then, set the attribute, but leave the object:

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:

Finally, if several objects should get the exact same values, we can also group them:

As mentioned earlier, all references to objects will be interpreted to future objects, never to objects already created. Furthermore, also as mentioned earlier, TikZ allows you to specify myself as ⟨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:

The list of permissible attributes is given in Section 26.4.

26.3.2 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

in the options of a node or a scope. For this reason, TikZ allows you to use a special syntax with nodes and scopes:

• 1. In a ⟨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

  :some attribute = {⟨options⟩}

  and this will have the same effect as if you had written

  [animate = { myself: = { :some attribute = {⟨options⟩}}}]

  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.

• 2. For the commands \tikz, \scoped and the environments {tikzpicture} and {scope}, when they are followed immediately by

  :some attribute = {⟨options⟩}

  then

  animate = { myself: = { :some attribute = {⟨options⟩}}}

  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.

Let us have a look at some examples. First, we use the syntax to set the fill opacity of a node:

Next, we additionally rotate the node:

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:

We can also use the special syntax with the \tikz command itself:

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

26.3.3 The Time Syntax: Specifying Times¶

For each object–attribute pair you must specify the 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:

⟨time⟩ ="⟨value⟩"

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:

⟨time⟩ = ⟨options⟩

Here, ⟨time⟩ is a text that “looks like a time”, which means that:

• 1. It is not a key and does not contain a colon and does not start with a quotation mark.

• 2. It starts with a digit, a plus or minus sing, a dot, or a parenthesis.

If these two things are the case, the above code is transformed to the following call:

sync = {time = ⟨time⟩, ⟨options⟩, entry}

26.3.4 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 xml). This quote syntax is as follows:

"⟨value⟩" base = ⟨options⟩

This syntax is triggered whenever a key starts with a quotation mark⁵ (and note that when the ⟨value⟩ contains a comma, you have to surround it by curly braces inside the quotation marks as in "{(1,1)}"). Then, the following code is executed:

sync = {value = ⟨value⟩, ⟨options⟩, entry}

This means that when you write 1s = "red", what actually happens is that TikZ executes the following:

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:

base = {value = ⟨value⟩}

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.

26.3.5 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:

• 1. 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:

  copy
animate = {
obj:color = {
0s = "red",
2s = "blue",
1s later = "green",
1s later = "green!50!black",
10s = "black"
}
}


  When you specify timelines for several attributes of the same object, you can group these together:

  copy
animate = {
obj: = {
:color = { 0s = "red", 2s = "green" },
:opacity = { 0s = "1", 2s = "0" }
}
}


  In this way of specifying animations the “object comes first”.

• 2. Alternatively, you can also group the animation by time and, for each “moment” (known as keyframes) you specify which values the attributes of the object(s) have:

  copy
animate = {
0s = {
obj:color = "red",
obj:opacity = "1"
},
2s = {
obj:color = "green",
obj:opacity = "0"
}
}


  Naturally, in this case it would have been better to “move the object outside”:

  copy
animate = {
obj: = {
0s = {
:color = "red",
:opacity = "1"
},
2s = {
:color = "green",
:opacity = "0"
}
}
}


  When there are several objects involved, we can mix all of these approaches:

  copy
animate = {
0s = {
obj: = {
:color = "red",
:opacity = "1"
},
main node: = {
:color = "black"
}
},
2s = {
obj: = {
:color = "green",
:opacity = "0"
},
main node: = {
:color = "white"
}
}
}


26.4 The Attributes That Can Be Animated¶

The following ⟨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):

• • :dash phase

• • :dash pattern

• • :dash

• • :draw opacity

• • :draw

• • :fill opacity

• • :fill

• • :line width

• • :opacity

• • :position

• • :path

• • :rotate

• • :scale

• • :stage

• • :text opacity

• • :text

• • :translate

• • :view

• • :visible

• • :xscale

• • :xshift

• • :xskew

• • :xslant

• • :yscale

• • :yshift

• • :yskew

• • :yslant

These attributes are detailed in the following sections, but here is a quick overview of those that do not have a TikZ key of the same name (and which thus do not just animate the attribute set using this key):

• • :shift allows you to add an animated shifting of the canvas, just like TikZ’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.

• • :position works similar to :shift, only the coordinates are not relative movements (no “shifts”), but refer to “absolute positions” in the picture.

• • :path allows you to animate a path (it will morph). The “values” are now paths themselves.

• • :view allows you to animate the view box of a view.

• • :visible decides whether an object is visible at all.

• • :stage is identical to :visible, but when the object is not animated, it will be hidden by default.

26.4.1 Animating Color, Opacity, and Visibility¶

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.

26.4.2 Animating Paths and their Rendering¶

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:

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

26.4.3 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 TikZ:

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 animation coordinate system, which defaults to the local coordinate system of the to-be-animated object. Consider the following example:

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:

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:

26.4.4 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

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 TikZ 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 prior to the setup of the node’s coordinate system and, thus, usually the picture’s coordinate system.

26.4.5 Animating Transformations: Views¶

The final method of changing the transformation matrix is to animate a view.

26.5 Controlling the 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.

26.5.1 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:

26.5.2 Beginning and Ending Timelines¶

The ⟨time⟩ used with the first use of the entry key in a timeline is the start time and the ⟨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.

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 event happens using the following 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:

26.5.3 Repeating Timelines and Accumulation¶

26.5.4 Smoothing and Jumping Timelines¶

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

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).

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: