North Pole Merriment

# npm

Get unlimited public & private packages + team-based management with npm Teams.Learn more »

## geodesy

2.2.0 • Public • Published

# Geodesy functions

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.

The intention was to have clear, simple illustrative code samples which could be adapted and re-used in other projects (whether those be coded in JavaScript, Java, C++, Excel VBA, or anything else...). With its untyped C-style syntax, JavaScript reads remarkably close to pseudo-code, exposing the algorithms with a minimum of syntactic distractions

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.

These functions are as language-agnostic as possible, avoiding excessive use of JavaScript-specific language features which would not be recognised by users of other languages (and which might be difficult to translate to other languages). I use Greek letters in variables representing maths symbols conventionally presented as Greek letters: I value the great benefit in legibility over the minor inconvenience in typing.

This version 2 of the library uses JavaScript ES classes and modules to organise the interdependencies; this makes the code both more immediately readable than previously, and also more accessible to non-JavaScript readers (always bearing in mind JavaScript uses prototype-based classes rather than classical inheritance-based classes). For older browsers (or Node.js <8.0.0), v1.1.3 is ES5-based. Note that there are breaking changes in moving from version 1 to version 2.

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:
• or to find the destination point for a given distance and initial bearing on an ellipsoidal model earth:

Full documentation is available at www.movable-type.co.uk/scripts/geodesy-library.html, and tests in the browser as well as Travis CI.

## Usage

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

The library can be used in a Node.js app from npm (currently the esm package is required to load ES-modules):

### Other examples

Some examples of calculations possible with the libraries:

e.g. for geodesic distance on an ellipsoidal model earth using Vincenty’s algorithm:

e.g. for UTM conversions:

e.g. for MGRS/NATO map references:

e.g. for OS grid references:

e.g. for testing if a point is enclosed within a polygon:

e.g. greater parsing & presentation control:

e.g. datum conversions:

(The format of the import statements will vary according to deployment).

### Install

`npm i geodesy`

5,176

2.2.0

MIT

427 kB

31

### Repository

github.com/chrisveness/geodesy