PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10

The Basic Layer

116Animations

  • \usepgfmodule{animations} % and plain and pure pgf

  • \usepgfmodule[animations] % Cont and pure pgf

  • This module contains the basic layer support of animations, which is documented in the following.

This section described the basic layer support of animations, the TikZ support is described in Section 26. As always, TikZ mainly converts syntactic constructs (like the special colon or quote syntax) to appropriate basic layer commands, which are documented here. Note, however, that while many attributes and options are the same on both layers, some things are handled differently on the basic layer.

116.1Overview

An animation changes the way some part of a graphic looks like over time. The archetypical animation is, of course, a movement of node, but a change of, say, the opacity of a path is also an animation. pgf allows you to specify such animations using a set of commands and keys that are documented in the following.


\tikz {
\pgfanimateattribute{opacity}{
whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
}

Differently from other packages, the animations created by pgf are not precomputed sequences of pictures that are displayed in rapid succession. Rather, an animation created by pgf consists mainly of 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. Interestingly, this means that animations neither increase the size of the output files noticeably nor does it put a special burden on . The hard and complicated calculations are done by the viewer application, not by and pgf.

Only few viewer applications and formats are currently “up to the job” of displaying animations. In particular, the popular pdf format does not allow one to specify animations in this way (one can partly “fake” animations at the high price of including a great number of precomputed pictures and using JavaScript in special viewers, but this is really not the same thing as what pgf does). Indeed, currently only the svg format allows one to specify animations in a sensible way. Thus, pgf’s animations will only be displayed when svg is used as output format.

Because of the shortcomings of the other formats and, also, for purposes of printing and depicting animations in a sequential manner, pgf also allows you to create “snapshots” of animations. As an example, the following code shows how the same drawing is shown at different “time snapshots”:

(-tikz- diagram)(-tikz- diagram)(-tikz- diagram)(-tikz- diagram)

\usetikzlibrary {animations} \def \pgfname {\textsc {pgf}}
\tikz [make snapshot of=0.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
\node [draw=blue, very thick] {\pgfname};
\tikz [make snapshot of=1s] \scoped :rotate = { 0s = "0", 2s = "90" }
\node [draw=blue, very thick] {\pgfname};
\tikz [make snapshot of=1.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
\node [draw=blue, very thick] {\pgfname};
\tikz [make snapshot of=2s] \scoped :rotate = { 0s = "0", 2s = "90" }
\node [draw=blue, very thick] {\pgfname};
116.2Animating an Attribute
116.2.1The Main Command

Creating an animation is done using the command \pgfanimateattribute, which takes a to-be-animated attribute and options specifying the timeline:

  • \pgfanimateattribute{attribute}{options}

  • Adds an animation of the attribute of a future object to the current graphic. Attributes are things like the “fill opacity” or the transformation matrix or the line width.

    The options are keys that configure how the attribute changes over time. Using the entry key multiple times, you specify which value the chosen attribute should have at different points in time. Unless special keys are used, “outside” the specified timeline the animation has no effect:


    \tikz {
    \pgfanimateattribute{opacity}{
    whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

    Other keys, like repeats, allow you to specify how the animation behaves “as a whole”. These keys are documented later in this section.

    The Attributes

    In detail, the \pgfanimateattribute command opens a -scope, looks up the type values of the specified attribute have (if you wish to animate the opacity of an object, the type is “scalar” meaning that entries must be scalar numbers; when you animate the fill attribute, the type is “color” and values must be colors, and so on), and then executes the options with the path prefix /pgf/animation. Finally, an appropriate system layer command \pgfsysanimate... is called to create the actual animation and the scope is closed.

    The following attributes are permissible:

    .
    Attribute Type
    draw, fill color
    line width dimension
    motion scalar
    opacity, fill opacity, draw opacity scalar
    path path
    rotate scalar
    scale scaling
    softpath softpath
    translate point
    view viewbox
    visible boolean
    stage boolean
    xskew, yskew scalar

    These attributes are detailed in Sections 116.3 to 116.5, but here is a quick overview:

    • draw and fill refer to the color used to draw (stroke) and fill paths in an object, respectively. Typical values for this attribute are red or black!10.

    • line width is, of course, the line width used in an object. Typical values are 0.4pt or 1mm. Note that you (currently) cannot use keys like thin or thick here, but this may change in the future.

    • motion is a slightly special attribute: It allows you to specify a path along which the object should be moved (using the along key). The values given to the entry key for this attribute refer to a fraction of the distance along the path. See the along key for details.

    • opacity and the variants fill opacity and draw opacity animate the opacity of an object. Allowed values range between 0 and 1.

    • path allows you to animate a path (it will morph). The “values” are now paths themselves. See Section 116.4 for details.

    • rotate refers to a rotation of the object. Values for the entry key are the rotation angles like 0 or 90.

    • scale refers to the scaling of the object. Values are either single scalars values (like 1 or 1.5) or two numbers separated by a comma (like 1,1.5 or 0.5,2), referring to the \(x\)-scaling and \(y\)-scaling.

    • softpath is a special case of the path attribute, see Section 116.4 once more.

    • translate shifts the object by a certain vector. Values are points like \pgfpoint{1cm}{2cm}.

    • view allows you to animate the view box of a view, see Section 116.5 for details.

    • visible refers to the visibility of an object. Allowed values are true and false.

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

    • xskew and yskew skew the object. Attributes are angles like 0 or 45 or even 90.

    The Target Object

    As stated earlier, the options are used to specify the object whose attribute for which an animation should be added to the picture. Indeed, you must specify the object explicitly using the whom key and you must do so before the object is created. Note that, in contrast, in svg you can specify an animation more or less anywhere and then use hyper-references to link the animation to the to-be-animated object; pgf insists that you specify the animation before the object. This is a bit of a bother in some situations, but it is the only way to ensure that pgf has a fighting chance to attach some additional code to the object (which is necessary for almost all animations of the transformation matrix).

    • /pgf/animation/whom=id.type(no default)

    • You must use this key once which each call of the \pgfanimateattribute command. The id and the optional type (which is whatever follows the first dot) will be passed to \pgfidrefnextuse, see that command for details.

    As explained in the introduction of this chapter, an “animation” is just a bit of special text in the output document asking a viewer application to animate the object at some later time. The \pgfanimateattribute command inserts this special text immediately, even though it refers to an object created only later on. Normally, this is not a problem, but the special text should be on the same page as the to-be-animated object. To ensure this, it suffices to call \pgfanimateattribute no earlier than the beginning of the pgfpicture containing the object.

    Naming the Animation

    You can assign a name to an animation for later (or early) reference. In particular, it is possible to begin another animation relative to the beginning or end of this animation and for referencing this animation must be assigned a name. See the of and of next keys for details.

  • \pgfanimateattributecode{attribute}{code}

  • The command works like \pgfanimateattribute, only instead of options you specify some code whose job is to setup the options.

116.2.2Specifying the Timeline

The core key for specifying how an attribute varies over time is the entry key:

  • /pgf/animation/entry={time}{value}(no default)

  • You use this key repeatedly to specify the different values that the attribute should have over time. At the time specified, the attribute will have the value specified as value:


    \tikz {
    \pgfanimateattribute{rotate}{
    whom = node, begin on = {click},
    entry = {0s}{0}, entry = {1s}{90}, entry = {1.1s}{45}, entry = {2s}{90}
    }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

    You need to call entry once for each time in the timeline for which you want to specify a value explicitly. Between these times, the values get interpolated (see below for details). You need to specify the times in non-decreasing order (it is permissible and sometimes also necessary to specify the same time twice, namely to create a “jump” of the value of some attribute).

    The time is parsed using the command \pgfparsetime described later.

    Start and end of the timeline. 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 begin and end keys) get offset by the start time; similarly end times are offset by this value.

    Syntax of the values. The syntax of the value varies according to the type of the attribute. In detail, these are:

    .
    Type

    Syntax

    color

    Standard color syntax like red or black!10

    scalar

    A value parsed using \pgfmathparse

    dimension

    A dimension parsed using \pgfmathparse

    path

    A sequence of path construction commands

    softpath

    A sequence of soft path construction commands

    scaling

    A scalar value or a pair of scalar values separated by a comma

    point

    A pgf-point like \pgfpoint{1cm}{5mm}

    viewbox

    Two pgf-points

    boolean

    true or false

    Interpolation between key times. You use the entry key repeatedly, namely once for each “key time”, which is a time point for which you specify the value of the attribute explicitly. Between these key times, the attribute’s value is interpolated. Normally, this is just a linear interpolation, but you can influence this using the following keys, see Section 26.5.4 for details.

    • /pgf/animations/entry control={time fraction}{value fraction}(no default)

    • Works like exit control.

    • /pgf/animations/linear(no value)

    • A shorthand for exit control={0}{0}, entry control={1}{1}. This will (re)install a linear curve.

When the time of an animation lies outside the timeline specified by the entry keys, no animation is present. This means that the value of the attribute is the object’s scope is used instead. Using the following key, you can set this value directly:

  • /tikz/animations/base=value(no default)

  • The syntax of the value is the same as for the entry key. The value is installed as the value of the object’s attribute whenever the timeline is not active. This makes it easy to specify the value of an attribute when the animation is “not running”.


    \tikz {
    \pgfanimateattribute{rotate}{
    whom = node, begin on = {click},
    entry = {0s}{90}, entry = {2s}{180},
    base = 45
    }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

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

  • \pgfparsetime{time}

  • This command works like \pgfmathparse (indeed, it calls is internally), but returns the result in the macro \pgftimeresult rather than \pgfmathresult. Furthermore, the following changes are installed:

    • • The postfix operator s is added, which has no effect.

    • • The postfix operator ms is added, which divides a number by 1000, so 2ms equals 0.002s.

    • • The postfix operator min is added, which multiplies a number by 60.

    • • The postfix operator h is added, which multiplies a number by 3600.

    • • The infix operator : is redefined, so that it multiplies its first argument by 60 and adds the second. This implies that 1:20 equals 80s and 01:00:00 equals 3600s.

    • • The parsing of octal numbers is switched off to allow things like 01:08 for 68s.

116.2.3“Anti-Animations”: Snapshots

There are a number of situations in which you want the “opposite” of an animation to happen: You want to create a “still image”. For instance, when you want to print an animation you will typically wish to show one or more “temporal snapshots” of the animation. Also, you may wish to specify a value for an object when it is not being animated.

Let us start with creating a snapshot:

  • \pgfsnapshot{time}

  • When this command is used inside a scope, the behavior of \pgfanimateattribute changes: Instead of adding an animation to the object and the attribute, the object’s attribute is set to value it would have during the animation at time time. Note that when this command is used in a scope, no animation is created and no support by the driver is needed (so, it works with pdf).

    (-tikz- diagram)

    \usetikzlibrary {animations}
    \tikz [make snapshot of=1s,
    animate = { myself: = {
    :rotate = { 0s = "0", 2s = "90" },
    :color = { 0s = "red", 2s = "green" },
    :line width = { 0s = "0mm", 4s = "4mm" }
    }}
    ]
    \node [fill=black!20, draw] { Node };

    Timing and Events. The timeline of an animation normally starts at a “moment 0s” and the time is considered relative to this time. For instance, if a timeline contains, say, the settings entry={2s}{0} and entry={3s}{10} and {time} is set to 2.5s, then the value the attribute will get is 5.

    It is, however, also possible to specify that animations begin and end at certain times relative to events like a click event. These events are not relevant with respect to snapshots. However, there is one key that allows you to specify the beginning of the snapshot timeline:

    • /tikz/animations/begin snapshot=begin time(no default)

    • When this key is used inside the options of \pgfanimateattribute, with respect to snapshots, the timeline begins at begin time. This means that, if the snapshot time is set to time and the beginning of the snapshot’s timeline is set to begin time, the attribute is set to the value of the timeline at time \(\meta {time} - \meta {begin time}\).

      The idea is that when you make a snapshot of several animations and all of them have started at different times because of different events, you use begin snapshot with each object and attribute to directly specify when these different events have happened.

    Note that the end keys have no effect with snapshots, that is, with a snapshot all animations always run till the end of the timeline (which may or may not be “forever”).

    Limitations. For snapshots, the value an animation has at time time must be computed by . While in many cases this is easy to achieve, in some cases this is not trivial such as a timeline for a path with repeats plus smoothing via splines. An additional complication is the fact that an animation may be specified at a place far removed from the actual to-be-animated object. For these reasons, certain limitations apply to snapshots:

    • • The begin and begin on keys have no effect (but begin snapshot has one.

    • • The end and end on keys have no effect.

    • • The current value may not be used in a timeline (since pgf cannot really determine this value).

    • • The accumulating specification may not be used with paths, views, or motions.

    • • Since the timing computations are done using code, they are not necessarily stable. For instance, when a time interval is very small and there are many repeats or when a spline is very complicated, the calculated values may not be fully accurate.

  • \pgfsnapshotafter{time}

  • This command works exactly like \pgfsnapshot 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:

    (-tikz- diagram) (-tikz- diagram) (-tikz- diagram) (-tikz- diagram) (-tikz- diagram)

    \usepgfmodule {animations}
    \foreach \t in {0,1,2,3,4} {
    \pgfsnapshot{\t}
    \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" }
    \node [draw=blue, very thick] {f}; }

    (-tikz- diagram) (-tikz- diagram) (-tikz- diagram) (-tikz- diagram) (-tikz- diagram)

    \usepgfmodule {animations}
    \foreach \t in {0,1,2,3,4} {
    \pgfsnapshotafter{\t}
    \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" }
    \node [draw=blue, very thick] {f}; }
116.3Animating Color, Opacity, Visibility, and Staging
  • \pgfanimateattribute{fill}{options}

  • You can animate the color of the target object of an animation using the attributes fill or draw, which animate the fill color and the drawing (stroking) color, respectively. To animate both the fill and draw color, you need to create two animations, one for each.


    \tikz {
    \pgfanimateattribute{fill}{
    whom = node.background, begin on = {click},
    entry = {0s}{white}, entry = {2s}{red} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

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:


\tikz {
\pgfanimateattribute{fill}{
whom = example, begin on = {click, of next=node},
entry = {0s}{white}, entry = {2s}{red} }
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\begin{scope}[name = example]
\fill (1.5,-0.75) rectangle ++ (1,1);
\fill [blue] (2,-0.25) rectangle ++ (1,1);
\end{scope}
}

Note that in certain cases, a graphic scope may contain graphic objects with their colors set explicitly “in places where you do not expect it”: In particular, a node normally consists at least of a background path and a text. For both the text and for the background path, colors will be set for the text and also for the path explicitly. This means that when you pick the fill attribute of a node as the target of an animation, you will not animate the color of the background path in case this color has been set explicitly. Instead, you must choose the background path of the node as the target of the animation. Fortunately, this is easy to achieve since when the background path of a node is created, the identifier type is set to background, which in turn allows you to access it as node.background through the whom key.

The text of a node also gets it color set explicitly, which means that a change of the node’s scope’s color has no effect on the text color. Instead, you must choose name.text as the target (or, if the node has more parts, use the name of the part as the identifier type instead of text).


\tikz {
\pgfanimateattribute{fill}{
whom = example, begin on = {click, of next=node},
entry = {0s}{white}, entry = {2s}{red} }
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\node at (2,0) (example) [fill = blue!20, circle] {No effect}; }


\tikz {
\pgfanimateattribute{fill}{
whom = example.background, begin on = {click, of next=node},
entry = {0s}{white}, entry = {2s}{red} }
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\node at (2,0) (example) [fill = blue!20, circle] {Effect}; }


\tikz {
\pgfanimateattribute{fill}{
whom = example.text, begin on = {click, of next=node},
entry = {0s}{white}, entry = {2s}{red} }
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\node at (2,0) (example) [fill = blue!20, circle, font=\huge] {Text}; }

Similarly to the color, you can also set the opacity used for filling and for drawing. You specify the opacity using a number between 0 (transparent) and 1 (opaque).

  • \pgfanimateattribute{opacity}{options}

  • Unlike colors, where there is no joint attribute for filling and stroking, there is a single opacity attribute in addition to the above two attributes. If supported by the driver, it treats the graphic object to which it is applied as a transparency group. In essence, “this attribute does what you want” at least in most situations.


    \tikz {
    \pgfanimateattribute{opacity}{
    whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

  • \pgfanimateattribute{visible}{options}

  • The difference between the visible attribute and an opacity of 0 is that an invisible object cannot be clicked and does not need to be rendered. The (only) two possible values for this attribute are false and true.


    \tikz {
    \pgfanimateattribute{visible}{
    whom = node, begin on = {click}, entry = {0s}{false}, entry = {2s}{false} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

  • \pgfanimateattribute{stage}{options}

  • This attribute is the same as the visible attribute, only base=false is set by default. This means that the object is only visible when you explicitly during the time the entries are set to true. The idea behind the name “stage” is that the object is normally “off stage” and when you explicitly set the “stage attribute” to true the object “enters” the stage and “leaves” once more when it is no longer “on stage”.


    \tikz {
    \pgfanimateattribute{stage}{
    whom = example, begin on = {click, of next=node},
    entry = {0s}{true}, entry = {2s}{true} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    \node at (2,0) (example) [fill = blue!20, circle] {Effect}; }

116.4Animating Paths and their Rendering

You can animate the appearance of a path in the following ways:

  • \pgfanimateattribute{dash}{options}


  • \tikz {
    \pgfanimateattribute{dash}{
    whom = node, begin on = {click}, entry = {0s}{{{10pt}{1pt}}{0pt}},
    entry = {2s}{{{1pt}{10pt}}{0pt}} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }


    \tikz {
    \pgfanimateattribute{dash}{
    whom = node, begin on = {click}, entry = {0s}{{{1cm}{1pt}}{0pt}},
    entry = {2s}{{{1cm}{1pt}}{1cm}} }
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

    To specify the dash pattern, you specify a sequence of “on and off” dimensions; see \pgfsetdash for details. Note that you must specify the same number of elements in all patterns of a timeline: You cannot specify that the dash pattern for 1s is {1pt}{2pt} and for 2s is {1pt}{3pt}{2pt} since the number of elements would differ. In particular, you cannot (sensibly) use current value for the first entry since this corresponds to an empty dash pattern (even when you have specified a dash pattern for the target object: this pattern will not be attached to the to-be-animated scope or object but to a surrounding scope and, thus, the to-be-animated scope will not have any dash pattern installed).

  • \pgfanimateattribute{path}{options}

  • You can animate the path itself:


    \tikz {
    \pgfanimateattribute{path}{
    whom = node.background.path, begin on = {click, of next=node},
    entry = {0s}{\pgfpathellipse{\pgfpointorigin}
    {\pgfpointxy{1}{0}}{\pgfpointxy{0}{1.5}}},
    entry = {2s}{\pgfpathellipse{\pgfpointxy{.5}{0}}
    {\pgfpointxy{.5}{.5}}{\pgfpointxy{0.25}{.25}}}}
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    }

    The path is specified by giving path construction commands as in the above example. They will be executed in a special protected scope to ensure that they have only little side effects.

    As for the dash pattern, you must ensure that all paths in the timeline have the same structure (same sequence of path construction commands); only the coordinates may differ. In particular, you cannot say that the path at 1s is a rectangle using \pgfpathrectangle and at 2s is a circle using \pgfpathcircle. Instead, you would have to ensure that at both times that path consists of appropriate Bézier curves.

    Unlike the dash pattern, the to-be-animated object is, indeed, the path itself and not some special scope. This means that you can use the current value for the start path. However, this also means that you really must pick the path object as the target of the animation. In conjunction with TikZ, this will be an object of type path as in the above example.

    When a path is animated, it cannot have “normal” arrows attached to it since due to the way pgf adds arrow tips to paths, these would not “move along” with the path (you get an error message if you try). However, it still is possible to add arrow tips to an animated path, only you need to use the arrows key described next.

    Concerning the bounding box computation of the path, a bounding box for all paths mentioned for any time point is used as the overall bounding box.

  • /pgf/animation/arrows=start tip spec-end tip spec(no default)

  • This key specifies arrow tips during the animation of the path. The syntax for the arrow tips is the same syntax as the \pgfsetarrow command or TikZ’s arrows key. The specified start and end arrow tips are rendered as “markers”, which are added to the path only during the animation. The markers are rotated along with the path in exactly the same way as normal arrow tips would be. To be precise, the rules used for the computation of where arrow tips go and in which direction they head is not always the same for “static” arrow tips (arrow tips added to a normal path) and the “dynamic” arrow tips based on markers; namely when the paths are very short or closed. For this reason, you should add arrow tips to animated paths only when the paths are “nice and simple” in the sense that they consist of a single segment whose ends are reasonably long.

    In addition to adding the arrow tips to the path during the animation, the path gets shortened as necessary to compensate for the extend of the arrow tips. However, for this to work, the arrow tips have to be specified before path values are specified (since the shortening is done immediately when a path value is parsed).


    \tikz {
    \pgfanimateattribute{path}{
    whom = p.path, begin on = {click, of next=node}, arrows = ->,
    entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
    \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
    entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
    \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    \draw [very thick, blue, name=p] (1,0.5) -- (2,0.5);
    }

    Note that the markers that visualize the arrow tips are rendered only once per animation. In consequence, “bending” arrow tips cannot be rendered correctly: As a path “morphs” a bend arrow tip needs not only to rotate along, but must actually “bend along”, which is not supported (neither by pgf nor by svg).

    As pointed out earlier, an animated path cannot have “static” arrow tips. However, when you specify a base value, which is the path used whenever there is no active animation, will use the arrow tips. As a result, you can use this to animate a path with an arrow tip:


    \tikz {
    \pgfanimateattribute{path}{
    whom = p.path, begin on = {click, of next=node}, arrows = ->,
    base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}}
    \pgfpathlineto{\pgfpoint{2cm}{5mm}}},
    entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
    \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
    entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
    \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
    \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
    \draw [very thick, blue, name=p];
    }

  • /pgf/animation/shorten <=dimension(no default)

  • Works like shorten >.

116.5Animating Transformations and Views

In order to animate the canvas transformation matrix, you do not animate an attribute called “transform” (or something similar). Rather, there are several keys 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.

Some, but not all, of these keys also have an effect on the bounding box computation: The translate and motion attribute change the computation of the bounding box in such a way that it is chosen large enough as to include the whole picture during all stages of the animation (however, if there are multiple transformations active at the same time, the computation may not be correct). In contrast, scale, rotate and skew animations change the canvas transformation, but are ignored for the bounding box computation. When in doubt, please set the bounding box explicitly.

Let us start with the basic keys that allow you to change the canvas transformation matrix directly:

  • \pgfanimateattribute{scale}{options}

  • The scale attribute adds an animation of the scaling:


    \tikz [very thick] {
    \pgfanimateattribute{scale}{
    whom = node, begin on = {click},
    entry = {0s}{0.5}, entry = {2s}{0.75,1.5} }
    \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
    }

    The values passed to the entry key must either be single scalar values or a pair of such numbers separated by a comma (which then refer to the \(x\)- and \(y\)-scaling).

  • \pgfanimateattribute{xskew}{options}

  • The xskew and yskew keys (and also skew x and skew y, which are aliases) add an animation of the skew (given in degrees, not as a slant):


    \tikz [very thick] {
    \pgfanimateattribute{xskew}{
    whom = node, begin on = {click}, entry = {0s}{0}, entry = {2s}{45} }
    \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
    }

    The values are scalar values.

  • \pgfanimateattribute{yskew}{options}

  • See xskew.

  • \pgfanimateattribute{skew x}{options}

  • An alias of xskew.

  • \pgfanimateattribute{skew y}{options}

  • An alias of yskew.

  • \pgfanimateattribute{translate}{options}

  • The translate key adds an animation of the translation (shift):


    \tikz [very thick] {
    \pgfanimateattribute{translate}{
    whom = node, begin on = {click},
    entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{5mm}{-5mm}} }
    \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
    }

    The values are pgf-points.

    Unlike for the previous canvas transformations, for this key the bounding box computation is changed: All points in the to-be-animated scope do not only contribute to the normal bounding box, but they also contribute shifted by all points in the entry list. The effect is that a bounding box is computed that encompasses the animated scope at all stages.

For all of these attributes, the following key is of importance:

  • /pgf/animation/origin=pgf point(no default)

  • An animation of the canvas transformation is added to all other transformations from surrounding or interior scopes. This means that, in particular, the origin of a canvas transformation is, by default, the origin of the canvas of the scope surrounding the transformation object.

    For some canvas animations, like a rotation or a scaling, you will typically wish to use a different origin (like the center of an object that is to be rotated or scaled). You can achieve this effect by surrounding the object by a scope that shifts the canvas to the desired origin, followed by a scope whose transformation matrix you animate, followed by a scope that shifts back the canvas.

    The origin key simplifies this process by allowing you to specify the origin of the transformation directly. Internally, however, all this key does is to create the above-mentioned scopes with the necessary shifts.


    \tikz [very thick] {
    \pgfanimateattribute{rotate}{
    whom = node, begin on = {click},
    origin = \pgfpoint{-5mm}{0mm}, entry = {0s}{0}, entry = {2s}{90} }
    \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
    }

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

116.6Commands for Specifying Timing: Beginnings and Endings

Using the entry key repeatedly, you specify a timeline: 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.

  • /pgf/animation/begin=time(no default)

  • This key specifies when the “moment 0s” should be relative to the moment when the current graphic is first displayed. You can use this key multiple times, in this case the timeline is restarted for each of the times specified (if it is already running, it will be reset). If no begin key is given at all, the effect is the same as if begin=0s had been specified.

    It is permissible to set time to a negative value.

  • /pgf/animation/end=time(no default)

  • This key will truncate the timeline so that it ends time after the display of the graphic, provided the timeline begins before the specified end time. For instance, if you specify a timeline starting at 2 s and ending at 5 s and you set begin to 1 s and end to 4 s, the timeline will run, relative to the moment when the graphic is displayed from 3 s to 4 s.


    \tikz [very thick] {
    \pgfanimateattribute{rotate}{
    whom = node, begin = 2s, end = 4s,
    entry = {1s}{0}, entry = {2s}{90}, entry = {3s}{180}, entry = {4s}{270} }
    \node (node) [fill = blue!20, draw = blue, circle] {Turn after 3s!}; }

It is not immediately clear what should happen with the attribute of an object when an animation ends: Should it revert to its original value “as if there had never been an animation” or should it “stay at the last value”? The following key governs what should happen:

  • /pgf/animation/freeze at end=true or false (default true, initially false)

  • When set to true, whenever a timeline ends (either because the last time of timeline has been reached or because an end or end of key have ended it prematurely), the last value the attribute had because of the animation “stays put”. When set to false, which is the initial value, once an animation ends, its effect will be removed “as if it never happened”.


    \tikz [very thick] {
    \pgfanimateattribute{rotate}{
    whom = node, begin on = {click}, freeze at end = false,
    entry = {0s}{0}, entry = {2s}{90} }
    \node (node) [fill = blue!20, draw = blue, circle] {Here!}; }


    \tikz [very thick] {
    \pgfanimateattribute{rotate}{
    whom = node, begin on = {click}, freeze at end,
    entry = {0s}{0}, entry = {2s}{90} }
    \node (node) [fill = blue!20, draw = blue, circle] {Here!}; }

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:

  • /pgf/animation/begin on=options(no default)

  • Has the same effect as /tikz/animate/option/begin on, see Section 26.5.2.

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

  • /pgf/animation/restart=choice (default true)

  • Has the same effect as /tikz/animate/option/restart, see Section 26.5.2.

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:

  • /pgf/animation/end on=options(no default)

  • Works exactly like begin on, one possible end of the timeline is specified using the options.

116.7Commands for Specifying Timing: Repeats

Normally, a timeline is displayed once and then ends. You can, however, request that the timeline should be repeated a certain number of times or indefinitely.

  • /pgf/animation/repeats=specification(no default)

  • Use this key to specify that the timeline animation should repeat at the end. The specification must consist of two parts, each of which may be empty. The first part is one of the following:

    The second part of the specification must be one of the following:

    • • Empty, in which case each time the timeline is restarted, the attribute’s value undergoes the same series of values it did previously.

    • • The text accumulating. This has the effect that each time the timeline is restarted, the attribute values specified by the timeline are added to the value from the previous iteration(s). A typical example is an animation that shifts a scope by, say, 1 cm over a time of 1 s. Now, if you repeat this five times, normally the scope will shift 1 cm for 1 s then “jump back”, shift again, jump back, and so on for five times. In contrast, when the repeats are accumulating, the scope will move by 5 cm over 5 s in total.


      \tikz [very thick] {
      \pgfanimateattribute{rotate}{
      whom = node, begin on = {click}, repeats = accumulating,
      entry = {0s}{0}, entry = {2s}{90} }
      \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }


      \tikz [very thick] {
      \pgfanimateattribute{rotate}{
      whom = node, begin on = {click}, repeats = 2 accumulating,
      entry = {0s}{0}, entry = {2s}{90} }
      \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }

  • /pgf/animation/repeat=specification(no default)

  • This is an alias for repeats.