Skip to content

Documentation / @interstellar-tools/equations / stateToElements

Function: stateToElements() ​

ts
function stateToElements(
  r: Vector3DTupleType,
  v: Vector3DTupleType,
  mu: number,
  tolerance?: number
): ClassicalElementsInterface;

Defined in: orbits/state-to-elements.ts:88

Convert a state vector (position and velocity) to the six classical orbital elements.

h=r×v,e=v×hμ−rr,n=k^×h,a=−μ2ε,ε=v22−μri=arccos⁡hzh,Ω=atan2(ny,nx),ω=∠(n,e),ν=∠(e,r)

where each angle ∠ is measured in the direction of motion, about h.

Units

  • Inputs: r in m, v in m/s, mu in m³/s².
  • Output: a in m, e dimensionless, angles in radians.

Notes

  • Works for elliptic and hyperbolic orbits. A hyperbolic orbit has a negative a, and nu in [0, 2π) like the others: the incoming branch is just below 2π.
  • Some angles are undefined for special orbits. Below tolerance, the function uses these conventions, which elementsToState reverses:
    • circular (e≈0): argp = 0, and nu is measured from the ascending node (the argument of latitude);
    • equatorial (i≈0 or π): raan = 0, and argp is measured from the x axis (the longitude of periapsis);
    • circular and equatorial: raan = argp = 0, and nu is measured from the x axis (the true longitude).
  • The frame is whatever inertial frame r and v are given in, centred on the body with parameter mu; the reference plane is its xy plane.
In practiceApollo 11, leaving for the Moon

e = 0.977

From the flown state at trans-lunar injection: 6 712.6 km from Earth's centre, 10 834.3 m/s, 7.367° above the horizontal

The AS-506 flight evaluation report gives 0.97696; the inputs here are rounded. An orbit that stretched reaches far beyond the Moon, but the Moon's gravity takes over long before.

ts
const r = 6_712_602; // m
const v = 10_834.3; // m/s
const gamma = toRad(7.367);
stateToElements(
  [r, 0, 0],
  [v * Math.sin(gamma), v * Math.cos(gamma), 0],
  3.986004418e14
).e; // ≈ 0.97715

Parameters ​

ParameterTypeDefault valueDescription
rVector3DTupleTypeundefinedPosition vector in m (finite components, not zero).
vVector3DTupleTypeundefinedVelocity vector in m/s (finite components).
munumberundefinedGravitational parameter μ in m³/s² (finite, > 0).
tolerance?number1e-10Below this, e counts as circular and sin⁡i as equatorial. Defaults to 1e-10.

Returns ​

ClassicalElementsInterface

The classical orbital elements.

Throws ​

  • If any input is not a finite number.
  • If mu <= 0, tolerance < 0, r is zero, or the motion is straight up or down (no angular momentum).

Example ​

ts
// Curtis, Orbital Mechanics for Engineering Students, in km and km/s
const { a, e, i, raan, argp, nu } = stateToElements(
  [-6045e3, -3490e3, 2500e3],
  [-3.457e3, 6.618e3, 2.533e3],
  398_600e9
);
// e ≈ 0.1712, i ≈ 153.2°, raan ≈ 255.3°, argp ≈ 20.07°, nu ≈ 28.45°

See ​