☰
PGF/TikZ Manual | PGFplots | TikZ Editor

TikZ and PGF Manual

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⟩}

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} {
    \pgfsysanimsnapshot{\t}
    \tikz {
    \pgfidrefnextuse{\objid}{node}
    \pgfsysanimkeywhom{\objid}{}
    \pgfsysanimkeytime{0}{1}{1}{0}{0}
    \pgfsysanimvalscalar{1}
    \pgfsysanimkeytime{2}{1}{1}{0}{0}
    \pgfsysanimvalscalar{0}
    \pgfsysanimate{opacity}
    \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.


    \animationexample{node}{}{
    \pgfsysanimkeytime{0}{1}{1}{0}{0}
    \pgfsysanimvalscalar{1}
    \pgfsysanimkeytime{2}{1}{1}{0}{0}
    \pgfsysanimvalscalar{0}
    \pgfsysanimate{opacity}
    }

123.3 Commands for Animating an Attribute: Paths and Their Rendering

The following attributes influence paths and how they are rendered.

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⟩}

  • \pgfsysanimate{skewy}

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

    Specify values with \pgfsysanimvalscalar.

123.5 Commands for Specifying the Target Object

  • \pgfsysanimkeywhom{⟨id⟩}{⟨type⟩}

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⟩}

  • \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⟩}

  • \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⟩}

  • \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@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⟩}

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

  • \pgfsysanimkeyrepeatdur⟨seconds⟩

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