% Copyright 2007--2008 Alexander Grahn
%
% This material is subject to the LaTeX Project Public License. See
%    http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
% for the details of that license.
%
\documentclass[a4paper]{article}
\frenchspacing
\usepackage[UKenglish]{babel}
\usepackage{pst-3dplot}
\usepackage{animate}
\usepackage{intcalc}
\usepackage{graphicx}
\usepackage{color}
\usepackage{textcomp}
\usepackage{lmodern}
\usepackage{mflogo}
\usepackage[T1]{fontenc}
\usepackage{microtype}
\usepackage{ifpdf}
\usepackage{parskip}
\usepackage{hyperref}
\usepackage[all]{hypcap}
\clubpenalty=10000
\widowpenalty=10000
\displaywidowpenalty=10000

\makeatletter
\renewcommand{\fnum@figure}[1]{\figurename~\thefigure}
\newcommand\myparagraph{\@startsection{paragraph}{3}{\z@}%
                                     {\parskip}%
                                     {0.001\parskip}%
                                     {\itshape\normalsize}}
\makeatother

\ifpdf
  \makeatletter
  \@latex@error{Please use LaTeX to compile this documentation}
  \makeatother
\fi

\def\keywords{include portable PDF animation animated PDF animating embed animated graphics LaTeX pdfLaTeX PSTricks pgf TikZ LaTeX-picture MetaPost inline graphics vector graphics animated GIF LaTeX dvips ps2pdf dvipdfmx XeLaTeX JavaScript Adobe Reader}
\hypersetup{
  bookmarksnumbered,linktocpage,breaklinks,
  pdftitle={The animate Package},
  pdfsubject={Documentation},
  pdfauthor={Alexander Grahn},
  pdfkeywords={\keywords},
  citebordercolor={0 0 1},
  filebordercolor={0 0 1},
  linkbordercolor={0 0 1},
  menubordercolor={0 0 1},
  pagebordercolor={0 0 1},
  urlbordercolor={0 0 1},
%  pdfpagelayout=SinglePage
}

\def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX}
\def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX}

