====== Set or Query Animation Parameters ======

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

===== 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. ''[[prob:brownian_motion|brownian.motion()]]'', ''[[prob:buffon_s_needle|buffon.needle()]]'', ...), but sometimes it is not (e.g. ''[[dmml:k-nearest_neighbour_algorithm|knn.ani()]]'', ''[[compstat:gradient_descent_algorithm|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((where ''k'' is the number of animation frames made in one step)). 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!

===== Examples =====

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

<code r>
# 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")
</code>

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,

<code r>
# 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
</code>

===== Discussion =====

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