The TikZ and PGF Packages
Manual for version 3.1.10

The system layer animation subsystem follows the following philosophy: An animation always concerns an attribute of a graphic object. A timeline specifies how the attribute changes its value over time. Finally, a set of keys configures the animation as a whole like whether the timeline repeats or a event that triggers the start of the animation. The four parts of an animation, namely the attribute, the graphic object, the timeline, and the keys, are specified in different ways:

• 1. You choose the attribute using the system layer command \pgfsysanimate.

• 2. The graphic object whose attribute is to be animated is always specified by naming the ID of the graphic object before this object is created, see Section 120.13. (However, in the context of TikZ, it suffices that the animation is given in the object’s options since these are executed before the actual object is created).

• 3. The timeline is specified using the commands \pgfsysanimkeytime, which specifies a time in seconds, and \pgfsys@animation@val..., which specify a value at this particular time. The timeline specifies for a sequence of times the values the attribute will have at these times. In between these key times, the value is interpolated.

• 4. The animation keys are specified by commands starting \pgfsys@animation@... and have the following effect: They set some property (like, say, whether the animation repeats or whether its effect is additive) to a given value for the current TeX scope, but do not create any animations. Rather, when \pgfsysanimate is called, a snapshot of the current values of all animation keys is taken and added to this animation of the attribute.

  When you set an animation key to a value, this will replace the value previously stored for the key (all keys are empty by default at the beginning).

  Note that animation keys are local to TeX scopes, not graphics scopes; indeed, they have little to do with the settings of the graphics scope other than the fact that a graphic scope is also a TeX scope and thereby influence the values of these keys.

A typical example of how all of this works is the following:

As a real-life example, consider the following definitions, which will be used in many examples in the rest of this section: Both take three parameters: The pgf/TikZ name of a to-be animated object, a type (relevant for objects that have subtypes or parts), and some code for triggering the actual animation. The animation will always start when the button is clicked. The second macro sets up things in such a way that the animation will last two seconds, while the first leaves the timing open.

Now the example, where the circle will disappear, when clicked:

Use this command in a scope prior to calling any other commands documented in this section concerning the configuration of animations. In this case, all uses of \pgfsysanimate inside the TeX scope no longer insert an animation into the output file. Instead, a “snapshot” is inserted of what the animation “would like at time ⟨time⟩”. For instance, if an animation inserts a movement of an object by 4cm over a time of 2s and you take a snapshot with \(\meta {time} = 2\mathrm s\), you get a picture in which the object is moved by 1cm.

A lot of care has been taken to make the output produced by the snapshot be as close as possible as what the animation really would look like at time ⟨time⟩, but note the following restrictions:

• 1. Interactive events of all kinds (like click or mouseover) make little sense for snapshots, which are created once and for all during the typesetting of the document. For this reason, all events are ignored for snapshots (even sync bases, and begin and end events, which might make some sense also in a snapshot setting).

  However, there is one command which helps you with “simulating” the effect of events:

  \pgfsysanimkeysnapshotstart{⟨time offset⟩} ¶

  This command specifies that for the current animation the “moment 0s” of the timeline is at ⟨time offset⟩. Thus, it works like \pgfsysanimkeyoffset, only the offset is now solely for the snapshot timeline. It has no effect on the actual animation.

• 2. The command \pgfsysanimvalcurrent cannot be used with snapshots since pgf has no chance of computing the correct current value. You always have to specify the start value explicitly.

• 3. The computation of time splines (entry and exit splines) and the accumulation of values after a large number of repeats may not be numerically stable.

Works like the previous command, only the “moment” that ⟨time⟩ refers to is conceptually \(\meta {time} + \epsilon \): When timeline specifies several values for ⟨time⟩, this command will select the last value at ⟨time⟩, while \pgfsnapshot will select the first value at ⟨time⟩. Similarly, when a timeline ends at ⟨time⟩, \pgfsnapshot will select the last value of the timeline while \pgfsnapshotafter will not apply the animation any more.

Adds an animation of the opacity to the graphic object specified using \pgfsysanimkeywhom. If the driver supports this, this is a bit different from animating the fill and stroke opacities individually: Paths are treated as transparency groups for this key. Typically, “this is what you want”.

