@locale-tools/navigation

Navigational tools.

Installation

Install a given package with npm or yarn.

npm install @locale-tools/navigation

yarn add @locale-tools/navigation

Usage

Types

// coordinates object
type Coordinates = {
  latitude: number;
  longitude: number;
};

enum CompassRose {}
CompassRose.CARDINAL; // "cardinal"

enum CardinalDirections {}
CardinalDirections.W; // "W"

enum CelestialDirections {}
CelstialDirections.SEBS; // "SEbS"

enum ClassicalDirections {}
ClassicalDirections.WNW; // "WNW"

enum MarinerDirections {}
MarinerDirections.SE; // "SE"

enum CompassPoints {
  CARDINAL = 4,
  MARINER = 8,
  CLASSICAL = 12,
  CELESTIAL = 32
}

Methods

bearingToDirection(bearing: number): Windrose

Converts a bearing to a given compass direction. Throws an error if bearing is not between 0 and 360.

| Parameter | Type | Description | Default | | ------------- | ------------- | ------------------------------- | ----------------------- | | bearing | number | Bearing to convert | Required | | compassPoints | CompassRose | Number of compass points to use | CompassRose.CLASSICAL |

import { bearingToDirection, CompassRose } from "@locale-tools/navigation";

const bearing = 243.62;

const windrose4Direction = bearingToDirection(bearing); // W

const windrose8Direction = bearingToDirection(bearing, CompassRose.MARINER); // SW

const windrose16Direction = bearingToDirection(bearing, CompassRose.CLASSICAL); // WSW

const windrose32Direction = bearingToDirection(bearing, CompassRose.CELESTIAL); // SWbW

getCenterOfCoordinates(coordinates: Coordinates[]): Coordinates`

Returns the coordinate center of a list of coordinates.

| Parameters | Type | Description | Default | | ----------- | --------------- | ------------------------- | ------------ | | coordinates | Coordinates[] | List of coordinate objets | Required |

import { getCenterOfCoordinates } from "@locale-tools/navigation";

const center = getCenterOfCoordinates([
  { latitude: 12.5, longitude: -69.9 },
  { latitude: 52.5, longitude: 5.75 }
]);
// returns { latitude: 38.44160133305245, longitude: -42.280221828555504 }

getRhumbLine({ from, to }): number`

Returns a rhumb line between 2 longitudes (meridians).

| Parameters | Type | Description | Default | | ---------- | -------- | ------------------ | ------------ | | from | number | starting longitude | Required | | to | number | ending longitude | Required |

import { getRhumbLine } from "@locale-tools/navigation";

const rhumbLine = getRhumbLine({from: -69.9, to: 5.75});
// returns 1.3203415791337105

geographicDistanceTo({ from, to, unit, useRhumbLine }): number`

Returns the great-circle distance between 2 points using the haversine formula.

| Parameters | Type | Description | Default | | ------------ | -------------- | -------------------------------------- | ------------ | | from | Coordinates | starting coordinates | Required | | to | Coordinates | destination coordinates | Required | | unit | DistanceUnit | unit of measurement to get distance in | kilometer | | useRhumbLine | boolean | whether or not to use a rhumb line | false |

import { geographicDistanceTo } from "@locale-tools/navigation";

const distance = geographicDistanceTo({
  from: location1,
  to: location2,
  unit: "mile"
});
// returns 12792.535602738117

const distanceUsingRhumbLine = geographicDistanceTo({
  from: location1,
  to: location2,
  unit: "kilometer",
  useRhumbLine: true
});
// returns 8156.327629644782

bearingDistanceTo({ from, to, useRhumbLine }): { initialBearing: number, finalBearing: number})`

Returns the initial bearing from start point to the destination point and the final bearing which differs by varying degrees according to the latitude/longitude.

| Parameters | Type | Description | Default | | ------------ | ------------- | ---------------------------------- | ------------ | | from | Coordinates | starting coordinates | Required | | to | Coordinates | destination coordinates | Required | | useRhumbLine | boolean | whether or not to use a rhumb line | false |

import { bearingDistanceTo } from "@locale-tools/navigation";

const bearing = bearingDistanceTo({ from: location1, to: location2 });
// returns { initialBearing: 51.51700060782139, finalBearing: 231.5170006078214 }

const bearingUsingRhumbLine = bearingDistanceTo({
  from: location1,
  to: location2,
  useRhumbLine: true
});
// returns { initialBearing: 56.90674499795489, finalBearing: 236.9067449979549 }