Haversine-ts NPM

haversine-ts

GitHub release (latest SemVer) License:

About

Typescript library for distance calculation on a sphere surface with both decimal degrees (DD) or degrees minutes seconds (DMS) coordinates.

Main package features:

Allows calculating distances between to points in metres, kilometres or miles.
Allows using decimal degree (DD) or degrees minutes seconds (DMS) coordinates.
Allows calculating start and end bearings of a path between two points.
Allows calculating the end point of a path given its start point, start bearing and distance.

At a glance

Calculate the distance, in kilometres, between two decimal degrees coordinates

import { DDPoint, Haversine } from "haversine-ts";

// New York decimal degrees (DD) coordinates are:
// latitude 40.730610 N,
// longitude 73.935242 W
const newYork = new DDPoint(40.73061, -73.935242);

// Madrid decimal degrees (DD) coordinates are:
// latitude 40.416775 N,
// longitude 3.703790 W
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();
const distance = haversine.getDistance(newYork, madrid);

console.log(`The distance from New York to Madrid is ${distance} kilometres.`);

Calculate the distance, in miles, between two degrees minutes seconds (DMS) coordinates

import {
  DMSCoordinate,
  DMSPoint,
  Haversine,
  UnitOfDistance
} from "haversine-ts";

// New York DMS coordinates are
// latitude 40° 43' 50.1960'' N,
// longitude 73° 56' 6.8712'' W
const newYork = new DMSPoint(
  new DMSCoordinate(40, 43, 50.196),
  new DMSCoordinate(-73, 56, 6.8712)
);

// Madrid DMS coordinates are
// latitude 40° 25' 0.3900'' N,
// longitude 3° 42' 13.6440'' W
const madrid = new DMSPoint(
  new DMSCoordinate(40, 25, 0.39),
  new DMSCoordinate(-3, 42, 13.644)
);

const haversine = new Haversine(UnitOfDistance.Mile);
const distance = haversine.getDistance(newYork.toDDPoint(), madrid.toDDPoint());

console.log(`The distance from New York to Madrid is ${distance} miles.`);

Calculate the bearing between two points

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();
const bearing = haversine.getBearing(newYork, madrid);

console.log(
  `The start bearing of the path from New York to Madrid is ${bearing.start} degrees, and the end bearing is ${bearing.end} degrees.`
);

Calculate the endpoint of a path

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const bearing = 65.71472;
const distance = 5762;

const haversine = new Haversine();
const madrid = haversine.getPoint(newYork, bearing, distance);

console.log(
  `Madrid is the endpoint of the path starting in New York with a bearing of ${bearing} degrees at a distance of ${distance} kilometers`
);

Installation

To install the package using nmp simply run this command in the root folder of your node project:

npm install haversine-ts

Usage

Overview

The Haversine class supports the implementation of the sphere path resolvers (distance and bearing between two points, end point given start point, bearing and distance).

It uses as input decimal degrees (DD) coordinates defined as DDPoint class object instances, that can be converted into degrees minutes seconds (DMS) coordinates as instances of the DMSPoint class. Each DMSPoint object instance is composed by two DMSCoordinate class object instances.

The SphereBearing class represents a tuple with the start and end bearings of a sphere path (orthodrome) between two points.

DDPoint class

Sphere point defined by a latitude and a longitude in decimal degrees (DD)

Constructors:
- new DDPoint(latitude, longitude)
Properties:
- latitude
- longitude
Methods:
- .toDMSPoint() ⇒ DMSPoint

new DDPoint(latitude, longitude)

Creates a sphere point object instance.

import { DDPoint } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);

console.log(
  `The coordinates of New York, in decimal notation, are latitude ${newYork.latitude}, longitude ${newYork.longitude}`
);

ddPoint.latitude ⇒ number

Returns the point latitude set in the object instance constructor.

ddPoint.longitude ⇒ number

Returns the point longitude set in the object instance constructor.

ddPoint.toDMSPoint() ⇒ DMSPoint

Gets the equivalent point in degrees minutes seconds (DMS) notation.

import { DDPoint } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const newYorkDMS = newYork.toDMSPoint();

console.log(
  `The coordinates of New York, in DMS notation, are ${newYorkDMS.degrees} degrees, ${newYorkDMS.minutes} minutes, ${newYorkDMS.seconds} seconds`
);

Returns:
- DMSPoint - Equivalent sphere point defined in degrees minutes seconds (DMS) notation

DMSCoordinate

Latitude/Longitude coordinate defined in degrees minutes seconds (DMS).

Constructors:
- new DMSCoordinate(degrees, minutes, seconds)
Properties:

new DMSCoordinate(degrees, minutes, seconds)

Initializes a DMSCoordinate object instance.

import { DMSCoordinate } from "haversine-ts";

const newYorkLatitude = new DMSCoordinate(40, 43, 50.196);

console.log(
  `The New York latitude, in DMS notation, is ${newYorkLatitude.degrees} degrees, ${newYorkLatitude.minutes} minutes, ${newYorkLatitude.seconds} seconds,`
);

Parameters
- degrees (number): Coordinate degrees, from -180 to 180.
- minutes (number): Coordinate minutes, from 0 to <60.
- seconds (number): Coordinate seconds, from 0 to <60.
Throws:
- Error if degrees, minutes or seconds are out of range.

dmsCoordinate.degrees ⇒ number

Returns the coordinate degrees set in the constructor.

dmsCoordinate.minutes ⇒ number

Returns the coordinate minutes set in the constructor.

dmsCoordinate.seconds ⇒ number

