Set or query animation options

Description

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

Usage

ani.options(...)

Arguments

Value

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:

interval

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

nmax

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.

outdir

character: specify the output directory when we export the animations using saveHTML, saveGIF, saveLatex and saveSWF; default to be the temporary directory tempdir and we can reset to the current working directory by ani.options(outdir = getwd()).

imgdir

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

htmlfile

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

ani.dev

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

ani.type

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 ani.dev

title, description

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

verbose

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.

loop

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

autobrowse

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

autoplay

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

use.dev

whether to use the graphics device specified in ani.options('ani.dev') (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!

withprompt

character: prompt to display while using ani.start (will be restored with ani.stop)

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:

convert

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 = shQuote('c:/program files/imagemagick/convert.exe')); note this option also works for Mac and Linux (see help(im.convert))

swftools

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

img.fmt

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('use.dev') == FALSE, then ani.options('img.fmt') will be a string like 'path/to/output/img.name%d.png', so we can use it to generate file names in the argument expr; see demo('rgl_animation') for example or the last example below

qpdf

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.

pdftk

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'.

ffmpeg

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.

Note

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.

Author(s)

Yihui Xie <http://yihui.name>

References

http://animation.yihui.name/animation:options

http://qpdf.sourceforge.net/

http://www.pdflabs.com/docs/pdftk-man-page/

See Also

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

Examples

## 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(ani.dev = "pdf", ani.type = "pdf", ani.height = 5, ani.width = 7)

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

## change outdir to the current working directory
ani.options(outdir = getwd())

## 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
ani.options(oopt)

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