\begin{document}
\title{The {\sffamily animate} Package}
\author{Alexander Grahn \animategraphics[autoplay,loop,height=1.8ex]{8}{bye_}{0}{3}\protect\footnote{Animated GIF taken from \href{http://www.phpBB.com}{phpBB} forum software and burst into a set of EPS files using \href{http://www.imagemagick.org}{ImageMagick} before embedding. Animations may run slowly if viewed in the Adobe Reader browser plugin.}\\[1ex]\includegraphics[height=2.7ex]{mailto}}
\maketitle

\begin{abstract}
\raggedright

\noindent A LaTeX package for creating portable, JavaScript driven PDF animations from sets of vector graphics or rasterized image files or from inline graphics.
\vskip 0.2\baselineskip

\emph{Keywords}: \keywords
\end{abstract}

\tableofcontents

%\newpage
\section{Introduction}
This package provides an interface to create PDFs with animated content from sets of graphics or image files, from inline graphics, such as \LaTeX-picture, PSTricks or pgf/TikZ generated pictures, or just from typeset text. Unlike standard movie/video formats, which can be embedded, for example, using the \LaTeX{} package `movie15'~\cite{movie15}, package `animate' allows for animating vector graphics. The result is roughly similar to the SWF (Flash) format, although not as space-efficient.

Package `animate' supports the usual PDF making workflows, i.\,e. pdf\LaTeX{}, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+.

The final PDF can be viewed in current Adobe Readers on all supported platforms.

%The `animate' package relies on Optional Content Groups (OCG), also known as PDF layers, which is a feature provided by the PDF-1.5 specification. Each frame of an animation is associated with an OCG that is hidden or made visible in a dynamic fashion by means of Adobe Reader's built-in JavaScript engine.

\section{Requirements}
\begin{trivlist}
\item $\varepsilon$-\TeX
\item pdf\TeX{}, version $\ge1.20$ for direct PDF output
\item Ghostscript, version $\ge8.31$ or Adobe Distiller for PS to PDF conversion
\item dvipdfmx, version $\ge20080607$ for DVI to PDF conversion
\item Adobe Reader, version $\ge7$
\end{trivlist}

\section{Installation}
Unzip the file \href{http://tug.ctan.org/tex-archive/install/macros/latex/contrib/animate.tds.zip}{`animate.tds.zip'} into the local TDS root directory which can be found by running `\verb+kpsewhich -var-value TEXMFLOCAL+' on the command line.

After installation, update the filename database by running `\verb+texhash+' on the command line.

MiK\TeX{} users should run the package manager for installation.

\section{Using the package}
First of all, read Section~\ref{sect:bugs} on problems related to this package. Then, invoke the package by putting the line
\begin{verbatim}
\usepackage[<package options>]{animate}
\end{verbatim}
to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+.

`animate' honours the package options:
\begin{verbatim}
dvipdfmx
xetex
autoplay
autopause
autoresume
loop
palindrome
draft
final
controls
buttonsize=<size>
buttonbg=<colour>
buttonfg=<colour>
step
useocg
poster[=first | none | last]
\end{verbatim}
Except for `\verb+dvipdfmx+' and `\verb+xetex+', the options above are also available (among others) as command options and will be explained shortly. However, if used as package options they have global scope, taking effect on all animations in the document. In turn, command options locally override global settings. Options without an argument are boolean options and can be negated, with the exception of package-only options `\verb+dvipdfmx+' and `\verb+xetex+', by appending `\verb+=false+'.

If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, the `graphicx' package is required. \emph{Important:} The \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-X 2400 -Y 2400+' \emph{after} `\verb+-Ppdf+' on the command line. Sometimes, if the same animation sequence made from graphics files is to be embedded multiple times into the document, more compact PDF output may be obtained by passing option `\verb+-dMaxInlineImageSize=0+' (Unix) or `\verb+-dMaxInlineImageSize#0+' (Win/DOS) to \verb+ps2pdf+.

\XeLaTeX{} and \verb+dvipdfmx+ require the `graphicx' package to be loaded. While \XeLaTeX{} will be auto-detected (package option `\verb+xetex+' is optional), `animate' and `graphicx' need the package option `\verb+dvipdfmx+' in the case of \verb+dvipdfmx+.

Occasionally, a second \LaTeX{} run may be necessary to resolve internally created object references. An appropriate warning will be issued in such a case.

\section{The user interface}
Package `animate' provides the command
\begin{verbatim}
\animategraphics[<options>]{<frame rate>}{<file basename>}{<first>}{<last>}
\end{verbatim}
and the environment
\begin{verbatim}
\begin{animateinline}[<options>]{<frame rate>}
    ... typeset material ...
\newframe[<frame rate>]
    ... typeset material ...
\newframe*[<frame rate>]
    ... typeset material ...
\newframe
\multiframe{<number of frames>}{[<variables>]}{
  ... repeated (parameterized) material ...
}  
\end{animateinline}
\end{verbatim}

While \verb+\animategraphics+ can be used to assemble animations from sets of existing graphics files or from multipage PDF, the environment `\verb+animateinline+' is meant to create the animation from the typeset material it encloses. This material can be pictures drawn within the \LaTeX{} `\verb+picture+' environment or using the advanced capabilities of PSTricks or pgf/TikZ. Even ordinary textual material may be animated in this way. The parameter \verb+<frame rate>+ specifies the number of frames per second of the animation.

The command \verb+\newframe+ terminates a frame and starts the next one. It can be used inside the `\verb+animateinline+' environment only. There is a starred variant, \verb+\newframe*+. If placed after a particular frame it causes the animation to pause at that frame. The animation continues normally after clicking it again. Both \verb+\newframe+ variants take an optional argument that allows to change the frame rate in the middle of an animation.

The command \verb+\multiframe+ allows to build loops around pictures. The first argument \verb+<number of frames>+ does what one would expect it to do, the second argument \verb+<variables>+ is a comma-separated list of variable declarations. The list may be of arbitrary, even zero, length. Variables may be used to parameterize pictures which are defined in the loop body (third argument of \verb+\multiframe+). A single variable declaration has the form
\begin{verbatim}
  <variable name>=<initial value>+<increment>
\end{verbatim}
\verb+<variable name>+ is a sequence of one or more letters \emph{without} a leading backslash\footnote{This is different from {\tt\string\multido} (package `multido') where variable names have a leading `{\tt\textbackslash}' in the declaration.}. The first (and possibly only) letter of the variable name determines the type of the variable. There are three different types: integers (`\verb+i+', `\verb+I+'), reals (`\verb+n+', `\verb+N+', `\verb+r+', `\verb+R+') and dimensions or \LaTeX{} lengths (`\verb+d+', `\verb+D+'). Upon first execution of the loop body, the variable takes the value \verb+<initial value>+. Each further iteration increments the variable by \verb+<increment>+. Negative increments must be preceded by `\verb+-+'. Here are some examples: `\verb:i=1+2:', `\verb:Rx=10.0+-2.25:', `\verb:dim=20pt+1ex:'. Within the loop body, variables are expanded to their current value by prepending a backslash to the variable name, that is \verb+\i+, \verb+\Rx+ and \verb+\dim+ according to the previous examples. \verb+\multiframe+ must be surrounded by \verb+\begin{animateinline}+ and \verb+\end{animateinline}+ or by any of the \verb+\newframe+ variants. Two consecutive \verb+\multiframe+ commands must be separated by one of the \verb+\newframe+ variants.

By default, the animation is built frame by frame in the order of inclusion of the embedded material. However, extended control of the order of appearance, superposition and repetition of the material is available through the `\verb+timeline+' option (see Section~\ref{sect:timeline}).

\myparagraph*{Sets of graphics files}
All files of the sequence should exist and be consecutively numbered. (Exception to this rule is allowed in connection with the `\verb+every+' option, see below.) {\tt <file base\-name>} is the leftmost part of the file name that is common to all members of the sequence. \verb+<first>+ is the number of the first and \verb+<last>+ the number of the last file in the set. File names may be simply numbered, such as $0\dots99$. If there are leading zeros, make sure that all file numbers have the same number of digits, such as $0000\dots0099$, and that the \verb+<first>+ and \verb+<last>+ arguments are filled in accordingly.

There is no file name extension to be specified as a parameter. The possible file formats depend on the output driver being used. In the case of \LaTeX{}+\verb+dvips+, files with the extension `eps' are searched for at first, followed by `mps' (\MP-generated Postscript) and `ps'. With pdf\LaTeX{} the searching order is: (1)~`pdf', (2)~`mps', (3)~`png', (4)~`jpg', (5)~`jpeg', (6)~`jbig2', (7)~`jb2', (8)~`jp2'\footnotemark[1], (9)~`j2k'\footnotemark[1], (10)~`jpx'\footnotemark[1]\footnotetext[1]{JPEG2000 is not yet supported by pdf\TeX.} and with \XeLaTeX{} or \LaTeX{}+\verb+dvipdfmx+: (1)~`pdf', (2)~`mps', (3)~`eps', (4)~`ps', (5)~`png', (6)~`jpg', (7)~`jpeg', (8)~`bmp'. That is, files capable to store vector graphics are found first. Make sure that all file names have \emph{lower case} extensions.

For example, given the sequence `frame\_5.png' through `frame\_50.png' from a possibly larger set that shall be used to build an animation running at 12 frames per second. Then, the correct inclusion command reads
\begin{verbatim}
  \animategraphics{12}{frame_}{5}{50}
\end{verbatim}

\myparagraph*{Multipage PDF {\rm(pdf\LaTeX, \XeLaTeX)} and JBIG2 {\rm(pdf\LaTeX)} inclusion}
If the file `\verb+<file basename>+.(pdf|jbig2|jb2)' exists (again, there is no file name extension to be specified), it is taken as a multipage document where each page represents one frame of the animation. In this case, the last two arguments, \verb+<first>+ \& \verb+<last>+, are interpreted differently from above; they specify a zero-based range of pages to be included in the animation. Either or both of them may be left empty, `\verb+{}+', in which case they default to $0$ and $n-1$, where $n$ is the total number of available pages. Arguments that fall outside this range are automatically corrected to the maximum allowed number, i.\,e. $n-1$.

For example, the line
\begin{verbatim}
  \animategraphics{12}{frames}{}{}
\end{verbatim}
would create an animation from all pages of the file `frames.pdf', running at 12 fps.

\section{Command options}
The following options to \verb+\animategraphics+ and `\verb+animateinline+' have been provided:
\subsection{Basic options}
\begin{verbatim}
poster[=first | none | last]
\end{verbatim}
Specifies which frame (first, last or none) to display and print if the animation is not activated. The first frame is shown by default. Thus `\verb+poster+' or `\verb+poster=first+' need not be explicitly set.
\begin{verbatim}
every=<num>
\end{verbatim}
Build animation from every \verb+<num>+\emph{th} frame only. Skipped frames are discarded and not embedded into the document. In the case of \verb+\animategraphics+, skipped input files may be missing.
\begin{verbatim}
autopause
\end{verbatim}
Pause animation when the page is closed, instead of stopping and rewinding it to the default frame.
\begin{verbatim}
autoplay
\end{verbatim}
Start animation after the page has opened. Also resumes playback of a previously paused animation.
\begin{verbatim}
autoresume
\end{verbatim}
Resume previously paused animation when the page is opened again.
\begin{verbatim}
loop
\end{verbatim}
The animation restarts immediately after reaching the end.
\begin{verbatim}
palindrome
\end{verbatim}
The animation continuously plays forward and backward.
\begin{verbatim}
step
\end{verbatim}
Step through the animation by one frame per mouse-click. The \verb+<frame rate>+ argument will be ignored.
\begin{verbatim}
width=<width>
height=<height>
depth=<depth>
\end{verbatim}
Resize the animation widget. Option `\verb+depth+' specifies how far the animation widget should extend below the bottom line of the running text. If only one or two of these options are given, the remaining, unspecified dimensions are scaled to keep the aspect ratio. Any valid \TeX{} dimension is accepted as a parameter. Moreover, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ may be used to refer to the original dimensions of the animation widget which correspond to the size of the first frame of the animated sequence.
\begin{verbatim}
scale=<factor>
\end{verbatim}
Scales the animation widget by \verb+<factor>+.
\begin{verbatim}
bb=<llx> <lly> <urx> <ury>
\end{verbatim}
(\verb+\animategraphics+ only, requires package `graphicx'.) The four, space separated arguments set the bounding box of the graphics files. Units can be omitted, in which case `bp' (Postscript points) is assumed.
\begin{verbatim}
viewport=<llx> <lly> <urx> <ury>
\end{verbatim}
(\verb+\animategraphics+ only, requires package `graphicx'.) This option takes four arguments, just like `\verb+bb+'. However, in this case the values are taken relative to the origin specified by the bounding box in the graphics files.
\begin{verbatim}
trim=<left> <bottom> <right> <top>
\end{verbatim}
(\verb+\animategraphics+ only, requires package `graphicx'.) Crops graphics at the edges. The four lengths specify the amount to be removed from or, if negative values have been provided, to be added to each side of the graphics.
\begin{verbatim}
controls
\end{verbatim}
Inserts control buttons below the animation widget. The meaning of the buttons is as follows, from left to right: stop \& first frame, step backward, play backward, play forward, step forward, stop \& last frame, decrease speed, default speed, increase speed. Both `play' buttons are replaced by a large `pause' button while the animation is playing.
\begin{verbatim}
buttonsize=<size>
\end{verbatim}
Changes the control button height to \verb+<size>+, which must be a valid \TeX{} dimension. The default button height is \verb+1.44em+ and thus scales with the current font size.
\begin{verbatim}
buttonbg=<colour>
buttonfg=<colour>
\end{verbatim}
By default, control button widgets are drawn with black strokes on transparent background. The background can be turned into a solid colour by the first option, while the second option specifies the stroke colour. The parameter \verb+<colour>+ is an array of colon-(\verb+:+)-separated numbers in the range from 0.0 to 1.0. The number of array elements determines the colour model in which the colour is defined: (1) gray value, (3) RGB, (4) CMYK. For example, `\verb+1+', `\verb+1:0.5:0.2+' and `\verb+0.5:0.3:0.7:0.1+' are valid colour specifications.
\begin{verbatim}
draft
final
\end{verbatim}
With `\verb+draft+' the animation is not embedded. Instead, a box with the exact dimensions of the animation is inserted. Option `\verb+final+' does the opposite as it forces the animation to be built and embedded. Both options can be used to reduce compilation time during authoring of a document. To get the most out of them it is recommended to set `\verb+draft+' globally as a package or class option and to set `\verb+final+' locally as a command option of the animation that is currently worked on. After the document has been finished, the global `\verb+draft+' option can be removed to embed all animations.
\begin{verbatim}
useocg
\end{verbatim}
Use an alternative animation method based on Optional Content Groups (OCGs, also known as PDF Layers). May result in less performing animations.
\begin{verbatim}
measure
\end{verbatim}
Measures the frame rate during one cycle of the animation. (For testing purposes.)
\begin{verbatim}
begin={<begin text>}
end={<end text>}
\end{verbatim}
(`\verb+animateinline+' only.) \verb+<begin text>+ and \verb+<end text>+ are inserted into the code at start and end of each frame. Mainly used for setting up some drawing environment, such as
\begin{verbatim}
  begin={\begin{pspicture}(...)(...)}, end={\end{pspicture}}
\end{verbatim}

\subsection{The `{\tt timeline}' option}\label{sect:timeline}
\begin{verbatim}
timeline=<timeline file>
\end{verbatim}
\verb+<timeline file>+ is a plain text file whose contents determines the order of appearance of the embedded material during the animation. It allows to freely rearrange, repeat and overlay the material at any point of the animation. This may greatly reduce the file size of the resulting PDF, as objects that do not change between several or all frames, such as coordinate axes or labels, can be embedded once and re-used in other frames of the animation.

If a timeline is associated with the animation, the graphics files or inline graphics embedded by \verb+\animategraphics+ and `\verb+animateinline+' no longer represent the actual frames of the animation. Rather, they are a collection of \emph{transparencies} that can be played with at will. However, it is now up to the author's responsability to construct a timeline that makes use of \emph{each} of those transparencies and to put them into a sensible order. In order to identify the transparencies within the timeline file, they are numbered in the order of their inclusion, starting at zero.

Each line of the timeline file that is not blank and which does not begin with a comment (`\verb+%+') specifies \emph{one} frame of the animation. There may be more transparencies than animation frames and vice-versa. A frame specification consists of three, colon-(\verb+:+)-separated fields:
\begin{verbatim}
  [*]:[<frame rate>]:[<frame content>]
\end{verbatim}
While any field may be left blank, the colons are mandatory.

An asterisk (`\verb+*+') in the leftmost field causes the animation to pause at that frame, very much as a \verb+\newframe*+ would do; a number in the second field changes the frame rate of the animation section that follows. (In connection with the `\verb+timeline+' option the asterisk extension and the optional \verb+<frame rate>+ argument of \verb+\newframe+ cease to make sense and will be tacitly ignored, if present.) The third field \verb+<frame content>+ is a comma-separated \emph{list} of \emph{transparency specifications} that determines the content of the frame. A \emph{single} transparency specification obeys the syntax
\begin{verbatim}
  <transparency ID>[x<number of frames>]
\end{verbatim}
where \verb+<transparency ID>+ is an integer number that identifies the transparency to be drawn into the current animation frame. As pointed out above, the transparencies are consecutively numbered in the order of their inclusion, starting at zero. The optional postfix `\verb+x<number of frames>+' specifies the number of consecutive frames the transparency is to appear within. If omitted, a postfix of `\verb+x1+' is assumed, which causes the transparency to be shown in the current frame only. Obviously, \verb+<number of frames>+ must be a non-negative integer number. The meaning of postfix `\verb+x0+' is special; it causes the transparency to be shown in all frames, starting with the current one, until the end of the animation.

Note that the order in which transparency specifications appear in the timeline file determines their \emph{depth} level. If a frame is composed of more than one transparency, transparency specifications on the left of the input line are closer to the background and will be overprinted by those on the right which are closer to the foreground. That is, the depth \emph{de}creases from left to right within \verb+<frame content>+. Also, if there are transparency specifications which span several frames (using postfix `\verb+x<number of frames>+'), they will be overprinted by transparency specifications that appear on subsequent lines in the timeline file. That is, the depth decreases in top-down direction within the timeline file.
%The animation may be thought of as a pile of transparencies. Transparencies are always put on top of that pile, possibly overdrawing objects that are on previously deposited transparencies. Once on the pile, each transparency remains at its place for the specified number of frames and is removed afterwards. That is, for a transparency to appear always on top it must be put to the rightmost end of each line in the timeline file.

Consider the two timelines
\small
\begin{verbatim}
  ::1,0 % zeroth transparency always in the foreground
  ::2,0
  ::3,0
  ::4,0
  etc...
\end{verbatim}
\normalsize
and
\small
\begin{verbatim}
  ::0x0,1 % zeroth transparency put to the background
  ::2
  ::3
  ::4
  etc...
\end{verbatim}
\normalsize
In the first example, transparency No. 0 appears in the foreground throughout the animation; it will never be obscured by other transparencies' content. In the second example it is put to the background, because it is the first transparency specification in the file, and stays there for the rest of the animation.

When designing the timeline, care should be taken not to include a transparency more than once into the \emph{same} animation frame. Besides the useless redundancy, this may slow down the animation speed in the Reader, because the graphical objects of a multiply included transparency have to be rendered unnecessarily often at the same time. `animate' is smart enough to detect multiple inclusion and issues a warning message along with the transparency ID and the frame number if it occurs. Here is an example of a poorly designed timeline:
\small
\begin{verbatim}
  ::0
  ::1x0
  ::2
  ::3
  ::4,2
  ::5,1 % bad: transparency `1' included twice
  ::6
\end{verbatim}
\normalsize
Also, `animate' finds and lists transparencies that have never been used in an animation timeline. This may help to avoid dead code in the final PDF.

\myparagraph*{Grouping objects into layers using `{\tt;}'}
The stack-like concept of animations, where transparencies are always put on top such that they overprint the content of previously deposited transparencies, can be inconvenient in certain situations. For example, it might be desirable to allow for changing the background image in the middle of an animation without affecting objects that are located in the foreground. For this purpose, transparency specifications can be grouped into \emph{layers} using the semicolon (\verb+;+) as a separator instead of the comma. This is best illustrated by an example:
\small
\begin{verbatim}
  % <--layer 1--> <--layer 2-->
  %
  ::    0x49     ;   2x0,3x0    % transparency `0' used as background
  ::             ;   4x0,5x0    % image during the first 49 frames
  ::             ;   6x0,7x0
  etc...
  ::             ;  98x0,99x0
  ::    1x0      ; 100x0,101x0  % transparency `1' used as new background
  ::             ; 102x0,103x0  % image until end of animation
  ::             ; 104x0,105x0
  etc...
\end{verbatim}
\normalsize
In this timeline, the transparencies are grouped into two layers. One is reserved for the background images, transparencies No. 0 \& 1, to be exchanged after 49 frames, and another one for the foreground objects that are successively added to the scene. As can be seen in this example, layers need not be explicitly populated; the leading semicolons just ensure the proper assignment of transparencies to animation layers. Note that \emph{without} setting up two layers, that is, by replacing the semicolons with commas, the foreground objects (transparencies 2 through 99) which have been added during the first 49 frames would be overprinted by the new background image, transparency 1, from frame 50 onward.

See the second animation, Fig.~\ref{fig:scarab}, in Section~\ref{sect:examples} for a working example that makes use of the timeline and the layer concept.

\section{Examples}
\subsection[Animations from sets of files, using `animategraphics' command]{Animations from sets of files, using {\tt \string\animategraphics} command}\label{sect:examples}
Animations in this section are made from graphics files that were prepared with \MP. Run `\verb+mpost --tex=latex+' on the files ending in `.mp' in the `doc/files' directory to generate the graphics files. Both examples make use of the `\verb+timeline+' option to reduce the resulting PDF file size.

The first example, Fig.~\ref{fig:taylor}, originally written by Jan Hole\v{c}ek~\cite{hol}, shows the exponential function $y=e^x$ and its approximation by Taylor polynomials of different degree.

\small
\begin{verbatim}
\documentclass{article}
\usepackage{animate}
\usepackage{graphics}

\begin{document}

\begin{center}
  \animategraphics[
    controls, loop,
    timeline=timeline.txt
  ]{4}{exp_}{0}{8}
\end{center}

\end{document}
\end{verbatim}
\normalsize
Contents of file `timeline.txt':
\small
\begin{verbatim}
  ::0x0 % coordinate system & y=e^x, repeated until last frame
  ::1   % one blue curve per frame
  ::2
  ::3
  ::4
  ::5
  ::6
  ::7
  ::8
\end{verbatim}
\normalsize

\begin{figure}\capstart
\centering
\animategraphics[controls,loop,timeline=timeline.txt]{4}{exp_}{0}{8}
\caption{}\label{fig:taylor}
\end{figure}

The second, somewhat more complex example, Fig.~\ref{fig:scarab}, animates the geometric construction of a scarabaeus. In addition to the use of a timeline, it introduces the layer concept. This example is adapted from Maxime Chupin's original \MP{} source file \cite{chupin}. The present version separates stationary from moving parts of the drawing and saves them into different files. A total of 254 files, scarab\_0.mps through scarab\_253.mps, is written out by running `\verb+mpost --tex=latex+' on the source file `scarab.mp'. Files 0 through 100 contain the red line segments that make up the growing scarabaeus. Files 101 through 201 contain the moving construction lines and files 202 through 252 contain the gray lines which represent intermediate stages of the construction. The last file, No. 253, contains the coordinate axes, two stationary construction lines and the labels which do not move. A timeline file `scarab.tln' is written out on-the-fly during the \LaTeX{} run. It arranges the animation into three layers, forcing the gray lines into the background, the coordinate axes into the intermediate layer and the scarabaeus along with the moving construction lines into the foreground. The final animation consists of 101 individual frames.
\begin{figure}[t]
\centering
\newcounter{scarab}
\setcounter{scarab}{0}
\newcounter{blueline}
\setcounter{blueline}{101}
\newcounter{grayline}
\setcounter{grayline}{202}
%
\newwrite\TimeLineFile
\immediate\openout\TimeLineFile=scarab.tln
\whiledo{\thescarab<101}{
  \ifthenelse{\intcalcMod{\thescarab}{2}=0}{
    \immediate\write\TimeLineFile{::\thegrayline x0;253;\thescarab x0,\theblueline}
    \stepcounter{grayline}
  }{
    \immediate\write\TimeLineFile{::;253;\thescarab x0,\theblueline}
  }
  \stepcounter{scarab}
  \stepcounter{blueline}
}
\immediate\closeout\TimeLineFile
%
\animategraphics[
  width=0.8\linewidth,
  controls,
  loop,
  timeline=scarab.tln
]{12}{scarab_}{0}{253}
%
\caption{}\label{fig:scarab}
\end{figure}

\small
\begin{verbatim}
\documentclass{article}
\usepackage{intcalc} %defines \intcalcMod for Modulo computation
\usepackage{animate}
\usepackage{graphics}

\newcounter{scarab}
\setcounter{scarab}{0}
\newcounter{blueline}
\setcounter{blueline}{101}
\newcounter{grayline}
\setcounter{grayline}{202}

%write timeline file
\newwrite\TimeLineFile
\immediate\openout\TimeLineFile=scarab.tln
\whiledo{\thescarab<101}{
  \ifthenelse{\intcalcMod{\thescarab}{2}=0}{
    %a gray line is added to every 2nd frame
    \immediate\write\TimeLineFile{%
      ::\thegrayline x0;253;\thescarab x0,\theblueline}
    \stepcounter{grayline}
  }{
    \immediate\write\TimeLineFile{%
      ::;253;\thescarab x0,\theblueline}
  }
  \stepcounter{scarab}
  \stepcounter{blueline}
}
\immediate\closeout\TimeLineFile

\begin{document}

\begin{center}
  \animategraphics[
    width=0.8\linewidth,
    controls, loop,
    timeline=scarab.tln
  ]{12}{scarab_}{0}{253}
\end{center}

\end{document}
\end{verbatim}
\normalsize
\subsection[Animating PSTricks graphics, using `animateinline' environment]{Animating PSTricks graphics, using `{\tt animateinline}' environment}
Fig.~\ref{fig:torus} is an inline graphics example adapted from \cite{gilg05}.
\small
\begin{verbatim}
\documentclass{article}
\usepackage{pst-3dplot}
\usepackage{animate}

%draws a torus sector
\newcommand{\torus}[2]{% #1: angle of the torus sector,
  %                      #2: linewidth of leading circle
  \psset{Beta=20,Alpha=50,linewidth=0.1pt,origin={0,0,0},unit=0.35}%
  \begin{pspicture}(-12.3,-6.3)(12.3,7)%
    \parametricplotThreeD[xPlotpoints=100](80,#1)(0,360){%
      t cos 2 mul 4 u sin 2 mul add mul
      t sin 2 mul 4 u sin 2 mul add mul
      u cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=75](0,360)(80,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=1,linewidth=#2](0,360)(#1,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
  \end{pspicture}%
}

\begin{document}

\begin{center}
\begin{animateinline}[poster=last, controls, palindrome]{12}%
  \multiframe{29}{iAngle=80+10, dLineWidth=2.9pt+-0.1pt}{%
    %iAngle = 80, 90, ..., 360 degrees
    %dLineWidth = 2.9pt, 2.8pt, ..., 0.1pt
    \torus{\iAngle}{\dLineWidth}%
  }%
\end{animateinline}%
\end{center}

\end{document}
\end{verbatim}
\normalsize

\begin{figure}
\centering
\newcommand{\torus}[2]{%
  \psset{Beta=20,Alpha=50,linewidth=0.1pt,origin={0,0,0},unit=0.35}%
  \begin{pspicture}(-12.3,-6.3)(12.3,7)%
    \parametricplotThreeD[xPlotpoints=100](80,#1)(0,360){%
      t cos 2 mul 4 u sin 2 mul add mul
      t sin 2 mul 4 u sin 2 mul add mul
      u cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=75](0,360)(80,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=1,linewidth=#2](0,360)(#1,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
  \end{pspicture}%
}

\begin{animateinline}[poster=last,controls,palindrome]{12}%
  \multiframe{29}{iAngle=80+10, dLineWidth=2.9pt+-0.1pt}{%
    \torus{\iAngle}{\dLineWidth}%
  }%
\end{animateinline}%
\caption{}\label{fig:torus}
\end{figure}

\section{Bugs}\label{sect:bugs}
\begin{itemize}
  \item The maximum frame rate that can actually be achieved largely depends on the complexity of the graphics and on the available hardware. Starting with version 8, Adobe Reader appears to be somewhat slower. However, you might want to experiment with the graphical hardware acceleration feature that was introduced in Reader 8. Go to menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Page Display' $\rightarrow$ `Rendering' to see whether hardware acceleration is available. A 2D GPU acceleration check box will be visible if a supported video card has been detected.

  \item Animations may run very slowly if viewed in the Adobe Reader web-browser plugin. Instead, open the PDF locally in the Reader application for best results.

  \item The Adobe Reader setting `Use page cache' (menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Startup') should be \emph{dis}abled for version 7, while remaining \emph{en}abled beginning with version 8 (menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Page Display' $\rightarrow$ `Rendering').

  \item The \verb+dvips+ option `\verb+-Ppdf+' should be avoided entirely or followed by something like `\verb+-X 2400 -Y 2400+' on the command line in order to set a sensible DVI resolution. In times of Type-1 fonts, this does \emph{not} degrade the output quality! The configuration file `config.pdf' loaded by option `\verb+-Ppdf+' specifies an excessively high DVI resolution that will be passed on to the final PDF. Eventually, Adobe Reader gets confused and will not display the frames within the animation widget.

  \item Animations do not work if the PDF has been produced with Ghostscript versions older than 8.31. This applies to all versions of ESP Ghostscript that comes with many Linux distributions.

  \item If the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller route is being taken make sure that the original graphics size (i.\,e. not scaled by any of the `{\tt scale}', `{\tt width}', `{\tt height}' or `{\tt depth}' options) does not exceed the page size of the final document. During PS to PDF conversion every graphic of the animation is temporarily moved to the lower left page corner. Those parts of the graphics that do not fit onto the document page will be clipped in the resulting PDF. Fortunately, graphics files for building animations may be resized easily to fit into a given bounding box by means of the `{\tt epsffit}' command line tool:

\quad{\tt epsffit -c <llx> <lly> <urx> <ury> infile.eps outfile.eps}

{\tt <llx> <lly> <urx> <ury>} are the bounding box coordinates of the target document. They can be determined using Ghostscript. For a document named `document.ps' the command line is

\quad{\tt gs -dNOPAUSE -q -dBATCH -sDEVICE=bbox document.ps}

Note that the name of the Ghostscript executable may vary between operating systems (e.\,g. `{\tt gswin32c.exe}' on Win/DOS).
 
  \item Animations with complex graphics and/or many frames may cause \LaTeX{} to fail with a `\verb+TeX capacity exceeded+' error. The following steps should fix most of the memory related problems.

  MiK\TeX:
  \begin{enumerate}
    \item Open a DOS command prompt window (execute `cmd.exe' via `Start' $\rightarrow$ `Run').
    \item\label{item:firststep} At the DOS prompt, enter\\
    {\tt initexmf -{}-edit-config-file=latex}
    \item Type\\
    {\tt main\_memory=10000000}\\
    into the editor window that opens, save the file and quit the editor.
    \item\label{item:laststep} To rebuild the format, enter\\
    {\tt initexmf -{}-dump=latex}
    \item Repeat steps \ref{item:firststep}--\ref{item:laststep} with config files `{\tt pdflatex}' and `{\tt xelatex}'
  \end{enumerate}

  \TeX\ Live:
  \begin{enumerate}
    \item Find the configuration file `texmf.cnf' by means of\\
    {\tt kpsewhich texmf.cnf}\\
    at the shell prompt in a terminal.
    \item As Root, open the file in your favourite text editor, scroll to the `{\tt main\_memory}' entry and change it to the value given above; save and quit.
    \item Rebuild the formats by\\
    {\tt fmtutil-sys -{}-byfmt latex}\\
    {\tt fmtutil-sys -{}-byfmt pdflatex}\\
    {\tt fmtutil-sys -{}-byfmt xelatex}
  \end{enumerate}

  \item Animations should not be placed on \emph{multilayered} slides created with presentation making classes such as Beamer or Powerdot. Although possible (on the last overlay of a slide, at best), the result might be disappointing. Put animations on flat slides only. (Of course, slides without animations may still have overlays.)
\end{itemize}

\section{Acknowledgements}
I would like to thank Fran\c{c}ois Lafont who discovered quite a few bugs and made many suggestions that helped to improve the functionality of the package. Many thanks to Jin-Hwan Cho, the developer of `\verb+dvipdfmx+', for contributing the `\verb+dvipdfmx+' specific code.

\begin{thebibliography}{8}
  \bibitem{chupin} Chupin, M.: \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\tt http://melusine.eu.org/syracuse/metapost/animations/} \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\tt chupin/?idsec=scara}
  \bibitem{gilg05} Gilg, J.: PDF-Animationen. In: \emph{Die \TeX nische Kom\"odie}, Issue 4, 2005, pp.~30--37
  \bibitem{hol} Hole\v{c}ek, J.: \emph{Animations in a pdf\TeX-generated PDF}. URL: \href{http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml}{\tt http://www.} \href{http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml}{\tt fi.muni.cz/\textasciitilde xholecek/tex/pdfanim.xhtml}
  \bibitem{movie15} \emph{The Movie15 Package}. URL: \href{http://www.ctan.org/tex-archive/macros/latex/contrib/movie15/}{\tt http://www.ctan.org/tex-archive/macros/} \href{http://www.ctan.org/tex-archive/macros/latex/contrib/movie15/}{\tt latex/contrib/movie15}
\end{thebibliography}

\end{document}