Lon/lat normalization
npm install @conveyal/lonlat[![NPM version][npm-image]][npm-url]
[![Build status][travis-image]][travis-url]
[npm-image]: https://img.shields.io/npm/v/@conveyal/lonlat.svg?maxAge=2592000&style=flat-square
[npm-url]: https://www.npmjs.com/package/@conveyal/lonlat
[travis-image]: https://img.shields.io/travis/conveyal/lonlat.svg?style=flat-square
[travis-url]: https://travis-ci.org/conveyal/lonlat
Lon/lat normalization cause...sigh.
No one has agreed on a standard way of representing lon/lat. This is a small normalization library. Use this to convert all outside input before processing internally and convert to an external format right when it's being output.
#### Table of Contents
* lonlat.types.input
* lonlat.types.output
* Properties
* lonlat.types.point
* Properties
* lonlat.types.InvalidCoordinateException
* conveyal/lonlat
* Parameters
* Examples
* fromCoordinates
* Parameters
* Examples
* fromLatlng
* Parameters
* Examples
* fromPoint
* Parameters
* Examples
* fromString
* Parameters
* Examples
* fromLatFirstString
* Parameters
* Examples
* isEqual
* Parameters
* Examples
* print
* Parameters
* Examples
* toCoordinates
* Parameters
* Examples
* toLeaflet
* Parameters
* Examples
* toPoint
* Parameters
* Examples
* toString
* Parameters
* Examples
* toLatFirstString
* Parameters
* Examples
* toPixel
* Parameters
* Examples
* fromPixel
* Parameters
* Examples
* PIXELS_PER_TILE
* PIXELS_PER_TILE
* longitudeToPixel
* Parameters
* Examples
* latitudeToPixel
* Parameters
* Examples
* MAX_LAT
* pixelToLongitude
* Parameters
* Examples
* pixelToLatitude
* Parameters
* Examples
(type)
An unknown type of input. Must be one of the following:
* array: An array with 2 elements. The first is longitude, the second is latitude.
* string: A string in the format longitude,latitude
* Object (x, y coordinates): An object with x and y properties.
x represents longitude and y represents latitude.
* Object (lat, lon): An object with latitude and longitude properties.
The properties can be named various things.
For longitude any of the following are valid: lon, lng or longitude
For latitude any of the following are valid: lat or latitude
Type: (Array | string | Object)
(type)
Standardized lon/lat object.
Type: Object
#### Properties
(type)
Object with x/y number values.
Type: Object
#### Properties
(exception type)
An error that is thrown upon providing invalid coordinates.
Type: Error
Parse an unknown type of input.
#### Parameters
* unknown lonlat.types.input
#### Examples
``javascript
var lonlat = require('@conveyal/lonlat')
// Object with lon/lat-ish attributes
var position = lonlat({ lon: 12, lat: 34 }) // { lon: 12, lat: 34 }
position = lonlat({ lng: 12, lat: 34 }) // { lon: 12, lat: 34 }
position = lonlat({ longitude: 12, latitude: 34 }) // { lon: 12, lat: 34 }
position = lonlat({ lng: 12, latitude: 34 }) // { lon: 12, lat: 34 }
// coordinate array
position = lonlat([12, 34]) // { lon: 12, lat: 34 }
// string
position = lonlat('12,34') // { lon: 12, lat: 34 }
// object with x and y attributes
position = lonlat({ x: 12, y: 34 }) // { lon: 12, lat: 34 }
// the following will throw errors
position = lonlat({ lon: 999, lat: 34 }) // Error: Invalid longitude value: 999
position = lonlat({ lon: 12, lat: 999 }) // Error: Invalid latitude value: 999
position = lonlat({}) // Error: Invalid latitude value: undefined
position = lonlat(null) // Error: Value must not be null or undefined
`
* Throws lonlat.types.InvalidCoordinateException
Returns lonlat.types.output
#### fromCoordinates
aliases: fromGeoJSON
Tries to parse from an array of coordinates.
##### Parameters
* coordinates Array An array in the format: \[longitude, latitude]
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromCoordinates([12, 34]) // { lon: 12, lat: 34 }
position = lonlat.fromGeoJSON([12, 34]) // { lon: 12, lat: 34 }
`
* Throws lonlat.types.InvalidCoordinateException
Returns lonlat.types.output
#### fromLatlng
aliases: fromLeaflet
Tries to parse from an object.
##### Parameters
* lonlat Object An object with a lon, lng or longitude attribute and a lat or latitude attribute
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromLatlng({ longitude: 12, latitude: 34 }) // { lon: 12, lat: 34 }
position = lonlat.fromLeaflet({ lng: 12, lat: 34 }) // { lon: 12, lat: 34 }
`
* Throws lonlat.types.InvalidCoordinateException
Returns lonlat.types.output
#### fromPoint
Tries to parse from an object.
##### Parameters
* point Object An object with a x attribute representing longitudey
and a attribute representing latitude
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromPoint({ x: 12, y: 34 }) // { lon: 12, lat: 34 }
`
* Throws lonlat.types.InvalidCoordinateException
Returns lonlat.types.output
#### fromString
aliases: fromLonFirstString
Tries to parse from a string where the longitude appears before the latitude.
##### Parameters
* str string A string in the format: longitude,latitude
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromString('12,34') // { lon: 12, lat: 34 }
var position = lonlat.fromLonFirstString('12,34') // { lon: 12, lat: 34 }
`
* Throws lonlat.types.InvalidCoordinateException
Returns lonlat.types.output
#### fromLatFirstString
Tries to parse from a string where the latitude appears before the longitude.
##### Parameters
* str string A string in the format: latitude,longitude
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromLatFirstString('12,34') // { lon: 34, lat: 12 }
`
* Throws lonlat.types.InvalidCoordinateException
Returns lonlat.types.output
#### isEqual
Determine if two inputs are equal to each other
##### Parameters
* lonlat1 lonlat.types.input lonlat2
* lonlat.types.input epsilon
* number The maximum acceptable deviation to be considered equal. (optional, default 0)
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var isEqual = lonlat.isEqual('12,34', [12, 34]) // true
`
* Throws lonlat.types.InvalidCoordinateException
Returns boolean
##### Parameters
* input lonlat.types.input fixed
* number The number of decimal places to round to. (optional, default 5)
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var pretty = lonlat.print('12.345678,34') // '12.34568, 34.00000'
`
* Throws lonlat.types.InvalidCoordinateException
Returns string A string with in the format longitude,latitude rounded tofixed
the number of decimal places as specified by
#### toCoordinates
aliases: toGeoJSON
Translates to a coordinate array.
##### Parameters
* input lonlat.types.input
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var coords = lonlat.toCoordinates('12,34') // [12, 34]
`
* Throws lonlat.types.InvalidCoordinateException
Returns Array An array in the format \[longitude, latitude]
#### toLeaflet
Translates to Leaflet LatLng object.
This function requires Leaflet to be installed as a global variable L in the window environment.
##### Parameters
* input lonlat.types.input
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var position = lonlat.toLeaflet({ lat: 12, long: 34 }) // Leaflet LatLng object
`
* Throws lonlat.types.InvalidCoordinateException
Returns Object A Leaflet LatLng object
#### toPoint
Translates to point Object.
##### Parameters
* input lonlat.types.input
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var point = lonlat.toPoint('12,34') // { x: 12, y: 34 }
`
* Throws lonlat.types.InvalidCoordinateException
Returns Object An object with x and y attributes representing latitude and longitude respectively
#### toString
aliases: toLonFirstString
Translates to coordinate string where the longitude appears before latitude.
##### Parameters
* input lonlat.types.input
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var str = lonlat.toString({ lat: 12, longitude: 34 }) // '34,12'
var str = lonlat.toLonFirstString({ lat: 12, longitude: 34 }) // '34,12'
`
* Throws lonlat.types.InvalidCoordinateException
Returns string A string in the format 'longitude,latitude'
#### toLatFirstString
Translates to coordinate string where the latitude appears before longitude.
##### Parameters
* input lonlat.types.input
##### Examples
`javascript
var lonlat = require('@conveyal/lonlat')
var str = lonlat.toLatFirstString({ lat: 12, longitude: 34 }) // '12,34'
`
* Throws lonlat.types.InvalidCoordinateException
Returns string A string in the format 'longitude,latitude'
#### toPixel
Convert a coordinate to a pixel.
##### Parameters
* input lonlat.types.input zoom
* number
##### Examples
`javascript`
var pixel = lonlat.toPixel({lon: -70, lat: 40}, 9) //= {x: 40049.77777777778, y:49621.12736343896}
* Throws lonlat.types.InvalidCoordinateException
* Throws Error If latitude is above or below MAX_LATzoom
* Throws Error If is undefined.
Returns Object An object with x and y attributes representing pixel coordinates
#### fromPixel
From pixel.
##### Parameters
* pixel lonlat.types.point zoom
* Number
##### Examples
`javascript`
var ll = lonlat.fromPixel({x: 40000, y: 50000}, 9) //= {lon: -70.13671875, lat: 39.1982053488948}
Returns lonlat.types.output
Pixel conversions and constants taken from
Pixels per tile.
Convert a longitude to it's pixel value given a zoom level.
#### Parameters
* longitude number zoom
* number
#### Examples
`javascript`
var xPixel = lonlat.longitudeToPixel(-70, 9) //= 40049.77777777778
Returns number pixel
Convert a latitude to it's pixel value given a zoom level.
#### Parameters
* latitude number zoom
* number
#### Examples
`javascript`
var yPixel = lonlat.latitudeToPixel(40, 9) //= 49621.12736343896
Returns number pixel
Maximum Latitude for valid Mercator projection conversion.
Convert a pixel to it's longitude value given a zoom level.
#### Parameters
#### Examples
`javascript`
var lon = lonlat.pixelToLongitude(40000, 9) //= -70.13671875
Returns number longitude
Convert a pixel to it's latitude value given a zoom level.
#### Parameters
#### Examples
`javascript``
var lat = lonlat.pixelToLatitude(50000, 9) //= 39.1982053488948
Returns number latitude