Skip to contents

Render a rotating cell plot animation

cell_plot_animate.Rd

Builds a cell_plot() recipe once, draws one frame per rotation angle, and encodes a GIF or video. Rotation geometry comes from cell_coord_rotate(). When a boomerang returns through an angle that was already drawn, that frame is copied instead of drawn again. An odd frames count is raised to the next even number, with a warning, so the return trip is made of those copies. File type, size, resolution, frame rate, and the frame backend belong here.

Usage

cell_plot_animate(
  object,
  file,
  frames = 500,
  width = 500,
  height = 500,
  res = 150,
  fps = 20,
  frame_backend = c("base", "ggplot2"),
  workers = 1L,
  boomerang = FALSE
)

Arguments

object

A cell_plot recipe that includes cell_coord_rotate().

file

Output path. The extension selects the encoder.

frames

Positive whole number of encoded frames. A boomerang with an odd count is raised to the next even number.

width, height

Output size in pixels.

res

PNG resolution in pixels per inch.

fps

Encoded frames per second.

frame_backend

Device used to draw each frame. "base" is faster. "ggplot2" matches the static renderer more closely.

workers

Positive whole number of parallel workers. 1 renders sequentially.

boomerang

Whether the encoded frames return through the rotation. Return frames that repeat an angle already drawn are copied.

Value

The output path, invisibly.

Details

GIF output uses gifski. Any other extension is encoded with av. The parent directory of file must already exist. An existing file is overwritten.

See also

cell_plot(), cell_coord_rotate(), cell_illuminate()

Examples

se <- ReadPNA_Seurat(minimal_pna_pxl_file())
#> ✔ Created a <Seurat> object with 5 cells and 158 targeted surface proteins
se <- LoadCellGraphs(se, cells = colnames(se)[4], verbose = FALSE) |>
  ComputeLayout(layout_method = "spectral")
#> ℹ Computing layouts for 1 graphs

cell_graph <- CellGraphs(se)[[4]]

layout_data <- FetchLayoutData(cell_graph, layout_method = "spectral_3d") |>
  # Downsample to speed up tests
  dplyr::slice_sample(n = 5000)
file <- tempfile(fileext = ".gif")
cell_plot(layout_data) |>
  cell_coord_rotate(axis = "y") |>
  cell_plot_animate(file, frames = 2, width = 160, height = 160, res = 72)
#> ℹ Encoding /tmp/Rtmp3BjCtL/file22fd775ea2c.gif
#> ✔ Encoding /tmp/Rtmp3BjCtL/file22fd775ea2c.gif [15ms]
#>