summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/animate
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-02-22 22:20:48 +0000
committerKarl Berry <karl@freefriends.org>2021-02-22 22:20:48 +0000
commit1f8a99f91f89d808a685fb90434693017786a8a6 (patch)
treec0adb02e7b8fd39fc9335d04d8dcd020fb37b570 /Master/texmf-dist/source/latex/animate
parent4220324e99226b427519e0380034f951f67a011f (diff)
parentd9e54ef03db8d244f5386fc89efffccb3d483a5e (diff)
sync with trunk 57841 to continue testing
git-svn-id: svn://tug.org/texlive/branches/branch2020@57848 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/animate')
-rw-r--r--Master/texmf-dist/source/latex/animate/animate.tex110
1 files changed, 66 insertions, 44 deletions
diff --git a/Master/texmf-dist/source/latex/animate/animate.tex b/Master/texmf-dist/source/latex/animate/animate.tex
index 684d9216df6..1cabe9c9fef 100644
--- a/Master/texmf-dist/source/latex/animate/animate.tex
+++ b/Master/texmf-dist/source/latex/animate/animate.tex
@@ -1,11 +1,12 @@
-\ifdefined\outputmode\outputmode=0\fi
-\ifdefined\pdfoutput\pdfoutput=0\fi
+\listfiles
% 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}
@@ -61,7 +62,7 @@
% \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 PDF-XChange Foxit Reader Firefox Chrome Chromium}
+\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},
@@ -112,13 +113,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), KDE Okular, 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}
@@ -128,8 +132,8 @@ On mobile devices, interaction with an animated SVG is similar to that on deskto
\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, PDF-XChange, Foxit Reader
-\item SVG: Chromium-based browsers, Firefox and others
+\item PDF: Acrobat Reader, KDE Okular, PDF-XChange, Foxit Reader
+\item SVG: Chromium-based browsers for best performance
\end{trivlist}
\section{Installation}
@@ -166,9 +170,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>
@@ -227,6 +235,11 @@ and the environment
\newframe
\multiframe{<number of frames>}{[<variables>]}{
... repeated (parameterized) material ...
+ \multiframebreak % optional!
+}
+\newframe*[...] % some \newframe variant required
+\multiframe{...}{...}{ % between two \multiframes
+ ...
}
\end{animateinline}
\end{verbatim}
@@ -241,6 +254,8 @@ The \verb+\multiframe+ command allows the construction of loops around pictures.
\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.
+\verb+\multiframebreak+ can be called to terminate a \verb+\multiframe+ loop prematurely, usually as part of a conditional statement. This command should preferably be placed near the end of the loop body in order not to produce an empty animation frame.
+
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}
@@ -266,9 +281,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 +296,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 +346,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}
+clip
+\end{verbatim}
+(\verb+\animategraphics+ only.) Clips the graphic to the (possibly modified) bounding box.
\begin{verbatim}
-pagebox
+pagebox=...
hiresbb
interpolate
\end{verbatim}
@@ -360,7 +379,7 @@ buttonbg=<colour>
buttonfg=<colour>
buttonalpha=<opacity>
\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. Option \verb+buttonalpha+ adds transparency to the control buttons. Its parameter \verb+<opacity>+ is a number between 0.0 and 1.0, where 0.0 produces fully transparent and 1.0 fully opaque buttons.
+By default, control button widgets are drawn with black strokes on empty, fully transparent background. The background can be filled with colour using the first option, while the second option specifies the stroke colour. Option \verb+buttonalpha+ adds transparency to the background 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. The parameter \verb+<opacity>+ is a number between 0.0 and 1.0, where 0.0 produces fully transparent and 1.0 fully opaque buttons.
\begin{verbatim}
draft
final
@@ -534,25 +553,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 +569,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 +583,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 +1356,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 +1373,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.
@@ -1368,8 +1385,11 @@ dvilualatex
xelatex -no-pdf
\end{verbatim}
to produce DVI or XDV output from the \LaTeX{} source. After this, SVG is obtained by running
+%\begin{verbatim}
+%dvisvgm --font-format=woff --exact --zoom=-1 --page=1,- --optimize ...
+%\end{verbatim}
\begin{verbatim}
-dvisvgm --font-format=woff --exact --zoom=-1 --page=1,- --optimize ...
+dvisvgm --font-format=woff --exact --zoom=-1 --page=1,- ...
\end{verbatim}
on the intermediate DVI or XDV file.
@@ -1381,7 +1401,7 @@ The purpose of `\verb+--zoom=-1+' is to produce responsive SVG. If embedded in a
By default, \verb+dvisvgm+ processes only the very first page of the input file. To convert multipage DVI/XDV with several animations, add option `\verb+--page=1,-+'.
-With option `\verb+--optimize+', \verb+dvisvgm+ applies several optimizations to reduce the output file size.
+%With option `\verb+--optimize+', \verb+dvisvgm+ applies several optimizations to reduce the output file size.
As SVG derives from XML it is not known to be particularly economical in terms of file size. Compressed SVG, with file extension `\verb+svgz+', shortens download times and is supported by most Web browsers. It can be generated by adding option `\verb+-z+'. Also, option `\verb+--precision=1+' may be used to reduce the SVG file size. It limits the precision of floating point numbers, such as coordinates, to one decimal figure. Sometimes, animations may behave stangely after applying this option. Then, of course, it should be omitted.
@@ -1455,13 +1475,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}