Specify values with \pgfsysanimvalscalar.

Adds an animation of only the opacity of fill operations.

Specify values with \pgfsysanimvalscalar.

Adds an animation of only the opacity of draw (stroke) operations.

Specify values with \pgfsysanimvalscalar.

Adds an animation of the “visibility”.

Specify values with \pgfsysanimvaltext. However, only two values are allowed: visible and hidden.

Adds an animation of the stroke color.

Specify values with \pgfsysanimvalcolorrgb and friends.

Adds an animation of the fill color.

Specify values with \pgfsysanimvalcolorrgb and friends.

Adds an animation of the path itself. That means that the path will morph its form from one path to another. When morphing a path, all “values”, which are the paths, must consist of the exact same path construction commands; they may only differ with respect to the numbers used in these descriptions.

Specify values with \pgfsysanimvalpath.

You can attach arrow tips to paths that are animated and these arrow tips will correctly “rotate and move along” with the path’s end points if you take the following points into considerations:

• • Arrow tips that “rotate and move along” with a path must be specified using a special animation command, see below. The normal arrow tips added to a path would not be animated automatically and, indeed, if you add arrow tips to a path using \pgfsetarrows and then animate the path, you will get an error message.

• • Internally, the arrow tips that “rotate and move along” are drawn using so-called markers. These are little graphic objects that can be added to the start and end of paths and that are automatically rotated and move along with the path.

  In principle, the rendering rules used by svg for markers are the same as for normal arrow tips: The markers are rotated and moved so that the point along a tangent of the path at the start or end of the path. However, when it comes to special cases such as a path with multiple segments, a path with degenerate segments, a closed path, and so on, the rules used by for instance svg may differ from the placement that pgf will compute.

  Thus, it is best to add arrow tips only to “normal” paths consisting of a single open path segment whose ends can be shortened a bit without causing degeneration.

• • When an arrow tip is added to a path, the path must typically be shortened a bit so that the tip of the arrow ends where the path would usually end. This shortening is not done by the system layer for to-be-animated paths; you must compute and then animate these shortened paths yourself. (However, the basic layer animation module will do this for you, so you only have to worry about this when you use the system layer directly.)

Let us now have a look at how we add arrow tip markers:

Adds an animation of the line width.

Specify values with \pgfsysanimvaldimension.

Adds an animation of the dash phase and pattern (like \pgfsys@setdash).

Specify values with \pgfsysanimvaldash.

In order to animate the canvas, you specify that, for instance, the canvas should be shifted over, say, one second by 2cm from left to right. In order to specify this, you specify that an additional shift should be added to the canvas transformation matrix that starts out as \((0,0)\) and ends at \((2\,\mathrm {cm},0)\). However, it is not immediately clear what “to the right” or \((2\,\mathrm {cm},0)\) actually means: “Right” relative to the paper? “Right” relative to the coordinate system at the point when the animation is created? “Right” relative to the object’s local coordinate system?

Using this command you can specify the coordinate system relative to which all canvas animations are specified. In detail, when you add an animation \(a\) of the canvas of an object foo, the following happens:

• 1. We start with the canvas transformation matrix that is installed when the object starts. More precisely, this is the canvas transformation matrix that is in force when the command \pgfsys@begin@idscope is called for the object. The canvas transformation matrix that is in force when the animation is created (which is typically “way before” the object is created and may even be in a totally different graphics scope) is irrelevant for the animation.

• 2. Now, when the object is created, the code ⟨pre⟩ is executed. It should call \pgfsys@transformcm at most once. This canvas transformation is added to the object’s canvas transformation.

• 3. Now, the animation \(a\) of the canvas is relative to the resulting canvas transformation. That means, when the animation shifts the object “to the right” the animation will actually be along the current direction of “right” in the canvas transformation resulting from the two transformations above.

• 4. Finally, at the point of creation of the to-be-animation object the code ⟨post⟩ is executed. Again, the code should call \pgfsys@transformcm at most once. The resulting transformation is also added to the object’s canvas transformation, but does not influence the animation.

