R: Play Recorded Coordinate Frames

animate.frames {ivue}

R Documentation

Play Recorded Coordinate Frames

Description

Display a sequence of point clouds or embedded graphs with browser playback controls. No layout algorithm, coordinate alignment, or interpolation is applied. The camera can be rotated while playback is paused or running.

Usage

animate.frames(
  frames,
  edges = NULL,
  labels = NULL,
  frame.index = NULL,
  max.frames = 100L,
  fps = 6,
  loop = TRUE,
  col = "#197A68",
  point.size = 5,
  edge.col = "gray65",
  edge.width = 1,
  camera = NULL,
  width = NULL,
  height = 600L,
  background.color = "white",
  mapping = NULL,
  legend.title = "Color",
  caption = NULL,
  description = NULL,
  controls = TRUE
)

Arguments

frames

List of at least two numeric n-by-2 or n-by-3 matrices with identical dimensions. A row is one vertex throughout the sequence. Each row must be entirely finite or entirely missing (NA or NaN, an inactive vertex). If row names are supplied, every frame must have the same unique names in the same order. Two-dimensional coordinates are embedded in the z=0 plane.

edges

Optional two-column matrix of one-based vertex indices, shared across frames. An edge is visible only when both endpoints are active.

labels

Optional character labels, one per original frame.

frame.index

Optional strictly increasing original frame indices to retain. Selection is explicit and takes precedence over max.frames.

max.frames

Maximum frames retained by evenly spaced subsampling, including the first and last. NULL keeps all frames. Subsampling reports a message; original indices remain in the timeline and returned metadata.

fps

Frames per second at the initial playback speed, from 0.1 to 100.

loop

Repeat browser playback.

col

Point colors, length one or n. Alpha components are preserved.

point.size

Point diameter in screen pixels.

edge.col

Edge colors, length one or the number of edges.

edge.width

Positive edge width in screen units.

camera

Initial camera specification, as in plot3D.plain(). The default is orthographic: face-on for 2D and camera.zup() for 3D.

width, height

Widget dimensions, as in plot3D.plain().

background.color

Canvas background color.

mapping

Optional result of map.colors(), with one color per vertex in frame row order. Mutually exclusive with col. Carries a fixed numerical or categorical legend into saved interactive HTML. Colors do not change with the frames; describe their meaning with caption.

legend.title

Title for the mapping's color legend.

caption

Optional plain-text interpretation retained below the widget when saved as HTML; for example, 'Color: final saddle height; positions: current frame.' For GIF output, request annotations = TRUE in write.animation.gif().

description

Optional plain-text scene description for readers who cannot see or manipulate the canvas. NULL describes the point count. Also shown below the widget, including when scripts or WebGL are unavailable.

controls

Show keyboard-operable view controls: rotate, zoom, reset, and download current view settings as an R recipe. The recipe contains camera, bounds, and aspect; use source("ivue-view.R"), then pass view$camera, view$limits, and view$aspect to a new plot. Browser interaction never changes the original R object. Match widget dimensions as well as settings for equal screen scale. Reset restores the initial view.

Details

Playback starts paused and steps between recorded frames. All frames have equal duration, even after subsampling; the timeline does not represent solver wall time. Bounds are fitted once to all original frames, including omitted frames. Inactive rows may appear or disappear at any step; missing positions are never interpolated. Supplied colors retain their association with vertex rows and edge rows. Numeric point, edge, and background palette indices are resolved when the widget is created, so later palette changes do not alter playback or GIF export.

Large traces increase widget size approximately with the product of frame count and the number of vertices plus edge endpoints. Use max.frames or frame.index to limit output size. A frame can be empty, but the full sequence must contain at least one finite point.

Only points and optional straight edges are animated. Use col with map.colors() to reuse numerical or categorical color scales; passing mapping instead also preserves its legend. Ordinary static plotting and validation retain their stricter finite-coordinate requirements. rgl is loaded only when a widget is constructed.

Value

An rglwidget/htmlwidget with an attached player. Save interactive output using htmlwidgets::saveWidget(). In Shiny, return the complete animation from shiny::renderUI() into shiny::uiOutput() so its separate player and caption are included; rgl::renderRglwidget() returns only the scene and is suitable for static views. attr(widget, "ivue.animation") contains the retained frames, original frame indices, labels, active masks, edges, fixed bounds, styles, fps, and initial camera for GIF export.

Examples

X <- rbind(c(0, 0), c(1, 0), c(0, 1))
first <- X; first[3, ] <- NA
frames <- list(first, X, X * 1.5)
edges <- rbind(c(1, 2), c(2, 3), c(3, 1))
if (nzchar(system.file(package = "rgl"))) {
  w <- animate.frames(frames, edges, fps = 2)
}

[Package ivue version 0.1.0 Index]