% Copyright 2007--\today Alexander Grahn % % This material is subject to the LaTeX Project Public License. See % http://mirrors.ctan.org/macros/latex/base/lppl.txt % for the details of that license. % \ifdefined\outputmode\outputmode=0\fi \ifdefined\pdfoutput\pdfoutput=0\fi \documentclass[a4paper]{article} \frenchspacing \usepackage[buttonbg=0.9]{animate} \usepackage[UKenglish]{babel} \usepackage{pst-3dplot} \usepackage{pst-node,pst-plot,pst-tools,pst-text,pst-ode} \usepackage{media9} \usepackage{intcalc} \usepackage{graphicx} \graphicspath{{files/}} \addmediapath{files} \usepackage{color} \usepackage{textcomp} \usepackage{mflogo} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} %\usepackage{lmodern} \usepackage[tt=false]{libertine} %override beramono (doesn't look like tt font) \usepackage{libertinust1math} \usepackage[protrusion]{microtype} %\usepackage{ifpdf} \usepackage{parskip} \usepackage{tabls} \usepackage{multirow} \usepackage[bookmarksnumbered,linktocpage]{hyperref} \usepackage[ocgcolorlinks]{ocgx2} \usepackage{breakurl} \usepackage{amsmath} \usepackage{fancyvrb} \usepackage{tabularx} \usepackage[all]{hypcap} \usepackage{listings} \lstset{basicstyle=\ttfamily,columns=fullflexible,language={[LaTeX]TeX},commentstyle=\color{gray}} \clubpenalty=10000 \widowpenalty=10000 \displaywidowpenalty=10000 \renewcommand{\textfraction}{0.0} \renewcommand{\topfraction}{1.0} \renewcommand{\bottomfraction}{1.0} \makeatletter \renewcommand{\fnum@figure}[1]{\figurename~\thefigure} \newcommand\myparagraph{\@startsection{paragraph}{3}{\z@}% {\parskip}% {0.001\parskip}% {\itshape\normalsize}} \makeatother %\ifpdf % \makeatletter % \@latex@error{This document contains PSTricks code.\MessageBreak Please compile it using the following commands:\MessageBreak\MessageBreak latex, dvips, ps2pdf\MessageBreak\MessageBreak Don't use option `-Ppdf` with dvips} % \makeatother %\fi \def\keywords{include portable PDF animation SVG animation animated PDF animated SVG dvisvgm html TeX4ht web animating embed animated graphics LaTeX pdfLaTeX LuaLaTeX PSTricks pgf TikZ LaTeX-picture MetaPost inline graphics vector graphics animated GIF LaTeX dvips ps2pdf dvipdfmx XeLaTeX JavaScript Acrobat Reader KDE Okular PDF-XChange Foxit Reader Firefox Chrome Chromium} \hypersetup{ pdftitle={The animate Package}, pdfsubject={Documentation}, pdfauthor={Alexander Grahn}, pdfkeywords={\keywords}, allcolors=blue } \def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX} \def\XeTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\TeX} \def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX} \def\parsedate#1/#2/#3\relax{ \def\year{#1} \def\month{#2} \def\day{#3} } \hyphenation{Ja-va-Script pro-vid-ed} \makeatletter \let\animVersion\@anim@version \makeatother \begin{document} \title{The {\sffamily animate} Package} \begingroup \makeatletter \def\@anim@sanitizeColon{}\def\@anim@sanitizeJS{}\def\@anim@endsanitize{} \expandafter\parsedate\animVersion\relax %set current date to package date \makeatother \author{Alexander Grahn \animategraphics[autoplay,loop,height=1.8ex,nomouse]{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.}% %\space\protect\footnote{Animations may run slowly if viewed in the Acrobat Reader browser plugin.}% \\[1ex]\url{https://gitlab.com/agrahn/animate}} \maketitle \endgroup \begin{abstract} \raggedright \noindent A LaTeX package for creating portable, JavaScript driven PDF and SVG animations from sets of vector graphics or raster image files or from inline graphics. \vskip 0.2\baselineskip \emph{Keywords}: \keywords \end{abstract} %\vspace{1.5cm} \tableofcontents %\newpage \section{Introduction} This package provides an interface for creating PDF and SVG files 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, 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 workflows for making PDF, i.\,e. pdf\LaTeX{}, Lua\-\LaTeX{}, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+. For animated SVG, it supports the \verb+dvisvgm+ driver. The DVI/XDV used as input for \verb+dvisvgm+ can be generated with \LaTeX{}, Lua\LaTeX{} (in DVI mode with command `\verb+dvilualatex+') and \XeLaTeX{} (with option `\verb+--no-pdf+'). PDF files with animations can be viewed in Acrobat Reader (except on mobile devices), KDE Okular, PDF-XChange and Foxit Reader. Animated SVG produced by means of \LaTeX{} and \verb+dvisvgm+ are self-sufficient files that can be embedded into HTML using the \verb++ tag or opened directly in a Web browser, such as Chromium or Firefox. Also, presentations, such as `beamer'-class documents, with embedded animations can be exported to SVG instead of PDF and viewed in a Web browser. SVG-capable Web browsers are standard on many platforms and operating systems and thus make SVG a very portable file format. A \LaTeX{} package for embedding video and audio into SVG is also available\cite{media4svg}. The user interacts with the animation through optional animation controls or using the mouse like so: pressing the mouse button over the animation widget immediately pauses a playing animation and releasing it resumes playback. Pressing the shift-key at the same time reverses the playback direction. Keeping the mouse button pressed while moving the mouse pointer off the animation widget permanently pauses playback. On mobile devices, tapping on the animation toggles between play and pause. %On mobile devices, interaction with an animated SVG is similar to that on desktop devices, just using finger touches instead of mouse button press/release. To permanently pause an animation without the pause button, touch the animation with a second finger, then lift both fingers off. \section{Requirements} \begin{trivlist} %\item $\varepsilon$-\TeX \item pdf\TeX{}, version $\ge1.40$, or Lua\TeX{}, version $\ge0.95$, for direct PDF output \item Ghostscript, version $\ge9.15$, or Adobe Distiller for PS to PDF conversion \item \verb+dvipdfmx+ for DVI to PDF conversion \item dvipdfmx, version $\ge 20190503$, for DVI to PDF conversion \item \verb+dvisvgm+ for DVI to SVG conversion (also requires Ghostscript) \item PDF: Acrobat Reader, KDE Okular, PDF-XChange, Foxit Reader \item SVG: Chromium-based browsers for best performance \end{trivlist} \section{Installation} Unzip the file \href{http://mirrors.ctan.org/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. \TeX-Live and MiK\TeX{} users should run the package manager of their system 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[]{animate} \end{verbatim} to the preamble of the document source, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+. `animate' honours the package options: \begin{verbatim} dvipdfmx xetex dvisvgm export autoplay autopause autoresume loop palindrome draft final controls[=(all|true|on) | (none|false|off) | {[play][,step][,stop][,speed]}] controlsaligned=left[+] | center | right[+] width= height= | totalheight= keepaspectratio scale= bb= viewport= trim= clip hiresbb interpolate pagebox=... buttonsize= buttonbg= buttonfg= buttonalpha= step nomouse type= method=icon | widget | ocg poster[=first | | last | none] alttext=none | {} \end{verbatim} Except for `\verb+dvipdfmx+', `\verb+xetex+', `\verb+dvisvgm+' and `\verb+export+', the listed package options 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+', `\verb+xetex+', `\verb+dvisvgm+ and `\verb+export+', by appending `\verb+=false+'. \begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} Option `\verb+-Ppdf+' should \emph{not} be used with \verb+dvips+ when converting DVI to PostScript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call. All workflows require the `graphicx' package to be loaded explicitly. Options `\verb+dvipdfmx+' or `\verb+dvisvgm+' must be set for the document class, as in %\verb+\documentclass[dvipdfmx,...]{...}+, \begin{verbatim} \documentclass[dvipdfmx,...]{...} \end{verbatim} or \begin{verbatim} \documentclass[dvisvgm,...]{...} \end{verbatim} because these drivers cannot be auto-detected by `animate', `graphicx' and other packages. Usually, a second \LaTeX{} run is necessary to resolve internally created object references. A warning message will be issued if appropriate. With option `\verb+export+', animation frames are output as individual pages of a multipage document that can be converted to other file formats, such as animated GIF. The `standalone' document class must be used together with `\verb+export+': \begin{verbatim} \documentclass{standalone} \usepackage[export]{animate} \end{verbatim} or \begin{verbatim} \documentclass[export]{standalone} \usepackage{animate} \end{verbatim} %\clearpage \section{The user interface} Package `animate' provides the command \begin{verbatim} \animategraphics[]{}{}{}{} \end{verbatim} and the environment \begin{verbatim} \begin{animateinline}[]{} ... typeset material ... \newframe[] ... typeset material ... \newframe*[] ... typeset material ... \newframe \multiframe{}{[]}{ ... 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++ specifies the number of frames per second of the animation. The \verb+\newframe+ command terminates a frame and starts the next one. It can be used only inside the `\verb+animateinline+' environment. 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 as normal after clicking it again. Both \verb+\newframe+ variants take an optional argument that allows the frame rate to be changed in the middle of an animation. The \verb+\multiframe+ command allows the construction of loops around pictures. The first argument \verb++ does what one would expect it to do, the second argument \verb++ 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} =+ \end{verbatim} \verb++ 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++. Each further iteration increments the variable by \verb++. 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 } is the leftmost part of the file name that is common to all members of the sequence. \verb++ is the number of the first and \verb++ the number of the last file in the set. If \verb++ is greater than \verb++, files are embedded in reverse order. 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++ and \verb++ arguments are filled in accordingly. 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, the correct inclusion command would read \begin{verbatim} \animategraphics{12}{frame_}{5}{50} \end{verbatim} The possible file formats depend on the output driver being used. In the case of \LaTeX{} + \verb+dvips+, files with the `eps' extension are at first searched for, followed by `mps' (\MP-generated PostScript) and `ps'. With pdf\LaTeX{} and Lua\LaTeX{} the searching order is: (1)~`pdf', (2)~`mps', (3)~`png', (4)~`jpg', (5)~`jpeg', (6)~`jp2'\footnotemark[1], (7)~`j2k'\footnotemark[1], (10)~`jpx'\footnotemark[1]\footnotetext[1]{Only Lua\LaTeX{} currently supports JPEG2000.}, with \XeLaTeX{} or \LaTeX{}+\verb+dvipdfmx+: (1)~`pdf', (2)~`mps', (3)~`eps', (4)~`ps', (5)~`png', (6)~`jpg', (7)~`jpeg', (8)~`bmp', and with \LaTeX{}+\verb+dvisvgm+: (1)~`pdf', (2)~`eps', (3)~`ps', (4)~`mps', (5)~`svg', (6)~`png', (7)~`jpg', (8)~`jpeg'. That is, files capable of storing vector graphics are found first. Make sure that all file names have \emph{lower case} extensions. This searching procedure can be skipped thanks to the package and command option `\verb+type=+'. It enforces the embedding of files with the given file name extension \verb++. Command \verb+\graphicspath{}+ from the `graphicx' package can be used to specify directories to be browsed for graphics files. \myparagraph*{Multipage PDF inclusion} %{\rm(pdf\LaTeX, \XeLaTeX, \texttt{dvipdfmx})} and JBIG2 {\rm(pdf\LaTeX)} inclusion} Lua\LaTeX{}, pdf\LaTeX{}, \XeLaTeX{} and the \verb+dvipdfmx+ and \verb+dvisvgm+ backends are able to embed animation frames from multipage PDF. If the file `\verb++.pdf' exists, it is taken as a multipage document where each page represents one frame of the animation. In this case, the last two arguments, \verb++ \& \verb++, 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 omitted, `\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 actual limits. If \verb++ is greater than \verb++, pages are embedded in reverse order. Again, option `\verb+type=+' can be used to enforce a particular file extension. 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. %\clearpage \section{Command options} The following options to \verb+\animategraphics+ and `\verb+animateinline+' have been provided. \subsection{Basic options} \begin{verbatim} label=