| Current File : //usr/share/texlive/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-animations.tex |
% Copyright 2019 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
\section{Animations}
\label{section-tikz-animations}
\begin{tikzlibrary}{animations}
This library must be loaded in order to use animations with \tikzname.
\end{tikzlibrary}
\subsection{Introduction}
An \emph{animation} changes the appearance of some part of a graphic over time.
The archetypical animation is, of course, a \emph{movement} of some part of a
picture, but a change of, say, the opacity of a path is also an animation.
\tikzname\ allows you to specify such animations using special keys and
notations.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
width=8cm,
animation list={0.7,1.4,2.1,2.8},
animation scale=.25,
]
\begin{tikzpicture}[
animate/orbit/.style 2 args = {
myself:shift = {
along = {
(0,0) circle [radius=#1]
} sloped in #2s/10,
repeats }} ]
\node :color = {0s = "orange",
2s = "red",
4s = "orange",
repeats}
{Sun};
\begin{scope}[animate={orbit={2.5cm}{365}}]
\node {Earth};
\node [animate={orbit={1cm}{28}}] {Moon};
\end{scope}
\useasboundingbox (-3.8,-3.8) (3.8,3.8);
\end{tikzpicture}
\end{codeexample}
Adding an animation to a \tikzname\ picture is done as follows:
%
\begin{enumerate}
\item \emph{Before} or \emph{in the options of} the to-be-animated object
you specify the object together with an \emph{attribute} that you wish
to animate. Attributes are things like the fill color or the line width
or the position of the object.
\item You specify \emph{when} this attribute should have \emph{which}
values using a so-called \emph{timeline}. This is just a curve that
specifies for each point in time which value the attribute should have.
\item You can additionally use further options to configure the animation,
for instance you can specify that the animation should repeat or that
it should only start when a certain object is clicked.
\end{enumerate}
As a simple example, let us move a circle within thirty seconds by three
centimeters to the left:
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
\end{codeexample}
As can be seen, a special syntax is used in several places: Entries with a
colon such as |:xshift| specify an attribute, values are specified in quotation
marks. This syntax will be explained in more detail later on.
\subsubsection{Animations Change Attributes}
Before we plunge into the details of how animations are specified, it is
important to understand what \tikzname\ actually does when creating an
animation: It does \emph{not} (as all other animation packages do) precompute a
sequence of pictures that are later somehow displayed in rapid succession.
Neither does it insert an external video into the document. Rather, a
\tikzname\ animation is just an ``annotation'' in the output that a certain
attribute of a certain object should change over time in some specific way when
the object is displayed. It is the job of the document viewer application to
actually compute and display the animation. The big advantage of this approach
is that animations neither increase the output file sizes noticeably nor do
they really slow down \TeX: The hard and complicated calculations are done by
the viewer application. The disadvantage is, of course, that a document viewer
application must understand the annotations and actually compute and display
the animations. The \textsc{svg} format is a format for which this is possible,
the popular \textsc{pdf} format is not. For the \textsc{svg} format, there are
actually different possible ways of ``formulating'' the animations (using
\textsc{smil} or \textsc{css} or JavaScript) and they have different advantages
and disadvantages.
To make a long story short: \tikzname\ animations currently work only with
\textsc{svg} output (and use the \textsc{smil} ``flavor'' of describing
animations). In future, it may well happen that other ``flavor'' of describing
animations will be added, but it is very unlikely that \textsc{pdf} will ever
support animations in a useful way.
It is, however, possible to create ``snapshots'' of an animation and insert
these into \textsc{pdf} files (or any other kind of file including \textsc{svg}
files), see Section~\ref{section-anim-snap} for details. Snapshots are also
useful for creating ``printed versions'' of animations and all of the small
sequences of pictures in the manual that are used for showing what an animation
key does have been creating using snapshots.
\subsubsection{Limitations of the Animation System}
There are a certain limitations of the animation system that you should keep in
mind when considering how and when to use it:
%
\begin{enumerate}
\item As pointed out earlier, animations require a specific output format
(currently only \textsc{svg} is supported).
\item It is extremely difficult to animate ``lines between moving nodes''
correctly. Consider code like |\draw(a)--(b);| where |a| and |b| are
nodes. Now, when you animate the position of~|(a)|, the line connecting
|(a)| and |(b)| will, unfortunately, not ``move along'' automatically
(but it is easy to move the whole group of |(a)|, |(b)|, and the
connecting line as whole). You must ``cheat'' and introduce some
``virtual'' nodes, which leads to rather complex and bloated code.
\item Animations are taken into consideration for bounding box computations,
but only for shifts, not for rotations, scaling, or skewing and also
possibly not when multiple shifts are active at the same time for the
same object.
\end{enumerate}
\subsubsection{Concepts: (Graphic) Objects}
During an animation an attribute of a certain ``object'' changes over time. The
term ``object'' is deliberately a bit vague since there are numerous different
``things'' whose attributes can change. In detail, the following objects have
attributes that can be animated:
%
\begin{enumerate}
\item Nodes, which are created by the |\node| command (and, also,
internally by commands such as |\graph|). For nodes, different parts of
the node can be animated separately; for instance, you can animate the
color of the background path, but also the color of the text, and also
the color of the foreground path (though most nodes do not have a
foreground path) and also the color of different text parts (though
only few nodes have multiple text parts).
\item Graphic scopes, which are created by numerous command, including the
|{scope}| environment, the |\scopes| command, but also |\tikz| itself
creates a graphic scope and so does each node and even each path.
\item View boxes, which can only be created using the |views| library.
\item Paths, which you create using the |\path| command or commands like
|\draw| that call |\path| internally. However, the (usually background)
path of a node can also be animated. Note that ``animating the path''
really means that the path itself should change over time; in essence,
you can ``warp'' a path over time.
\end{enumerate}
In all of these cases, you must either specify the animation inside the
object's options using |animate| or use the |name| key to name the object and,
then, refer to it in an |animate|. For nodes you can, of course, use the
|(|\meta{node name}|)| syntax to name the node. Recall that you must
\emph{always} specify the animation \emph{before} the object is created; it is
not possible to animate an already created object.
There is a special syntax for choosing the object of an animation, see
Section~\ref{section-anim-syntax-obj}, but you can also use the |object| key to
choose them directly, see Section~\ref{section-anim-def-obj}.
\subsubsection{Concepts: Attributes}
In addition to the to-be-animated object, you must also choose an
\emph{attribute} that you wish to animate. Attributes are things like the color
of an object, the position, but also things like the line width. The syntax for
choosing attributes and the list of attributes will be explained in detail
later on.
Most attributes correspond directly to attributes that are directly supported
by the backend driver (\textsc{svg}), but this is not always the case. For
instance, for a node, \tikzname\ differentiates between the fill color, the
draw (stroke) color, and the text color, while \textsc{svg} treats the text
color are a special case of the fill color. \tikzname\ will do some internal
mappings to ensure that you can animate the ``\tikzname\ attributes'' even when
they are not directly supported.
The same syntax that is used for specifying object is also used to specify
attributes, see Section~\ref{section-anim-syntax-obj}, but you could also set
them directly using the |attribute| key see
Section~\ref{section-anim-def-attr}.
\subsubsection{Concepts: Timelines}
Once an object and an attribute have been chosen, a \emph{timeline} needs to be
established. This is, essentially, a curve that specifies for each ``moment in
time'' which value the attribute should have.
A timeline has a \emph{start} and an \emph{end}, but the start need not be the
``moment zero'' (we will come to that) and may even be negative, while the end
may be at infinity. You specify the timeline by specifying for certain points
in time what the value is at that moment; for all other moments the value is
then interpolated. For instance, if you specify that the attribute |:xshift|
(the ``horizontal position'' of the object) is 0\,mm at time 5\,s and 10\,mm at
time 10\,s, then at 7.5\,s it will be 5\,mm and at 9\,s it will be 8\,mm
(assuming a linear interpolation). The resulting optical effect will be that
the object \emph{smoothly moves} by one centimeter to the right over a period
of five seconds, starting five seconds after ``moment zero''.
Now, what is the ``moment zero'', the ``beginning of an animation''? If nothing
else is specified, an animation starts immediately when the graphic is shown
and this is the moment zero relative to which the timeline is measured.
However, it is also possible to change this. In particular, you can specify
that the moment zero is when a particular \emph{event} occurs such as the user
clicking on another object or another animation ending or starting.
The interpolation of values is not always a straightforward affair. Firstly,
for certain kinds of values is not clear how an interpolation should be
computed. How does one interpolate between two paths? Between the colors red
and green? Between the values |"true"| and |"false"|? In these cases, one must
define carefully what the interpolation should be. Secondly, you may wish to
use a non-linear interpolation, which is useful for ``easing'' motions: The
visual effect of the movement specified above is that the object sits still
from moment $0$ for five seconds, then there is an ``infinite acceleration''
causing the object to suddenly move at the speed of 2\,mm per second, then
there is no acceleration at all for five seconds, causing the object to move
for one centimeter, followed by an ``infinite negative acceleration'' that
makes the object come to a full stop. As a viewer you experience these infinite
accelerations as ``unrealistic'', spoiling the effect of watching a (virtual)
physical process. Non-linear interpolations allow you to avoid this effect.
Just as for specifying objects and attributes, there is also a special syntax
for specifying times and values.
\subsection{Creating an Animation}
\subsubsection{The Animate Key}
In order to animate a picture, you create timelines for all objects and
attributes that change during the animation. The key |animate| is used for
creating these timelines.
\begin{key}{/tikz/animate=\meta{animation specification}}
You must place all specifications of animations inside uses of |animate|.
You can, and usually should, place the specification of all timelines of a
single picture inside a single use of this key since it will reset the time
and the fork time (explained in Section~\ref{section-anim-def-times}). You
can, however, use this key several times, in principle. Note that if you
animate the same attribute of the same object in two different uses of
|animate|, two separate timelines will result (and complicated rules are
used to determine which one ``wins'' in case they specify conflicting
values for the attribute at different times).
The key can be used at all places where a \tikzname\ key is used; typically
you will use it with a |{scope}| environment, inside the options of a node,
or directly with the |\tikz| command:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2},
]
\tikz \node [fill, text = white, animate = {
myself:fill = {0s = "red", 2s = "blue", begin on = click }}] {Click me};
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2},
]
\tikz [animate = {a node:fill = {0s = "red", 2s = "blue",
begin on = click}}]
\node (a node) [fill, text = white] {Click me};
\end{codeexample}
The details of what, exactly, happens in the \meta{animation specification}
will be described in the rest of this section. However, basically, an
\meta{animation specification} is just a sequence of normal \tikzname\
key--value pairs that get executed with the path prefix |/tikz/animate| and
with some special syntax handlers installed. In particular, you can define
styles for this key path and use them. For instance, we can define a
|shake| animation like this:
%
\begin{codeexample}[width=4cm,preamble={\usetikzlibrary{animations}}]
\tikzset{
animate/shake/.style = {myself:xshift = { begin on=click,
0s = "0mm", 50ms = "#1", 150ms = "-#1", 250ms = "#1", 300ms = "0mm" }}}
\tikz \node [fill = blue!20, draw=blue, very thick, circle,
animate = {shake = 1mm}] {Shake};
\tikz \node [fill = blue!20, draw=blue, very thick, circle,
animate = {shake = 2mm}] {SHAKE};
\end{codeexample}
Note that, as stressed earlier, you can only use the |animate| key to
specify animations for objects that do not yet exist. The node and object
names mentioned in a specification always refer to ``upcoming'' objects;
already existing objects of the same name are not influenced.
You can use the |name| key inside |animate| to ``name'' the animation. Once
named, you can later reference the animation in other animations; for
instance, you can say that another animation should start when the present
animation has ended.
\end{key}
\subsubsection{Timeline Entries}
The ``job'' of the options passed to the |animate| key is to specify the
timelines of the animation of (a part of) a picture. For each object and each
attribute there may or may not be a timeline and, if present, the timeline
consist of sequences of pairs of times and values. Thus, the most basic entity
of an animation specification is a tuple consisting of five parts, which are
selected by five different keys:
%
\begin{itemize}
\item |object| for selecting the object,
\item |attribute| for selecting the attribute,
\item |id| for selecting the timeline id (explained in
Section~\ref{section-anim-def-id}),
\item |time| for selecting a time, and
\item |value| for selecting a value.
\end{itemize}
%
When all of these parts have been set up (using the above keys, which will be
explained in more detail in a moment), you can use the following key to create
an entry:
\begin{key}{/tikz/animate/entry}
Each time this key is used in the options of |animate|, \tikzname\ checks
whether the five keys |object|, |attribute|, |id|, |time|, and |value| are
set. If one of them is not set, nothing happens. (The |id| key is set to
the value |default| by default, all other keys must be set explicitly.)
If all of these keys are set, a \emph{time--value} pair is created and
added to the timeline of attribute of the object. Additionally, all options
starting with |/tikz/animate/options/|, which also influence the timeline
like |begin on|, are also added to the timeline of the object--attribute
pair.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = {
object = node, attribute = fill, time = 0s, value = red, entry,
object = node, attribute = fill, time = 2s, value = blue, entry,
object = node, attribute = fill, begin on = click, entry}]
\node (node) [fill, text=white] { Click me };
\end{codeexample}
%
In the above example, it would not have been necessary the specify the
object and the attribute in each line, they retain their values unless they
are overwritten. Thus, we could also have written:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = {
object = node, attribute = fill, time = 0s, value = red, entry,
time = 2s, value = blue, entry,
begin on = click, entry}]
\node (node) [fill, text=white] { Click me };
\end{codeexample}
%
Note, however, that in both examples we actually add the time--value pair
$(2\mathrm{s}, \mathrm{blue})$ twice since the |time| and |value| keys also
retain their settings and, thus, for the third |entry| they have the same
values as before and a new pair is added. While this superfluous pair is
not a problem in the example (it has no visual effect), we will see later
on how such pairs can be avoided by using the |scope| key.
A sequence of calls of |entry| can freely switch between objects and
attributes (that is, between timelines), but the times for any given
timeline must be given in non-decreasing order:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = {
object = node, attribute = fill, time = 0s, value = red, entry,
object = node2, attribute = draw, entry,
object = node, attribute = fill, time = 2s, value = blue, entry,
object = node2, attribute = draw, entry,
object = node, attribute = fill, begin on = click, entry,
object = node2, attribute = draw, begin on = click, entry}] {
\node (node) [fill, text=white] { Node 1 };
\node (node2) [draw, ultra thick] at (0,-1) { Node 2 };
}
\end{codeexample}
%
In the above example, we could not have exchanged the first two lines of
the |animate| options with the third and fourth line since the values for
time |0s| must come before the values for time |2s|.
\end{key}
In the following, we have a closer look at the five keys the influence the
|entry| key and then have a look at ways of grouping keys more easily.
\subsubsection{Specifying Objects}
\label{section-anim-def-obj}
You use the |object| key to select the object(s) to which the next use of
|entry| applies. There is also a special syntax for this, which is explained in
Section~\ref{section-anim-syntax-obj}.
\begin{key}{/tikz/animate/object=\meta{list of objects}}
The \meta{list of objects} is a comma-separated list of strings of the form
\meta{object}\opt{|.|\meta{type}}. All of the objects in the list are
selected as to-be-animate object for the next use of the |entry| key. The
objects referred to by \meta{object} will be the \emph{next} objects with
the |name| key set to \meta{object}. You can apply the |name| key to nodes
(where you can also use the special parentheses-syntax and put the name in
parentheses, it has the same effect), but also to scopes and paths. (The
|name path| key is not the same as |name|; it is an older key from the
intersections package and not related.)
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
begin on = click }}] {
\node (a) [fill, text = white, minimum width=1.5cm] at (0,1cm) {a};
\node (b) [fill, text = white, minimum width=1.5cm] at (0,5mm) {b};
\node (c) [fill, text = white, minimum width=1.5cm] at (0,0mm) {c}; }
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
begin on = click },
object = c, :fill = {0s = "green", 2s = "blue",
begin on = click } }] {
\scoped [name = a, yshift=1cm] \fill (0,0) rectangle (1.5cm,2mm);
\scoped [name = b, yshift=5mm] \fill (0,0) rectangle (1.5cm,2mm);
\scoped [name = c, yshift=0mm] \fill (0,0) rectangle (1.5cm,2mm); }
\end{codeexample}
If the \meta{object} name is never used later in the file, no animation is
created.
The \meta{object} may also be the special text |myself|. In this case, the
referenced object is the scope or object to which the |animate| key is
given. If an object is named |myself| (as in |\node (myself) ...|), you
cannot reference this node using the |object| key, |myself| \emph{always}
refers to the object where the |animate| key is given (of course, you can
animate the node named |myself| by placing the |animate| key inside the
options of this node; you only cannot ``remotely'' add an animation to it).
The \meta{object} may be followed by a dot and a \emph{type}. This is need
in rare cases where you want to animate only a special ``part'' of an
object that is not accessible in other ways. Normally, \tikzname\ takes
care of choosing these types automatically, you only need to set these ``if
you know what you are doing''.
\end{key}
\subsubsection{Specifying Attributes}
\label{section-anim-def-attr}
\begin{key}{/tikz/animate/attribute=\meta{list of attributes}}
The list of attributes must be a comma-separated list of attribute names.
The timelines specified later will apply to all of these attributes (and to
all objects previously selected using |object|). Possible attributes
include colors, positions, line width, but even the paths themselves. The
exact list of possible attributes is documented in
Section~\ref{section-anim-attrs}.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = {attribute = fill, n: = { 0s = "red", 2s = "blue",
begin on = click } }]
\node (n) [fill, text = white] {The node};
\end{codeexample}
\end{key}
\subsubsection{Specifying IDs}
\label{section-anim-def-id}
\begin{key}{/tikz/animate/id=\meta{id} (initially default)}
Timelines are use to defined how the values of an attribute of an object
change over time. In many cases, you will have at most one timeline for
each object--attribute pair, but, sometimes, you may wish to have more than
one timeline for the same object and the same attribute. For instance, you
might have a timeline that specifies a changing |shift| of a node in some
direction and, at the same time, another timeline that specifies an
additional |shift| in some other direction(s). The problem is that there is
only one |shift| attribute and it would be difficult to compute the joint
effect of the two timelines.
For this purpose, timelines are actually identified not only by the
object--attribute pair but, in reality, by the triple consisting of the
object, the attribute, and the value of this key. We can now specify two
separate timelines:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = {
id = 1, n:shift = { 0s = "{(0,0)}", 2s = "{(0,5mm)}", begin on = click },
id = 2, n:shift = { 0s = "{(0,0)}", 2s = "{(5mm,0)}", begin on = click }
}]
\node (n) [fill = blue!20, draw=blue, very thick] {The node};
\end{codeexample}
The default value of |id| is |default|.
\end{key}
Because of the possibility of creating multiple timelines for the same
attribute, it may happen that there is more than one timeline active that is
``trying to modify'' a given attribute. In this case, the following rules are
used to determine, which timeline ``wins'':
%
\begin{enumerate}
\item If no animation is active at the current time (all animation either
have not yet started or they have already ended), then the |base| value
given in the animation encountered last in the code is used. (If there
are no base values, the attribute is taken from the surrounding scope
and the animations have ``no effect''.)
\item If there are several active animations, the one that has started last
is used and its value is used.
\item If there are several active animations that have started at the same
time, the one that comes last in the code is used.
\end{enumerate}
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).
\subsubsection{Specifying Times}
\label{section-anim-def-times}
\begin{key}{/tikz/animate/time=\meta{time}\opt{|later|}}
Sets the time for the next time--value pair in a call of |entry| to
\meta{time} plus the current fork time. The text |later| is optional. Both
``fork times'' and the optional |later| will be explained in a moment.
\medskip\textbf{Time Parsing.}
The \meta{time} is parsed using the command |\pgfparsetime|, which is
essentially the same as the usual math parser of \tikzname, and the result
is interpreted as a time in seconds. Thus, a \meta{time} of |2+3| means ``5
seconds'' and a \meta{time} of |2*(2.1)| means ``4.2 seconds''. (You could
even specify silly times like |1in|, which results in the time ``72.27
seconds''. Please do not do that.) The ``essentially'' refers to the fact
that some extras are installed when the time parser is running:
%
\begin{itemize}
\item The postfix operator |s| is added, which has no effect. Thus,
when you write |5s| you get the same results as |5|, which is
exactly 5 seconds as desired.
\item The postfix operator |ms| is added, which divides a number by
1000, so |2ms| equals 0.002s.
\item The postfix operator |min| is added, which multiplies a number by
60.
\item The postfix operator |h| is added, which multiplies a number by
3600.
\item 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.
\item The parsing of octal numbers is switched off to allow things like
|01:08| for 68s.
\end{itemize}
Note that you cannot use the colon syntax for times in things like
|01:20 = "0"| would (falsely) be interpreted as: ``For the object named |01|
and its attribute named |20|, do something.'' You can, however, use |01:20|
in arguments to the |time| key, meaning that you would have to write
instead: |time = 1:20, "0"|, possibly surround by a |scope|.
\medskip\textbf{Relative Times.}
You can suffix a |time| key with ``|later|''. In this case, the \meta{time}
is interpreted as an offset to the time in the previous use of the time
key:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :fill = { begin on = click,
0s = "white",
500ms later = "red",
500ms later = "green", % same as 1s = "-5mm"
500ms later = "blue"} % same as 1.5s = "-2.5mm"
[fill=blue!20, draw=blue, very thick, circle] {Click me};
\end{codeexample}
In reality, the offset is not taken to just any previous use of the |time|
key, but to the most recent use of this key or of the |resume| key in the
current local \TeX\ scope. Here is an example:
%
\begin{codeexample}[code only]
time = 2s,
time = 1s later, % same as time = 3s
time = 500ms later, % same as time = 3.5s
time = 4s,
time = 1s later, % same as time = 5s
scope = { % opens a local scope
time = 1s later, % same as time = 6s
time = 10s
time = 1s later % same as time = 11s
}, % closes the scope, most recent time is 5s once more
time = 2s later % same as time = 7s
\end{codeexample}
\medskip\textbf{Fork Times.}
The time meant by the value \meta{time} passed to the |time| key is not
used directly. Rather, \tikzname\ adds the current \emph{fork time} to it,
which is |0s| by default. You can change the fork time using the following
key:
%
\begin{key}{/tikz/animate/fork=\meta{t} (default 0s later)}
Sets the fork time for the local scope to \meta{t} and sets the current
time to |0s|. In this scope, when you use ``absolute'' times like |0s|
or |2s|, you actually refer to later times that have started as
\meta{t}.
One application of forks is in the definition of keys that add a
certain part to a longer animation. Consider for instance the
definition of a |highlight| key:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1.05,1.1,1.15,1.2,2.05,2.1,2.15,2.2},
]
\tikz [animate/highlight/.style = {
scope = { fork = #1,
:fill = { 0s = "black", 0.1s = "white", 0.2s = "black"} }
}]
\node [animate = { myself: = {
:fill = { 0s = "black", begin on = click },
highlight = 1s, highlight = 2s } },
fill = blue, text=white, very thick, circle] { Click me };
\end{codeexample}
%
In the above example, we could also have written |0.1s later| instead
of |0.2s| and, indeed, the whole style could have been defined using
only times with |later|, eliminating the need for the |fork| key.
However, using forks you can specify absolute times for things
happening in a conceptual ``subprocess'' and also relative times. The
name |fork| for the key is also borrowed from operating system theory,
where a ``fork'' is the spawning of an independent process.
\end{key}
\medskip\textbf{Remembering and Resuming Times.}
When you have a complicated animation with a long timeline, you will
sometimes wish to start some animation when some other animation has
reached a certain moment; but this moment is only reached through heavy use
of |later| times and/or forks. In such situations, the following keys are
useful:
%
\begin{key}{/tikz/animate/remember=\meta{macroname}}
This key stores the current time (the time of the last use of the
|time| key) globally in the macro \meta{macroname}. This time will
include the offset of the fork time:
%
\begin{codeexample}[code only]
time = 2s,
fork = 2s later, % fork time is now 4s
time = 1s, % local time is 1s, absolute time is 5s (1s + fork time)
time = 1s later, % local time is 2s, absolute time is 6s (2s + fork time)
remember = \mytime % \mytime is now 6s
\end{codeexample}
\end{key}
%
\begin{key}{/tikz/animate/resume=\meta{absolute time}}
The \meta{absolute time} is evaluated using |\pgfparsetime| and, then,
the current time is set to the resulting time minus the fork time. When
the \meta{absolute time} is a macro previously set using |remember|,
the net effect of this is that we return to the exact ``moment'' in the
global time line when |remember| was used.
%
\begin{codeexample}[code only]
fork = 4s,
time = 1s,
remember = \mytime % \mytime is now 5s
fork = 2s, % fork time is now 2s, local time is 0s
resume = \mytime % fork time is still 2s, local time is 3s
\end{codeexample}
%
Using resume you can easily implement a ``join'' operation for forked
times. You simply remember the times at the ends of the forks and then
resume the maximum time of these remembered times:
%
\begin{codeexample}[code only]
scope = {
fork,
time = 1s later,
...
remember = \forka
},
scope = {
fork,
time = 5s later,
...
remember = \forkb
},
scope = {
fork,
time = 2s later,
...
remember = \forkc
},
resume = {max(\forka,\forkb,\forkc)} % "join" the three forks
\end{codeexample}
\end{key}
\end{key}
\subsubsection{Values}
\label{section-anim-def-values}
\begin{key}{/tikz/animate/value=\meta{value}}
This key sets the value of the next time--value pair created by |entry| to
\meta{value}. The syntax of the \meta{value} is not fixed, it depends on
the type of the attribute. For instance, for an attribute like |opacity|
the \meta{value} must be an expression that can be evaluated to a number
between 0 and 1; for the attribute |color| the \meta{value} must, instead,
be a color; and so on. Take care that when a value contains a comma, you
must surround it by braces as in |"{(1,1)}"|.
The allowed texts for the \meta{value} is always the same as the one you
would pass to the \tikzname\ option of the same name. For instance, since
the \tikzname\ option |shift| expects a coordinate, you use coordinates as
\meta{value} with the usual \tikzname\ syntax (including all sorts of
extensions, the animation system calls the standard \tikzname\ parsing
routines). The same is true of dimensions, scalar values, colors, and so
on.
In addition to the values normally use for setting the attribute, you can
also (sometimes) use the special text |current value| as \meta{value}. This
means that the value of the point in the timeline should be whatever the
value the attribute has at the beginning of the timeline. For instance,
when you write
%
\begin{codeexample}[code only]
animate = { obj:color = { 0s = "current value", 2s = "white" } }
\end{codeexample}
%
the color of |obj| will change from whatever color it currently has to
white in two seconds. This is especially useful when several animations are
triggered by user events and the current color of |obj| cannot be
determined beforehand.
There are several limitations on the use of the text |current value|, which
had to be imposed partly because of the limited support of this feature in
\textsc{svg}:
%
\begin{itemize}
\item You can use |current value| only with the first time in a
timeline.
\item You can only have two times in a timeline that starts with
|current value|.
\item You cannot use |current value| for timelines of which you wish to
take a snapshot.
\end{itemize}
\end{key}
\subsubsection{Scopes}
\label{section-anim-scopes}
When you specify multiple timelines at the same time, it is often useful and
sometimes even necessary to have keys be set only locally. The following key
makes this easy:
\begin{key}{/tikz/animate/scope=\meta{options}}
Executed the \meta{options} inside a \TeX\ scope. In particular, all
settings made inside the scope have no effect after the end of the |scope|.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node [animate = { myself: = { begin on = click,
scope = { attribute = fill, repeats = 3, 0s = "red", 2s = "red!50" },
scope = { attribute = draw, 0s = "red", 2s = "red!50" }
}},
fill=blue!20, draw=blue, very thick, circle] {Click me};
\end{codeexample}
Without the use of the |scope| key, the |repeats| key would also affect the
draw attribute.
\end{key}
While the |scope| key is useful for structuring timeline code, it also keeps
the current time local to the scope, that is, if you use something like
|1s later| after the scope, this will refer to one second after the last use of
|time| \emph{before} the scope. The times set inside the |scope| do not matter.
While this is desirable effect for forks, you may also sometimes wish to
synchronize the local time after the scope with the last time reached in the
scope. The following key makes this easy:
\begin{key}{/tikz/animate/sync=\meta{options}}
A shorthand for |scope={| \meta{options} |, remember=\temp},resume=\temp|
where |\temp| is actually an internal name. The effect is that after a
|sync| the local time just continues as if the scope where not present --
but regarding everything else the effects are local to the |sync| scope.
\end{key}
\subsection{Syntactic Simplifications}
\label{section-anim-syntax-animate}
In the previous subsection we saw how timelines can be created by specifying
the individual entries of the timelines sequentially. However, most of the time
you will wish to use a simpler syntax that makes it easier to specify
animations. This syntax is only available inside the |animate| key (it is
switched on at the beginning) and consists of three ``parts'': The colon
syntax, the time syntax, and the quote syntax.
\subsubsection{The Colon Syntax I: Specifying Objects and Attributes}
\label{section-anim-syntax-obj}
Inside the \meta{animation specification} passed to the |animate| key, you can
specify an object and an attribute of this object using the following syntax,
whose use is detected by the presence of a colon inside a key:
%
\begin{quote}
\normalfont
\opt{\meta{object name(s)}}|:|\opt{\meta{attribute(s)}}
|={|\meta{options}|}|
or
\opt{\meta{object
name(s)}}|:|\opt{\meta{attribute(s)}}|_|\opt{\meta{id}}
|={|\meta{options}|}|
\end{quote}
%
In the place to the left of an equal sign, where you would normally use a key,
you can instead place an object name and an attribute separated by a colon.
Additionally, the attribute may be followed by an underscore and an \meta{id},
which identifies the timeline (see Section~\ref{section-anim-def-id}).
Each of these values may be missing, in which case it is not changed from its
previous value.
The effect of the above code is the same as:
%
\begin{quote}
\normalfont
|sync = { object = |\meta{objects}|, attribute = |\meta{attribute}|, id = |\meta{id}|, |\meta{options}|, entry }|
\end{quote}
%
although when the object, the attribute, or the id is left empty in the colon
syntax, the corresponding setting will be missing in the above call of |sync|.
Note that because of the |sync| the last time used inside the \meta{options}
will be available afterwards as the last time. Also note that an |entry| is
added at the end, so any settings of keys like |begin| or |repeats| inside the
\meta{options} will get added to the timeline.
Let us now have a look at some examples. First, we set the \meta{object name}
to |mynode| and |othernode| and the \meta{attribute} to |opacity| and to
|color|:
%
\begin{codeexample}[code only]
animate = {
mynode:opacity = { 0s = "1", 5s = "0" },
mynode:color = { 0s = "red", 5s = "blue" },
othernode:opacity = { 0s = "1", 5s = "0" },
}
\end{codeexample}
Next, we do the same, but ``in two steps'': First, we set the object to
|mynode|, but leave the attribute open and, then, set the attribute, but leave
the object:
%
\begin{codeexample}[code only]
animate = {
mynode: = {
:opacity = { 0s = "1", 5s = "0" },
:color = { 0s = "red", 5s = "blue" }
},
othernode:opacity = { 0s = "1", 5s = "0" },
}
\end{codeexample}
%
Note how both in |mynode:| and in |:opacity| and |:color| you must provide the
colon. Its presence signals that an object--attribute pair is being specified;
only now either the object or the attribute is missing.
We can also do it the other way round:
%
\begin{codeexample}[code only]
animate = {
:opacity = {
mynode: = { 0s = "1", 5s = "0" },
othernode: = { 0s = "1", 5s = "0" }
},
mynode:color = { 0s = "red", 5s = "blue" }
}
\end{codeexample}
%
Finally, if several objects should get the exact same values, we can also group
them:
%
\begin{codeexample}[code only]
animate = {
{mynode,othernode}:opacity = { 0s = "1", 5s = "0" },
mynode:color = { 0s = "red", 5s = "blue" }
}
\end{codeexample}
As mentioned earlier, all references to objects will be interpreted to future
objects, never to objects already created. Furthermore, also as mentioned
earlier, \tikzname\ allows you to specify |myself| as \meta{object}, which is
interpreted as the scope or node where the |animate| is given (you cannot
animate a node or scope named |myself|, this special name always refers to the
current node). In order to have all attributes refer to the current object, you
write:
%
\begin{codeexample}[code only]
\begin{scope} [animate = {
myself: = { % Animate the attribute of the scope
:opacity = { ... },
:xshift = { ... }
}
}]
...
\end{scope}
\end{codeexample}
The list of permissible attributes is given in
Section~\ref{section-anim-attrs}.
\subsubsection{The Colon Syntax II: Animating Myself}
A frequent use of the |animate| key is for animating attributes of the current
object |myself|. In these cases, it is a bit length to write
%
\begin{codeexample}[code only]
[animate = { myself: = { :some attribute = {...} } } ]
\end{codeexample}
%
\noindent in the options of a node or a scope. For this reason, \tikzname\
allows you to use a special syntax with nodes and scopes:
%
\begin{enumerate}
\item In a \meta{node specification}, which is everything following a
|node| command up to the content of the node (which is surrounded by
curly braces), you can write
%
\begin{quote}
|:some attribute = {|\meta{options}|}|
\end{quote}
%
and this will have the same effect as if you had written
%
\begin{quote}
|[animate = { myself: = { :some attribute = {|\meta{options}|}}}]|
\end{quote}
%
Note that you can use this syntax repeatedly, but each use creates a
new use of the |animate| key, resulting in a new timeline. In order to
create complex timelines for several objects, use the |animate| key.
\item For the commands |\tikz|, |\scoped| and the environments
|{tikzpicture}| and |{scope}|, when they are followed immediately by
%
\begin{quote}
|:some attribute = {|\meta{options}|}|
\end{quote}
%
then
%
\begin{quote}
|animate = { myself: = { :some attribute = {|\meta{options}|}}}|
\end{quote}
%
is added to the options of the command or scope. Again, you can use the
syntax repeatedly. Note that when an opening square bracket is
encountered, this special parsing stops.
\end{enumerate}
Let us have a look at some examples. First, we use the syntax to set the fill
opacity of a node:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node
:fill opacity = { 0s="1", 2s="0", begin on=click }
[fill = blue!20, draw = blue, ultra thick, circle] {Here!};
\end{codeexample}
%
Next, we additionally rotate the node:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node
:fill opacity = { 0s="1", 2s="0", begin on=click }
:rotate = { 0s="0", 2s="90", begin on=click }
[fill = blue!20, draw = blue, ultra thick, circle] {Here!};
\end{codeexample}
%
Note that there is no comma between consecutive uses of the colon syntax in
this case. We could have exchanged the order of the options and the uses of the
colon syntax:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node
:fill opacity = { 0s="1", 2s="0", begin on=click }
[fill = blue!20, draw = blue, ultra thick, circle]
:rotate = { 0s="0", 2s="90", begin on=click } {Here!};
\end{codeexample}
We can also use the special syntax with the |\tikz| command itself:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz :fill opacity = { 0s="1", 2s="0", begin on=click }
:rotate = { 0s="0", 2s="90", begin on=click }
[ultra thick]
\node [fill = blue!20, draw = blue, circle] {Here!};
\end{codeexample}
Note that we could \emph{not} have moved the |[ultra thick]| options before
|:rotate| since the options in square brackets end the special parsing.
\subsubsection{The Time Syntax: Specifying Times}
For each object--attribute pair you must specify the \emph{timeline} of the
attribute. This is a curve that specifies for each ``moment in time'' which
value the attribute should have. In the simplest case, you specify such a
time--value pair as follows:
%
\begin{quote}
\normalfont
\meta{time} |="|\meta{value}|"|
\end{quote}
When you specify time--value pairs, you must specify the times in chronological
order (so earlier times come first), but you may specify the same time several
times (this is useful in situations where you have a ``jump'' from one value to
another at a certain moment in time: you first specify the value ``from which
the attribute jumps'' and then you specify the value ``to which the attribute
jumps'' for the same moment).
The above syntax is just a special case of a more general situation. Let us
start with the times. The general syntax for specifying times is as follows:
%
\begin{quote}
\normalfont
\meta{time} \opt{|=| \meta{options}}
\end{quote}
Here, \meta{time} is a text that ``looks like a time'', which means that:
%
\begin{enumerate}
\item It is not a key and does not contain a colon and does not start with
a quotation mark.
\item It starts with a digit, a plus or minus sing, a dot, or a
parenthesis.
\end{enumerate}
If these two things are the case, the above code is transformed to the
following call:
%
\begin{quote}
\normalfont
|sync = {time = |\meta{time}|, |\meta{options}|, entry}|
\end{quote}
\subsubsection{The Quote Syntax: Specifying Values}
We saw already in several examples that values are put in quotation marks
(similar to the way this is done in \textsc{xml}). This quote syntax is as
follows:
%
\begin{quote}
\normalfont
|"|\meta{value}|"| \opt{|base|} \opt{|=| \meta{options}}
\end{quote}
This syntax is triggered whenever a key starts with a quotation mark%
\footnote{Of catcode 12 for those knowledgeable of such things.} (and note that
when the \meta{value} contains a comma, you have to surround it by curly braces
\emph{inside} the quotation marks as in |"{(1,1)}"|). Then, the following code
is executed:
%
\begin{quote}
\normalfont
|sync = {value = |\meta{value}|, |\meta{options}|, entry}|
\end{quote}
This means that when you write |1s = "red"|, what actually happens is that
\tikzname\ executes the following:
%
\begin{codeexample}[code only]
sync = { time = 1s, sync = { value = red, entry }, entry }
\end{codeexample}
%
Note that the second entry has no effect since no value is specified and the
|entry| key only ``takes action'' when both a time and a value have been
specified. Thus, only the innermost |entry| does, indeed, create a time--value
pair as desired.
In addition to the above, if you have added |base| after the closing quote, the
following gets executed before the above |sync|:
%
\begin{quote}
\normalfont
|base = {value = |\meta{value}|}|
\end{quote}
This makes it easy to specify base values for timelines.
Interestingly, instead of |1s="red"| you can also write |"red"=1s|. Let us now
have a look at situations where this can be useful.
\subsubsection{Timesheets}
Using the |sync| key or using the three different syntactic constructs
introduced earlier (the color syntax, the time syntax, the value syntax), you
can organize the specification of an animation in different ways. Basically,
the two most useful ways are the following:
%
\begin{enumerate}
\item You first select an object and an attribute for which you wish to
establish a timeline and then provide the time--value pairs in a
sequence:
%
\begin{codeexample}[code only]
animate = {
obj:color = {
0s = "red",
2s = "blue",
1s later = "green",
1s later = "green!50!black",
10s = "black"
}
}
\end{codeexample}
%
When you specify timelines for several attributes of the same object,
you can group these together:
%
\begin{codeexample}[code only]
animate = {
obj: = {
:color = { 0s = "red", 2s = "green" },
:opacity = { 0s = "1", 2s = "0" }
}
}
\end{codeexample}
%
In this way of specifying animations the ``object comes first''.
\item Alternatively, you can also group the animation by time and, for each
``moment'' (known as \emph{keyframes}) you specify which values the
attributes of the object(s) have:
%
\begin{codeexample}[code only]
animate = {
0s = {
obj:color = "red",
obj:opacity = "1"
},
2s = {
obj:color = "green",
obj:opacity = "0"
}
}
\end{codeexample}
%
Naturally, in this case it would have been better to ``move the object
outside'':
%
\begin{codeexample}[code only]
animate = {
obj: = {
0s = {
:color = "red",
:opacity = "1"
},
2s = {
:color = "green",
:opacity = "0"
}
}
}
\end{codeexample}
%
When there are several objects involved, we can mix all of these
approaches:
%
\begin{codeexample}[code only]
animate = {
0s = {
obj: = {
:color = "red",
:opacity = "1"
},
main node: = {
:color = "black"
}
},
2s = {
obj: = {
:color = "green",
:opacity = "0"
},
main node: = {
:color = "white"
}
}
}
\end{codeexample}
%
\end{enumerate}
\subsection{The Attributes That Can Be Animated}
\label{section-anim-attrs}
The following \meta{attributes} are permissible (actually, the attribute names
do not include a colon, but since they will almost always be used with the
colon syntax, it makes it easier to identify them):
%
\begin{itemize}
\itemsep0pt
\item |:dash phase|
\item |:dash pattern|
\item |:dash|
\item |:draw opacity|
\item |:draw|
\item |:fill opacity|
\item |:fill|
\item |:line width|
\item |:opacity|
\item |:position|
\item |:path|
\item |:rotate|
\item |:scale|
\item |:stage|
\item |:text opacity|
\item |:text|
\item |:translate|
\item |:view|
\item |:visible|
\item |:xscale|
\item |:xshift|
\item |:xskew|
\item |:xslant|
\item |:yscale|
\item |:yshift|
\item |:yskew|
\item |:yslant|
\end{itemize}
These attributes are detailed in the following sections, but here is a quick
overview of those that do not have a \tikzname\ key of the same name (and which
thus do not just animate the attribute set using this key):
%
\begin{itemize}
\item |:shift| allows you to add an animated shifting of the canvas, just
like \tikzname's |shift| key. However, in conjunction with the |along|
key, you can also specify the shifting along a path rather than via a
timeline of coordinates.
\item |:position| works similar to |:shift|, only the coordinates are not
relative movements (no ``shifts''), but refer to ``absolute positions''
in the picture.
\item |:path| allows you to animate a path (it will morph). The ``values''
are now paths themselves.
\item |:view| allows you to animate the view box of a view.
\item |:visible| decides whether an object is visible at all.
\item |:stage| is identical to |:visible|, but when the object is not
animated, it will be hidden by default.
\end{itemize}
\subsubsection{Animating Color, Opacity, and Visibility}
\label{section-animation-painting}
You can animate the color of the target object of an animation using the
attributes |fill|, |draw|, and |text|. When the target of a color animation is
a scope, you animate the color ``used in this scope'' for filling or stroking.
However, when an object inside the scope has its color set explicitly, this
color overrules the color of the scope.
\begin{tikzanimateattribute}{fill, draw}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz :fill = {0s = "red", 2s = "blue", begin on = click}
[text = white, fill = orange ] {
\node [fill] at (0mm,0) {A};
\node [fill] at (5mm,0) {B};
\node [fill = green!50!black ] at (1cm,0) {C};
}
\end{codeexample}
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{text}
The |text| attribute only applies to nodes and you need to directly animate
the |text| attribute of each node individually.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [my anim/.style={ animate = {
myself:text = {0s = "red", 2s = "blue", begin on = click}}},
text = white, fill = orange ] {
\node [fill, my anim] at (0,0) {A};
\node [fill, my anim] at (1,0) {B};
}
\end{codeexample}
%
Unlike the |fill| and |draw| colors, you cannot animate the |text| color
for scopes:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz [animate = {myself:text = {0s = "red", 2s = "blue",
begin on = click}},
text = white, fill = orange ] {
\node [fill] at (0,0) {A};
\node [fill] at (1,0) {B};
}
\end{codeexample}
%
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{color}
The |color| attribute is not really an attribute. Rather, it is a shorthand
for |{draw,fill,text}|. This means that |color| does not start a separate
timeline, but continues the |draw| timeline, the |fill| timeline, and the
|text| timeline.
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{opacity, fill opacity, stroke opacity}
Similarly to the color, you can also set the opacity used for filling and
for drawing using the attributes |fill opacity| and |draw opacity|, which
are exactly the same as the usual \tikzname\ keys of the same names.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :fill opacity = { 0s="1", 2s="0", begin on=click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
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.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :opacity = { 0s="1", 2s="0", begin on=click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{visible, stage}
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|.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1,2,3,4},
]
\tikz :visible = {begin on=click, 0s="false", 2s="false"}
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\end{codeexample}
This |stage| attribute is the same as the |visible| attribute, only
|base="false"| is set by default. This means that the object is \emph{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''.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={-1,0,1,2,3},
animation bb={(1.3,-0.7) rectangle (2.7,0.7)},
]
\tikz [animate = {example:stage = {
begin on = {click, of next=node},
0s="true", 2s="true" }}] {
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\node at (2,0) (example) [fill = blue!20, circle] {Effect};
}
\end{codeexample}
\end{tikzanimateattribute}
\subsubsection{Animating Paths and their Rendering}
\label{section-animation-paths}
The attributes of the appearance of a path that you can animate include the
line width and the dash pattern, the path itself, as well as the arrow tips
attached to the paths. Animating the line width and the dash pattern is easy
since the animation attributes simply have that same names as the properties
that they animate and the syntax for setting is also the same:
\begin{tikzanimateattribute}{line width}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :line width = { 0s="1pt", 2s="5mm", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
Note that you must specify number (or expressions that evaluate to numbers)
as values, you cannot say |thin| or |thick| (these are styles, internally,
and you also cannot say |line width=thick|).
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{dash, dash phase, dash phase}
The values for an animation of the dashing are specifications (see the
|dash| key for details) consisting of a sequence of |on| and |off| numbers.
In each value of the animation the length of these sequences \emph{must} be
identical. The interpolation of the values is done for each position of the
sequences individually, and also on the phase.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :dash = { 0s="on 10pt off 1pt phase 0pt",
2s="on 1pt off 10pt phase 0pt", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :dash = { 0s="on 1cm off 1pt phase 0pt",
2s="on 1cm off 1pt phase 1cm", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
This |dash pattern| key allows you to animate the dash phase only. However,
due to the way dashing is handled by certain drivers, the dash pattern is
also set, namely to the current dash pattern that is in force when the
animation is created.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :dash phase = { 0s="0pt", 2s="1cm", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle, dashed] {Click me!};
\end{codeexample}
%
\end{tikzanimateattribute}
The above attributes ``only'' influence how the path is rendered. You can,
however, also animate the path itself:
\begin{tikzanimateattribute}{path}
When you animate a path, the values are, of course, paths themselves:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :path = {
0s = "{(0,-1) .. controls (0,0) and (0,0) .. (0,1) -- (1,1)}",
2s = "{(0,-1) .. controls (-1,0) and (-1,0) .. (-1,1) -- (.5,-1)}",
begin on=click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
There a number of things to keep in mind when you animate a path:
%
\begin{itemize}
\item The path ``values'' are parsed and executed in an especially
protected scope to ensure that they have only little side effects,
but you should not do ``fancy things'' on these paths.
\item 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 |rectangle| and at |2s| is a circle using |circle|. Instead,
you would have to ensure that at both times the path consists of
appropriate Bézier curves (which is cumbersome as the following
example shows, where we used the fact that a circle consists of
four Bézier curves):
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :path = {
0s = "{(0,0) circle [radius=1cm]}",
2s = "{(0,0)
(1,0) .. controls +(0,0) and +(0,0) .. (0,1)
.. controls +(0,0) and +(0,0) .. (-1,0)
.. controls +(0,0) and +(0,0) .. (0,-1)
.. controls +(0,0) and +(0,0) .. (1,0)
-- cycle (0,0)}",
begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\item You must specify arrow tips for an animated path in a special
way, namely using the |arrows| key for \emph{animations}, not the
normal |arrows| key (see below).
\end{itemize}
\end{tikzanimateattribute}
\begin{key}{/tikz/animate/arrows=\meta{arrow spec}}
This key only has an effect on |:path| animations. It causes the arrow tips
specified in \meta{arrow spec} to be added to the path during the animation
(the syntax is the same as for the normal |arrows| key). If you have
several different animations for a paths, these may contain different arrow
tips, but each animation must stick to one kind of arrow tips.
What happens internally when this key is used is the following: The
specified arrow tips are rendered internally as so-called \emph{markers,}
which are small graphics that can be placed at the beginning and ends of
paths and which ``rotate along'' as a path changes. Note that these markers
are used \emph{only} in the context of animated paths, the arrow tips of
normal, ``static'' paths are drawn without the use of markers. Normally,
there is no visual difference between an arrow tip drawn using markers or
those drawn for static paths, but in rare cases there may be differences.
You should only add arrows to open path consisting of a single segment with
sufficiently long first and last segments (so that \tikzname\ can shorten
these segments correctly when necessary).
As pointed out earlier, the only way to add arrow tips to a path that is
animated is using this key, you can \emph{not} say something like
%
\begin{codeexample}[code only]
\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}" }
[->] (0,0) -- (1,0);
\end{codeexample}
%
This will raise an error since you try to animate a path (|:path = ...|)
that has normal arrow tips attached (|[->]|).
Instead, you must specify the arrow tips inside the animation command:
%
\begin{codeexample}[code only]
\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}", arrows = -> }
(0,0) -- (1,0);
\end{codeexample}
However, the above code now has a big shortcoming: While the animation is
\emph{not} running, \emph{no} arrow tip is shown (the |arrows| key only
applies to the animation.
The trick is to use the |base| key. It allows you to install a path as the
``base'' path that is used when no animation is running and the arrows
specified for the animation will also be used for the base. All told, the
``correct'' way to specify the animation is the following (note that no
static path is specified, any specified path would be overruled by the
|base| path anyway):
%
\begin{codeexample}[code only]
\draw :path = { 1s = "{(0,0) -- (1,0)}" base, 2s = "{(0,1) -- (1,0)}", arrows = -> };
\end{codeexample}
Here is an example:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
animation bb={(-0.1,-0.1) rectangle (1.1,1.1)},
]
\tikz [very thick] {
\node (node) at (-2,0)
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
\draw :path = {
0s = "{(0,0) to[out=90, in=180] (.5,1) to[out=0, in=90] (.5,.5)}" base,
2s = "{(1,0) to[out=180, in=180] (.25,.5) to[out=0, in=180] (1,.5)}",
arrows = <.<->, begin on = {click, of=node} }; }
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/animate/shorten < = \meta{dimension}}
\end{key}
\begin{key}{/tikz/animate/shorten > = \meta{dimension}}
For animated paths, just as the key |arrows| has to be passed to the
animation (to |:path|) instead of to the static path, the keys |shorten >|
and |shorten <| also have to be passed to the |:path| key.
\end{key}
\subsubsection{Animating Transformations: Relative Transformations}
In order to animate the canvas transformation matrix, you do not animate an
attribute called ``|:transform|''. Rather, there are several attributes that
all manipulate the canvas transformation matrix in different ways. These keys,
taken in appropriate combination, allow you to achieve any particular canvas
transformation matrix. All keys that animate the transformation matrix always
accumulate.
Let us start with the ``standard'' attributes that are also available as keys
in \tikzname:
\begin{tikzanimateattribute}{scale, xscale, yscale}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :scale = { 0s="1", 2s="0.2", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{rotate}
The |rotate| key adds an animation of the rotation:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :rotate = { 0s="45", 2s="90", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
Note that there is no |rotate around| attribute, but you can use the
|origin| key to change the origin of the rotation.
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{xskew, yskew, xslant, yslant}
The keys add an animation of the skew (given in degrees) or slant (given as
in the |xslant| and |yslant| key):
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :xskew = { 0s="0", 2s="45", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :xslant = { 0s="-1", 2s="1", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{xshift, yshift}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :shift = { 0s="{(0,0)}", 2s="{(5mm,-5mm)}",
begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :xshift = { 0s="0pt", 2s="5mm", begin on=click}
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\end{tikzanimateattribute}
\begin{tikzanimateattribute}{shift}
This |:shift| attribute can be animated in two ways. First, you can simply
specify a sequence of coordinates in the same way as you would use the
|shift| key in \tikzname:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz \node :shift = { 0s = "{(0,0)}", 2s = "{(5mm,-5mm)}",
begin on = click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
However, you can also specify the sequence of positions along which the
shift should occur in a different way, namely by \emph{specifying a path
along which the object should be moved.} This is often not only more
natural to do, but also allows you to specify movements along curves.
\begin{key}{/tikz/animate/options/along=\marg{path}\meta{|sloped| or
|upright|}\opt{| in|\meta{time}}%
}
Use this key with a |:shift| (or a |:position|) to make \tikzname\
shift the object by the coordinates along the \meta{path}. When this
key is used, the values may no longer be coordinates, but must be
fractions of the distance along the path. A value of |"0"| refers to
the beginning of the path and |"1"| refers to the end:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
\draw (1,.5) circle [radius=1mm];
\node :shift = {
along = {(0,0) circle[radius=5mm]} upright,
0s="0", 2s=".25", begin on=click }
at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
\end{key}
Following the \meta{path}, which must be put in braces, you must either
specify |upright| or |sloped|. In the first case, the to-be-animated object
is moved along the path normally (and stays ``upright''), whereas when you
use |sloped|, the object will be continuously rotated so that it always
points along the path.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
\draw (1,.5) circle [radius=1mm];
\node :shift = {
along = {(0,0) circle[radius=5mm]} sloped,
0s="0", 2s=".25", begin on=click }
at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
In most motion animations that use |along|, you will set the value for |0s|
to |"0"| and the value for some specific \meta{time} to |"1"|. Because of
this, you can add |in| \meta{time} after the path, to achieve exactly this
effect.
\end{tikzanimateattribute}
For the above attributes, it is not immediately clear which coordinate system
should be used for the animation. That is, when you move an object 1cm ``to the
right'', where is ``the right''? By default, movements and transformations like
|:shift| or |:scale| are relative to the \emph{animation coordinate system,}
which defaults to the local coordinate system of the to-be-animated object.
Consider the following example:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
\node :rotate = { 0s="0", 2s="45", begin on=click}
at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
Note how the node rotates around its center even though this center is at
position |(1,1)| in the picture's coordinate system. This is because |at (1,1)|
actually only does a shift of the coordinate system and the node is then drawn
at the origin of this shifted coordinate system. Since this shifted coordinate
system becomes the animation coordinate system, the rotation ``around the
origin'' is actually a rotation around the origin of the animation coordinate
system, which is at |(1,1)| in the picture's coordinate system.
Let us, by comparison, do a rotation of a scope surrounding the node where the
origin is not (yet) shifted:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
\scoped :rotate = { 0s="0", 2s="45", begin on={click, of next=n} }
\node (n) at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
Now the rotation is really around the origin of the picture.
Most of the time the animation coordinate system will be setup in the way ``you
expect'', but you can modify it using the following keys:
\begin{key}{/tikz/animate/options/origin=\meta{coordinate}}
Shifts the animation coordinate system by \meta{coordinate}. This has the
effect that the ``origin'' for scalings and rotations gets shifted by this
amount. In the following example, the point around which the rotation is
done is the right border at |(2,1)| since the origin of the animation is at
|(1,1)| relative to the picture's origin and the |origin| key shifts it one
centimeter to the right.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
\node :rotate = { 0s="0", 2s="45", begin on=click,
origin = {(1,0)}}
at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/animate/options/transform=\meta{transformation keys}}
While the |origin| key does only a shift, the |transform| key allows you to
add an arbitrary transformation to the animation coordinate system using
keys like |shift|, |rotate| or even |reset cm| and |cm|. In particular,
|origin=|\meta{c} has the same effect as |transform| |=|
|{shift=|\meta{c}|}|. Note that the transformation only influences the
animation, not the object itself.
As an example, when you say |transform={scale=2}|, an |:xshift| with a
value of |"1cm"| will actually shift the object by 2cm. Similarly, after
you say |transform={rotate=90,scale=2}|, the same |:xshift| of |"1cm"| will
actually shift the object by 2cm upwards.
Note that, internally, \tikzname\ has to invert the transformation matrix
resulting from the \meta{transformation keys} (plus the original animation
transformation matrix), which can by numerically instable when you use
ill-conditioned transformations.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
\node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
transform = {rotate=-90} }
at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
\node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
transform = {rotate=-45, scale=2} }
at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
}
\end{codeexample}
%
\end{key}
\subsubsection{Animating Transformations: Positioning}
The attributes for specifying transformations and, in particular, the |:shift|
attribute are always expressed in the local animation coordinate system. This
makes it easy to ``shift around a node a little bit'', but makes it hard to
move a node ``from one position to another'' since coordinates need to be
expressed relative to the node's coordinate system, which leads to all sorts of
problems: Suppose you wish to have a node move from $(1,1)$ to $(2,1)$ and then
to $(2,0)$. Now, if the node has already been placed at $(1,1)$ in the usual
manner using |at|, then from the ``node's point of view'' you need to move the
node to $(0,0)$, $(1,0)$, and $(1,-1)$. To make matters worse, when you use
named coordinates as in
%
\begin{codeexample}[code only]
\coordinate(A) at (1,1);
\coordinate(B) at (2,1);
\coordinate(C) at (2,0);
\end{codeexample}
%
and then say that the movement should be from |(A)| to |(B)| to |(C)|, what
should you expect? On the one hand, |(A)| and |(1,1)| should normally be
interchangeable; on the other hand, |(A)| is a specific point in the plane, no
matter from which coordinate system we look at it. It turns out that \tikzname\
will stick to the second interpretation and actually turn |(A)| into |(0,0)|
when it is parsed in the local coordinate system of a node starting at |(A)| --
while |(1,1)| will stay the same.
Because of all these confusing effects, there is another attribute |:position|,
which is similar to a |:shift|, but the coordinates are not interpreted in the
local coordinate system of the node, but in the coordinate system that is in
force when the |animate| key is used. For a node, this is \emph{prior} to the
setup of the node's coordinate system and, thus, usually the picture's
coordinate system.
\begin{tikzanimateattribute}{position}
Compare the two animations, one with |:position|, one with |:shift|.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
\draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
\node :position = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
%
Compare this to a shift:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
\draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
\node :shift = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
at (1,.5) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
%
You can use the |along| key with |:position| in the same way as with
|:shift|, which is especially useful for specifying that a node ``travels''
between positions of the canvas:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2},
]
\tikz {
\draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
\draw (1,1) circle [radius=1mm] (1.5,0) circle [radius=1mm];
\node :position = {
along = {(1,1) to[bend left] (1.5,0)} sloped in 2s,
begin on = click }
at (1,1) [fill = blue, opacity=.5, circle] {Click};
}
\end{codeexample}
%
\end{tikzanimateattribute}
\subsubsection{Animating Transformations: Views}
\label{section-animation-views}
The final method of changing the transformation matrix is to animate a
\emph{view}.
\begin{tikzanimateattribute}{view}
A view is a canvas transformation that shifts and scales the canvas in such
a way that a certain rectangle ``matches'' another rectangle: The idea is
that you ``look through'' a ``window'' (the view) and ``see'' a certain
area of the canvas. View animation do not allow you to do anything that
cannot also be done using the |shift| and |scale| keys in combination, but
it often much more natural to animate which area of a graphic you wish to
see than to compute and animate a scaling and shift explicitly.
In order to use a view, you first need to create a view, which is done
using the |meet| or |slice| keys from the |views| library, see
Section~\ref{section-library-views}. You can then animate the view using
the |view| attribute. The values passed to the |entry| key follow the same
syntax as the views in the |views| library (though you only animate the
to-be-viewed rectangle).
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations,views}},
animation list={0.5,1,1.5,2},
animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
]
\tikz [very thick] {
\node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
\draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
\begin{scope}[view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)},
animate = {myself:view = {
begin on = {click, of=node},
0s = "{(0,0) (2,2)}",
2s = "{(1,1) (1.5,1.5)}" }}]
\draw [red] (10mm,10mm) rectangle (15mm,15mm);
\node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
\end{scope}
}
\end{codeexample}
%
\end{tikzanimateattribute}
\subsection{Controlling the Timeline}
\label{section-anim-timeline}
We can already specify timelines by giving a sequence of times in
non-decreasing order along with corresponding values. In this section we have a
look at further options that allow us to extend or control the timeline.
\subsubsection{Before and After the Timeline: Value Filling}
When you specify the timeline, you specify it for a certain interval
$[t_1,t_2]$. By default, outside this interval the animation has no effect on
the to-be-animated attribute. The following keys allows you to change this:
\begin{key}{/tikz/animate/base=\meta{options}}
A ``base'' value is a value that is used for the attribute whenever the
timeline is \emph{not} active:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2,2.5},
]
\tikz \node [fill = green, text = white] :fill =
{ 1s = "red", 2s = "blue", base = "orange", begin on = click }
{Click me};
\end{codeexample}
Syntactically, the |base| key works much like special time syntax: It sets
up a local |sync| scope and executes the \meta{options} in it and creates
an |entry|. However, instead of setting the |time| attribute to a time, it
sets it to a special value that tells \tikzname\ that when the entry is
created, the current \meta{value} should be used as the |base| value.
This means that you can write |base = "orange"| as in the above example to
set the base. However, you can also use the |base| key in other ways; most
noticeably, you can use it \emph{after} some value:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2,2.5},
]
\tikz \node [fill = green, text = white] :fill =
{ 1s = {"red" = base}, 2s = "blue", begin on = click }
{Click me};
\end{codeexample}
Instead of using |base| as a key, you can also add |base| directly after
the quotes of a value. This is particularly useful for setting up a base
value that is also used in a timeline:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2,2.5},
]
\tikz \node [fill = green, text = white] :fill =
{ 1s = "red" base, 2s = "blue", begin on = click }
{Click me};
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/animate/options/forever}
This key causes the timeline to continue ``forever'' after the last time
with the last value. You can also think of this as having the animation
``freeze'' at the end.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2,2.5},
]
\tikz \node :fill = { 1s="red", 2s="blue", forever, begin on=click}
[fill = green!50!black, text = white] {Click me};
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list = {0.5,1,1.5,2,2.5},
]
\tikz \node [fill = green!50!black, text = white]
:fill = { 1s = "red", 2s = "blue", begin on = click }
{Click me};
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/animate/options/freeze}
An alias for |forever|.
\end{key}
\subsubsection{Beginning and Ending Timelines}
\label{section-anim-begin-end}
The \meta{time} used with the first use of the |entry| key in a timeline is the
start time and the \meta{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.
\begin{key}{/tikz/animate/options/begin=\meta{time}}
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 \meta{time} to a negative value.
Note that this key has no effect for snapshots.
\end{key}
\begin{key}{/tikz/animate/options/end=\meta{time}}
This key will truncate the timeline so that it ends \meta{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.
%
\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
\tikz \node [fill = green!50!black, text = white]
:rotate = { 1s = "0", 5s = "90", begin = 2s, end = 4s }
{Click me};
\end{codeexample}
%
\end{key}
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 \emph{event} happens using the following key:
\begin{key}{/tikz/animate/options/begin on=\meta{options}}
The \meta{options} will be executed with the path |/pgf/animation/events|
and will cause a new beginning to be added to the list of possible
beginnings for the timeline (so the uses of this key accumulate). Each
``beginning'' is just another possible ``moment |0s|'' for the timeline.
For instance, when the \meta{options} are set to |click|, then each time
the graph is clicked a moment |0s| starts for the timeline.
Most events are ``caused'' or ``happen to'' some object. For instance, the
|click| event happens when you click on a certain object. In order to
specify this object, use the following two keys inside the \meta{options}:
|of| and |of next|. If neither of these keys are given, the to-be-animated
object is used.
\begin{key}{/pgf/animation/events/of=\meta{id}\opt{|.|\meta{type}}}
This specifies a graphic object id in the same way as the |whom| key,
also with an optional \meta{type}. This is the object that ``causes''
the event to happen.
Unlike the |whom| key, which always refers to a not-yet-existing
object, this key always refers to an already existing object, namely to
the most recent use of the \meta{id}. In the following example, the
referenced object is the node with the label |2| since it is the most
recently referenced node with \meta{id} |X|.
%
\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
\tikz [very thick] {
\node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
\node (X) at (1,0.4) [fill = orange!20, draw = orange, circle] {2};
\node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}}
[fill = red!20, draw = red, rectangle] {Anim};
\node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3};
\node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
\end{codeexample}
\end{key}
\begin{key}{/pgf/animation/events/of next=\meta{id}\opt{|.|\meta{type}}}
This key works like the |of| key, only it refers to a future (actually,
the next) object with the given \meta{id}, not to a previous one. This,
in the next example, the referenced node is the one with label |3|.
%
\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
\tikz [very thick] {
\node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
\node (X) at (1,0.4) [fill = blue!20, draw = blue, circle] {2};
\node (node) :rotate = {
0s="0", 2s="90", begin on = {click, of next = X}}
[fill = red!20, draw = red, rectangle] {Anim};
\node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3};
\node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
\end{codeexample}
\end{key}
The following key allows you to specify the event that should cause the
animation to start:
%
\begin{key}{/pgf/animation/events/event=\meta{event name}}
Specifies the name of the event whose occurrence should start the
timeline. Which events are supported depends on the device on which the
animation is displayed, the output format (\textsc{svg} or some other
format), and the setup of scripts, but here is a list of events
supported by ``plain \textsc{svg}'': |click|, |focusin|, |focusout|,
|mousedown|, |mouseup|, |mouseover|, |mousemove|, |mouseout|, |begin|,
|end|. However, the following keys make using these events simpler:
%
\begin{key}{/pgf/animate/events/click}
This is a shorthand for |event=click|. This event gets triggered
when the user clicks on the triggering object with a mouse (or
something equivalent).
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}}
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/mouse down}
Shorthand for |event=mousedown|. The event gets triggered when the
user presses a mouse button down on the object.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}}
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/mouse up}
Shorthand for |event=mouseup| and gets triggered, of course, when a
pressed button is released on the object.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} }
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/mouse over}
Shorthand for |event=mouseover|. The event gets triggered the
moment the mouse cursor moves over the object.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} }
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/mouse move}
Shorthand for |event=mousemove|. The event gets triggered lots of
times, namely each time the mouse moves while being ``over'' the
object.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} }
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/mouse out}
Shorthand for |event=mouseout|. The opposite of |mouse over|:
triggered when the mouse leaves the object.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} }
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/begin}
Shorthand for |event=begin|. The ``begin'' refers to the beginning
of another animation, namely the one referenced by |of| or
|of whom|. This means that the current animation will begin when
some other animation begins.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node [animate = {
myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}},
myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim}
},
fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/end}
Shorthand for |event=end|. Again, the ``end'' refers to the end of
another animation, namely the one referenced by |of| or |of whom|.
This means that the current animation will \emph{begin} when some
other animation \emph{ends}.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node [animate = {
myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}},
myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim }
},
fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
%
\begin{key}{/pgf/animation/events/focus in}
This is a shorthand for |event=focusin|. This event gets triggered
when the graphic object gets the focus (this usually makes sense
only for text input fields).
\end{key}
%
\begin{key}{/pgf/animation/events/focus out}
This is a shorthand for |event=focusout|.
\end{key}
\end{key}
In addition to the events specified using the generic |event| key, there
are two further events that take a parameter:
%
\begin{key}{/pgf/animation/events/repeat=\meta{number}}
The event is triggered when a repeating animation has been repeated
\meta{number} times.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={
0.333/\frac{1}{3},0.666/\frac{2}{3},1,
1.333/1\frac{1}{3},1.666/1\frac{2}{3},2,
2.333/2\frac{1}{3},2.666/2\frac{2}{3},3,
3.333/2\frac{1}{3},3.666/2\frac{2}{3},4%
},
]
\tikz
\node [animate = { myself: = {
:rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim },
begin snapshot = 2 },
:xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}},
fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{key}
\begin{key}{/pgf/animation/events/key=\meta{key}}
The event is triggered when the keyboard key \meta{key} has been
pressed. For security reasons, a viewer may suppress this.
\end{key}
Having specified the event, you can also specify a delay relative to this
event:
\begin{key}{/pgf/animation/events/delay=\meta{time}}
Specifies that the timeline should not start with the event, but,
rather, be delayed by \meta{time}.
\end{key}
\end{key}
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
\emph{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:
\begin{key}{/tikz/animate/options/restart=\meta{choice} (default true)}
You can set \meta{choice} to one of the following:
%
\begin{itemize}
\item |true| means that the animation will restart each time the event
is triggered. If the animation is already running, it will be reset
to its beginning.
\item |false| means that once the animation has started once, it will
never be restarted.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90",
restart = false, begin on = {click}}
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
%
\item |never| means the same as |false|.
\item |when not active| means that the animation will restart when the
event is triggered, but \emph{not} while the animation is running.
%
\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
\tikz \node :rotate = { 0s="0", 2s="90",
restart = when not active, begin on = {click}}
[fill = blue!20, draw = blue, circle, ultra thick] {Here!};
\end{codeexample}
\end{itemize}
\end{key}
Just like |begin on| specifies when a timeline begins relative to some event,
the |end on| allows you to stop is early when some event happens:
\begin{key}{/tikz/animate/options/end on=\meta{options}}
Works exactly like |begin on|, one possible end of the timeline is
specified using the \meta{options}.
\end{key}
\subsubsection{Repeating Timelines and Accumulation}
\begin{key}{/tikz/animate/options/repeats=\meta{specification}}
Use this key to specify that the timeline animation should repeat at the
end. The \meta{specification} must consist of two parts, each of which may
be empty. The first part is one of the following:
%
\begin{itemize}
\item Empty, in which case the timeline repeats forever.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1,2,3,4,5},
]
\tikz \node :rotate = { 0s = "0", 2s = "90",
repeats, begin on = click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\item A \meta{number} (like |2| or |3.25|), in which case the timeline
repeats \meta{number} times.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1,2,3,4,5},
]
\tikz \node :rotate = { 0s = "0", 2s = "90",
repeats = 1.75, begin on = click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
which case the timeline repeats however often necessary so that it
stops exactly after \meta{time}.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1,2,3,4,5},
]
\tikz \node :rotate = { 0s = "0", 2s = "90",
repeats = for 3.5s, begin on = click }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
\end{itemize}
%
The second part of the specification must be one of the following:
%
\begin{itemize}
\item Empty, in which case each time the timeline is restarted, the
attribute's value undergoes the same series of values it did
previously.
\item The text |accumulating|. This has the effect that each time the
timeline is restarted, the last values specified by the timeline is
\emph{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.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1,2,3,4,5},
]
\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
repeats = accumulating }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={1,2,3,4,5},
]
\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
repeats = for 4s accumulating }
[fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
\end{codeexample}
\end{itemize}
\end{key}
\begin{key}{/tikz/animate/options/repeat=\meta{specification}}
An alias for |repeats|.
\end{key}
\subsubsection{Smoothing and Jumping Timelines}
\label{section-anim-smooth}
Your specification of the timeline will consist of a sequence of times along
with values that the attribute should have at these ``key times''. Between
these key times, the attribute's value needs to be interpolated.
Suppose that an animation is supposed to interpolate a attribute's value
between the two values |50| and |100| over a time of 10\,s. The simplest way of
doing so is to do a linear interpolation, where the value as, say, 1\,s is 55,
at 2\,s it is 60, and so on. Unfortunately, the linear interpolation does not
``look'' nice in many cases since the acceleration of a linear interpolation is
zero during the animation, but infinite at the beginning and at the end; which
looks ``jerky''.
To avoid this, you can specify that the time--attribute curve should not be a
straight line, but rather a curve. You specify this curve using a spline. The
most logical ``coordinate rectangle'' used for this spline in our example would
be |(0s,50)| and |(10s,100)| and we would like to specify something like
%
\begin{codeexample}[code only]
(0s,50) .. controls (5s,50) and (9s,100) .. (10s,100)
\end{codeexample}
%
This would result in a time--attribute curve where the attribute at |50|
changes slowly at 0\,s and also arrives slowly at |100| at 10\,s, but speeds up
between these values.
We call the first control point |(5s,50)| the ``exit control'' and call
|(9s,100)| the ``entry control'': The first control dictates how quickly or
slowly a time point is left, the second dictates how quickly or slowly we enter
the next one.
The control points are, however, not specified in the coordinate system
indicated above. Rather, the rectangle |(0s,50)| to |(10s, 100)| gets
normalized to |(0,0)| to |(1,1)|. The control point |(5s,50)| would thus become
|(0.5,0)| and |(9s,100)| becomes |(0.9,1)|.
\begin{key}{/tikz/animate/options/exit control=\marg{time fraction}\marg{value fraction}}
Specifies an exit control using two values as above. The spline from above
would be specified as follows:
%
\begin{codeexample}[code only]
exit control={0.5}{0},
entry control={0.9}{1},
0s = "50",
10s = "100"
\end{codeexample}
Note that the curve specified using exit and entry controls must be
``well-behaved'' in the sense that exactly one value must be specified for
each point in time in the time interval.
In the next three example, we first specify a ``smooth'' exit from the
start position, then a smooth arrival at the end position, and, finally
both.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
]
\tikz {
\foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
\node :yshift = { begin on = click,
0s = { exit control = {1}{0}, "0cm" },
1s = "-5mm",
2s = "-10mm" }
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
]
\tikz {
\foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
\node :yshift = { begin on = click,
0s = "0cm",
1s = "-5mm",
2s = { entry control = {0}{1}, "-10mm" } }
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
]
\tikz {
\foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
\node :yshift = { begin on = click,
0s = { exit control = {1}{0}, "0cm" },
1s = "-5mm",
2s = { entry control = {0}{1}, "-10mm" } }
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/animate/options/entry control=\marg{time fraction}\marg{value fraction}}
Works like |exit control|.
\end{key}
\begin{key}{/tikz/animate/options/ease in=\marg{fraction} (default 0.5)}
A shorthand for |entry control={1-|\meta{fraction}|}{1}|.
\end{key}
\begin{key}{/tikz/animate/options/ease out=\marg{fraction} (default 0.5)}
A shorthand for |exit control={|\meta{fraction}|}{1}|.
\end{key}
\begin{key}{/tikz/animate/options/ease=\marg{fraction} (default 0.5)}
A shorthand for |ease in=|\meta{fraction}|, ease out=|\meta{fraction}.
Note that since for the first time the entry control is ignored and,
similarly, for the last time the exit control is ignored, using the |ease|
key with an animation having only two times is particularly easy, since we
only need to set |ease| once:
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
]
\tikz {
\foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
\node :yshift = { begin on = click, ease, 0s = "0cm", 2s = "-10mm" }
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
%
\end{key}
The opposite of having a smooth curve between two values, is to have a ``jump''
from one value to the next. There are two keys for this:
\begin{key}{/tikz/animate/options/stay}
Specifies that inside the time interval the value ``stays put'' at the
first value till the end of the interval, where it will jump to the second
value. This is similar to an exit control where the curve is ``infinitely
flat''.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2,2.5},
]
\tikz {
\foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
\node :yshift = { begin on = click,
0s = "0cm",
1s = {stay, "-5mm"},
2s = "-10mm" }
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/animate/options/jump}
Works like the |stay| key, but will cause the value to ``jump to'' the new
value right at the beginning of the time interval. It is similar to an
entry control specifying a ``flat'' curve.
%
\begin{codeexample}[
preamble={\usetikzlibrary{animations}},
animation list={0.5,1,1.5,2,2.5},
]
\tikz {
\foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
\node :yshift = { begin on = click,
0s = "0cm",
1s = {jump, "-5mm"},
2s = "-10mm" }
[fill = blue!20, draw = blue, very thick, circle] {Click me!};
}
\end{codeexample}
%
\end{key}
\subsection{Snapshots}
\label{section-anim-snap}
Snapshots are a way of taking a ``photographic snapshot'' of an animation at a
certain time and then insert these into \textsc{pdf} files (or, for that
matter, Postscript files or files in any other format, including \textsc{svg}):
You specify a time like |2s| and then \tikzname\ will compute what the
animation ``would look like after 2s'' and insert the necessary graphics
command for rendering the graphic objects in the correct way. Since this
computation is done by \tikzname\ and since only ``normal'' graphics command
are inserted into the output, snapshots work with all output formats.
Apart from providing a fallback for \textsc{pdf}, snapshots are very useful by
themselves: They make it easy to ``show'' how an animation unfolds on paper.
For this, you simply typeset the same picture with the same animation several
times (using a simple |\foreach| loop), but each time you set a different
snapshot time. This will result in a sequence of pictures that depict the
animation at different points in time and which can then be inserted alongside
each other into the printed document. This approach has been used with the
examples of animations in this manual.
%
\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
\foreach \t in {0.5, 1, 1.5, 2}
\tikz [make snapshot of = \t]
\fill :fill = {0s="black", 2s="red"} (0,0) circle [radius = 5mm];
\end{codeexample}
Creating snapshots is done using the following key:
\begin{key}{/tikz/make snapshot of=\meta{time}}
When this key is used in a \TeX\ scope, animation commands given in the
scope do not add animation code to the output. Instead, \tikzname\ computes
the values the attributes of the animation would have at the specified
\meta{time} and inserts the necessary system layer command to set the
attribute to the computed values (some care has been taken to make this
computation match the computations done by viewer applications as best as
possible).
%
\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
\tikz [make snapshot of = 1s] {
\fill :fill = { 0s = "black", 2s = "white" } (0,0) rectangle ++(1,1);
\fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
}
\end{codeexample}
The moment \meta{time} is best thought of as \meta{time} seconds after the
``moment zero'' where all timelines start by default. Now, ``real''
animation may start at different time through user interaction, which
clearly makes no sense for snapshots. Nevertheless, you will sometimes wish
to have more control over when a timeline starts for the purposes of taking
snapshots. You can use the following key for this:
\begin{key}{/tikz/animate/options/begin snapshot=\meta{start time}}
Use this key on a timeline to specify that, only for purposes of taking
snapshots, the timeline starts at \meta{start time} rather than at
``moment zero''. (Think of this as saying that the animation starts
when a virtual user clicks on the animation and this click occurs
\meta{start time} seconds after the general ``moment zero'', causing
the animation to ``lag behind'' by this amount of time.)
Computationally, for the timeline the \meta{start time} is subtracted
from the snapshot's \meta{time} when the value needs to be determined:
%
\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
\tikz [make snapshot of = 1s] {
\fill :fill = { 0s = "black", 2s = "white",
begin snapshot = 1s } (0,0) rectangle ++(1,1);
\fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
}
\end{codeexample}
\end{key}
The computations of the values the animation ``would have'' are done
entirely by \tikzname, which has the big advantage is that no support from
the viewer application or the output format is needed -- snapshots work
with all output formats, not just with \textsc{svg}. However, computations
done by \tikzname\ are not always very precise and can be slow because of
\TeX's limitations. In addition, there are some further limitations when it
comes to \tikzname's computation of snapshot values:
%
\begin{itemize}
\item As mentioned above, except for |begin snapshot|, other commands
for specifying the beginning or end of a timeline based on user
interaction make no sense for timelines: The keys |begin|,
|begin on|, |end|, and |end on| are silently ignored.
\item The value |current value| for a value is forbidden since this
value is almost impossible to compute by \tikzname.
\item Accumulating repeats of a motion are (currently) not supported,
but should not rely on this.
\end{itemize}
When \meta{time} is empty, ``snapshot taking'' is switched off and
animation commands are inserted once more.
\end{key}
\begin{key}{/tikz/make snapshot after=\meta{time}}
Works exactly like |make snapshot of|, only the \meta{time} is interpreted
as $\meta{time} + \epsilon$. This only makes a difference at the end of a
timeline and when there are two or more values specified for the same time:
When there are several values specified for time~$t$, a normal snapshot for
time~$t$ uses the first value given for the attribute. In contrast, this
command would use the last one given. Similarly, when an animation timeline
ends at time $t$, a normal snapshot of time $t$ would use the last value of
the timeline, while this key would not apply the animation at all (it has
already ended at time $t + \epsilon$).
%
\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
\tikz [make snapshot of = 2s]
\fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
\tikz [make snapshot after = 2s]
\fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
\end{codeexample}
%
\end{key}
\begin{key}{/tikz/make snapshot if necessary=\meta{time} (default 0s)}
This key makes a snapshot of \meta{time} only when the output format does
not provide support for animations; if the output format supports
animations (like \textsc{svg}), then the command has no effect and
animations are created normally.
This manual is typeset with the following being set once are for all in
preamble:
%
\begin{codeexample}[code only]
\tikzset{make snapshot if necessary}
\end{codeexample}
Because of this setting, in the \textsc{pdf} version of this document, all
animations are shown at the value they would have at moment~$0s$. In
contrast, in the \textsc{svg} version, the animations are created normally.
In both versions, the smaller pictures showing how the animation proceeds
over time are created using |make snapshot of| for the indicated times.
\end{key}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End: