JAnimateGIF: Combine multiple plots into an animated GIF file.

In JimMcL/JUtils: Some R Utilities

Combine multiple plots into an animated GIF file.

Description

Writes each frame to a PNG file, then combines them into a GIF file. Frames are created by calling a custom plot function. The PNG to GIF conversion is performed by a 3rd party R package or application.

Usage

JAnimateGIF(
  videoFileName,
  nFrames = NULL,
  frameKeys = 1:nFrames,
  plotFn,
  frameRate = 30,
  loop = 0,
  method = c("auto", "magick-r", "gifski", "magick", "ffmpeg"),
  optimize = FALSE,
  progress = FALSE,
  tmpDir = tempdir(TRUE),
  ...
)

Arguments

videoFileName	Name of the video file to be created. The file type is inferred from the file extension, but must be GIF if method == "gifski".
nFrames	Number of frames to be generated. You must specify one of nFrames or frameKeys.
frameKeys	Vector of keys to be passed to plotFn to identify the frame to be plotted. If not specified, frameKeys will be set to the sequence 1:nFrames.
plotFn	Function which is called once for each frame. It is called once for each frame to be generated, with a single argument which is one of the values from frameKeys. If it does not generate a plot, the frame will be silently skipped. If no frames are created for the entire animation, an error is generated.
frameRate	Play back frame rate - used to set the frame delay in the GIF file.
loop	Number of times animation should be played. 0 means loop infinitely.
method	Specify the library/tool used to convert from PNG to GIF: "magick-r" uses the magick R package. "magick" uses the ImageMagick command line application. "gifski" uses the gifski R package. "ffmpeg" uses the FFMpeg command line application, which can output mp4 files. The output format is suitable for use by Powerpoint (at least on my version). "auto" if videoFileName has an .mp4 extension, uses ffmpeg; otherwise uses "gifski" if it is installed, then "magick-r" if it is installed; otherwise "magick".
optimize	Only used if method == "magick-r". Passed to image_animate.
progress	Only used if method == "gifski". Passed to gifski; if TRUE, prints some progress messages.
tmpDir	Name of a directory to be used to create temporary files in.
...	Any additional arguments are passed to the JPlotToPNG function.

Details

You must have a suitable image conversion tool installed - see the documentation of the argument method for details. ImageMagick installed, and the ImageMagick bin subdirectory must be in your PATH environment variable. If ImageMagick is not installed, or is not in your PATH, JAnimateGIF will fail with an exception such as:

Error in system2("magick", c("convert", "jp*.png", "-delay",
100/frameRate, : '"magick"' not found

.

For a general discussion about creating an animation in R, see https://stackoverflow.com/questions/1298100/creating-a-movie-from-a-series-of-plots-in-r, or https://r-graph-gallery.com/animation.

The png to gif conversion can be quite time consuming for a large number of frames, so start with a small number of frames to ensure everything works as expected.

In theory, magick can create mpeg files, but I can't get it to work, so use method="ffmpeg" for file formats other than GIF.

Value

The error message (as a character vector) from the ImageMack convert command, or character(0) (returned invisibly) on success.

See Also

JPlotToPNG, JAnimateScenes for smoothly animating changing parameters.

Examples

## Not run: 
# Number of frames in the animation
nFrames <- 50

# A function to plot a coloured polygon
.plotPoly <- function(frame) {
  # Created an empty plot
  plot(NULL, xlim = c(-1, 1), ylim = c(-1, 1), asp = 1, xlab = "", ylab = "", axes = FALSE)
  # Frame starts from 1, but a 1 cornered polygon is not very visually interesting
  nCorners <- frame + 1
  angles <- 2 * pi * (1:nCorners) / nCorners
  f <- frame / nFrames
  # Pick a colour based on the frame number
  col <- rgb(sin(pi / 2 * f), cos(pi / 2 * f), sin(pi / 2 * (f + .5)))
  # Draw a polygon
  polygon(cos(angles), sin(angles), col = col, border = "black", lwd = 4)
}

JAnimateGIF("poly.gif", nFrames, plotFn = .plotPoly, frameRate = 10)

## End(Not run)

JimMcL/JUtils documentation built on Nov. 7, 2024, 11:25 a.m.