| write.animation.gif {ivue} | R Documentation |
Export Recorded Frames to GIF
Description
Render the retained frames of an animate.frames() widget to an animated
GIF. Export uses a separate orthographic raster renderer and requires the
optional magick package; it does not launch a browser or native 3D window.
Usage
write.animation.gif(
animation,
file,
fps = NULL,
width = 600L,
height = 600L,
final.hold = 2,
loop = TRUE,
labels = TRUE,
overwrite = FALSE,
annotations = FALSE
)
Arguments
animation |
A widget returned by |
file |
Destination ending in .gif. Its parent directory must exist. |
fps |
Frames per second, from 0.1 to 100; NULL uses the widget's initial speed. |
width, height |
GIF dimensions in pixels. |
final.hold |
Additional seconds to hold the last frame, from zero to 600. |
loop |
Repeat the GIF indefinitely; FALSE plays once. |
labels |
Draw the retained frame labels above the image. |
overwrite |
Allow replacing an existing destination. |
annotations |
Include the animation's mapping legend and plain-text caption. FALSE preserves the unannotated layout. TRUE reserves space beside and below the scene within width and height; enlarge these dimensions if the text does not fit. No annotation is drawn over observations. |
Details
GIF export uses the widget's retained coordinates, visibility masks, colors, edge widths, and initial camera orientation. Camera rotations or speed changes made later in the browser are not returned to R. Download view settings and supply their camera when constructing a new animation to reuse its orientation and zoom. With annotations = TRUE, a raster legend and caption are drawn from the retained mapping and caption, including category counts and missing values. Arbitrary HTML is not rasterized. Create a widget with an explicit camera to export that view. Perspective cameras (fov greater than zero) are rejected; use camera.zup(fov = 0).
The raster renderer projects points and straight edges orthographically, with fixed bounds and equal coordinate scales across all frames. Zoom has the rgl convention: smaller values enlarge the scene. The observer position and bounds determine its orthographic scale. Annotations reduce the available scene area; compare exports using the same dimensions and annotation layout. Text wraps at a fixed readable size; layouts that cannot fit are rejected. Edges are painted before points, ordered within each group from back to front. This is a diagram renderer, not a pixel-identical WebGL screenshot or a depth-buffered rendering of intersecting 3D geometry. Point sizes can differ slightly between browser and raster output. No alignment, recentering of individual frames, or interpolation is performed.
GIF delays are rounded to centiseconds, with a minimum of one centisecond. The additional final hold is applied once per loop. Export works from an R widget object, not from a saved HTML file. Temporary images and graphics devices are cleaned up on success and failure.
Value
The normalized output path, invisibly.
See Also
Examples
if (nzchar(system.file(package = "rgl")) &&
requireNamespace("magick", quietly = TRUE)) {
X <- rbind(c(0, 0), c(1, 0), c(0, 1))
w <- animate.frames(list(X, X * 1.5), fps = 2)
path <- tempfile(fileext = ".gif")
write.animation.gif(w, path, width = 240, height = 240)
unlink(path)
}