Movable Type Home Page

Movable Type Scripts


Geodesy Library

This JavaScript library covers a range of geodesic calculations, coordinate system conversions, and mapping functions. It started out as a collection of ‘latitude/longitude’ code fragments covering distances and bearings, and has grown steadily since.

Many of these functions involve complex inter­depen­dencies; ES modules are used to organise these inter­depen­dencies in a clear robust way within JavaScript, so this library runs in relatively recent browsers/Node.js.

This page summarises all methods available in the library, with links to the more detailed complete documentation. Full source code is available on GitHub (github.com/chrisveness/geodesy), and tests in the browser and Travis CI.

Further information is available on the Movable Type scripts pages for spherical, ellipsoidal/Vincenty, and vector-based geodesy scripts, and UK OS grid references & UTM/MGRS mapping functions.

module functions trig. vector spherical ellipsoidal
dms.js formatting / parsing of degrees, minutes, seconds
latlon-ellipsoidal.js core ellipsoidal methods & ellipsoid / cartesian conversion
latlon-ellipsoidal-datum.js ellipsoid parameters / datum conversions for historical/OSGB datums
latlon-ellipsoidal-referenceframe.js ellipsoid parameters / datum conversions for modern TRFs
latlon-ellipsoidal-vincenty.js geodesics on the ellipsoid
latlon-nvector-ellipsoidal.js delta vectors between points and various conversions
latlon-nvector-spherical.js distances, bearings, and other functions
latlon-spherical.js distances, bearings, and other functions
mgrs.js MGRS grid references
osgridref.js Ordnance Survey grid references
utm.js UTM / WGS-84 conversions
vector3d.js general 3-d vector operations

 

The library is available for browsers from jsDelivr – e.g.:

    <script type="module">
        import LatLon from 'https://cdn.jsdelivr.net/npm/geodesy@2.3.0/latlon-spherical.min.js';
        const d = new LatLon(52.205, 0.119).distanceTo(new LatLon(48.857, 2.351));
    </script>

Or for Node.js from npm – e.g.:

    $ npm install geodesy
    $ node
    > import LatLon from 'geodesy/latlon-spherical.js';
    > const d = new LatLon(52.205, 0.119).distanceTo(new LatLon(48.857, 2.351));

Note Node.js has native ES-Module support from v13.2.0; the library can be used in v8.0.0–v12.15.0* with the esm package

 

Module dms.js Latitude/longitude points may be represented as decimal degrees, or subdivided into sexagesimal minutes and seconds. This module provides methods for parsing and representing degrees / minutes / seconds.
import Dms from 'https://cdn.jsdelivr.net/npm/geodesy@2/dms.js'; // browser
import Dms from 'geodesy/dms.js'; // Node.js
Class Dms Functions for parsing and representing degrees / minutes / seconds.
Property Description
Dms.separator

Separator character to be used to separate degrees, minutes, seconds, and cardinal directions.

Default separator is U+202F ‘narrow no-break space’.

To change this (e.g. to empty string or full space), set Dms.separator prior to invoking formatting.

Method Description
Dms.parse(dms)

Parses string representing degrees/minutes/seconds into numeric degrees.

This is very flexible on formats, allowing signed decimal degrees, or deg-min-sec optionally suffixed by compass direction (NSEW); a variety of separators are accepted. Examples -3.62, '3 37 12W', '3°37′12″W'.

Dms.toLat(deg, format='d', dp=4|2|0) Converts numeric degrees to deg/min/sec latitude (2-digit degrees, suffixed with N/S), for use in toString() methods: format 'd' for deg, 'dm' for deg+min, 'dms' for deg+min+sec, default 4dp for 'd', 2dp for 'dm', 0dp for 'dms'; e.g. 52.65798 => 52.6580° N / 52° 39.48′ N / 52° 39′ 29″ N.
Dms.toLon(deg, format='d', dp=4|2|0) Convert numeric degrees to deg/min/sec longitude (3-digit degrees, suffixed with E/W), for use in toString() methods: format 'd' for deg, 'dm' for deg+min, 'dms' for deg+min+sec, default 4dp for 'd', 2dp for 'dm', 0dp for 'dms'; e.g. 1.71605 => 001.7161° E / 001° 42.96′ E / 001° 42′ 58″ E.
Dms.toBrng(deg, format='d', dp=4|2|0) Converts numeric degrees to deg/min/sec as a bearing (0°..360°), for use in toString() methods; e.g. -3.62 => 356° 22′ 48″.
Dms.fromLocale(str) Converts DMS string from locale thousands/decimal separators to JavaScript comma/dot separators for subsequent parsing.
Dms.toLocale(str) Converts DMS string from JavaScript comma/dot thousands/decimal separators to locale separators.
Dms.compassPoint(bearing, precision=3) Returns compass point (to given precision) for supplied bearing; e.g. 24° => NNE.
 
