Set or query animation options


There are various parameters that control the behaviour of the animation, such as time interval, maximum number of animation frames, height and width, etc.





arguments in tag = value form, or a list of tagged values. The tags usually come from the animation parameters described below, but they are not restricted to these tags (any tag can be used; this is similar to options).


ani.options() returns a list containing the options: when parameters are set, their former values are returned in an invisible named list. Such a list can be passed as an argument to ani.options to restore the parameter values.

ani.options('tag') returns the value of the option 'tag'.

ani.options(c('tag1', 'tag2')) or ani.options('tag1', 'tag2') returns a list containing the corresponding options.

Animation options

The supported animation parameters:


a positive number to set the time interval of the animation (unit in seconds); default to be 1.


maximum number of steps in a loop (e.g. iterations) to create animation frames. Note: the actual number of frames can be less than this number, depending on specific animations. Default to be 50.

ani.width, ani.height

width and height of image frames (unit in px); see graphics devices like png, jpeg, ...; default to be 480. NB: for different graphics devices, the units of these values might be different, e.g. PDF devices usually use inches, whereas bitmap devices often use pixels.


character: the name of the directory (a relative path) for images when creating HTML animation pages; default to be 'images'.


character: name of the target HTML main file (without path name; basename only; default to be 'index.html')

a function or a function name: the graphics device; e.g. (png, pdf, ...); default to be 'png'


character: image format for animation frames, e.g. png, jpeg, ...; default to be 'png'; this will be used as the file extension of images, so don't forget to change this option as well when you changed the option

title, description

character: the title and description of the animation in the HTML page created by saveHTML


logical or character: if TRUE, write a footer part in the HTML page containing detailed technical information; if given a character string, it will be used as the footer message; in other cases, the footer of the page will be blank.


whether to iterate or not (default TRUE to iterate for infinite times)


logical: whether auto-browse the animation page immediately after it is created? (default to be interactive())


logical: whether to autoplay the animation when the HTML page is loaded (default to be TRUE); only applicable to saveHTML

whether to use the graphics device specified in ani.options('') (default to be TRUE); if FALSE, we need to generate image files by our own approaches in the expression expr (see functions saveHTML, saveGIF, saveLatex and saveSWF); this can be useful when the output cannot be captured by standard R graphics devices – a typical example is the rgl graphics (we can use rgl.snapshot to capture rgl graphics to png files, or rgl.postscript to save plots as postscript/pdf; see demo('rgl_animation') or demo('use_Cairo') for examples or the last example below). Note, however, we do not really have to create the images using R graphics devices – see demo('flowers') on how to download images from the Internet and create an HTML animation page!

Hidden options

There are a couple of “hidden” options which are designed to facilitate the usage of some functions but are not initialized like the above options when the package is loaded, including:


this option will be checked first when calling im.convert (or saveGIF) to see if it contains the path to ‘convert.exe’; we can specify it beforehand to save the efforts in searching for ‘convert.exe’ in ImageMagick under Windows. For example, ani.options(convert = 'c:/program files/imagemagick/convert.exe'); note this option also works for Mac and Linux (see help(im.convert))


this can help saveSWF save the efforts of searching for the software package “SWF Tools” under Windows; e.g. we can specify ani.options(swftools = 'c:/program files/swftools') in advance


the value of this option can be used to determine the image filename format when we want to use custom graphics devices to record images, e.g. in saveLatex, if ani.options('') == FALSE, then ani.options('img.fmt') will be a string like 'path/to/output/', so we can use it to generate file names in the argument expr; see demo('rgl_animation') for example or the last example below


the path of the program qpdf, e.g. ani.options(qpdf = 'C:/Software/qpdf/bin/qpdf.exe'); qpdf is mainly used to compress PDF files in this package, and it is a smaller tool than pdftk. It is recommended over pdftk especially under Linux, because tests show that pdftk does not work well under Linux in compressing PDF files, while qpdf is much better.


the path of the program Pdftk, e.g. ani.options(pdftk = 'C:/Software/pdftk.exe') or ani.options(pdftk = '/home/john/bin/pdftk'); pdftk will be used to compress the PDF graphics output in the function pdftk; compression will not be tried if this options is NULL. This option will only affect saveGIF, saveLatex and saveSWF when ani.options('ani.type') is 'pdf'.


the path of the progam ffmpeg, e.g. ani.options(ffmpeg = 'C:/Software/ffmpeg/bin/ffmpeg.exe'); FFmpeg is used to convert a sequence of images to a video. See saveVideo.


Please note that nmax is not always equal to the number of animation frames. Sometimes there is more than one frame recorded in a single step of a loop, for instance, there are 2 frames generated in each step of kmeans.ani, and 4 frames in knn.ani, etc; whereas for newton.method, the number of animation frames is not definite, because there are other criteria to break the loop.

This function can be used for almost all the animation functions such as brownian.motion, boot.iid, buffon.needle, cv.ani, flip.coin, kmeans.ani, knn.ani, etc. Most of the options here will affect the behaviour of animations of the formats HTML, GIF, SWF and PDF; on-screen animations are only affected by interval and nmax.


Yihui Xie

See Also

options, dev.interactive, saveHTML, saveGIF, saveLatex, saveSWF, pdftk


## see the first example in help(animation) on how to set and
## restore animation options

## use the PDF device: remember to set 'ani.type' accordingly
oopt = ani.options( = "pdf", ani.type = "pdf", ani.height = 5, 
    ani.width = 7)

## use the Cairo PDF device if (require('Cairo')) {
## ani.options( = CairoPDF, ani.type = 'pdf', ani.height =
## 6, ani.width = 6) }

## don't loop for GIF/HTML animations
ani.options(loop = FALSE)

## don't try to open the output automatically
ani.options(autobrowse = FALSE)

## it's a good habit to restore the options in the end so that
## other code will not be affected

## how to make use of the hidden option 'img.fmt'
saveHTML(expr = {
    for (i in 1:5) plot(runif(10))
}, = "custom_plot", = FALSE, ani.type = "png", 
    description = "Note how we use our own graphics device in 'expr'.", 
    htmlfile = "custom_device.html")

Want to suggest features or report bugs for Use the GitHub issue tracker. Vote for new features on Trello.

comments powered by Disqus