There are various parameters that control the behaviour of the animation, such as time interval, maximum number of animation frames, height and width, etc.
ani.options(...)
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.
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.
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.
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
.
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.
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 ani.dev
character: the title and description of the
animation in the HTML page created by saveHTML
logical: if TRUE
, write a footer part
in the HTML page containing detailed technical information else
the footer of the page will be blank.
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).
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('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!
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('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
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
.
Examples at https://yihui.org/animation/example/ani-options/
options
, dev.interactive
,
saveHTML
, saveGIF
, saveLatex
,
saveSWF
, pdftk