shift_reference_frame: Shift the coordinate reference frame of the simulation

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

Shift the coordinate reference frame of the simulation

Description

Recalculates the positions and velocities of all bodies relative to a specific target body, or to the system's center of mass. This effectively "anchors the camera" to the chosen point, placing it at the origin (0, 0, 0) for all time steps.

Usage

shift_reference_frame(sim_data, center_id, keep_center = TRUE)

Arguments

sim_data	A tidy 'tibble' containing the output from 'simulate_system()'.
center_id	The character string ID of the body to use as the new origin, or ‘"barycenter"' to use the system’s center of mass (the mass-weighted mean position and velocity of all bodies at each time step).
keep_center	Logical. Should the central body remain in the dataset (it will have 0 for all coordinates) or be removed? Default is 'TRUE'. Ignored when 'center_id = "barycenter"'.

Details

The shift is a Galilean transformation: at every time step the chosen point's position and velocity are subtracted from every body. No physics changes; the same forces and accelerations produced the data, and you are only choosing where to stand when you look at it.

The barycentric frame is the natural one for binary stars and any other system where no single body dominates. In it the total momentum is zero and the center of mass sits at the origin for the whole run, which removes the slow drift you get when a system is built with one body at rest but nonzero total momentum (for example, a planet given an orbital velocity around a star that was not given the balancing recoil).

If a body in the system is itself named '"barycenter"', that body is used as the center rather than the center of mass.

Value

A tidy 'tibble' with updated 'x', 'y', 'z', 'vx', 'vy', and 'vz' columns.

Examples

# Simulate Sun-Earth-Moon
orbit_data <- create_system() |>
  add_sun() |>
  add_body("Earth", mass = mass_earth, x = distance_earth_sun, vy = speed_earth) |>
  add_body("Moon", mass = mass_moon, x = distance_earth_sun + distance_earth_moon,
           vy = speed_earth + speed_moon) |>
  simulate_system(time_step = seconds_per_hour, duration = seconds_per_year)

# Shift view to Earth and plot
orbit_data |>
  shift_reference_frame(center_id = "Earth") |>
  plot_orbits()

# The Sun started at rest with Jupiter in orbit: the pair's center of mass
# drifts, because the total momentum is not zero. The barycentric frame
# removes the drift and shows the Sun's own small orbit.
sun_jupiter <- create_system() |>
  add_sun() |>
  add_planet("Jupiter", parent = "Sun") |>
  simulate_system(time_step = seconds_per_day, duration = seconds_per_year * 12)

sun_jupiter |>
  shift_reference_frame("barycenter") |>
  plot_orbits(three_d = FALSE)

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