Animate neuron/mesh objects across timepoints as a ggplot2 GIF

Renders a set of objects that change over time (each a per-timepoint list of neuron/neuronlist/mesh3d/hxsurf/point objects accepted by geom_neuron()) to a GIF, each object in its own colour, over an optional fixed reference volume and an optional set of static targets drawn in a transparent greyscale beneath the moving objects (e.g. the fixed shapes a warp should land on).

Usage

ggneuron_gif(
  x,
  flows = NULL,
  cols = NULL,
  volume = NULL,
  volume_col = "grey80",
  volume_alpha = 0.12,
  targets = NULL,
  target_cols = NULL,
  target_alpha = 0.18,
  alpha = 0.6,
  rotation_matrix = NULL,
  file = NULL,
  width = 900,
  height = 800,
  delay = 0.14,
  dpi = 96,
  pingpong = TRUE,
  fixed_limits = TRUE,
  centre = NULL,
  turntable_frames = 36L,
  spin_axis = c("z", "y", "x"),
  points = NULL,
  point_cols = NULL,
  point_size = 3,
  point_alpha = 1,
  point_stroke = 0.8
)

Arguments

x: Either a single spatial object to turn into a turntable (when flows is NULL), or — for back-compatibility — a flows list passed positionally.
flows: A named list; each element is the per-timepoint list of objects for one structure (all the same length, one entry per frame). Colours are per structure. If NULL (default) it is built from x: a turntable if x is a single spatial object, otherwise x is taken to already be the flows list.
cols: Named vector of colours (one per flows entry); recycled from a default palette if NULL.
volume: Optional fixed reference object drawn under every frame (e.g. a brain surface / hull).
volume_col: Colour of the reference volume (default "grey80"; pass e.g. a light pink to render a brain hull as a soft envelope).
volume_alpha, target_alpha: Alphas for the reference volume and target objects.
targets: Optional named list of fixed reference objects drawn above the volume but below the flow (e.g. the fixed targets each moving object should land on). Static across frames.
target_cols: Named vector of colours for targets; defaults to a transparent greyscale ramp so the coloured flow reads clearly on top.
alpha: Alpha for the moving (flow) objects: a single value for all, or a per-structure named vector (matched to flows by name) so e.g. a rotating brain mesh can be translucent while neurons stay opaque.
rotation_matrix: Optional 4x4 view matrix (as geom_neuron()/rgl use), applied to every object so all layers share one projection.
file: Output GIF path. Frames are written next to it. If NULL, frames are written to a temporary directory and their paths returned (no GIF assembled).
width, height, delay, dpi: GIF frame size (px), per-frame delay (s) and dpi.
pingpong: If TRUE (default) the frame sequence plays forward then back for a seamless loop.
fixed_limits: If TRUE (default) all frames share one set of x/y limits (spanning every frame plus the volume and targets) so moving objects don't make the camera appear to zoom; set FALSE to let each frame auto-scale.
centre: Rotation centre for the turntable (length-3). Defaults to the volume's centroid if a volume is given, else x's centroid.
turntable_frames: Number of frames in an auto-built turntable.
spin_axis: Axis the turntable rotates about: "y" (default), "x" or "z".
points: Optional named list of point sets drawn as circles on top of the neurons — e.g. neuron root points / somata. Each entry is either a static N x 3 matrix (same every frame) or, like flows, a per-timepoint list of matrices (circles that move with the warp). Anything nat::xyzmatrix() accepts works.
point_cols: Named vector of fill colours for points (one per entry); recycled from a default palette if NULL.
point_size, point_alpha, point_stroke: Circle size, alpha and outline width.

Value

The GIF path if written (needs gifski, or falls back to magick), else the vector of frame PNG paths.

Details

The simplest use is a turntable: pass a single spatial object as x (a neuron/neuronlist/mesh3d/hxsurf/dotprops/matrix) and, with flows left NULL, it is spun about its centroid (or centre) to a looping rotation GIF.

Examples

if (FALSE) { # \dontrun{
# Turntable of a single object (spun about its centroid):
ggneuron_gif(banc.brain_neuropil, file = "spin.gif")

# Turntable of neurons about the brain-hull centroid, brain shown translucent:
ggneuron_gif(banc.skels[1:6], volume = banc.brain_neuropil,
             rotation_matrix = banc_view, file = "spin.gif")

# Explicit animation: `warp` is a named list of per-timepoint mesh states.
ggneuron_gif(warp, volume = brain, volume_col = "lightpink",
             targets = target_meshes, file = "morph.gif")
} # }