Skip to content

Documentation / @interstellar-tools/equations / centralAngle

Function: centralAngle() ​

ts
function centralAngle(
  lat1: Radians,
  lon1: Radians,
  lat2: Radians,
  lon2: Radians
): Radians;

Defined in: cartography/central-angle.ts:51

Compute the central angle between two points on a sphere from their latitudes and longitudes, with the haversine formula.

h=sin2⁡Δφ2+cos⁡φ1cos⁡φ2sin2⁡Δλ2,Δσ=2arcsin⁡h

Where:

  • φ1, φ2 are the latitudes and Δφ, Δλ the differences in latitude and longitude (rad)
  • Δσ is the angle between the two points, seen from the centre (rad)

Units

  • Inputs: latitudes and longitudes in radians.
  • Output: Δσ in radians, in [0, π].

Notes

  • The haversine form stays accurate for points close together, where the spherical law of cosines loses precision. h is clamped to 1 so rounding can't break antipodal points.
  • On an oblate body, use geocentric latitudes for the angle between the position vectors, or accept an error of up to about 0.5% on Earth with geodetic ones. For exact distances on an ellipsoid, Vincenty's or Karney's methods are needed.
  • Multiply by a radius for the distance: greatCircleDistance. From position vectors, use centralAngleFromVectors.

Parameters ​

ParameterTypeDescription
lat1RadiansLatitude of the first point in radians (finite, in [-π/2, π/2]).
lon1RadiansLongitude of the first point in radians (finite).
lat2RadiansLatitude of the second point in radians (finite, in [-π/2, π/2]).
lon2RadiansLongitude of the second point in radians (finite).

Returns ​

Radians

The central angle Δσ in radians.

Throws ​

  • If any input is not a finite number.
  • If a latitude is outside [-π/2, π/2].

Example ​

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

// A quarter of the equator
centralAngle(
  0 as Radians,
  0 as Radians,
  0 as Radians,
  (Math.PI / 2) as Radians
); // π/2

See ​