These libraries started life (a long time ago) as simple ‘latitude/longitude’ code fragments covering distances and bearings, intended to help people who had little experience of geodesy, and perhaps limited programming experience.
While still valid for that purpose, they have grown since then into considerable libraries, based around:
- simpler trig-based functions (distance, bearing, etc) based on a spherical earth model
- more sophisticated trig-based functions (distance, bearing, etc) based on a more accurate ellipsoidal earth model
- vector-based functions mostly based on a spherical earth model, with some ellipsoidal functions
Complementing these are various mapping-related functions covering:
- UTM coordinates & MGRS grid references
- UK Ordnance Survey (OSGB) national grid references
And also functions for historical datum conversions (such as between NAD83, OSGB36, Irl1975, etc) and modern reference frame conversions (such as ITRF2014, ETRF2000, GDA94, etc), and conversions between geodetic (latitude/longitude) coordinates and geocentric cartesian (x/y/z) coordinates.
There are also supporting libraries:
- 3d vector manipulation functions (supporting cartesian (x/y/z) coordinates and n-vector geodesy)
- functions for conversion between decimal degrees and (sexagesimal) degrees/minutes/seconds
The spherical-earth model provides simple formulae covering most ‘everyday’ accuracy requirements; the ellipsoidal-earth model provides more accurate formulae at the expense of complexity. The vector-based functions provide an alternative approach to the trig-based functions, with some overlapping functionality; which one to use may depend on availability of related functions or on other considerations.
While some aspects of the library are quite complex to understand and use, basic usage is simple – for instance:
- to find the distance between two points using a simple spherical earth model:
;const p1 = 52205 0119;const p2 = 48857 2351;const d = p1; // 404.3×10³ m
- or to find the destination point for a given distance and initial bearing on an ellipsoidal model earth:
;const p1 = -3795103 14442487;const dist = 54972271;const brng = 30686816;const p2 = p1; // 37.6528°S, 143.9265°E
Full documentation is available at www.movable-type.co.uk/scripts/geodesy-library.html, and tests in the browser as well as Travis CI.
While originally intended as illustrative code fragments, these functions can be used ‘as-is’; either client-side in-browser, or with Node.js.
Usage in browser
The library can be used in the browser by taking a local copy, or loading it from jsDelivr: for example,
Usage in Node.js
$ npm install geodesy esm$ node -r esm> import LatLon from 'geodesy/latlon-spherical.js';> const p1 = new LatLon;> const p2 = new LatLon;> const d = p1.distanceTo;> console.assert;> const mid = p1.midpointTo;> console.assert;
Some examples of calculations possible with the libraries:
e.g. for geodesic distance on an ellipsoidal model earth using Vincenty’s algorithm:
;const p1 = 5006632 -571475;const p2 = 5864402 -307009;const d = p1;console;
e.g. for UTM conversions:
;const utm = Utm;const latlon = utm;console;console
e.g. for MGRS/NATO map references:
;const mgrs = Mgrs;const latlon = mgrs;console;const p = LatLon;const ref = p;console;
e.g. for OS grid references:
;const gridref = 651409903 313177270;const pWgs84 = gridref;console;const pOsgb = gridref;console;
e.g. for testing if a point is enclosed within a polygon:
;const polygon = 482 492 493 483 ;const enclosed = 48924;console;
e.g. greater parsing & presentation control:
;Dmsseparator = ' '; // full-space separator between degrees-minutes-secondsconst p1 = LatLon;const p2 = LatLon;const mid = p1;console;
e.g. datum conversions:
;const pWgs84 = 533444 -62577;const pIrl1975 = pWgs84;console;
(The format of the import statements will vary according to deployment).