renderers: Renderers provided by gganimate

In dgrtwo/gganimate: A Grammar of Animated Graphics

Renderers provided by gganimate

Description

The purpose of the renderer function is to take a list of image files and assemble them into an animation. gganimate provide a range of renderers but it is also possible to provide your own, if the supplied ones are lacking in any way. A renderer is given as argument to animate()/print() and receives the paths to the individual frames once they have been created.

Usage

gifski_renderer(file = NULL, loop = TRUE, width = NULL, height = NULL)

file_renderer(dir = ".", prefix = "gganim_plot", overwrite = FALSE)

av_renderer(file = NULL, vfilter = "null", codec = NULL, audio = NULL)

ffmpeg_renderer(
  format = "auto",
  ffmpeg = NULL,
  options = list(pix_fmt = "yuv420p")
)

magick_renderer(loop = TRUE)

sprite_renderer()

Arguments

file	The animation file
loop	Logical. Should the produced gif loop
width, height	Dimensions of the animation in pixels. If NULL will take the dimensions from the frame, otherwise it will rescale it.
dir	The directory to copy the frames to
prefix	The filename prefix to use for the image files
overwrite	Logical. If TRUE, existing files will be overwritten.
vfilter	A string defining an ffmpeg filter graph. This is the same parameter as the -vf argument in the ffmpeg command line utility.
codec	The name of the video codec. The default is libx264 for most formats, which usually the best choice. See the av documentation for more information.
audio	An optional file with sounds to add to the video
format	The video format to encode the animation into
ffmpeg	The location of the ffmpeg executable. If NULL it will be assumed to be on the search path
options	Either a character vector of command line options for ffmpeg or a named list of option-value pairs that will be converted to command line options automatically

Details

The gifski_renderer() is used unless otherwise specified in animate() or in options('gganimate.renderer'). This renderer requires both the gifski and png packages to be installed.

Other possible renderers are:

• magick_renderer() which requires the magick package and produce a gif. If gifski is not installed, the rendering will be much slower than using the gifski_renderer() and can potentially result in system problems when many frames need to be rendered (if gifski is installed magick will use it under the hood)

• av_renderer() which requies the av package and uses ffmpeg to encode the animation into a video file.

• ffmpeg_renderer() which requires that ffmpeg has been installed on your computer. As with av_renderer() it will use ffmpeg to encode the animation into a video

• sprite_renderer() which requires magick and will render the animation into a spritesheet

• file_renderer() which has no dependencies and simply returns the animation as a list of image files (one for each frame)

It is possible to create your own renderer function providing that it matches the required signature (frames and fps argument). The return value of your provided function will be the return value ultimately given by animate()

Value

The provided renderers are factory functions that returns a new function that take frames and fps as arguments, the former being a character vector with file paths to the images holding the separate frames, in the order they should appear, and the latter being the framerate to use for the animation in frames-per-second.

The return type of the different returned renderers are:

• gifski_renderer: Returns a gif_image object

• magick_renderer: Returns a magick-image object

• av_renderer: Returns a video_file object

• ffmpeg_renderer: Returns a video_file object

• file_renderer: Returns a vector of file paths

Examples

anim <- ggplot(mtcars, aes(mpg, disp)) +
  transition_states(gear, transition_length = 2, state_length = 1) +
  enter_fade() +
  exit_fade()

## Not run: 
# Renderers are specified in the `animate()` function
animate(anim, renderer = sprite_renderer())

## End(Not run)

dgrtwo/gganimate documentation built on March 3, 2024, 8:15 a.m.