Skip to content

Documentation / @interstellar-tools/maps / mercator

Function: mercator() ​

ts
function mercator(
  phi: Radians,
  lambda: Radians,
  R: number,
  options?: ProjectionOptionsInterface
): ProjectedPointInterface;

Defined in: projections/mercator.ts:66

Project a point on a sphere with the Mercator projection: the conformal cylindrical map, which keeps angles and shapes locally true.

x=R(λ−λ0),y=Rln⁡tan(π4+φ2)

Where:

  • φ and λ are the point's latitude and longitude (rad)
  • λ0 is the central meridian (rad)
  • R is the sphere's radius (m)

Units

  • Inputs: angles in radians, R in m.
  • Output: { x, y } in m, with x in [−πR, πR].

Notes

  • The scale is sec⁡φ in every direction: true on the equator, twice as large at 60°, and without bound towards the poles. That's why Greenland looks as large as Africa. Angles stay true, so a line of constant compass bearing (a rhumb line) is straight.
  • y grows without bound towards the poles, so the poles themselves throw a RangeError. Maps clip the latitude: web maps (see inverseMercator) stop at arctan⁡sinh⁡π≈85.0511°, where the map is as tall as it is wide.
  • λ−λ0 is wrapped to (−π, π], so the map is centred on the central meridian. −π itself stays on the left edge, so a line that ends there, like a ground track split at the antimeridian, isn't drawn across the map.
  • A sphere only: on an oblate body this is the spherical Mercator web maps use, not the ellipsoidal one.

Parameters ​

ParameterTypeDescription
phiRadiansLatitude φ in radians (finite, in (−π/2, π/2)).
lambdaRadiansLongitude λ in radians (finite).
RnumberRadius R of the sphere in m (finite, > 0).
options?ProjectionOptionsInterfacelambda0, the central meridian (radians, defaults to 0).

Returns ​

ProjectedPointInterface

The point on the map, { x, y } in m.

Throws ​

  • If any input is not a finite number.
  • If phi is not in (−π/2, π/2), or R <= 0.

Example ​

ts
// The edge of a web map: 180° E, 85.0511° N on a 6 378 137 m sphere
mercator(toRad(85.05112878), toRad(180), 6_378_137);
// ≈ { x: 20 037 508, y: 20 037 508 } m

See ​