Module latlon-ellipsoidal.js

A latitude/longitude point defines a geographic location on or above/below the earth’s surface, measured in degrees from the equator & the International Reference Meridian and in metres above the ellipsoid, and based on a given datum

As so much modern geodesy is based on WGS-84 (as used by GPS), this module includes WGS-84 ellipsoid parameters, and it has methods for converting geodetic (latitude/longitude) points to/from geocentric cartesian points; the latlon-ellipsoidal-datum and latlon-ellipsoidal-referenceframe modules provide transformation parameters for converting between historical datums and between modern reference frames.

This module is used for both trigonometric geodesy and n‑vector geodesy, and for UTM/MGRS mapping.

import LatLon, { Cartesian, Vector3d, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-ellipsoidal.js'; // browser
import LatLon, { Cartesian, Vector3d, Dms } from 'geodesy/latlon-ellipsoidal.js'; // Node.js
Class LatLonEllipsoidal

Latitude/longitude points on an ellipsoidal model earth, with ellipsoid parameters and methods for converting points to/from cartesian (ECEF) coordinates.

This is the core class, which will usually be used via other modules.

Constructor Description
LatLon(latitude, longitude, height=0)

Creates a geodetic latitude/longitude point on a (WGS84) ellipsoidal model earth.

Property Description
this.lat this.latitude Latitude in degrees north from equator: can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
this.lon this.lng this.longitude Longitude in degrees east from international reference meridian: can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
this.height Height in metres above ellipsoid.
LatLon.ellipsoids Ellipsoids with their parameters; this module only defines WGS84 parameters a = 6378137, b = 6356752.314245, f = 1/298.257223563.
LatLon.datums Datums; this module only defines WGS84 datum, hence no datum transformations.
Method Description
LatLon.parse(latitude, longitude, height=0) LatLon.parse(latlon, height=0)

Parses a latitude/longitude point from a variety of formats.

Latitude & longitude (in degrees) can be supplied as two separate parameters, as a single comma-separated lat/lon string, or as a single object with { lat, lon } or GeoJSON properties.

The latitude/longitude values may be numeric or strings; they may be signed decimal or deg-min-sec (hexagesimal) suffixed by compass direction (NSEW); a variety of separators are accepted. Examples: LatLon.parse(51.4778, -0.0015) // ≡ new LatLon() LatLon.parse('51°28′40″N, 000°00′05″W', 17) LatLon.parse({ lat: 52.205, lon: 0.119 }, 17)

this.toCartesian() Converts this point from (geodetic) latitude/longitude coordinates to (geocentric) cartesian (x/y/z) coordinates.
this.equals(point) Checks if another point is equal to this point.
this.toString(format='d', dp=4|2|0, dpHeight=null) Returns a string representation of this point, formatted as degrees ('d'), degrees+minutes ('dm'), or degrees+minutes+seconds ('dms'), to specified decimal places (default 4dp for 'd', 2dp for 'dm', 0dp for 'dms').
Class Cartesian
(extends Vector3d)
Converts ECEF (earth-centered earth-fixed) geocentric cartesian coordinates to latitude/longitude points, applies Helmert transformations.
Constructor Description
Cartesian(x, y, z) Creates cartesian coordinate representing ECEF (earth-centred earth-fixed) point.
Method (extra to Vector3d) Description
this.toLatLon(ellipsoid=LatLon.ellipsoids.WGS84) Converts this (geocentric) cartesian (x/y/z) coordinate to (geodetic) latitude/longitude point on specified ellipsoid using Bowring’s (1985) formulation.
this.toString(dp=0) Returns a string representation of this cartesian point.
 
Module latlon-ellipsoidal-datum.js

Historical geodetic datums: a latitude/longitude point defines a geographic location on (or above/below) the earth’s surface, measured in degrees from the equator and the International Reference Meridian and metres above the ellipsoid, and based on a given datum. The datum is based on a reference ellipsoid and tied to geodetic survey reference points.

Modern geodesy is generally based on the WGS84 datum (as used for instance by GPS systems), but previously various reference ellipsoids and datum references were used.

This module extends the core latlon-ellipsoidal module to include ellipsoid parameters and datum transformation parameters, and methods for converting between different (generally historical) datums.

It can be used for UK Ordnance Survey mapping (OS National Grid References are still based on the otherwise historical OSGB36 datum), as well as for historical purposes.

import LatLon, { Cartesian, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-ellipsoidal-datum.js'; // browser
import LatLon, { Cartesian, Dms } from 'geodesy/latlon-ellipsoidal-datum.js'; // Node.js
Class LatLonEllipsoidal_Datum
(extends LatLonEllipsoidal)
Latitude/longitude points on an ellipsoidal model earth, with ellipsoid parameters and methods for converting between datums and to geocentric (ECEF) cartesian coordinates.
Constructor Description
LatLon(latitude, longitude, height=0, datum=LatLon.datums.WGS84)

Creates a geodetic latitude/longitude point on an ellipsoidal model earth using a specified datum.

Property (extra to LatLonEllipsoidal) Description
this.datum Datum this point is defined within.
LatLon.ellipsoids Ellipsoids with their parameters; semi-major axis (a), semi-minor axis (b), and flattening (f).
LatLon.datums

Datums; with associated ellipsoid, and Helmert transform parameters to convert from WGS-84 into given datum.

Note that precision of various datums will vary, and WGS-84 (original) is not defined to be accurate to better than ±1 metre. No transformation should be assumed to be accurate to better than a metre, for many datums somewhat less.

This is a small sample of commoner datums from a large set of historical datums. I will add new datums on request.

Method (extra to LatLonEllipsoidal) Description
LatLon.parse(latitude, longitude, height=0, datum=LatLon.datums.WGS84) LatLon.parse(latlon, height=0, datum=LatLon.datums.WGS84)

Parses various representations of latitude/longitude coordinate as per LatLonEllipsoidal.parse().

this.convertDatum(toDatum) Converts this lat/lon coordinate to new coordinate system.
this.toCartesian() Converts this point from (geodetic) latitude/longitude coordinates to (geocentric) cartesian (x/y/z) coordinates.
Class Cartesian_Datum
(extends Cartesian)
Converts geocentric ECEF (earth-centered earth-fixed) cartesian coordinates to latitude/longitude points, applies Helmert transformations.
Property (extra to Cartesian) Description
this.datum Datum this point is defined within.
Method (extra to Cartesian) Description
this.toLatLon() Converts this (geocentric) cartesian (x/y/z) coordinate to (geodetic) latitude/longitude point.
this.convertDatum(toDatum) Converts this cartesian coordinate to new datum (using Helmert 7-parameter transformation).
 
Module latlon-ellipsoidal-referenceframe.js

Modern geodetic reference frames: a latitude/longitude point defines a geographic location on or above/below the earth’s surface, measured in degrees from the equator and the International Reference Meridian and metres above the ellipsoid within a given terrestrial reference frame at a given epoch.

This module extends the core latlon-ellipsoidal module to include methods for converting between different reference frames.

This is scratching the surface of complexities involved in high precision geodesy, but may be of interest and/or value to those with less demanding requirements.

import LatLon, { Cartesian, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-ellipsoidal-referenceframe.js'; // browser
import LatLon, { Cartesian, Dms } from 'geodesy/latlon-ellipsoidal-referenceframe.js'; // Node.js
Class LatLonEllipsoidal_ReferenceFrame
extends LatLonEllipsoidal
Latitude/longitude points on an ellipsoidal model earth, with ellipsoid parameters and methods for converting between reference frames and to geocentric (ECEF) cartesian coordinates.
Constructor Description
LatLon(latitude, longitude, height=0, referenceFrame=ITRF2014, epoch=referenceFrame.epoch)

Creates geodetic latitude/longitude point on an ellipsoidal model earth using using a specified reference frame.

Note that while the epoch defaults to the frame reference epoch, the accuracy of ITRF realisations is meaningless without knowing the observation epoch.

Property (extra to LatLonEllipsoidal) Description
this.referenceFrame Reference frame this point is defined within.
this.epoch Point’s observed epoch t₀.
LatLon.ellipsoids

Ellipsoid parameters; semi-major axis (a), semi-minor axis (b), and flattening (f).

The only ellipsoids used in modern geodesy are WGS-84 and GRS-80 (while based on differing defining parameters, the only effective difference is a 0.1mm variation in the semi-minor axis b).

LatLon.referenceFrames Reference frames, with their base ellipsoids and reference epochs.
LatLon.transformParameters

14-parameter Helmert transformation parameters between (dynamic) ITRS frames, and from ITRS frames to (static) regional TRFs NAD83, ETRF2000, and GDA94.

This is a limited set of transformations; e.g. ITRF frames prior to ITRF2000 are not included. More transformations could be added on request.

Method (extra to LatLonEllipsoidal) Description
LatLon.parse(latitude, longitude, height, referenceFrame, epoch=referenceFrame.epoch) LatLon.parse(latlon, height, referenceFrame, epoch=referenceFrame.epoch)

Parses various representations of latitude/longitude coordinate as per LatLonEllipsoidal.parse().

this.convertReferenceFrame(toReferenceFrame) Converts this lat/lon coordinate to new coordinate system.
this.toCartesian() Converts this point from (geodetic) latitude/longitude coordinates to (geocentric) cartesian (x/y/z) coordinates.
this.toString(format='d', dp=4|2|0, dpHeight=null, referenceFrame=false) Returns a string representation of this point, formatted as degrees ('d'), degrees+minutes ('dm'), or degrees+minutes+seconds ('dms'), to specified decimal places (default 4dp for 'd', 2dp for 'dm', 0dp for 'dms').
Class Cartesian_ReferenceFrame
extends Cartesian
Augments Cartesian with reference frame and observation epoch the cooordinate is based on, and methods to convert between reference frames (using Helmert 14-parameter transforms), and to convert to geodetic latitude/longitude points.
Constructor Description
Cartesian(x, y, z, referenceFrame, epoch=referenceFrame.epoch) Creates cartesian coordinate representing ECEF (earth-centric earth-fixed) point on a given reference frame.
Property (extra to Cartesian) Description
this.referenceFrame Reference frame this point is defined within.
this.epoch Point’s observed epoch t₀.
Method (extra to Cartesian) Description
this.toLatLon() Converts this (geocentric) cartesian (x/y/z) coordinate to (geodetic) latitude/longitude point.
this.convertReferenceFrame(toReferenceFrame) Converts this cartesian coordinate to new reference frame (using Helmert 14-parameter transformation), leaving observation epoch unchanged.
 
Module latlon-ellipsoidal-vincenty.js Distances & bearings between points, and destination points given start points & initial bearings, calculated on an ellipsoidal earth model using ‘direct and inverse solutions of geodesics on the ellipsoid’ devised by Thaddeus Vincenty.
import LatLon, { Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-ellipsoidal-vincenty.js'; // browser
import LatLon, { Dms } from 'geodesy/latlon-ellipsoidal-vincenty.js'; // Node.js
Class LatLonEllipsoidal_Vincenty
extends LatLonEllipsoidal

Extends LatLonEllipsoidal with methods for calculating distances and bearings between points, and destination points given distances and initial bearings, accurate to within 0.5mm distance, 0.000015″ bearing.

By default, these calculations are made on a WGS-84 ellipsoid. Geodesic calculations on other ellipsoids can be done by setting the datum of this point to make it appear as a LatLonEllipsoidal_Datum point.

Method (extra to LatLonEllipsoidal) Description
this.distanceTo(point) Returns the distance between this point and destination point along a geodesic, using Vincenty inverse solution.
this.initialBearingTo(point) Returns the initial bearing (forward azimuth) to travel along a geodesic from this point to the given point, using Vincenty inverse solution.
this.finalBearingTo(point) Returns the final bearing (reverse azimuth) having travelled along a geodesic from this point to the given point, using Vincenty inverse solution.
this.destinationPoint(distance, initialBearing) Returns the destination point having travelled the given distance along a geodesic given by initial bearing from this point, using Vincenty direct solution.
this.finalBearingOn(distance, initialBearing) TODO: arg order? Returns the final bearing (reverse azimuth) having travelled along a geodesic given by initial bearing for a given distance from this point, using Vincenty direct solution.
 
Module latlon-nvector-ellipsoidal.js Tools for working with points on (ellipsoidal models of) the earth’s surface using a vector-based approach using ‘n‑vectors’ (rather than the more common spherical trigonometry).
import LatLon, { Nvector, Cartesian, Ned, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-nvector-ellipsoidal.js'; // browser
import LatLon, { Nvector, Cartesian, Ned, Dms } from 'geodesy/latlon-nvector-ellipsoidal.js'; // Node.js
Class LatLonNvectorEllipsoidal
extends LatLonEllipsoidal
Latitude/longitude points on an ellipsoidal model earth augmented with methods for calculating delta vectors between points, and converting to n‑vectors.
Method (extra to LatLonEllipsoidal) Description
this.deltaTo(point) Calculates delta (north-east-down NED vector) from this point to supplied point.
this.destinationPoint(delta) Calculates destination point using supplied delta (north-east-down NED vector) from this point.
this.toNvector() Converts this lat/lon point to n‑vector (normal to the earth's surface).
this.toCartesian() Converts this point from (geodetic) latitude/longitude coordinates to (geocentric) cartesian (x/y/z) coordinates.
Class NvectorEllipsoidal
extends Vector3d

An n-vector is a position representation using a (unit) vector normal to the Earth ellipsoid. Unlike latitude/longitude points, n-vectors have no singularities or discontinuities.

For many applications, n-vectors are more convenient to work with than other position representations such as latitude/longitude, earth-centred earth-fixed (ECEF) vectors, UTM coordinates, etc.

Constructor Description
Nvector(x, y, z, h=0, datum=LatLon.datums.WGS84) Creates a 3d n‑vector normal to the Earth's surface.
Method (extra to Vector3d) Description
this.toLatLon() Converts this n‑vector to latitude/longitude point.
this.toCartesian() Converts this n‑vector to cartesian coordinate.
this.toString(dp=3, dpHeight=null) Returns a string representation of this (unit) n‑vector. Height component is only shown if dpHeight is specified.
Class Cartesian_Nvector
extends Cartesian
Cartesian_Nvector extends Cartesian with method to convert cartesian coordinates to n‑vectors.
Method (extra to Cartesian) Description
this.toNvector(datum=LatLon.datums.WGS84) Converts this cartesian coordinate to an n‑vector.
Class Ned North-east-down (NED), also known as local tangent plane (LTP), is a vector in the local coordinate frame of a body.
Constructor Description
Ned(north, east, down) Creates North-East-Down vector.
Property Description
this.length Length of NED vector.
this.bearing Bearing of NED vector.
this.elevation Elevation of NED vector.
Method (extra to Cartesian) Description
Ned.fromDistanceBearingElevation(dist, brng, elev) Creates North-East-Down vector from distance, bearing, & elevation (in local coordinate system).
this.toString(dp=0) Returns a string representation of this NED vector.
 
Module latlon-nvector-spherical.js Tools for working with points and paths on (a spherical model of) the earth’s surface using a vector-based approach using ‘n‑vectors’. In contrast to the more common spherical trigonometry, a vector-based approach makes many calculations much simpler and easier to follow.
import LatLon, { Nvector, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-nvector-spherical.js'; // browser
import LatLon, { Nvector, Dms } from 'geodesy/latlon-nvector-spherical.js'; // Node.js
Class LatLonNvectorSpherical Latitude/longitude points on an spherical model earth, and methods for calculating distances, bearings, destinations, etc on great circle paths.
Constructor Description
LatLon(latitude, longitude) Creates a latitude/longitude point on the earth’s surface, using a spherical model earth.
Property Description
this.lat this.latitude Latitude in degrees north from equator: can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
this.lon this.lng this.longitude Longitude in degrees east from international reference meridian: can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
LatLon.metresToKm Conversion factor metres to kilometres.
LatLon.metresToMiles Conversion factor metres to miles.
LatLon.metresToNauticalMiles Conversion factor metres to nautical miles.
Method Description
this.toNvector() Converts this latitude/longitude point to an n-vector (normal to earth's surface).
this.distanceTo(point, radius=6371e3) Returns the distance on the surface of the sphere from this point to destination point.
this.initialBearingTo(point) Returns the initial bearing from this point to destination point.
this.finalBearingTo(point) Returns final bearing arriving at destination point from this point; the final bearing will differ from the initial bearing by varying degrees according to distance and latitude.
this.midpointTo(point) Returns the midpoint between this point and given point.
this.intermediatePointTo(point, fraction) Returns the point at given fraction between this point and given point.
this.intermediatePointOnChordTo(point, fraction) Returns the latitude/longitude point projected from the point at given fraction on a straight line between between this point and given point.
this.destinationPoint(distance, bearing, radius=6371e3) Returns the destination point from this point having travelled the given distance on the given initial bearing (bearing normally varies around path followed).
LatLon.intersection(path1start, path1brngEnd, path2start, path2brngEnd) Returns the point of intersection of two paths each defined by point pairs or start point and bearing.
this.crossTrackDistanceTo(pathStart, pathBrngEnd, radius=6371e3) Returns (signed) distance from this point to great circle defined by start-point and end-point/bearing.
this.nearestPointOnSegment(point1, point2) Returns closest point on great circle segment between point1 & point2 to this point.
this.isWithinExtent(point1, point2) Returns whether this point is within the extent of a line segment joining point 1 & point 2.
LatLon.triangulate(point1, bearing1, point2, bearing2) Locates a point given two known locations and bearings from those locations.
LatLon.trilaterate(point1, distance1, point2, distance2, point3, distance3, radius=6371e3) Locates a latitude/longitude point at given distances from three other points.
this.isEnclosedBy(polygon) Tests whether this point is enclosed by the polygon defined by a set of points.
LatLon.areaOf(polygon, radius=6371e3) Calculates the area of a spherical polygon where the sides of the polygon are great circle arcs joining the vertices.
LatLon.centreOf(polygon) LatLon.centerOf(polygon) Calculates the centre of a spherical polygon where the sides of the polygon are great circle arcs joining the vertices.
LatLon.meanOf(points) Returns point representing geographic mean of supplied points.
this.equals(point) Checks if another point is equal to this point.
this.toGeoJSON() Converts this point to a GeoJSON object.
this.toString(format='d', dp=4|2|0) Returns a string representation of this point, formatted as degrees ('d'), degrees+minutes ('dm'), or degrees+minutes+seconds ('dms'), to specified decimal places (default 4dp for 'd', 2dp for 'dm', 0dp for 'dms').
Class NvectorSpherical
extends Vector3d

An n‑vector is a (unit) vector normal to the Earth's surface (a non-singular position representation).

For many applications, n-vectors are more convenient to work with than other position representations such as latitude/longitude, UTM coordinates, etc.

On a spherical model earth, an n‑vector is equivalent to a (normalised) earth-centred earth-fixed (ECEF) vector.

Constructor Description
Nvector(x, y, z, h=0) Creates a 3d n‑vector normal to the Earth’s surface.
Method (extra to Vector3d) Description
this.toLatLon() Converts this n‑vector to latitude/longitude point.
this.toString(dp=3, dpHeight=null) Returns a string representation of this n‑vector.
 
Module latlon-spherical.js

Library of geodesy functions for operations on a spherical earth model.

Includes distances, bearings, destinations, etc, for both great circle paths and rhumb lines, and other related functions.

import LatLon, { Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/latlon-spherical.js'; // browser
import LatLon, { Dms } from 'geodesy/latlon-spherical.js'; // Node.js
Class LatLonSpherical Latitude/longitude points on an spherical model earth, and methods for calculating distances, bearings, destinations, etc on great circle paths and rhumb lines.
Constructor Description
LatLon(latitude, longitude) Creates a latitude/longitude point on the earth’s surface, using a spherical model earth.
Property Description
this.lat this.latitude Latitude in degrees north from equator: can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
this.lon this.lng this.longitude Longitude in degrees east from international reference meridian: can be set as numeric or hexagesimal (deg-min-sec); returned as numeric.
LatLon.metresToKm Conversion factor metres to kilometres.
LatLon.metresToMiles Conversion factor metres to miles.
LatLon.metresToNauticalMiles Conversion factor metres to nautical miles.
Method Description
LatLon.parse(latitude, longitude) LatLon.parse(latlon)

Parses a latitude/longitude point from a variety of formats.

Latitude & longitude (in degrees) can be supplied as two separate parameters, as a single comma-separated lat/lon string, or as a single object with { lat, lon } or GeoJSON properties.

The latitude/longitude values may be numeric or strings; they may be signed decimal or deg-min-sec (hexagesimal) suffixed by compass direction (NSEW); a variety of separators are accepted. Examples: LatLon.parse(52.205, 0.119) // ≡ new LatLon() LatLon.parse('52°12′18.0″N, 000°07′08.4″E') LatLon.parse({ lat: 52.205, lon: 0.119 })

this.distanceTo(point, radius=6371e3) Returns the distance on the surface of the sphere from this point to destination point.
this.initialBearingTo(point) Returns the initial bearing from this point to destination point.
this.finalBearingTo(point) Returns final bearing arriving at destination point from this point; the final bearing will differ from the initial bearing by varying degrees according to distance and latitude.
this.midpointTo(point) Returns the midpoint between this point and given point.
this.intermediatePointTo(point, fraction) Returns the point at given fraction between this point and given point.
this.destinationPoint(distance, bearing, radius=6371e3) Returns the destination point from this point having travelled the given distance on the given initial bearing (bearing normally varies around path followed).
LatLon.intersection(p1, brng1, p2, brng1) Returns the point of intersection of two paths defined by start point and bearing.
this.crossTrackDistanceTo(pathStart, pathEnd, radius=6371e3) Returns (signed) distance from this point to great circle defined by start-point and end-point.
this.alongTrackDistanceTo(pathStart, pathEnd, radius=6371e3) Returns how far this point is along a path from from start-point, on bearing heading towards end-point. That is, if a perpendicular is drawn from this point to the (great circle) path, the along-track distance is the distance from the start point to where the perpendicular crosses the path.
this.maxLatitude(bearing) Returns maximum latitude reached when travelling on a great circle on given bearing from this point (‘Clairaut’s formula’). Negate the result for the minimum latitude (in the southern hemisphere).
LatLon.crossingParallels(point1, point2, latitude) Returns the pair of meridians at which a great circle defined by two points crosses the given latitude. If the great circle doesn't reach the given latitude, null is returned.
this.rhumbDistanceTo(point, radius=6371e3) Returns the distance travelling from this point to destination point along a rhumb line.
this.rhumbBearingTo(point) Returns the bearing from this point to destination point along a rhumb line.
this.rhumbDestinationPoint(distance, bearing, radius=6371e3) Returns the destination point having travelled along a rhumb line from this point the given distance on the given bearing.
this.rhumbMidpointTo(point) Returns the loxodromic midpoint (along a rhumb line) between this point and second point.
LatLon.areaOf(polygon, radius=6371e3) Calculates the area of a spherical polygon where the sides of the polygon are great circle arcs joining the vertices.
this.equals(point) Checks if another point is equal to this point.
this.toGeoJSON() Converts this point to a GeoJSON object.
this.toString(format='d', dp=4|2|0) Returns a string representation of this point, formatted as degrees ('d'), degrees+minutes ('dm'), or degrees+minutes+seconds ('dms'), to specified decimal places (default 4dp for 'd', 2dp for 'dm', 0dp for 'dms').
 
Module mgrs.js

Military Grid Reference System (MGRS/NATO) grid references provides geocoordinate references covering the entire globe, based on UTM projections.

MGRS references comprise a grid zone designator, a 100km square identification, and an easting and northing (in metres); e.g. ‘31U DQ 48251 11932’.

Depending on requirements, some parts of the reference may be omitted (implied), and eastings/northings may be given to varying resolution.

import Mgrs, { Utm, LatLon, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/mgrs.js'; // browser
import Mgrs, { Utm, LatLon, Dms } from 'geodesy/mgrs.js'; // Node.js
Class Mgrs Military Grid Reference System (MGRS/NATO) grid references, with methods to parse references, and to convert to UTM coordinates.
Constructor Description
Mgrs(zone, band, e100k, n100k, easting, northing, datum=LatLon.datums.WGS84) Creates an Mgrs grid reference object.
Method Description
this.toUtm() Converts MGRS grid reference to UTM coordinate.
Mgrs.parse(mgrsGridRef) Parses string representation of MGRS grid reference.
this.toString(digits=10)

Returns a string representation of an MGRS grid reference.

To distinguish from civilian UTM coordinate representations, no space is included within the zone/band grid zone designator.

Components are separated by spaces: for a military-style unseparated string, use Mgrs.toString().replace(/ /g, '');

Note that MGRS grid references get truncated, not rounded (unlike UTM coordinates).

Class Utm_Mgrs
extends Utm
Extends Utm with method to convert UTM coordinate to MGRS reference.
Method (extra to Utm) Description
this.toMgrs() Converts UTM coordinate to MGRS reference.
Class Latlon_Utm_Mgrs
extends LatLonEllipsoidal
Extends LatLonEllipsoidal adding toMgrs() method to the Utm object returned by LatLon.toUtm().
Method (extra to LatLonEllipsoidal) Description
this.toUtm() Converts latitude/longitude to UTM coordinate (with toMgrs() method).
 
Module osgridref.js Ordnance Survey grid references provide geocoordinate references for UK mapping purposes.
import OsGridRef, { LatLon, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/osgridref.js'; // browser
import OsGridRef, { LatLon, Dms } from 'geodesy/osgridref.js'; // Node.js
Class OsGridRef OS grid references with methods to parse and convert them to latitude/longitude points.
Constructor Description
OsGridRef(easting, northing) Creates an OsGridRef object.
Method Description
this.toLatLon(datum=LatLon.datums.WGS84)

Converts this Ordnance Survey grid reference easting/northing coordinate to latitude/longitude (SW corner of grid square).

While OS grid references are based on OSGB-36, the Ordnance Survey have deprecated the use of OSGB-36 for latitude/longitude coordinates (in favour of WGS-84), hence this function returns WGS-84 by default, with OSGB-36 as an option. See www.ordnancesurvey.co.uk/blog/2014/12/2.

OsGridRef.parse(gridref)

Parses grid reference to OsGridRef object.

Accepts standard grid references (eg 'SU 387 148'), with or without whitespace separators, from two-digit references up to 10-digit references (1m × 1m square), or fully numeric comma-separated references in metres (eg '438700,114800').

this.toString(digits=10) Converts this numeric grid reference to standard OS grid reference.
Class LatLon_OsGridRef
extends LatLonEllipsoidal
Extends LatLon class with method to convert LatLon point to OS grid reference.
Method (extra to LatLonEllipsoidal) Description
this.toOsGrid() Converts latitude/longitude to Ordnance Survey grid reference easting/northing coordinate.
 
Module utm.js

The Universal Transverse Mercator (UTM) system is a 2-dimensional Cartesian coordinate system providing locations on the surface of the Earth.

UTM is a set of 60 transverse Mercator projections, normally based on the WGS-84 ellipsoid. Within each zone, coordinates are represented as eastings and northings, measures in metres; e.g. ‘31 N 448251 5411932’.

import Utm, { LatLon, Dms } from 'https://cdn.jsdelivr.net/npm/geodesy@2/utm.js'; // browser
import Utm, { LatLon, Dms } from 'geodesy/utm.js'; // Node.js
Class Utm UTM coordinates, with functions to parse them and convert them to LatLon points.
Constructor Description
Utm(zone, hemisphere, easting, northing, datum=LatLon.datums.WGS84, convergence=null, scale=null) Creates a Utm coordinate object.
Method Description
this.toLatLon() Converts UTM zone/easting/northing coordinate to latitude/longitude.
Utm.parse(utmCoord, datum=LatLon.datums.WGS84)

Parses string representation of UTM coordinate.

A UTM coordinate comprises (space-separated) zone, hemisphere, easting, northing.

this.toString(digits=0)

Returns a string representation of a UTM coordinate.

To distinguish from MGRS grid zone designators, a space is left between the zone and the hemisphere.

Note that UTM coordinates get rounded, not truncated (unlike MGRS grid references).

Class LatLon_Utm
extends LatLonEllipsoidal
Extends LatLon with method to convert LatLon points to UTM coordinates.
Method (extra to LatLonEllipsoidal) Description
this.toUtm(zoneOverride=undefined) Converts latitude/longitude to UTM coordinate.
 
Module vector3d.js Library of 3-d vector manipulation routines.
import Vector3d from 'https://cdn.jsdelivr.net/npm/geodesy@2/vector3d.js'; // browser
import Vector3d from 'geodesy/vector3d.js'; // Node.js
Class Vector3d Functions for manipulating generic 3-d vectors.
Constructor Description
Vector3d(x, y, z) Creates a 3-d vector.
Property Description
this.length Length (magnitude or norm) of this vector.
Method Description
this.plus(v) Adds supplied vector to this vector.
this.minus(v) Subtracts supplied vector from this vector.
this.times(x) Multiplies this vector by a scalar value.
this.dividedBy(x) Divides this vector by a scalar value.
this.dot(v) Multiplies this vector by the supplied vector using dot (scalar) product.
this.cross(v) Multiplies this vector by the supplied vector using cross (vector) product.
this.negate() Negates a vector to point in the opposite direction.
this.unit() Normalizes a vector to its unit vector.
this.angleTo(v, vSign=undefined) Calculates the angle between this vector and supplied vector.
this.rotateAround(axis, angle) Rotates this point around an axis by a specified angle.
this.toString(dp=3) String representation of vector.
Geodesy Library Class Dependencies