Keplerian Elements To Cartesian — Robotics/Spacecraft Dynamics

Keplerian Elements To Cartesian

Robotics / Spacecraft Dynamics

The six classical orbital elements turned into a position and velocity in a planet-centred equatorial frame:

• p = a·(1 − e²) on an ellipse, 2·a on a parabola, a·(e² − 1) on a hyperbola
• r_pqw = p/(1 + e·cos ν)·[cos ν; sin ν; 0], v_pqw = √(μ/p)·[−sin ν; e + cos ν; 0]
• r = R₃(RAAN)·R₁(incl)·R₃(argp)·r_pqw, and the same rotation for v

Ports

• a – the semi-major axis, [1,1], in the length unit. On a hyperbola (ecc > 1) the distance from periapsis to the hyperbola's centre; on a parabola the periapsis radius.
• ecc – the eccentricity, [1,1]. Within 1e-10 of 1 it is parabolic.
• incl – the inclination, [1,1], in the angle unit.
• RAAN – the right ascension of the ascending node, [1,1].
• argp – the argument of periapsis, [1,1].
• nu – the true anomaly, [1,1].
• Position – r, a [3,1] column in the length unit.
• Velocity – v, a [3,1] column in the speed unit.

RAAN, argp and nu are wrapped into [0, 2π) first (x − 2π·floor(x/2π)); incl is used as given. A negative a or a negative ecc makes both outputs NaN, as in Simulink.

Parameters

• Units – the length and speed units of a, r and v:
  • Metric (m/s) – metres, metres per second
  • Metric (km/s) – kilometres, kilometres per second
  • Metric (km/h) – kilometres, kilometres per hour
  • English (ft/s) – feet, feet per second
  • English (kts) – nautical miles, knots
  a is converted to SI first, the arithmetic runs in SI, and r and v are converted back.
• Angle Units – Degrees or Radians, for the four angle inputs.
• Central Body – Earth, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Sun or Custom. Each named body carries its gravitational parameter μ, the same double the Simulink block uses (Earth 3.986004418e14 m³/s²).
• Gravitational Parameter – μ, used only when Central Body is Custom, in the Units' own length cubed per second squared: m³/s² for Metric (m/s), km³/s² for both Metric (km/s) and Metric (km/h), and ft³/s² for both English units – so under English (kts) it is in feet while positions are in nautical miles. Measured; the Simulink dialog relabels its prompt the same way. Default 42828314258067, the Simulink dialog's own.
• Open Or Undefined Orbit Action – None, Warning or Error, for a negative a or ecc, a parabolic or hyperbolic orbit, and an angle outside Simulink's documented range (incl in [0, π], the other three in [0, 2π]). Warning reports each kind once per run; Error stops the run.
• Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.

Code export

All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. Every parameter is baked into the arithmetic at export.

The three HDL targets are simulation-only: trigonometry, a square root and a division by p do not belong in a Q16.16 datapath, so they compute in real and quantize only at the ports – which also bounds what can cross a port, ±32768, so model an HDL export in kilometres or nautical miles. HDL and PLC Structured Text have no NaN: an invalid element set writes 0.0 there, and the action config does not travel into any export. MATLAB multiplies the three rotation matrices exactly as the Simulink block does; the other nine write the product out entry by entry, which agrees to a few units in the last place.

Simulink bridge

Import and export, mapped to Aerospace Blockset's aerolibsatdyn/Keplerian Orbital Elements to Cartesian State Vectors (its library path carries an embedded newline before Cartesian). Units → units, Angle Units → angleUnits, Central Body → centralBody, Gravitational Parameter → customMu and Open Or Undefined Orbit Action → action; every combo is Simulink's own list, so the mapping is lossless. orbitType is always written as Keplerian: Simulink's Elliptical equatorial, Circular inclined and Circular equatorial types take 4, 4 and 2 inputs (a, ecc, nu, lonper / a, incl, RAAN, arglat / a, truelon – measured) and do not cross. The Simulink block has no SampleTime (measured), so the rate stays on the ICore side.

Notes

• Algebraic and stateless; nonlinear, so no state space.
• Measured, and bit-exact against R2026a on about 2300 element sets over all five units, both angle units, all eleven bodies, circular, equatorial, retrograde, parabolic, hyperbolic, negative and multi-lap inputs.
• A circular or equatorial orbit needs no other orbit type here: at ecc = 0 the result depends on argp + nu only, and at incl = 0 on RAAN + argp only, so feed the combined angle in either and 0 in the other.
• The parabolic band is 1e-10, found by bisection against the block: an ecc of 1 − 9.99e-11 is parabolic (p = 2a) and 1 − 1.0000000827e-10 is not – where p = a·(1 − e²) collapses the orbit to a point.