mt-latlon

Latitude/longitude spherical geodesy formulae and scripts.

Installation

$ npm install mt-latlon

Usage

The module exposes the LatLon class which represents a point on the earth's surface. With this class you can create LatLon objects on which you can perform various operations.

var LatLon = require('mt-latlon');
var point = new LatLon(51.5136, -0.0983);

The available operations of the LatLon objects is listed below.

LatLon(lat, lon, rad)

Creates a point on the earth's surface at the supplied latitude/longitude.

• lat (number) latitude in numeric degrees
• lon (number) longitude in numeric degrees
• rad (number, default = 6371) radius of earth if different value is required from standard 6,371km

var point = new LatLon(51.5136, -0.0983);

distanceTo(point, precision)

Returns the distance from this point to the supplied point, in km (using Haversine formula). Source: Haversine formula - R. W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol 68, no 2, 1984.

• point (LatLon) Latitude/longitude of destination point
• precision (number, default = 4) Number of significant digits to use for returned value

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var dist = p1.distanceTo(p2);
// => 7.794

bearingTo(point)

Returns the (initial) bearing from this point to the supplied point, in degrees. (see http://williams.best.vwh.net/avform.htm#Crs)

• point (LatLon) Latitude/longitude of destination point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var brng = p1.bearingTo(p2);
// => 120.67420693455165

finalBearingTo(point)

Returns final bearing arriving at supplied destination point from this point; the final bearing will differ from the initial bearing by varying degrees according to distance and latitude.

• point (LatLon) Latitude/longitude of destination point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var brng = p1.finalBearingTo(p2);
// => 120.74995889218458

midpointTo(point)

Returns the midpoint between this point and the supplied point. (see http://mathforum.org/library/drmath/view/51822.html for derivation)

• point (LatLon) Latitude/longitude of destination point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var p3 = p1.midpointTo(p2);
// p3 = 51°29′45″N, 000°03′00″W (as LatLon object)

destinationPoint(brng, dist)

Returns the destination point from this point having travelled the given distance (in km) on the given initial bearing (bearing may vary before destination is reached). (see http://williams.best.vwh.net/avform.htm#LL)

• brng (number) Initial bearing in degrees
• dist (number) Distance in km

var p1 = new LatLon(51.5136, -0.0983);
var p2 = p1.destinationPoint(120, 10);
// p2 = 51°28′07″N, 000°01′36″E (as LatLon object)

LatLon.intersection(p1, brng1, p2, brng2)

Returns the point of intersection of two paths defined by point and bearing. null is returned if no unique intersection is defined. (see http://williams.best.vwh.net/avform.htm#Intersection)

• p1 (LatLon) First point
• brng1 (number) Initial bearing from first point
• p2 (LatLon) Second point
• brng2 (number) Initial bearing from second point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var p3 = LatLon.intersection(p1, 120, p2, 10);
// p3 = 51°28′43″N, 000°00′05″W

rhumbDistanceTo(point)

Returns the distance from this point to the supplied point, in km, travelling along a rhumb line. (see http://williams.best.vwh.net/avform.htm#Rhumb)

• point (LatLon) Latitude/longitude of destination point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var dist = p1.rhumbDistanceTo(p2);
// => 7.794

rhumbBearingTo(point)

Returns the bearing from this point to the supplied point along a rhumb line, in degrees from North.

• point (LatLon) Latitude/longitude of destination point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var dist = p1.rhumbBearingTo(p2);
// => 120.71209100924256

rhumbDestinationPoint(brng, dist)

Returns the destination point from this point having travelled the given distance (in km) on the given bearing along a rhumb line.

• brng (number) Bearing in degrees from North
• dist (number) Distance in km

var p1 = new LatLon(51.5136, -0.0983);
var p2 = p1.rhumbDestinationPoint(120, 10);
// p2 = 51°28′07″N, 000°01′36″E (as LatLon object)

rhumbMidpointTo(point)

Returns the loxodromic midpoint (along a rhumb line) between this point and the supplied point. (see http://mathforum.org/kb/message.jspa?messageID=148837)

• point (LatLon) Latitude/longitude of destination point

var p1 = new LatLon(51.5136, -0.0983);
var p2 = new LatLon(51.4778, -0.0015);
var p3 = p1.rhumbMidpointTo(p2);
// p3 = 51°29′45″N, 000°03′00″W (as LatLon object)

lat(format, dp)

Returns the latitude of this point; signed numeric degrees if no format, otherwise format and dp as per Geo.toLat().

• format (string, optional) Return value as d, dm, dms
• dp (number, optional, 0|2|4) Number of decimal places to display

var p1 = new LatLon(51.5136, -0.0983);
var lat = p1.lat();
// => 51.5136
lat = p1.lat('d');
// => 51.5136°N
lat = p1.lat('dm');
// => 51°30.82′N
lat = p1.lat('dms');
// => 51°30′49″N
lat = p1.lat('d', 2);
// => 51.51°N

lon(format, dp)

Returns the longitude of this point; signed numeric degrees if no format, otherwise format and dp as per Geo.toLon().

• format (string, optional) Return value as d, dm, dms
• dp (number, 0|2|4) Number of decimal places to display

var p1 = new LatLon(51.5136, -0.0983);
var lon = p1.lon();
// => -0.0983
lon = p1.lon('d');
// => 000.0983°W
lon = p1.lon('dm');
// => 000°05.90′W
lon = p1.lon('dms');
// => 000°05′54″W
lon = p1.lon('d', 2);
// => 000.10°W

Copyright and license

The original code was written by Chris Veness and can be found at http://www.movable-type.co.uk/scripts/latlong.html. It is released under the simple Creative Commons attribution license (http://creativecommons.org/licenses/by/3.0/).

This project is released under the MIT license.