Test whether two locations are equal or approximately equal. The third argument epsilon is optional and is 0 by default (i.e. only locations that are strictly equal return true).
// compare locations in different formatsisEqual({longitude: 4, latitude: 51}, [4, 51]) // trueisEqual({longitude: 4.1, latitude: 51.2}, [4, 51]) // false// A calculation like 0.1 + 0.2 introduces a round off error, which can be dealt// with by passing a value for epsilon specifying the maximum absolute difference.const epsilon = 1e-12 // max absolute differenceisEqual({longitude: 0, latitude: 0.1 + 0.2}, {lon: 0, lat: 0.3}) // falseisEqual({longitude: 0, latitude: 0.1 + 0.2}, {lon: 0, lat: 0.3}, epsilon) // true
isLatLon(object: Location) : boolean
Test whether an object is an object containing numeric properties lat and lon.
Calculate the average of a list with locations. Returns null when the input is an empty Array or no Array. Returned Location format is the same as the format of the first entry of locations. The array can contain mixed content.
Get the bounding box of a list with locations, optionally with an extra margin around it in meters. Returns a BoundingBox with topLeft and bottomRight location.
Test whether a location lies inside a given bounding box.
Returns true when the location is inside the bounding box or on the edge.
The function is resilient against mixing up locations of the bounding boxes' topLeft and bottomRight location.
Test whether a location lies inside a circle defined by a center location and a radius in meters.
Returns true when the location is inside the circle or on the edge.
const center = {lat: 51, lon: 4}const radius = 10000 // metersinsideCircle({lat: 51.03, lon: 4.05}, center, radius) // trueinsideCircle({lat: 51.3, lon: 4.5}, center, radius) // false
Calculate the closest point of approach (CPA) for two moving objects, for example two ships or cars.
Both tracks contain a location, speed in meters per second, and heading in degrees.
The returned result contains the time and distance of the moment when the two moving objects are closest.
The time in seconds and distance in meters.
// the following two ships are near each other and closing inconst ship1 = { location: {lon: 4.61039, lat: 51.70401}, speed: 5, // meters/second heading: 200 // degrees}const ship2 = { location: {lon: 4.60109, lat: 51.69613}, speed: 0.8334, // meters/second heading: 180 // degrees}// lets see how close these ships will get and when they are closestconst { time, distance } = cpa(ship1, ship2)// time = 251.22255125913932 seconds// distance = 231.90976012822378 meters
Normalization
normalizeHeading(heading: number) : number
Normalize a heading in degrees into the range [0, 360) (lower bound included, upper bound excluded).
Normalize a latitude into the range [-90, 90] (upper and lower bound included). For example a latitude of 91 is normalized into 89 (crossed the pool one degree).
Normalize the longitude and latitude of a location.
Latitude will be in the range [-90, 90] (upper and lower bound included).
Lontitude will be in the range (-180, 180] (lower bound excluded, upper bound included).
normalizeLocation([360, 95]) // [ 0, 85 ] degrees
Units
degToRad(angle: number) : number
Convert an angle in degrees into an angle in radians.
degToRad(45) // 0.7853981633974483 radians
radToDeg(angle: number) : number
Convert an angle in radians into an angle in degrees.
radToDeg(Math.PI / 4) // 45 degrees
knotsToMeterPerSecond(knots: number) : number
Convert a speed in knots into a speed in meter per second.
1 knot is 0.514444 m/s.
knotsToMeterPerSecond(10) // 5.14444 m/s
meterPerSecondToKnots(meterPerSecond: number) : number
Convert a speed in meter per second into a speed in knots.
1 knot is 0.514444 m/s.
Yeah, it has bitten you probably too. What is the correct order of a geolocation tuple? Is it [lat, lon] or [lon, lat]? Turns out... there is no right way. There is an ISO standard (ISO 6709), but only half of the big geolocation software libraries adhere to this standard whilst others do the opposite. It's painful and embarrassing having to scratch your head over this out again and again. Like Shane puts it in an answer on StackOverflow:
This situation has wreaked unimaginable havoc on project deadlines and programmer sanity.
A nice overview is written down by Tom Macwright in the blog lon lat lon lat. Here a copy (with some additions):
Category
[lon, lat]
[lat, lon]
formats
GeoJSON, KML, Shapefile, WKT, WKB, geobuf
GeoRSS, Encoded Polylines (Google)
javascript apis
OpenLayers, d3, ArcGIS API for JavaScript, Mapbox GL JS
Leaflet, Google Maps API
mobile apis
Tangram ES
Google Maps iOS/Android, Apple MapKit
misc
OSRM, MongoDB, Redis
The geolocation-utils library supports the [lon, lat] format.
To prevent issues in this regard, it is safest to use an object instead of an array. There are various options:
{latitude: 51.9280573, longitude: 4.4203587} // HTML5 geolocation API{lat: 51.9280573, lon: 4.4203587}{lat: 51.9280573, lng: 4.4203587} // Leaflet, MongoDB, and Google Maps
TODO: write out which object stucture are supported by which libraries exactly
Build
To generate ES5 code in the lib folder, run:
npm run build
TODO: create a bundle for browser usage
Test
To test the library (using Ava), run:
npm test
To automatically re-test on change of source code, run:
npm test -- --watch
Publish
Update version number in package.json
Describe version number, date, and changes in CHANGELOG.md
Commit the changes, and create a tag with version number
git add ...git commit -m "Released version 1.2.3"git push origin mastergit tag v1.2.3git push --tags
Publish the library
npm publish
Before publishing, the library will be built and the unit tests will run.