The Six Elements
An orbit in three-dimensional space has six degrees of freedom — the same number as a Cartesian state vector (x, y, z, vx, vy, vz). The Keplerian elements split those six numbers into three intuitive groups: shape, orientation, and position.
Shape: Semi-Major Axis and Eccentricity
The first two elements define the geometry of the ellipse — how big it is and how stretched.
Semi-major axis (\(a\)) is the average distance from the
orbiting body to its parent. Technically it’s half the longest diameter
of the ellipse. Larger \(a\) means a
bigger orbit and a longer period. In orbitr, it’s specified
in meters.
Eccentricity (\(e\)) controls the shape. A circle has \(e = 0\); as \(e\) increases toward 1, the ellipse becomes more elongated. At any point along the orbit, the actual distance from the parent is:
\[r = \frac{a(1 - e^2)}{1 + e \cos\nu}\]
where \(\nu\) is the true anomaly (the body’s current angular position — more on that below). At the closest approach (periapsis, \(\nu = 0\)), the distance is \(r_{\text{peri}} = a(1-e)\). At the farthest point (apoapsis, \(\nu = 180°\)), it’s \(r_{\text{apo}} = a(1+e)\).
Let’s see how eccentricity changes the orbit shape:
make_ecc_orbit <- function(e, label) {
create_system() |>
add_sun() |>
add_body_keplerian(
"Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = e, nu = 0
) |>
simulate_system(time_step = seconds_per_day, duration = seconds_per_year * 2) |>
filter(id == "Planet") |>
mutate(case = label)
}
bind_rows(
make_ecc_orbit(0.0, "e = 0.0 (circle)"),
make_ecc_orbit(0.2, "e = 0.2 (Mercury-like)"),
make_ecc_orbit(0.5, "e = 0.5 (comet-like)"),
make_ecc_orbit(0.85, "e = 0.85 (Halley-like)")
) |>
ggplot(aes(x = x, y = y, color = case)) +
geom_path(linewidth = 0.8) +
geom_point(x = 0, y = 0, color = "gold", size = 4, inherit.aes = FALSE) +
coord_equal() +
theme_minimal() +
labs(title = "Same semi-major axis, different eccentricities",
color = NULL)
All four orbits have the same semi-major axis, so they have the same orbital period (Kepler’s Third Law: \(T^2 \propto a^3\)). But their shapes are radically different — from a perfect circle to a narrow ellipse that barely misses the Sun at periapsis and swings far out at apoapsis.
Orientation: Inclination, Longitude of Ascending Node, and Argument of Periapsis
The next three elements rotate and tilt the ellipse in 3D space. They’re specified in degrees.
Inclination (\(i\)) is the tilt of the orbital plane relative to a reference plane (typically the ecliptic — the plane of Earth’s orbit). An inclination of \(0°\) means the orbit lies flat in the reference plane. \(90°\) means the orbit is perpendicular to it.
make_inc_orbit <- function(inc, label) {
create_system() |>
add_sun() |>
add_body_keplerian(
"Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = 0.1, i = inc, nu = 0
) |>
simulate_system(time_step = seconds_per_day, duration = seconds_per_year) |>
filter(id == "Planet") |>
mutate(case = label)
}
bind_rows(
make_inc_orbit(0, "i = 0 (flat)"),
make_inc_orbit(30, "i = 30"),
make_inc_orbit(60, "i = 60"),
make_inc_orbit(90, "i = 90 (polar)")
) |>
ggplot(aes(x = x, y = z, color = case)) +
geom_path(linewidth = 0.8) +
coord_equal() +
theme_minimal() +
labs(title = "Same orbit, different inclinations (viewed from the side: X vs Z)",
x = "X (m)", y = "Z (m)", color = NULL)
The flat orbit (\(i = 0\)) stays in the XY plane with \(z = 0\). As inclination increases, the orbit tilts further out of the plane until \(i = 90°\) makes a full polar orbit.
Longitude of ascending node (\(\Omega\), called lan in
orbitr) is the compass direction of the tilt. It measures
the angle from a reference direction (the vernal equinox in real
astronomy) to the point where the orbit crosses the reference plane
going “upward.” Think of inclination as how much the orbit
tilts, and \(\Omega\) as which
direction it tilts toward.
When \(i = 0\), the ascending node is undefined and \(\Omega\) has no effect.
make_lan_orbit <- function(lan_val, label) {
create_system() |>
add_sun() |>
add_body_keplerian(
"Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = 0.1, i = 45, lan = lan_val, nu = 0
) |>
simulate_system(time_step = seconds_per_day, duration = seconds_per_year) |>
filter(id == "Planet") |>
mutate(case = label)
}
bind_rows(
make_lan_orbit(0, "LAN = 0"),
make_lan_orbit(90, "LAN = 90"),
make_lan_orbit(180, "LAN = 180")
) |>
ggplot(aes(x = x, y = y, color = case)) +
geom_path(linewidth = 0.8) +
geom_point(x = 0, y = 0, color = "gold", size = 4, inherit.aes = FALSE) +
coord_equal() +
theme_minimal() +
labs(title = "Same orbit tilted in different directions (top-down view)",
color = NULL)
All three orbits have the same shape and inclination — \(\Omega\) just rotates the whole tilted plane around the vertical axis.
Argument of periapsis (\(\omega\), called arg_pe in
orbitr) is the angle within the orbital plane from
the ascending node to the closest-approach point (periapsis). It
controls where along the orbit the body gets closest to its parent.
make_argpe_orbit <- function(argpe_val, label) {
create_system() |>
add_sun() |>
add_body_keplerian(
"Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = 0.5, arg_pe = argpe_val, nu = 0
) |>
simulate_system(time_step = seconds_per_day, duration = seconds_per_year * 2) |>
filter(id == "Planet") |>
mutate(case = label)
}
bind_rows(
make_argpe_orbit(0, "arg_pe = 0"),
make_argpe_orbit(90, "arg_pe = 90"),
make_argpe_orbit(180, "arg_pe = 180")
) |>
ggplot(aes(x = x, y = y, color = case)) +
geom_path(linewidth = 0.8) +
geom_point(x = 0, y = 0, color = "gold", size = 4, inherit.aes = FALSE) +
coord_equal() +
theme_minimal() +
labs(title = "Same ellipse, rotated within the orbital plane",
color = NULL)
The ellipse is the same shape every time — \(\omega\) just spins it around the parent, moving the periapsis to different points along the orbit.
Position: True Anomaly
The final element pins down where the body currently is along its orbit.
True anomaly (\(\nu\), called nu in
orbitr) is the angle measured from periapsis to the body’s
current position, in the direction of orbital motion. \(\nu = 0°\) means the body starts at
periapsis (closest point); \(\nu =
180°\) puts it at apoapsis (farthest point).
sys_0 <- create_system() |>
add_sun() |>
add_body_keplerian("Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = 0.3, nu = 0)
sys_90 <- create_system() |>
add_sun() |>
add_body_keplerian("Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = 0.3, nu = 90)
sys_180 <- create_system() |>
add_sun() |>
add_body_keplerian("Planet", mass = 1e24, parent = "Sun",
a = distance_earth_sun, e = 0.3, nu = 180)
# Plot starting positions
starts <- bind_rows(
sys_0$bodies |> filter(id == "Planet") |> mutate(case = "nu = 0 (periapsis)"),
sys_90$bodies |> filter(id == "Planet") |> mutate(case = "nu = 90"),
sys_180$bodies |> filter(id == "Planet") |> mutate(case = "nu = 180 (apoapsis)")
)
# Full orbit for reference
orbit <- simulate_system(sys_0, time_step = seconds_per_day,
duration = seconds_per_year * 2) |>
filter(id == "Planet")
ggplot() +
geom_path(data = orbit, aes(x = x, y = y), color = "grey70", linewidth = 0.5) +
geom_point(data = starts, aes(x = x, y = y, color = case), size = 4) +
geom_point(x = 0, y = 0, color = "gold", size = 4) +
coord_equal() +
theme_minimal() +
labs(title = "Starting position at different true anomaly values",
color = NULL)
By default, add_body_keplerian() and
add_planet() use \(\nu =
0\) (starting at periapsis). In load_solar_system(),
all planets start at periapsis — if you want to spread them out around
their orbits for a more realistic snapshot, pass different
nu values to add_planet():
# Spread the inner planets around their orbits
create_system() |>
add_sun() |>
add_planet("Mercury", parent = "Sun", nu = 30) |>
add_planet("Venus", parent = "Sun", nu = 120) |>
add_planet("Earth", parent = "Sun", nu = 210) |>
add_planet("Mars", parent = "Sun", nu = 300) |>
simulate_system(time_step = seconds_per_day, duration = seconds_per_year) |>
plot_orbits(three_d = FALSE)
