Skip to content

Documentation / @interstellar-tools/equations / heightAboveEllipsoid

Function: heightAboveEllipsoid() ​

ts
function heightAboveEllipsoid(
  x: number,
  y: number,
  z: number,
  a: number,
  eSquared: number
): number;

Defined in: cartography/height-above-ellipsoid.ts:67

Compute a point's height above a body's reference ellipsoid: the exact height along the ellipsoid's normal, the height maps and GPS receivers give.

h=pcos⁡φ+zsin⁡φ−a1−e2sin2⁡φ

with the geodetic latitude φ from bodyFixedToGeodetic.

Where:

  • p=x2+y2 is the distance from the rotation axis (m)
  • a is the equatorial radius (m)
  • e2 is the first eccentricity squared

Units

  • Inputs: x, y, z and a in m, eSquared dimensionless.
  • Output: h in m, negative below the ellipsoid.

Notes

  • Exact, not the approximation ‖r‖−R(φ): the height is measured along the normal to the ellipsoid, which misses the centre except at the equator and the poles.
  • Where heightAboveSphere uses one radius, this follows the body's flattening. On Earth the two differ by up to 21.4 km at the poles if the sphere has the equatorial radius. With e2=0 they agree.
  • Heights on the ellipsoid are geometric. Elevations on maps are usually measured from an equipotential surface instead: the geoid on Earth, within about 100 m of the ellipsoid, or the areoid on Mars.
  • The position must be in the body-fixed frame, with z along the rotation axis.
In practiceApollo 11, in Earth orbit

191.1 km up

At orbit insertion: 6 563.0 km from Earth's centre, at 32.502° N geocentric

Above the WGS84 ellipsoid, which at that latitude is 6.2 km below a sphere of the equatorial radius: heightAboveSphere gives 184.9 km.

ts
const lat = toRad(32.502);
const r = 6_563_041;
heightAboveEllipsoid(
  r * Math.cos(lat),
  0,
  r * Math.sin(lat),
  6_378_137,
  0.00669437999014
);
// ≈ 191 100 m

Parameters ​

ParameterTypeDescription
xnumberBody-fixed x in m (finite), through the prime meridian.
ynumberBody-fixed y in m (finite), through 90° east.
znumberBody-fixed z in m (finite), along the rotation axis.
anumberEquatorial radius a in m (finite, > 0).
eSquarednumberFirst eccentricity squared e2 (finite, in [0, 1)).

Returns ​

number

The height h in m.

Throws ​

  • If any input is not a finite number.
  • If a <= 0, eSquared is outside [0, 1), or the point is at the centre.

Example ​

ts
// On the WGS84 ellipsoid at the North Pole: the polar radius, 21.4 km short of the equatorial one
heightAboveEllipsoid(0, 0, 6_356_752.314, 6_378_137, 0.00669437999014); // ≈ 0 m

See ​