PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10

The System Layer

123 Animation System Layer

In conjunction with the right output format (namely svg), you can specify that certain parts of you graphics can be animated. For this, there are a number of commands that cover, currently, what svg 1.1 can do regarding animations. For a detailed introduction to animations, please see Section 116; the current section assumes that you are familiar with the concepts explained there.

The animation system consists of two layer itself: Commands starting with \pgfsys@anim... and commands starting with \pgfsysanim. These work as follows:

  • 1. The commands starting with \pgfsys@anim... insert the actual animation commands into the output stream. A driver must implement these commands.

  • 2. The command starting with \pgfsysanim... provide an. These commands, which are the ones that should be called by higher layers, implement the snapshot mechanism: When the command \pgfsysanimsnapshot is used, the \pgfsysanim... commands do not call the \pgfsys@anim... commands but, instead, insert non-animation commands to show the values of the attributes at the snapshot’s time. To use this abstraction layer, you have to load the file pgfsysanimations.code.tex, which is not loaded by default (but is loaded by the pgf module animations).

The bottom line is that if you wish to implement a new driver, you need to implement the \pgfsys@anim... commands, if you use the animation layer, you call the \pgfsysanim... commands.

123.1 Animations and Snapshots

To add an animation to a graphic, use the following command (as described above, the first command is the one you actually call, the second is the one a driver implements):

  • \pgfsysanimate{attribute}

  • \pgfsys@animate{attribute}

  • 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 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 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 scope and thereby influence the values of these keys.

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

    \pgfsysanimkeyrepeatindefinite % Both of the following animations
    % repeat indefinitely
    \pgfsysanimkeywhom{\someid}{}% The id of a later object
    \pgfsysanimkeyevent{}{}{click}{0}{begin}% Begin on a click ...
    \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline starts after 5s
    \pgfsysanimvalscalar{0} % With a value of 0
    \pgfsysanimkeytime{8}{1}{1}{0}{0} % Timeline ends after 8s
    \pgfsysanimvalscalar{0.9} % With a value of 0.9
    \pgfsysanimate{fillopacity}% ... and the attribute is the fill opacity
    \pgfsysanimkeywhom{\someid}{}% The id of a later object
    \pgfsysanimkeyoffset{0}{begin}% Begin right away ...
    \pgfsysanimkeytime{1}{1}{1}{0}{0} % Timeline starts after 1s
    \pgfsysanimvalcurrent % With the current value
    \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline ends after 5s
    \pgfsysanimvaldimension{5pt} % With a value of 5pt
    \pgfsysanimate{linewidth}% ... and the attribute is the line width

    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.

    \tikz[fill=blue!25, draw=blue, ultra thick] {
    \node [font=\scriptsize, circle, fill, draw, align=center]
    (node) {Click \\ here};

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


The “opposite” of \pgfsysanimate is the following command:

  • \pgfsysanimsnapshot{time}

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

    \foreach \t in {0.5,1,1.5,2} {
    \tikz {
    \node (node) [draw = blue, very thick, fill=blue!20, circle] {Hi};
  • \pgfsysanimsnapshotafter{time}

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

123.2 Commands for Animating an Attribute: Color, Opacity, Visibility, Staging

The commands from this and the next sections specify that some attribute should be animated. We start with rather basic animation attributes for color, visibility, and opacity.

  • \pgfsysanimate{opacity}

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


123.3 Commands for Animating an Attribute: Paths and Their Rendering

The following attributes influence paths and how they are rendered.

  • \pgfsysanimate{path}

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

    \animationexample{my path}{path}{
    \filldraw [ultra thick,draw=blue,fill=blue!20, name=my path]
    (1,0) -- (1,1) -- (2,0); }

    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:

    • \pgfsysanimkeytipmarkers{start marker}{end marker}

123.4 Commands for Animating an Attribute: Transformations and Views

The commands in this section allow you to animate the canvas transformation matrix of a scope. However, there is one command that needs to be explained first.

  • \pgfsysanimkeycanvastransform{pre}{post}

  • \pgfsys@animation@canvas@transform{pre}{post}

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

    \fill [ball color=red,name=ball] (1,0) circle [radius=3mm]; }
    \fill [ball color=blue,name=ball] (1,0) circle [radius=3mm]; } }




  • \pgfsysanimate{skewy}

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

    Specify values with \pgfsysanimvalscalar.

  • \pgfsysanimate{motion}

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

    • \pgfsysanimkeymovealong{path}

    • \pgfsys@animation@movealong{path}

    • Defines the path along which the motion will occur. It will simply be executed and must call \pgfsys@lineto and similar path-construction commands, but should not call other commands.

      \pgfsyssoftpath@curvetotoken{-5mm}{-1cm} }

    • \pgfsysanimkeynorotatealong

    • \pgfsys@animation@norotatealong

    • Indicates that no additional rotation should be added during the movement. This is the default.

    • \pgfsysanimkeyrotatealong

123.5 Commands for Specifying the Target Object
  • \pgfsysanimkeywhom{id}{type}

  • \pgfsys@animation@whom{id}{type}

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

123.6 Commands for Specifying Timelines: Specifying Times

Animations are specified using timelines, which are functions mapping times to values for these times. The functions are cubic splines, which are specified using time–value pairs plus control points.

In order to specify a time–value pair, you first use the command \pgfsysanimkeytime to specify a time. Next, you use \pgfsysanimval... to specify a value, which adds the time–value pair to the timeline. Note that the times must be given in non-decreasing order. Between time–value pairs, the values are interpolated using a spline.

