animate_system: Animate the System Over Time (Smart 2D/3D Dispatch)

In orbitr: A Tidy Physics Engine for Building and Visualizing Orbital Simulations

Animate the System Over Time (Smart 2D/3D Dispatch)

Description

Plays the simulation forward as an animation. Bodies move through their orbits frame by frame, optionally leaving a fading wake behind them. This is the animated counterpart to [plot_system()] — a moving snapshot rather than a single frozen one.

Usage

animate_system(
  sim_data,
  fps = 20,
  duration = 10,
  trails = FALSE,
  three_d = NULL
)

Arguments

sim_data	A tibble output from [simulate_system()].
fps	Frames per second of the rendered animation. Default '20'.
duration	Length of the animation in seconds. Default '10'. Together with 'fps', this determines how many simulation time steps are sampled into frames ('fps * duration'). If your simulation has fewer steps than that, every step becomes a frame.
trails	Logical. If 'TRUE' (the default), each body leaves a fading wake of its recent positions behind it. Set 'FALSE' for naked moving dots.
three_d	Logical. If 'TRUE', forces a 3D animation even for planar data.

Details

If any body has non-zero motion in the Z dimension (or 'three_d = TRUE'), [animate_system_3d()] is used; otherwise a 2D 'gganimate' animation is returned.

The 2D path requires the 'gganimate' package, which is in 'Suggests'. Install it with 'install.packages("gganimate")'. Rendering a 2D animation is much slower than a static plot — expect tens of seconds for typical simulations, since every frame is drawn and encoded as a GIF (or MP4).

The 3D path uses ‘plotly'’s built-in 'frame' aesthetic, which produces an interactive HTML widget with a play button and time slider. No GIF encoding is involved, so 3D animations render essentially instantly.

Value

A rendered 'gganimate' animation (2D) or a 'plotly' HTML widget with built-in play/pause controls (3D). The 2D return value can be saved to disk with [gganimate::anim_save()].

Examples

sim <- create_system() |>
  add_sun() |>
  add_body("Earth", mass = mass_earth, x = distance_earth_sun, vy = speed_earth) |>
  simulate_system(time_step = seconds_per_day, duration = seconds_per_year)

# 2D fading-wake animation (requires gganimate)
anim <- animate_system(sim, fps = 20, duration = 8)
anim

# Save to disk
gganimate::anim_save(file.path(tempdir(), "earth_orbit.gif"), anim)

orbitr documentation built on Oct. 2, 2026, 1:06 a.m.