README
maptools
Maptools 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 @stewartmac/maptools --save
const maptools = require('maptools');
import {toDEC, toDMS, toDDM, getDistance, orderByDistance, getCenterPoint } from 'maptools';
Web
All functions can be accessed via window.MapTools
<script language="JavaScript" src="/dist/maptools.js"></script>
<script>
window.Maptools.toDEC([`S43°38'19.39`, `W116°14'28.86"`])
</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 numberlong
– longitude in Accepted format, either string or numberprecision
- 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} pairsformat
- 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 formatpoints
– Array of {"lat": lat, "long": long} pairs in DEC formatformat
- 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"