The first and last times of the timeline are a bit special: The timeline starts on the first time and the duration of the timeline is the difference between the first and last time. “Starting” on the start time actually means that any beginnings (see the commands for specifying beginnings and endings) get as offset the start time; similarly end times are offset by this value.

  • \pgfsysanimkeytime{time}{entry spline control x}{entry spline control y}{exit spline control x}{exit spline control y}

  • \pgfsys@animation@time{time}{entry spline control x}{entry spline control y}{exit spline control x}{exit spline control y}

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

  • \pgfsysanimkeybase

  • \pgfsys@animation@base

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

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

  • 2. If there are several active animations, the one that has started last is used and the 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).

123.7 Commands for Specifying Timelines: Specifying Values

The following commands are used to specify the values of a timeline. Each use of one of the following commands adds one time–value pair to the timeline. Which of the commands must be used depends on the type of the to-be-animated attribute (see the \pgfsysanimate command instances, which list the command that must be used).

  • \pgfsysanimvalcurrent

  • \pgfsys@animation@val@current

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

  • \pgfsysanimvaltext{text}

  • \pgfsys@animation@val@text{text}

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

  • \pgfsysanimvalscalar{number}

  • \pgfsys@animation@val@scalar{number}

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

  • \pgfsysanimvaldimension{dimension}

  • \pgfsys@animation@val@dimension{dimension}

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

  • \pgfsysanimvalcolorrgb{red}{green}{blue}

  • \pgfsys@animation@val@color@rgb{red}{green}{blue}

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

  • \pgfsysanimvalcolorcmyk{cyan}{magenta}{yellow}{black}

  • \pgfsys@animation@val@color@cmyk{cyan}{magenta}{yellow}{black}

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

  • \pgfsysanimvalcolorcmy{cyan}{magenta}{yellow}

  • \pgfsys@animation@val@color@cmy{cyan}{magenta}{yellow}

  • Like the \pgfsysanimvalcolorcmyk only without the black part.

  • \pgfsysanimvalcolorgray{gray value}

  • \pgfsys@animation@val@color@gray{gray value}

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

  • \pgfsysanimvalpath{low-level path construction commands}

  • \pgfsys@animation@val@path{low-level path construction command}

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

  • \pgfsysanimvaltranslate{x dimension}{y dimension}

  • \pgfsys@animation@val@translate{x dimension}{y dimension}

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

  • \pgfsysanimvalscale{x scale}{y scale}

  • \pgfsys@animation@val@scale{x scale}{y scale}

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

  • \pgfsysanimvalviewbox{\(x_1\)}{\(y_1\)}{\(x_2\)}{\(y_2\)}

  • \pgfsys@animation@val@viewbox{\(x_1\)}{\(y_1\)}{\(x_2\)}{\(y_2\)}

  • 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 dimensions, and the upper right corner is \((x_2,y_2)\).

  • \pgfsysanimvaldash{pattern}{phase}

  • \pgfsys@animation@val@dash{pattern}{phase}

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

123.8 Commands for Specifying Timing: Repeats
  • \pgfsysanimkeyrepeatnumber of times

  • \pgfsysanimkeyrepeatindefinite

  • \pgfsysanimkeyrepeatdurseconds

123.9 Commands for Specifying Timing: Beginning and Ending

Normally, animations start when a graphic is displayed. Using the following commands, you can change this behavior: For instance, you can specify that the animation should start when, say, some button has been pressed or a key has been hit. Similarly, you can also use the commands to specify that the animation should stop early, for instance when a button is pressed.

Note that all of the commands for specifying a nonstandard begin (or end) of an animation’s timeline refer to when the time \(0\,\mathrm s\) of the timeline should actually be. If the first time–value point for a timeline is at, say, 2 s and you specify that the begin of the animation is one second after the click of a button, the attribute will attain the value specified by the time–value point three seconds after the button has been pressed.

All of the following commands take either the text begin or end as their last argument.

You can call the commands several times. This will result in several different possible beginnings (or endings).

  • \pgfsysanimkeyoffset{time offset}{begin or end}

  • \pgfsysanimkeysyncbegin{sync base id}{type}{time offset}{begin or end}

  • \pgfsys@animation@syncbegin{sync base id}{type}{time offset}{begin or end}

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

  • \pgfsysanimkeysyncend{sync base id}{type}{time offset}{begin or end}

  • \pgfsys@animation@syncend{sync base id}{type}{time offset}{begin or end}

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

  • \pgfsysanimkeyevent{id}{type}{event name}{time offset}{begin or end}

  • \pgfsysanimkeyrepeatevent{id}{type}{repeat count}{time offset}{begin or end}

  • \pgfsysanimkeyaccesskey{character}{time offset}{begin or end}

123.10 Commands for Specifying Timing: Restart Behaviour
  • \pgfsysanimkeyrestartalways

  • \pgfsysanimkeyrestartnever

  • \pgfsysanimkeyrestartwhennotactive

  • \pgfsysanimkeyfreezeatend

  • \pgfsysanimkeyremoveatend

123.11 Commands for Specifying Accumulation

Animations specify how an attribute of an object changes over time. When more than one animation changes the same value at the same time, the last value given for the attribute “wins”, except for animations of the canvas, which always accumulate. Additionally, when a repeat is specified for an attribute, during each repeat the values can add up:

  • \pgfsysanimkeyaccumulate

  • \pgfsysanimkeynoaccumulate