summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/animate/animate.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/animate/animate.tex')
-rw-r--r--macros/latex/contrib/animate/animate.tex89
1 files changed, 50 insertions, 39 deletions
diff --git a/macros/latex/contrib/animate/animate.tex b/macros/latex/contrib/animate/animate.tex
index 684d9216df..0249961249 100644
--- a/macros/latex/contrib/animate/animate.tex
+++ b/macros/latex/contrib/animate/animate.tex
@@ -1,11 +1,11 @@
-\ifdefined\outputmode\outputmode=0\fi
-\ifdefined\pdfoutput\pdfoutput=0\fi
% 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}
@@ -112,13 +112,16 @@
\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) and \XeLaTeX.
+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), PDF-XChange and Foxit Reader. Animated SVG produced by means of \LaTeX{} and \verb+dvisvgm+ are self-contained files that can be embedded into HTML using the \verb+<object>+ tag or opened directly in a Web browser, such as Chromium or Firefox.
+PDF files with animations can be viewed in Acrobat Reader (except on mobile devices), PDF-XChange and Foxit Reader.
-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.
+Animated SVG produced by means of \LaTeX{} and \verb+dvisvgm+ are self-sufficient files that can be embedded into HTML using the \verb+<object>+ 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.
-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}
@@ -129,7 +132,7 @@ On mobile devices, interaction with an animated SVG is similar to that on deskto
\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, PDF-XChange, Foxit Reader
-\item SVG: Chromium-based browsers, Firefox and others
+\item SVG: Chromium-based browsers for best performance
\end{trivlist}
\section{Installation}
@@ -166,9 +169,13 @@ width=<h-size>
height=<v-size> | totalheight=<v-size>
keepaspectratio
scale=<factor>
+bb=<llx> <lly> <urx> <ury>
+viewport=<llx> <lly> <urx> <ury>
+trim=<left> <bottom> <right> <top>
+clip
hiresbb
interpolate
-pagebox
+pagebox=...
buttonsize=<size>
buttonbg=<colour>
buttonfg=<colour>
@@ -266,9 +273,9 @@ For example, the line
\end{verbatim}
would create an animation from all pages of the file `frames.pdf', running at 12 fps.
-\clearpage
+%\clearpage
\section{Command options}
-The following options to \verb+\animategraphics+ and `\verb+animateinline+' have been provided:
+The following options to \verb+\animategraphics+ and `\verb+animateinline+' have been provided.
\subsection{Basic options}
\begin{verbatim}
label=<label text>
@@ -281,7 +288,7 @@ Overrides the searching procedure for graphics files explained in the previous s
\begin{verbatim}
poster[=first | <num> | last | none]
\end{verbatim}
-Specifies which frame 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. A frame number \verb+<num>+ may as well be given; \verb+<num>+ is zero-based, that is, the first frame has number `0'.
+Specifies which frame 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. A frame number \verb+<num>+ may as well be given; \verb+<num>+ is zero-based, that is, the first frame has number `0'.
\begin{verbatim}
every=<num>
\end{verbatim}
@@ -331,9 +338,13 @@ viewport=<llx> <lly> <urx> <ury>
\begin{verbatim}
trim=<left> <bottom> <right> <top>
\end{verbatim}
-(\verb+\animategraphics+ only.) 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.
+(\verb+\animategraphics+ only.) Crops graphic 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 graphic.
\begin{verbatim}
-pagebox
+clip
+\end{verbatim}
+(\verb+\animategraphics+ only.) Clips the graphic to the (possibly modified) bounding box.
+\begin{verbatim}
+pagebox=...
hiresbb
interpolate
\end{verbatim}
@@ -534,25 +545,7 @@ or
\end{verbatim}
`\verb+anim+' is an array of animation object references. Animations must be labelled using the `\verb+label=...+' command option in order to be present in the `\verb+anim+' array. As usual, properties and methods are accessed via the dot notation. Properties and methods of the animation object are summarized in Tables \ref{tab:props} and \ref{tab:methods}.
-One potential use of the JavaScript interface could be within a timeline file associated with an animation. For example, loops over a sub-range of frames can be programmed by setting the `\verb+frameNum+' property. See Section~\ref{sect:timeline}, p.~\pageref{sect:jsfield} for details.
-
-Also, the programming interface can be used to create custom buttons for playback control. The command \verb+\mediabutton+ from the `media9' package provides a convenient way for achieving this:
-\begin{lstlisting}
- \usepackage{media9}
- \usepackage{animate}
- ...
-
- \animategraphics[label=my_anim]{12}{...}{...}{...}
-
- \mediabutton[
- jsaction={anim['my_anim'].playFwd();}
- ]{\fbox{Play}}
- \mediabutton[
- jsaction={anim['my_anim'].frameNum=5;}
- ]{\fbox{Goto 6th frame}}
-\end{lstlisting}
-
-\begin{table}[p]%[hbp]
+\begin{table}[hbp]%[p]%[hbp]
\centering
\caption{Animation object properties}\label{tab:props}
\begin{tabularx}{\linewidth}[t]{lllX}\hline
@@ -568,7 +561,7 @@ name & type & access & description\\\hline\hline
\end{tabularx}
\end{table}
-\begin{table}[p]%[htbp]
+\begin{table}[htp]%[p]%[htbp]
\centering
\caption{Animation object methods}\label{tab:methods}
\begin{tabularx}{\linewidth}[t]{lX}\hline
@@ -582,6 +575,24 @@ name & description\\\hline\hline
\end{tabularx}
\end{table}
+One potential use of the JavaScript interface could be within a timeline file associated with an animation. For example, loops over a sub-range of frames can be programmed by setting the `\verb+frameNum+' property. See Section~\ref{sect:timeline}, p.~\pageref{sect:jsfield} for details.
+
+Also, the programming interface can be used to create custom buttons for playback control. The command \verb+\mediabutton+ from the `media9' package provides a convenient way for achieving this:
+\begin{lstlisting}
+ \usepackage{media9}
+ \usepackage{animate}
+ ...
+
+ \animategraphics[label=my_anim]{12}{...}{...}{...}
+
+ \mediabutton[
+ jsaction={anim['my_anim'].playFwd();}
+ ]{\fbox{Play}}
+ \mediabutton[
+ jsaction={anim['my_anim'].frameNum=5;}
+ ]{\fbox{Goto 6th frame}}
+\end{lstlisting}
+
\clearpage
\section{Examples}
\subsection{Animations from sets of files, using {\tt\textbackslash animategraphics}}\label{sect:examples}
@@ -1337,17 +1348,16 @@ The following code may serve as a template for generating standalone animated SV
\begin{lstlisting}
\documentclass[dvisvgm]{standalone}
-\usepackage{animate}
-\usepackage{graphicx}
-
%\usepackage{xcolor}
%\pagecolor{white} % opaque background with solid colour
%\usepackage{pstricks} % enable as needed
%\usepackage{tikz}
-\begin{document}
+\usepackage{animate}
+\usepackage{graphicx}
+\begin{document}
%
% \animategraphics{..}{...}{...}{...}
%
@@ -1355,7 +1365,6 @@ The following code may serve as a template for generating standalone animated SV
%
% \begin{animateinline}{..} ... \end{animateinline}
%
-
\end{document}
\end{lstlisting}
Note that when animating external graphics with \verb+\animategraphics+, only PDF and PostScript (EPS, PS, MPS) files are converted to inline SVG code; files in other formats (SVG, PNG, JPEG) remain external and must be bundled with the final SVG output. Thus, for obtaining self-contained SVG, it is recommended to convert PNG, JPEG and SVG files to PDF or PostScript first. Also note that PostScript files must have all required fonts embedded. This is not always the case for \MP-generated PostScript. Here, embedding of fonts is ensured by putting `\verb+prologues := 3;+' into the header of the \MP{} input.
@@ -1455,13 +1464,15 @@ In \TeX4ht documents, the whole \verb+<object>...</object>+ tag can be inserted
\section{Acknowledgements}
I would like to thank Franç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, and to Walter Scott for proof-reading the documentation.
+\enlargethispage{4ex}
\begin{thebibliography}{8}
- \bibitem{chupin} Chupin, M.: \emph{Syracuse MetaPost/Animations.} URL: \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{http://melusine.eu.org/}} \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{syracuse/metapost/animations/chupin/?idsec=scara}}
+\bibitem{chupin} Chupin, M.: \emph{Syracuse MetaPost/Animations.} URL: \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{http://melusine.eu.org/}} \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{syracuse/metapost/animations/chupin/?idsec=scara}}
\bibitem{dvisvgm} \emph{dvisvgm: A fast DVI to SVG converter} URL: \url{http://dvisvgm.de}
\bibitem{gilg05} Gilg, J.: PDF-Animationen. In: \emph{Die \TeX nische Kom\"odie}, Issue 4, 2005, pp.~30--37
%\bibitem{hol} Holeček, J.: \emph{Animations in a pdf\TeX-generated PDF}. URL: \url{http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml}
\bibitem{hol} Holeček, J.; Sojka, P.: Animations in pdf\TeX-generated PDF. In: \emph{\TeX, XML, and Digital Typography}, Springer, 2004, pp.~179--191. doi:10.1007/978-3-540-27773-6\textunderscore14
\bibitem{luque12} Luque, M.: \emph{PSTricks : applications.} URL: \url{http://pstricks.blogspot.com}
+\bibitem{media4svg} \emph{The media4svg Package}. URL: \url{http://www.ctan.org/pkg/media4svg}
\bibitem{media9} \emph{The media9 Package}. URL: \url{http://www.ctan.org/pkg/media9}
\bibitem{texsx} \emph{Beamer: animate package and overlay}. URL: \href{https://tex.stackexchange.com/a/385209}{\url{https://tex.stackexchange.com}}\\ \href{https://tex.stackexchange.com/a/385209}{\url{/a/385209}}
\end{thebibliography}