The net effect of the above is that, normally, you use the ⟨pre⟩ code to setup a transformation matrix relative to which you wish to perform your animation and, normally, you use ⟨post⟩ to undo this transformation (using the inverted matrix) to ensure that when no animation is in force, the object is placed at the same position as if no animation were used.

Let us now have a look at some examples. We use the following macro, which takes a pre and a post code and animates a red ball over 1cm to the right in two seconds and rotates the blue ball over 90\(^\circ \) around the origin. The ball is placed at \((1,0)\).

Adds an (additional) translate animation. Effectively, this causes the group to be shifted to different positions.

Specify values with \pgfsysanimvaltranslate.

Adds an animation of the scaling relative to the origin. This causes a scaling of the canvas, including fonts and line widths.

Specify values with \pgfsysanimvalscale.

Adds a rotation animation around the origin.

Specify values with \pgfsysanimvalscalar.

Adds an animation of a skewing of the canvas along the \(x\)-axis. Unlike the slant options of TikZ, the skew is given in degrees.

Specify values with \pgfsysanimvalscalar.

Adds an animation of a skewing of the canvas along the \(y\)-axis.

Specify values with \pgfsysanimvalscalar.

Works a bit like \pgfsysanimvaltranslate: It also adds an animated shift transformation of the canvas. However, instead of specifying some shift coordinates as values, you now specify a whole path (which may include curves). The effect is that an animated translate transformation for the different points on this path gets installed. Furthermore, if you use \pgfsysanimkeyrotatealong, an additional adaptive rotation transformation will be added so that the animated graphic scope “points along” the path.

You specify the path along which you wish to move objects along using \pgfsysanimkeymovealong. You use the timeline to specify how far the object gets moved along this path using scalar values where 0 is the beginning of the path and 1 is the end. Thus, setting the timeline to the scalar value of 0 at time \(t_0\) and to 1 at time \(t_1\) will cause the object o move along the complete path between times \(t_0\) and \(t_1\).

Specify values with \pgfsysanimvalscalar.

Adds an animation of the view box. The graphic scope to which this animation is added must have been created using \pgfsys@viewboxmeet or \pgfsys@viewboxslice; adding it to other scopes has no effect. Note that this command does not change or animate the scope’s transformation matrix – it only animates the “what we see through the view box”.

Specify values with \pgfsysanimvalviewbox.

Sets the target of the animation. The {⟨id⟩} must previously have been created using \pgfsys@new@id, {⟨type⟩} must be a type (the empty type is also allowed). See Section 120.13 for details on ids and types.

The ⟨time⟩ is a number representing seconds (so 0.5 means 500 ms).

The spline between a time–value pair and the next is specified using the four parameters following the time. The first two of these specify the second control point of the interval preceding the time–value pair (called the “entry” control point), the last two parameters specify the first control point of the interval following the pair (called the “exit” control point). Consider for instance, the following calls:

This will create (at least) the time interval \([10\,\mathrm s,15\,\mathrm s]\) and the control points for this interval will be \((0.3,0.4)\) and \((0.5,0.6)\).

Control points are specified in a different “coordinate” system from the time–value pairs themselves: While the time–value pairs are specified using a number representing seconds and a value using some special commands, the control points are specified as numbers between \(0\) and \(1\), each time representing a fraction of the time interval or the value interval. In the example, the time interval is \([10\,\mathrm s,15\,\mathrm s]\) and the value interval is \([100,200]\). This means that a control point of \((0.3,0.4)\) actually refers to the time–value \((11.5\,\mathrm s,140)\). The “time–value curve” in the interval thus “(10s,100) .. controls (11.5s,140) and (12.5s,160) .. (15s,200)”.

Note that by setting the control points always to \((1,1)\) and \((0,0)\) you get a linear interpolation between time–value pairs.

Two special cases are the following: When the two last parameters, the exit spline, take the special values stay and 0, the attribute’s value “stays” until the next value for the next time (it then “jumps” to the next value then). This corresponds, roughly, to an “infinite” ⟨exit spline control x⟩. Similarly, when the entry spline parameters take the special values jump and 1, the value immediately jumps from the previous value to the next value when the previous value was specified.

