File: saveGIF.Rd

package info (click to toggle)
r-cran-animation 2.7%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, forky, sid, trixie
  • size: 1,268 kB
  • sloc: javascript: 873; sh: 15; makefile: 2
file content (117 lines) | stat: -rw-r--r-- 4,061 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/saveGIF.R
\name{saveGIF}
\alias{saveGIF}
\alias{saveMovie}
\title{Convert images to a single animation file (typically GIF) using ImageMagick
or GraphicsMagick}
\usage{
saveGIF(
  expr,
  movie.name = "animation.gif",
  img.name = "Rplot",
  convert = "magick",
  cmd.fun,
  clean = TRUE,
  extra.opts = "",
  ...
)

saveMovie(
  expr,
  movie.name = "animation.gif",
  img.name = "Rplot",
  convert = "magick",
  cmd.fun,
  clean = TRUE,
  extra.opts = "",
  ...
)
}
\arguments{
\item{expr}{an expression to generate animations; use either the animation
functions (e.g. \code{brownian.motion()}) in this package or a custom
expression (e.g. \code{for(i in 1:10) plot(runif(10), ylim = 0:1)}).}

\item{movie.name}{file name of the movie (with the extension)}

\item{img.name}{file name of the sequence of images (`pure' name; without any
format or extension)}

\item{convert}{the command to convert images (default to be \command{convert}
(i.e. use ImageMagick), but might be \command{imconvert} under some Windows
platforms); can be \command{gm convert} in order to use GraphicsMagick; see
the 'Note' section for details}

\item{cmd.fun}{a function to invoke the OS command; by default
\code{\link{system}}}

\item{clean}{whether to delete the individual image frames}

\item{extra.opts}{additional options passed to \code{\link{im.convert}}}

\item{\dots}{other arguments passed to \code{\link{ani.options}}, e.g.
\code{ani.height} and \code{ani.width}, ...}
}
\value{
The command for the conversion (see \code{\link{im.convert}}).
}
\description{
This function opens a graphical device (specified in
\code{ani.options('ani.dev')}) first to generate a sequence of images based
on \code{expr}, then makes use of the command \command{convert} in
`ImageMagick' to convert these images to a single animated movie (as a GIF or
MPG file). An alternative software package is GraphicsMagick (use
\code{convert = 'gm convert'}), which is smaller than ImageMagick.
}
\details{
This function calls \code{\link{im.convert}} (or \code{\link{gm.convert}},
depending on the argument \code{convert}) to convert images to a single
animation.

The advantage of this function is that it can create a single movie file,
however, there are two problems too: (1) we need a special (free) software
ImageMagick or GraphicsMagick; (2) the speed of the animation will be beyond
our control, as the \code{interval} option is fixed. Other approaches in this
package may have greater flexibilities, e.g. the HTML approach (see
\code{\link{saveHTML}}).

See \code{\link{ani.options}} for the options that may affect the output,
e.g.  the graphics device (including the height/width specifications), the
file extension of image frames, and the time interval between image frames,
etc.  Note that \code{ani.options('interval')} can be a numeric vector!
}
\note{
See \code{\link{im.convert}} for details on the configuration of
  ImageMagick (typically for Windows users) or GraphicsMagick.

  It is recommended to use \code{ani.pause()} to pause between animation
  frames in \code{expr}, because this function will only pause when called in
  a non-interactive graphics device, which can save a lot of time.  See the
  demo \code{'Xmas2'} for example (\code{demo('Xmas2', package =
  'animation')}).

  \code{\link{saveGIF}} has an alias \code{\link{saveMovie}} (i.e. they are
  identical); the latter name is for compatibility to older versions of this
  package (< 2.0-2). It is recommended to use \code{\link{saveGIF}} to avoid
  confusions between \code{\link{saveMovie}} and \code{\link{saveVideo}}.
}
\references{
Examples at \url{https://yihui.org/animation/example/savegif/}

  ImageMagick: \url{http://www.imagemagick.org/script/convert.php};

  GraphicsMagick: \url{http://www.graphicsmagick.org}
}
\seealso{
Other utilities: 
\code{\link{im.convert}()},
\code{\link{saveHTML}()},
\code{\link{saveLatex}()},
\code{\link{saveSWF}()},
\code{\link{saveVideo}()}
}
\author{
Yihui Xie
}
\concept{utilities}