Returns the coordinate seconds set in the constructor.

DMSPoint class

Sphere point defined by a latitude and a longitude in degrees minutes seconds (DMS).

Constructors:
- new DMSPoint(latitude, longitude)
Properties
- latitude
- longitude
Methods:
- .toDDPoint() ⇒ DDPoint

new DMSPoint(latitude, longitude)

Creates a sphere point object instance in DMS notation.

import { DMSPoint } from "haversine-ts";

const newYork = new DMSPoint(
  new DMSCoordinate(40, 43, 50.196),
  new DMSCoordinate(-73, 56, 6.8712)
);

const newYorkLatitude = newYork.latitude;
const newYorkLongitude = newYork.longitude;

console.log(
  `The New York coordinates, in DMS notation, are latitude ${newYorkLatitude.degrees} degrees ${newYorkLatitude.minutes} minutes, ${newYorkLatitude.seconds} seconds, longitude ${newYorkLongitude.degrees} degrees ${newYorkLongitude.minutes} minutes, ${newYorkLongitude.seconds} seconds`
);

Parameters
- latitude (DMSCoordinate): Latitude coordinate in degrees minutes seconds.
- longitude (DMSCoordinate): Longitude coordinate in degrees minutes seconds.
Throws:
- Error if latitude degrees are out of range (-90 to 90).

dmsPoint.latitude ⇒ DMSCoordinate

Returns the point latitude set in the constructor.

dmsPoint.longitude ⇒ DMSCoordinate

Returns the point longitude set in the constructor.

dmsPoint.toDDPoint() ⇒ DDPoint

Gets the equivalent point in decimal degrees notation.

import { DMSPoint } from "haversine-ts";

const newYork = new DMSPoint(
  new DMSCoordinate(40, 43, 50.196),
  new DMSCoordinate(-73, 56, 6.8712)
);
const newYorkDD = newYork.toDDPoint();

console.log(
  `The coordinates of New York, in DD notation, are latitude ${newYorkDD.latitude}, longitude ${newYorkDD.longitude}`
);

Returns:
- DDPoint - Equivalent sphere point defined in decimal degrees (DD) notation.

Haversine class

Haversine formula resolver.

Constructors:
- new Haversine([uod], [sphereRadius])
Methods:
- .getBearing(startPoint, endPoint) ⇒ SphereBearing
- .getDistance(pointA, pointB) ⇒ number
- .getPoint(startPoint, bearing, distance) ⇒ DDPoint

new Haversine(uod, sphereRadius)

Initializes the Haversine resolver.

import { Haversine, UnitOfDistance } from "haversine-ts";

const haversine = new Haversine(UnitOfDistance.Mile);

Parameters:
- uod (UnitOfDistance, optional): Unit of distance (default: UnitOfDistance.Kilometre)
- sphereRadius (number, optional): Custom sphere radius in uod units (default: equatorial Earth radius).

haversine.getBearing(startPoint, endPoint) ⇒ SphereBearing

Calculates the sphere bearing, or start and end bearings, of the path between two points in a sphere.

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();
const bearing = haversine.getBearing(newYork, madrid);

console.log(
  `The start bearing of the path from New York to Madrid is ${bearing.start} degrees, and the end bearing is ${bearing.end} degrees.`
);

Parameters:
- startPoint (DDPoint): Start point, in decimal degrees coordinates.
- endPoint (DDPoint): End point, in decimal degrees coordinates.
Returns:
- SphereBearing - Bearings of the path from startPoint to endPoint, in degrees (0 to 360, clockwise from North).

haversine.getDistance(pointA, pointB) ⇒ number

Calculates the distance between to sphere points defined as decimal degrees (DD) coordinates.

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();

const distance = haversine.getDistance(newYork, madrid);

console.log(`The distance from New York to Madrid is ${distance} kilometres.`);

Parameters:
- pointA (DDPoint): Point A, in decimal degrees coordinates.
- pointB (DDPoint): Point B, in decimal degrees coordinates.
Returns:
- number - Distance between the points, in the unit of distance set in the class constructor.

haversine.getPoint(startPoint, bearing, distance) ⇒ DDPoint

Calculates the coordinates of the end point of a path given its start point, start bearing and distance.

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const bearing = 65.71472;
const distance = 5762;

const haversine = new Haversine();
const madrid = haversine.getPoint(newYork, bearing, distance);

console.log(
  `Madrid is the endpoint of the path starting in New York with a bearing of ${bearing} degrees at a distance of ${distance} kilometers`
);

Parameters:
- startPoint (DDPoint): Start point, in decimal degrees coordinates.
- bearing (number): Bearing to the end point, in degrees (0 to 360, clockwise from North).
- distance (number): Distance from the start point to the targetted point, using as unit of measure that set in the class constructor (metres, kilometres or miles).
Returns:.
- DDPoint - End point, in decimal degrees coordinates.

SphereBearing

Sphere bearing as a tuple of start and end bearings of a sphere path (orthodrome) between two points.

Constructors:
- new SphereBearing(start, end)
Properties:
- start
- end

new SphereBearing(start, end)

Initializes a sphere bearing object instance.

import { SphereBearing } from "haversine-ts";

const bearing = new SphereBearing(60.5, 181);

console.log(
  `The start bearing of the path from A to B is ${bearing.start} degrees, and the end bearing is ${bearing.end} degrees.`
);

Parameters
- start (number): Start bearing, from 0 to <360 clockwise from North.
- end (number): End bearing, from 0 to <360 clockwise from North.
Throws:
- Error if start or end bearings are out of range.