Cartesian To Keplerian Elements — Robotics/Spacecraft Dynamics

Cartesian To Keplerian Elements

Robotics / Spacecraft Dynamics

A position r and velocity v in a planet-centred equatorial frame, turned into the orbit they lie on. With h = r × v, the node vector n = k̂ × h and the eccentricity vector e = ((|v|² − μ/|r|)·r − (r·v)·v)/μ:

• a = −μ/(2·ε), ε = |v|²/2 − μ/|r|
• ecc = |e|, incl = acos(h_z/|h|), RAAN = acos(n_x/|n|)
• argp = the angle from n to e, nu = the angle from e to r, arglat = the angle from n to r, truelon = the angle from the x-axis to r, lonper = the angle from the x-axis to e

Every angle is folded into [0, 2π) by testing a sign (n_y, e_z, r·v, r_z, r_y, e_y) – the textbook algorithm, transcribed from measurements of the Simulink block rather than from a book, because where the two differ the block is what a model is compared against.

Ports

• Position – r, a [3,1] column in the chosen length unit.
• Velocity – v, a [3,1] column in the chosen speed unit.
• a – the semi-major axis, [1,1], in the length unit. Negative on a hyperbola; on a parabola, the periapsis radius p/2.
• ecc – the eccentricity, [1,1]. Reported as exactly 0 on a circular orbit and exactly 1 on a parabolic one (see Tolerance).
• incl – the inclination, [1,1]. Reported as exactly 0 or π (180) on an equatorial orbit.
• RAAN – the right ascension of the ascending node, [1,1].
• argp – the argument of periapsis, [1,1]; elliptical inclined orbits only.
• nu – the true anomaly, [1,1]; every non-circular orbit.
• truelon – the true longitude, [1,1]; circular equatorial orbits only.
• arglat – the argument of latitude, [1,1]; circular inclined orbits only.
• lonper – the longitude of periapsis, [1,1]; non-circular equatorial orbits only.

An element that does not exist for the orbit's class is NaN – exactly what the Simulink block reports, in either of its port configurations; it substitutes nothing.

Parameters

• Units – the length and speed units of r, v and a:
  • 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
  The inputs are converted to SI first, the arithmetic runs in SI, and a is converted back.
• Angle Units – Degrees or Radians, for all seven angle outputs.
• 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.
• Tolerance – the band that decides the orbit's class, default 1e-12: circular when ecc < Tolerance, equatorial when incl or π − incl is below it (radians), parabolic when |ecc − 1| is below it. It ALSO decides RAAN: RAAN is reported only when |n| > Tolerance, and |n| is in SI units (m²/s) – an absolute test, not the inclination test, measured.
• Open Or Undefined Orbit Action – None, Warning or Error, for a parabolic or hyperbolic orbit and for r and v with |r × v| ≤ 1e-6 m²/s (all nine outputs NaN). 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: nine arccosines, five square roots and a division by μ 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 rig or model an HDL export in kilometres or nautical miles. HDL and PLC Structured Text have no NaN: where the other targets write NaN they write 0.0, and the action config does not travel into any export.

Simulink bridge

Import and export, mapped to Aerospace Blockset's aerolibsatdyn/Cartesian State Vectors to Keplerian Orbital Elements (its library path carries an embedded newline before Keplerian). Units → units, Angle Units → angleUnits, Central Body → centralBody, Gravitational Parameter → customMu, Tolerance → tolerance and Open Or Undefined Orbit Action → action; every combo is Simulink's own list, so the mapping is lossless. outputPortConfiguration is always written as All – the nine ports this block has. 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 5000 state vectors over all five units, both angle units, all eleven bodies and five tolerances.
• A parabola reports a = p/2 and ecc = 1, and its argp and nu then divide by 1 rather than by |e|. When a Tolerance is so wide that an orbit is both circular and parabolic, ecc reads 1.
• A retrograde equatorial orbit reports truelon = 2π − acos(r_x/|r|) and lonper = 2π − acos(e_x/|e|) whatever the sign of r_y or e_y – ONE fold, where the textbook applies two. Measured on 128 samples.
• Wide tolerances are how the special classes are reached on purpose: the verification rigs set Tolerance to 0.25 or 0.3 to put a whole run on the circular, equatorial or parabolic branch.