Geodesy
Where things are on a planet or moon: how far apart, how high, how much ground a footprint covers. These functions are in @interstellar-tools/equations, in the Cartography group. They take angles in radians and lengths in metres.
The examples are on Mars, between the two rovers' landing sites, and every number on this page is checked by a test.
import type { Radians } from '@interstellar-tools/types';
const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;
const toDeg = (rad: number) => (rad * 180) / Math.PI;Choose a reference surface
Planets spin, so most are flattened at the poles: an oblate spheroid, with an equatorial radius
PLANETS and MOONS in @interstellar-tools/constants carry each body's reference ellipsoid, from the IAU. Get the flattening
import { PLANETS } from '@interstellar-tools/constants';
import {
eccentricitySquaredOblateSpheroid,
flatteningOblateSpheroid
} from '@interstellar-tools/equations';
const mars = PLANETS.find((planet) => planet.id === 'mars')!;
const a = mars.ellipsoid!.equatorialRadius.value * 1000; // 3 396 190 m
const c = mars.ellipsoid!.polarRadius.value * 1000; // 3 376 200 m
const R = mars.radius.value * 1000; // mean radius, 3 389 500 m
const f = flatteningOblateSpheroid(a, c); // ≈ 0.005886, 1/169.9
const eSquared = eccentricitySquaredOblateSpheroid(a, c); // ≈ 0.011737Mars's poles are 19.99 km closer to its centre than its equator.
| Body | Use | Why |
|---|---|---|
| Earth | WGS84 from @interstellar-tools/constants | GPS latitudes and heights are on WGS 84. The IAU's ellipsoid agrees to under a metre. |
| Mars | The ellipsoid in PLANETS, or the mean radius | Flattened by 1/170: a sphere is up to 13 km off in height. |
| Moon | A sphere, 1 737.4 km | The IAU's lunar ellipsoid is a sphere. |
| Other | ellipsoid in PLANETS and MOONS, where it's given | Small, irregular bodies have only a mean radius. |
Two kinds of latitude
On an ellipsoid, latitude can be measured two ways, and they differ by a fraction of a degree:
- Planetocentric latitude
: the angle up from the equator, seen from the centre. Most current Mars maps and datasets use it, with longitude east. - Planetographic latitude
: the angle of the normal to the surface, where a plumb line would hang. Earth's maps and GPS use it, as geodetic latitude, and so do geodeticToBodyFixedandbodyFixedToGeodetic.
h, is measured along the normal; the height above a sphere along the line from the centre.On Mars the two latitudes differ most at 45°, by 0.34°: about 20 km on the ground. Convert through a position vector:
import {
geodeticToBodyFixed,
planetocentricLatitude
} from '@interstellar-tools/equations';
// 45° planetographic, on the surface
const [x, y, z] = geodeticToBodyFixed(toRad(45), toRad(0), 0, a, eSquared);
toDeg(planetocentricLatitude(x, y, z)); // ≈ 44.662°planetographicLatitudeOblate(x, y, z, a, c) goes the other way, for a point on the surface. On a sphere the two latitudes are the same.
Distances on a sphere
The great-circle distance is the shortest way between two points along the surface. centralAngle gives the angle between them at the centre, with the haversine formula, and greatCircleDistance multiplies it by the radius.
Curiosity landed in Gale crater, at 4.5895° S, 137.4417° E. Perseverance landed in Jezero crater, at 18.4447° N, 77.4508° E:
import {
centralAngle,
greatCircleDistance
} from '@interstellar-tools/equations';
const curiosity = [toRad(-4.5895), toRad(137.4417)] as const;
const perseverance = [toRad(18.4447), toRad(77.4508)] as const;
toDeg(centralAngle(...curiosity, ...perseverance)); // ≈ 63.41°
greatCircleDistance(...curiosity, ...perseverance, R); // ≈ 3 751 kmOn the mean sphere this is good to about the flattening, 0.6%. If you have position vectors instead, centralAngleFromVectors(r1, r2) gives the same angle without converting to latitude and longitude.
Radii of curvature
On an ellipsoid the surface curves differently north–south and east–west, and both change with latitude. The two radii of curvature turn angles into distances on the ground:
, along the meridian: one degree of latitude is . , in the prime vertical, east–west: one degree of longitude is .
import {
meridionalRadiusOfCurvature,
primeVerticalRadiusOfCurvature
} from '@interstellar-tools/equations';
const phi = toRad(18.4447);
const M = meridionalRadiusOfCurvature(phi, a, eSquared); // ≈ 3 362 252 m
const N = primeVerticalRadiusOfCurvature(phi, a, eSquared); // ≈ 3 398 187 m
const degreeOfLatitude = (M * Math.PI) / 180; // ≈ 58.68 km
const degreeOfLongitude = (N * Math.cos(phi) * Math.PI) / 180; // ≈ 56.26 kmUse them to size a grid cell in metres, or to turn a small offset in metres into degrees.
Coordinates and heights
geodeticToBodyFixed turns a planetographic latitude, longitude and height into a body-fixed position vector: bodyFixedToGeodetic goes back, with Bowring's method.
import {
bodyFixedToGeodetic,
geodeticToBodyFixed
} from '@interstellar-tools/equations';
const r = geodeticToBodyFixed(toRad(18.4447), toRad(77.4508), 0, a, eSquared);
const { phi, lambda, h } = bodyFixedToGeodetic(...r, a, eSquared);
// phi ≈ 18.4447°, lambda ≈ 77.4508°, h ≈ 0 mFor an altitude readout from a position vector, there are two heights:
heightAboveSphere(r, R): the distance from the centre less the radius.heightAboveEllipsoid(x, y, z, a, eSquared): the exact height along the normal, the one maps give.
An orbiter 300 km above Mars's north pole:
import {
heightAboveEllipsoid,
heightAboveSphere
} from '@interstellar-tools/equations';
const above = c + 300_000;
heightAboveEllipsoid(0, 0, above, a, eSquared); // 300 000 m
heightAboveSphere([0, 0, above], R); // 286 700 mThe mean sphere is 13.3 km above the ellipsoid at the poles, so its height reads low there, and high at the equator.
Heights on maps
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 geoid, Earth's equipotential surface, from satellite gravity data. Its height above the ellipsoid is exaggerated thousands of times here; in reality it stays within about 100 m.
Horizons and footprints
How far can that orbiter see? horizonDistance(h, R) is the straight line of sight to the horizon, and horizonSurfaceDistance(h, R) the distance along the ground to it.

The horizon from the International Space Station, about 420 km up, over the Pacific off Chile.
import {
horizonDistance,
horizonSurfaceDistance
} from '@interstellar-tools/equations';
horizonDistance(300_000, R); // ≈ 1 457 km
horizonSurfaceDistance(300_000, R); // ≈ 1 376 kmThe area of a footprint, a map quadrangle or a region comes from its corner points with sphericalPolygonArea. Its edges are great-circle arcs, and the winding doesn't matter. A box of one degree by one degree north-east of Jezero:
import { sphericalPolygonArea } from '@interstellar-tools/equations';
const box = [
[18, 77],
[18, 78],
[19, 78],
[19, 77]
].map(([lat, lon]) => ({ lat: toRad(lat), lon: toRad(lon) }));
sphericalPolygonArea(box, R); // ≈ 3 318.83 km²A box this small is nearly flat:
Next
- Maps: project these coordinates onto a flat map, cut it into tiles, and read the terrain from an elevation grid.
- The Cartography reference has every function, with its formula and limits.