The animate Package Alexander Grahn th May Abstract A - PDF document

TheanimatePackageAlexanderGrahn 4thMay2007AbstractALATEXpackageforcreatingportable,JavaScriptdrivenPDFanimationsfromsetsofgraphicslesorinlinegraphics.Keywords:include,portable,animation,animating,embed,animated,in-linegraphics,vectorgraphics,graphicsles,LaTeX,dvips,ps2pdf,pdfLa-TeX,PDF,JavaScript,PSTricks,pgf,TikZ,LaTeX-picture,AdobeReaderContents1Introduction22Requirements23Installation24Usingthepackage25Theuserinterface36Examples56.1Animationfromasetofles,using`animategraphics'command.56.2AnimatingPSTricksgraphics,using`animateinline'environment67Bugs78Acknowledgements81 1IntroductionThispackageprovidesaninterfacetocreatePDFswithanimatedcontentfromsetsofgraphicsles,frominlinegraphics,suchasLATEX-picture,PSTricksorpgf/TikZgeneratedpictures,orjustfromtypesettext.Unlikestandardmovie/videoformats,whichcanbeembedded,forexample,usingtheLATEXpackage`movie15'[1],package`animate'allowsforanimatingvectorgraphics.TheresultisroughlysimilartotheSWF(Flash)format,althoughnotasspace-ecient.Package`animate'supportstheusualPDFmakingworkows,i.e.pdfLATEXandLATEX!dvips!ps2pdf(Ghostscript).ThenalPDFcanbeviewedincurrentAdobeReader®sonallsupportedplat-forms.The`animate'packagemakesuseofOptionalContentGroups(OCG),alsoknownasPDFlayers,whichisafeatureprovidedbythePDF-1.5specication.EachframeofananimationisassociatedwithanOCGthatismadevisibleorinvisibleinadynamicfashionbymeansofAdobeReader'sbuilt-inJavaScriptengine.2Requirementspdf"TEX,version1:20forPDFoutputAdobeReader,version63InstallationThele`animate.sty'shouldbestoredinaplacewhereLATEXcanndit.4UsingthepackageFirstofall,readSection7onproblemsrelatedtothispackage.Then,invokethepackagebyputtingtheline\usepackage[packageoptions&#x-4.9;祔]{animate}tothepreambleofyourdocument,i.e.somewherebetween\documentclassand\begin{document}.`animate'honoursthepackageoptions:autoplayautopauseautoresumecontrolsbuttonsize=size&#x-4.9;職2 looppalindromescreenbg=colour&#x-4.9;祔buttonbg=colour&#x-4.9;祔stepposter=[first|none|last]Thesameoptionsarealsoavailableascommandoptionsandwillbeexplainedshortly.However,ifusedaspackageoptionstheyhaveglobalscope,takingeectonallanimationsinthedocument.IfPDFisgeneratedviaDVIandPostscriptbythecommandsequencelatex!dvips!ps2pdf,the`graphicx'packageisrequired.Important:Thedvipsoption`-Ppdf'shouldnotbesetwhenconvertingtheintermediateDVIintoPostscript.Ifyoucannotdowithout,put`-X2400-Y2400'after`-Ppdf'onthecommandline.5TheuserinterfacePackage`animate'providesthecommand\animategraphics[options&#x-4.9;祔]{framerate&#x-4.9;祔}{filebasename&#x-4.9;祔}{first&#x-4.9;葄}{last.07;爠}andtheenvironment\begin{animateinline}[options&#x-4.9;祔]{framerate&#x-4.9;祔}...typesetmaterial...\newframe...typesetmaterial...\newframe*...typesetmaterial...\end{animateinline}While\animategraphicscanbeusedtoassembleanimationsfromsetsofex-istinggraphicsles,theenvironment`animateinline'isintendedtocreatetheanimationfromthetypesetmaterialitencloses.ThismaterialcanbepicturesdrawnwithintheLATEXpictureenvironmentorusingtheadvancedcapabili-tiesofPSTricksorpgf/TikZ.Evenordinarytextualmaterialmaybeanimatedinthisway.Thecommand\newframeterminatesaframeandstartsthenextone.Thereisastarredversion,\newframe*.Ifplacedafteraparticularframeitcausestheanimationtopauseatthatframe.Theanimationcontinuesnormallyafterclickingitagain.Theparameterframerate&#x-4.9;職speciesthenumberofframespersecondoftheanimation.Alllesofthesequencemustbeconsecutivelynumbered.filebasename&#x-4.9;祔istheleftmostpartofthelenamethatallmembersofthesequencehaveincommon.first&#x-4.9;祔isthenumberoftherstandlast&#x-4.9;祔thenumberofthelastleintheset.first&#x-4.9;祔andlast&#x-4.9;祔musthavethesamenumberofdigitstoensurepropersorting.Ifnecessary,renametheleswithzerospaddedtotheleft.3 Thereisnolenameextensiontobespeciedasparameter.ThepossibleleformatsdependonwhetherLATEXorpdfLATEXisused.InthecaseofLATEX,leswiththeextension`eps'aresearchedforatrst,followedby`mps'(METAPOST-generatedPostscript)and`ps'.WithpdfLATEXthesearchingorderis:(1)`pdf',(2)`mps',(3)`png',(4)`jpg',(5)`jpeg',(6)`jbig2'and(7)`jb2'.Thatis,lescapabletostorevectorgraphicsarefoundrst.Makesurethatalllenameshavelowercaseextensions.Forexample,giventhesequence`frame_05.png'through`frame_19.png'fromapossiblylargersetthatshallbeusedtobuildtheanimation.Then,filebasename&#x-4.9;祔wouldbespeciedas`frame_',first&#x-4.9;祔as`05'andlast&#x-4.9;祔as`19'.Thefollowingoptionsto\animategraphicsand`animateinline'havebeenprovided:autopausePauseanimationwhenthepageisclosed,insteadofstoppingandrewindingittothedefaultframe.autoplayStartanimationafterthepagehasopened.Alsoresumesplaybackofapreviouslypausedanimation.autoresumeResumepreviouslypausedanimationwhenthepageisopenedagain.loopTheanimationrestartsimmediatelyafterreachingtheend.palindromeTheanimationcontinuouslyplaysforwardandbackward.controlsInsertscontrolbuttonsbelowtheanimationwidget.Themeaningofthebuttonsisasfollows,fromlefttoright:stop&rstframe,stepbackward,playbackward,playforward,stepforward,stop&lastframe,decreasespeed,defaultspeed,increasespeed.Both`play'buttonsarereplacedbyalarge`pause'buttonwhiletheanimationisplaying.width=width&#x-4.9;職height=height&#x-4.9;祔depth=depth&#x-4.9;職Resizetheanimationwidget.AnyvalidTEXdimensionisacceptedasparameter.Option`depth'specieshowfartheanimationwidgetshouldextendbelowthebottomlineoftherunningtext.Ifonlyoneoftheseoptionsisgiven,theothersarescaledtokeeptheaspectratio.4 scale=factor&#x-4.9;職Scalestheanimationwidgetbyfactor&#x-4.9;祔.buttonsize=size&#x-4.9;職Changesthecontrolbuttonheighttosize&#x-4.9;祔,whichmustbeavalidTEXdi-mension.Thedefaultbuttonheightis1.44emandthusscaleswiththecurrentfontsize.screenbg=colour&#x-4.9;祔buttonbg=colour&#x-4.9;祔Thebackgroundoftheanimationandcontrolbuttonwidgetsistransparentbydefault.Itcanbeturnedintoasolidcolourbytheparametercolour&#x-4.9;祔,whichisanarrayofnumbers(withoutsurroundingbrackets)intherangefrom0.0to1.0.Thenumberofarrayelementsdeterminesthecolourmodelinwhichthecolourisdened:(1)grayvalue,(3)RGB,(4)CMYK.stepStepthroughtheanimationbyoneframepermouse-click.poster=[first|none|last]Specieswhichframe(rst,lastornone)todisplayandprintiftheanimationisnotactivated.Option`poster=rst'neednotbeexplicitlysetbecauseitisthedefault.6Examples6.1Animationfromasetofles,using`animategraphics'command\documentclass{article}\usepackage{animate}\usepackage{graphics}\begin{document}\begin{center}\animategraphics[controls,loop]{4}{frame_}{0}{8}\end{center}\end{document}5 6.2AnimatingPSTricksgraphics,using`animateinline'environment\documentclass{article}\usepackage{pst-3dplot}\usepackage{fp}\usepackage{animate}%drawsatorussector\newcommand{\torus}[1]{%#1:angleofthetorussector\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){%tcos2mul4usin2muladdmultsin2mul4usin2muladdmulucos4mul}%\parametricplotThreeD[yPlotpoints=75](0,360)(80,#1){%ucos2mul4tsin2muladdmulusin2mul4tsin2muladdmultcos4mul}%\FPupn\strokewidth{360#1sub360div3mul}%\parametricplotThreeD[yPlotpoints=1,linewidth=\strokewidthpt](0,360)(#1,#1){%ucos2mul4tsin2muladdmulusin2mul4tsin2muladdmultcos4mul}%\end{pspicture}%}\begin{document}\begin{center}\newcounter{torusangle}\setcounter{torusangle}{80}6 \begin{animateinline}[poster=last,controls,palindrome]{10}%\torus{\thetorusangle}%\whiledo{\thetorusangle360}{%\newframe%\addtocounter{torusangle}{10}%\torus{\thetorusangle}%}\end{animateinline}%\end{center}\end{document} 7BugsˆThecommand\multidoanditsrelativesfrompackage`multido'donotworkiftheloopbodycontains\newframe.Use\whiledofrompackage`ifthen'instead.Acountermustbedeclaredtokeeptrackofthenumberofiterations.Furthervariablesthattakexedpointdecimalstobeusedwithintheloopbodycanbedenedandincrementedbymeansofthecommands\FPsetand\FPaddfrompackage`fp'.Forexample:%declareloopcounter\newcounter{iter}%\begin{animateinline}{12}%initializeloopcounter\setcounter{iter}{0}%%definesomevariable,e.g.`\somevar'\FPset{\somevar}{1.0}%%makecopy`\varcopy'of`\somevar'withglobalscope\xdef\varcopy{\somevar}%......createfirstframeusing\somevar(=1.0)...(\multido_can_beusedhere!)...\whiledo{\theiter50}{%do50iterations7 %startnewframe\newframe%%incrementloopcounterby1\addtocounter{iter}{1}%%increment\somevarby,e.g.,0.5\FPadd{\somevar}{\varcopy}{0.5}%%refreshthecopy\xdef\varcopy{\somevar}%......createframeusing\somevar...(\multido_can_beusedhere!)...}\end{animateinline}ˆCurrently,animationscannotbeplacedonmultilayeredslidescreatedwiththeBeamerclass.Putanimationsonatslidesonly.(Ofcourse,slideswithoutanimationsmaystillhaveoverlays.)ˆThedvipsoption`-Ppdf'shouldbeavoidedentirelyorfollowedby`-X2400-Y2400'onthecommandlineinordertosetasensibleDVIresolution.IntimesofType-1fonts,thisdoesnotdegradetheoutputquality!Thecongurationle`config.pdf'loadedbyoption`-Ppdf'speciesanex-cessivelyhighDVIresolutionthatwillbepassedontothenalPDF.Eventually,AdobeReadergetsconfusedandwillnotdisplaytheframeswithintheanimationwidget.ˆAnimationswithcomplexgraphicsand/ormanyframesmaycauseLATEXtofailwitha`TeXcapacityexceeded'error.EnlargeTEX'smemorywithcommandlineoption`--mem-max=...'.ˆOriginally,package`animate'wasbasedonamethodsuggestedbyJanHole£ekandPetrSoika[2],butwasrewrittentouseOptionalContentGroups(OCG).OCG-basedanimationsarefullysupportedinAdobeReader8,buthavesomeperformanceissues.PlaybackisusuallyslowerinReader8thaninolderReaderversions,whichisprobablyabug.Thenon-OCGapproachperformsbetterinAdobeReader8,butpackage/commandoptions`autoplay',`autopause'and`autoresume'donotwork.Moreover,theanimationpositionandtheplay/pause'buttonsarenotproperlyresetonpagechange.ThisisduetousagerestrictionsthatAdobeimposedonsomeimportantJavaScriptmethodsinReader8.Anon-OCGversionofthepackageisstillavailableas`animate-noocg.sty'.8AcknowledgementsIwouldliketothankFrançoisLafontwhodiscoveredquiteafewbugsandmademanysuggestionsthathelpedtoimprovethefunctionalityofthepackage.8 References[1]TheMovie15Package.URL:http://www.ctan.org/tex-archive/macros/latex/contrib/movie15[2]Hole£ek,J.;Sojka,P.:AnimationsinpdfTEX-generatedPDF.In:LectureNotesinComputerScience,Vol.3130,2004,pp.1791919