Set or Query Animation Parameters

The function ani.options() is mainly based on the function options() to set or query animation parameters.

In all there are currently 13 parameters to control the output of animations (mainly for HTML output): interval, nmax, ani.width, ani.height, outdir, filename, withprompt, ani.type, ani.dev, title, description, footer, autobrowse. Among these options, maybe nmax is the most difficult to understand. Sometimes it is equal to the maximum number of animation frames (e.g. brownian.motion(), buffon.needle(), …), but sometimes it is not (e.g. knn.ani(), grad.desc(), …).

Generally speaking, what nmax really governs is the number of steps in a loop. We know that there might be: (1) more than one condition to end (or break) a loop (2) more than one frame being recorded in a step. These two facts make nmax a little complicated. The former case will make nmax no greater than what you specified, while the latter one will produce k * nmax animation frames during a whole loop¹⁾. You should refer to the help pages to know what nmax exactly means.

At last, it is recommended that you should specify nmax each time you call an animation function, because usually in the last part of an animation function, the nmax will be reset to the actual number of animation frames, which might be larger or smaller than the value set before!

The most common options that will be used are interval and nmax. For example,

# 100 frames of brownian motion
ani.options(nmax = 100)
brownian.motion(pch = 21, cex = 5, col = "red", bg = "yellow")
 
# too slow? OK, faster: interval = 0.02
ani.options(interval = 0.02)
brownian.motion(pch = 21, cex = 5, col = "red", bg = "yellow")

Note that ani.options() will change the global options for any animation functions unless you quit R, so you'd better save the value returned to an object and restore the options when you have finished creating an animation. For example,

# save the options in 'oopt'
 > oopt = ani.options(interval = 0.5, nmax = 40)
 
# play the animation
 > boot.iid(main = c("", ""))
# see the values of interval and nmax
 > ani.options('interval')
[1] 0.5
 > ani.options('nmax')
[1] 40
 
# restore the options
 > ani.options(oopt)
# default options
 > ani.options('interval')
[1] 0.02
 > ani.options('nmax')
[1] 50
 
# what's oopt?
 > str(oopt)
List of 13
 $ interval   : num 0.02
 $ nmax       : num 50
 $ ani.width  : num 480
 $ ani.height : num 480
 $ outdir     : chr "C:\\WINDOWS\\Temp\\Rtmpi1JPFO"
 $ filename   : chr "index.htm"
 $ withprompt : chr "ANI> "
 $ ani.type   : chr "png"
 $ ani.dev    :function (filename = "Rplot%03d.png", width = 480, height = 480, 
    units = "px", pointsize = 12, bg = "white", res = NA\, restoreConsole = TRUE\)  
 $ title      : chr "Statistical Animations Using R"
 $ description: chr "This is an animation."
 $ footer     : logi TRUE\
 $ autobrowse : logi TRUE\

If I have not made it clear enough, please raise you questions here.