This command can be used in any place where \pgfsys@animation@time is usually used. The effect is that the next value does not become part of the timeline, but will become the value used for the attribute when no animation is active. (Normally, when the animation is not active, no value is set at all and the value is inherited from the surrounding scope.)

Creates a time–value pairs where the value is the current value that the attribute has. This command can only be used in conjunction with “real” animations, when you use it with a snapshot an error is raised.

Creates a time–value pairs where the value is some text. Which texts are permissible depends on the to-be-animated attribute.

Creates a time–value pairs where the value is a number like 0.5 or -2.25.

Creates a time–value pairs where the value is a TeX dimension like 0.5pt or -2in.

Creates a time–value pairs where the value is color specified by three fractional values between 0 and 1 for the red, the green, and the blue part.

Creates a time–value pairs where the value is color specified by four fractional values between 0 and 1 for the cyan, magenta, yellow, and black part.

Like the \pgfsysanimvalcolorcmyk only without the black part.

Creates a time–value pairs where the value is gray value (a fraction between 0 and 1).

Creates a time–value pairs where the value is path. The ⟨low-level commands⟩ must consist of a sequence of path construction commands like \pgfsys@lineto or \pgfsyssoftpath@linetotoken (more precisely, the commands must form a list of TeX tokens and dimensions surrounded by braces). For each call of this command, the sequence of tokens and numbers must be the some. During the animation, only and exactly the numbers will be interpolated.

Creates a time–value pairs where the value is a coordinate. The dimensions must be TeX dimensions.

Creates a time–value pairs where the value is pair of scalar values.

Creates a time–value pairs where the value is view box. The lower left corner is given by \((x_1,y_1)\), consisting of two TeX dimensions, and the upper right corner is \((x_2,y_2)\).

Creates a time–value pairs where the value is dash pattern and phase with the same syntax as \pgfsys@setdash.

Specifies that the animation should repeat the specified ⟨number of times⟩, which may be a fractional number.

Specifies that the animation should repeat indefinitely.

Specifies that the animation should repeat until ⟨seconds⟩ have elapsed.

Specifies that (in addition to any other beginnings or endings) the animation’s timeline should begin (or end) ⟨time offset⟩ many seconds after the graphic is shown. For instance, in the next example the animation will start automatically after 5 s or when then button is pressed.

Specifies that the animation should begin ⟨time offset⟩ many seconds after the ⟨sync base id⟩ with the given ⟨type⟩ has begun. Here, the ⟨sync base id⟩ must have been obtained using \pgfsys@new@id.

The idea behind a sync base is that you setup an animation and name it, other animations can start alongside this animation. An animation whose sole purpose is to orchestrate other animations in this way is called a sync base.

Works like \pgfsysanimkeysyncbegin only the animation begin (or ends) when the sync base ends.

Specifies that the animation should begin (or end) ⟨time offset⟩ many seconds after a certain event has occurred. Which events are possible depends on the specific output language, here are the events currently supported in svg:

• • click occurs when the object with the given ⟨id⟩ and ⟨type⟩ has been clicked.

• • focusin and focusout occur when the focus enters or leaves the object.

• • mouseup, mousedown, mouseover, mousemove, and mouseout occur when the mouse is pressed up or down on the object, moved onto the object, moved over the object, or moved off the object.

The animation begins (or end) with a certain offset when another animation has reached a certain repeat count.

Begin or end the animation when a certain key is pressed. Note that this event may not be supported by some browsers for security reasons (prevent key loggers).

Defines that the animation can be restarted at any time. This is the default.

Defines that the animation cannot be restarted once it has run.

Defines that the animation cannot be restarted while it is running.

When an animation ends, the question is whether the “effect” of the animation (like changing a color or translating the coordinate system) should disappear or “remain in force”. Using this key, you specify that at the end of the animation the last value of the attributes stays in effect.

The opposite of \pgfsysanimkeyfreezeatend. This is the default.

Specifies that each repeat of an animation works as if the last values attained during previous repeats are added to the current value.

Specifies that each repeat resets the to-be-animated value. This is the default.