Skip to content

Documentation / @interstellar-tools/equations / elementsToState

Function: elementsToState() ​

ts
function elementsToState(
  elements: ClassicalElementsInterface,
  mu: number
): StateVectorInterface;

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

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

In the perifocal frame, with p=a(1−e2):

rPQW=p1+ecos⁡ν(cos⁡νsin⁡ν0),vPQW=μp(−sin⁡νe+cos⁡ν0)

then rotated into the inertial frame:

r=R3(Ω)R1(i)R3(ω)rPQW,v=R3(Ω)R1(i)R3(ω)vPQW

Units

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

Notes

  • The inverse of stateToElements, including its conventions for circular and equatorial orbits.
  • Elliptic orbits need a>0 and hyperbolic ones a<0. A parabolic orbit (e=1) has no finite a, so it isn't supported.
  • On a hyperbola, only true anomalies with 1+ecos⁡ν>0 exist: the body never reaches the asymptotes.

Parameters ​

ParameterTypeDescription
elementsClassicalElementsInterfaceThe classical orbital elements.
munumberGravitational parameter μ in m³/s² (finite, > 0).

Returns ​

StateVectorInterface

The position r in m and velocity v in m/s.

Throws ​

  • If any input is not a finite number.
  • If mu <= 0, e < 0, e = 1, i is outside [0, π], a has the wrong sign for e, or nu is beyond a hyperbola's asymptotes.

Example ​

ts
import type { Radians } from '@interstellar-tools/types';

// A circular, equatorial orbit at 7000 km, a quarter of the way round
const { r, v } = elementsToState(
  {
    a: 7_000_000,
    e: 0,
    i: 0 as Radians,
    raan: 0 as Radians,
    argp: 0 as Radians,
    nu: (Math.PI / 2) as Radians
  },
  3.986004418e14
);
// r ≈ [0, 7 000 000, 0] m, v ≈ [-7546, 0, 0] m/s

See ​