R: Set or query animation options

ani.options {animation}

R Documentation

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

...

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

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.
ani.res: The nominal resolution in ppi which will be recorded in the bitmap file, if a positive integer. Also used for units other than the default, and to convert points to pixels.; see graphics devices like png, jpeg.
imgnfmt: Customizing image number format in saveHTML, saveGIF, saveLatex and saveVideo, saveSWF is not included, it allows user to define the C-style string format for output image.
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: if TRUE, write a footer part in the HTML page containing detailed technical information else the footer of the page will be blank.
loop: logical or numeric: Number of times the GIF animation is to cycle through the image sequence before stopping. By default, this is set to zero or boolean value TRUE (infinite loop).
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!

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

References

Examples at https://yihui.org/animation/example/ani-options/