maptoolz

Maptoolz is a WGS84 map utility library. Its core functionality is to convert between DMS, DEC and DDM coordinate formats. Given a group of coordinates it can calculate distance, order by distance, and find the center point.

Install

Node.JS

npm install maptoolz --save

const maptoolz = require('maptoolz');

import {toDEC, toDMS, toDDM, getDistance, orderByDistance, getCenterPoint } from 'maptoolz';

Web

All functions can be accessed via window.MapToolz

<script src="/dist/maptoolz.js"></script>
<script>
  window.Maptoolz.toDEC([`S43°38'19.39`, `W116°14'28.86"`])
</script>

OR

<script src="https://unpkg.com/maptoolz/dist/maptoolz.js"></script>

Accepted Input

• Whitespace is acceptable in Latitude and Longitude
• Negative values for Latitude are assumed to be S
• Negative values for Longitude are assumed to be W
• Single digits in number format are acceptable
• degree, minutes, and seconds signs may be included or ommitted

Degrees Minutes Seconds (DMS)

| Latitude | Longitude | | :---| :--- | | Ndd°mm'ss.ss" | Wddd°mm's.ss" | | dd mm ' ss " S| dd mm ' s W | |-d mm ss| -d |

Decimal Degrees (DEC)

| Latitude | Longitude | | :---| :--- | | -dd.ddddd | ddd.ddddd| | -d | d|

Degrees Decimal Minutes (DDM)

| Latitude | Longitude | | :---| :--- | | dd°mm.mmmm' | Wddd°mm.mmmm' | | dd mm.mmmm S| dd mm | |-d mm.mmmm| -d |

Conversion Functions

Accepts an array of strings or numbers as per the accepted format. Returns an object with the converted latitude and longitude pair(s).

toDMS([lat, long])

toDEC([lat, long], precision = 5)

toDDM([lat, long])

Params

Even length array of lat and long pairs

• lat – latitude in Accepted format, either string or number
• long – longitude in Accepted format, either string or number
• precision - toDEC only - Optional number of decimal places, default is 5

Returns an Array of Objects

[{ "lat": "latitude", "long": "longitude" }]

• Latitude is of type string
• Longitude is of type string

Errors

| Input | Error | | :---| :--- | |Empty Array | TypeError: "One or more lat/long pairs invalid" | |Odd length array | TypeError: "One or more lat/long pairs invalid" | |Out of Range Lat | TypeError: "Invalid Range: Lat" | |Out of Range Long | TypeError: "Invalid Range: Long" |

Examples

const pointA = toDEC([`S43°38'19.39`, `W116°14'28.86"`])
// [{ lat: -43.63872, long: -116.24135 }]
const pointB = toDMS([-43.63872, -116.24135])
// [{ lat: S43°38'19.39", long: W116°14'28.86" }]
const pointC = toDDM([`32° 18.385' N`, `122° 36.875' W`])
// [{ lat: N32°18.385', long: W122°36.875' }]

Map Functions

getDistance(points, format = "km", precision = 2)

Uses the Harvesine Formula to calculate the distance between two pairs of coordinates. The spherical radius is calculated using the average latitude between the two points. The distance between points [A, B, C, D] is the sum of: (A + B) + (B + C) + (C + D). The unit of measurement is optional with the default as km. The precision is also option with the default as 2 decimal places. Precision must be used in combination with the format argument.

Params

Array of at least 2 pairs of coordinates in object form

• points - Array of {"lat": lat, "long": long} pairs

• format - unit of measurement for output, default is 'km'

  | Symbol | Unit of Measurement | | :---| :--- | |m | Meters | |km | Kilometers | |nm | Nautical miles | |mi | Miles |

• precision - number of decimal places, default is 2. Must be used in combination with format.

Returns an Object

{"distance": distance, "format": format }

• distance is of type number
• format is of type string

Example

const points = toDEC([
    `N53°27'-18.85"`, `W113°32'-23.09"`,
    `N53°30'-14.91"`, `W113°23'-8.08"`,
    `N53°30'22.8"`, `W113°13'-28.44"`,
    `N53°35'-15.29"`, `W113°11'-8.45"`,
    `N53°35'1.61"`, `W112°60'-5.29"`,
    ]);
const distanceKM = getDistance(points);
// { distance: 42.96, format: "km" }
const distanceNM = getDistance(points, 'nm', 4);
// { distance: 23.1982, format: "nm" }

Errors

| Input | Error | | :---| :--- | |Less than 2 points | TypeError: "At least 2 points are needed to calculate the distance" | |Invalid format symbol | TypeError: "Invalid output format" |

orderByDistance(origin, points, format = "km")

Accepts an origin point of {"lat": lat, "long": long} type and an array of {"lat": lat, "long": long} objects. Returns an array of objects ordered from nearest to farthest. Iterates over the array and uses the getDistance() function under the hood.

Params

An origin point and array of coordinate pairs

• origin – {"lat": lat, "long": long} pair in DEC format

• points – Array of {"lat": lat, "long": long} pairs in DEC format

• format - unit of measurement for output, default is 'km'

  | Symbol | Unit of Measurement | | :---| :--- | |m | Meters | |km | Kilometers | |nm | Nautical miles | |mi | Miles |

Returns an Array of Objects

{from: { "lat": lat, "long": long }, to: { "lat": lat, "long": long }, "distance": distance, "format": format }

• from is a { "lat": lat, "long": long } object
• to is a { "lat": lat, "long": long } object
• distance is of type number
• format is of type string

Example

const points = orderByDistance(
  {lat: 56.495000228117775, long:-88.26338679703304}, 
  toDEC([
      61.46659628870247, -93.86230787510061,
      63.32600658563838, -85.55269557039314,
      60.26988668328659, -77.2462962114008,
      55.46098932075369, -77.3115710914306,     
    ])
/* [
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '61.46660', long: '-93.86231' },
        distance: 637.8,
        format: 'km'
      },
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '55.46099', long: '-77.31157' },
        distance: 689.41,
        format: 'km'
      },
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '60.26989', long: '-77.24630' },
        distance: 764.76,
        format: 'km'
},
      {
        from: { lat: 56.495000228117775, long: -88.26338679703304},
        to: { lat: '63.32601', long: '-85.55270' },
        distance: 773.21,
        format: 'km'
      },
    ]
*/

Errors

| Input | Error | | :---| :--- | |Missing Parameters | TypeError: "Input parameters missing" | |Less than 2 points | TypeError: "At least 2 points are needed to calculate the distance" | |Invalid format symbol | TypeError: "Invalid output format" |

getCenterPoint(points)

Accepts an array of {"lat": lat, "long": long} objects. Iterates over the array, converting the pairs of Geodetic coordinates into their respective Cartesian coordinates. The height is assumed to be 0. Sums and averages to find the center point.

Params

Array of pairs of coordinates in object form

• points - Array of {"lat": lat, "long": long} pairs

Returns an Object

{"lat": lat, "long": long }

• Latitude is of type string in DEC format
• Longitude is of type string in DEC format

Example

const center = getCenterPoint(
       toDEC([
          -21.0781885,
          130.2679653,
          -22.0304073,
          133.3797261,
          -20.1017191,
          133.3017134,
          -20.1017192,
          133.3017126,
        ])
// { lat: "-20.83315", long: "132.56395" }

Errors

| Input | Error | | :---| :--- | |Missing Parameters | TypeError: "Input parameters missing" |

Errors

Errors can be handled with a try-catch block.

try {
  const distanceKM = getDistance({lat: -43.63872, long: -116.24135});
} catch (e) {
  console.log(e.message)
}
// "At least 2 points are needed to calculate the distance"