Skip to content

Documentation / @interstellar-tools/equations / sphericalPolygonArea

Function: sphericalPolygonArea() ​

ts
function sphericalPolygonArea(
  vertices: readonly {
    lat: Radians;
    lon: Radians;
  }[],
  R: number
): number;

Defined in: cartography/spherical-polygon-area.ts:97

Compute the area of a polygon on a sphere, such as an instrument footprint or a region on a planet, from its corner points.

A=R2E,E=∑i=1nαi−(n−2)π

The spherical excess E is summed over the triangles from the first vertex, (v1,vi,vi+1), each from the unit vectors a, b, c to its corners with Van Oosterom and Strackee's formula:

tan⁡E2=a⋅(b×c)1+a⋅b+b⋅c+c⋅a

Where:

  • αi are the polygon's interior angles
  • a, b, c are unit vectors from the sphere's centre to a triangle's corners
  • R is the sphere's radius (m)

Units

  • Inputs: latitudes and longitudes in radians, R in m.
  • Output: A in m².

Notes

  • Edges are great-circle arcs, the shortest path between neighbouring vertices, not lines of constant latitude: the top edge of a "latitude–longitude box" bulges towards the pole. Add vertices along an edge to follow a parallel more closely.
  • Winding doesn't matter: clockwise and anticlockwise give the same area. A polygon splits the sphere in two, and this is the area of the smaller part, at most half the sphere. Closing the ring by repeating the first vertex is allowed.
  • Exact for any simple polygon that fits within a hemisphere, including one that crosses the antimeridian or has a pole inside it or as a vertex: the vertices are joined in 3D, so longitudes need no unwrapping. The formula's sign follows each triangle's winding, so concave polygons work too. A self-intersecting polygon gives the difference of its loops.
  • The formula stays accurate for tiny triangles and for long, thin ones, where adding up the interior angles, or l'Huilier's theorem from the side lengths, loses the excess to rounding. The triple product is taken from the differences b−a and c−a to keep its digits.
In practiceThe Bermuda Triangle

1.15 million km²

Between Miami, Bermuda and San Juan, on a 6 371 km Earth

The triangle has no official edges: this is the area between the three cities, with great-circle sides.

ts
sphericalPolygonArea(
  [
    { lat: toRad(25.7617), lon: toRad(-80.1918) }, // Miami
    { lat: toRad(32.3078), lon: toRad(-64.7505) }, // Bermuda
    { lat: toRad(18.4655), lon: toRad(-66.1057) } // San Juan
  ],
  6_371_000
);
// ≈ 1.147e12 m²

Parameters ​

ParameterTypeDescription
verticesreadonly { lat: Radians; lon: Radians; }[]The polygon's corners in order, each { lat, lon } in radians (at least 3; finite, latitudes in [-π/2, π/2]).
RnumberRadius R of the sphere in m (finite, > 0).

Returns ​

number

The area A in m².

Throws ​

  • If any input is not a finite number.
  • If there are fewer than 3 vertices, a latitude is outside [-π/2, π/2], or R <= 0.

Example ​

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

const toRad = (deg: number) => ((deg * Math.PI) / 180) as Radians;

// An octant, one eighth of the sphere: πR²/2
sphericalPolygonArea(
  [
    { lat: toRad(0), lon: toRad(0) },
    { lat: toRad(0), lon: toRad(90) },
    { lat: toRad(90), lon: toRad(0) }
  ],
  1
);
// ≈ 1.5708

See ​