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.

API

#### 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

$3

(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)

$3

(type)

Standardized lon/lat object.

Type: Object

#### Properties

* lat number
* lon number

$3

(type)

Object with x/y number values.

Type: Object

#### Properties

* x number
* y number

$3

(exception type)

An error that is thrown upon providing invalid coordinates.

Type: Error

$3

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 longitude
and a y 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

#### print

##### 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 to
the number of decimal places as specified by fixed

#### 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_LAT
* Throws Error If zoom 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

$3

Pixel conversions and constants taken from


$3

Pixels per tile.

$3

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

$3

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

$3

Maximum Latitude for valid Mercator projection conversion.

$3

Convert a pixel to it's longitude value given a zoom level.

#### Parameters

* x number
* zoom number

#### Examples

`javascript
var lon = lonlat.pixelToLongitude(40000, 9) //= -70.13671875
`

Returns number longitude

$3

Convert a pixel to it's latitude value given a zoom level.

#### Parameters

* y number
* zoom number

#### Examples

`javascript
var lat = lonlat.pixelToLatitude(50000, 9) //= 39.1982053488948
``

Returns number latitude