@conveyal/lonlat
v1.4.1
Published
Lon/lat normalization
Downloads
2,516
Readme
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
- lonlat.types.point
- lonlat.types.InvalidCoordinateException
- conveyal/lonlat
- PIXELS_PER_TILE
- PIXELS_PER_TILE
- longitudeToPixel
- latitudeToPixel
- MAX_LAT
- pixelToLongitude
- pixelToLatitude
lonlat.types.input
(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
andy
properties.x
represents longitude andy
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
orlongitude
For latitude any of the following are valid:lat
orlatitude
Type: (Array | string | Object)
lonlat.types.output
(type)
Standardized lon/lat object.
Type: Object
Properties
lonlat.types.point
(type)
Object with x/y number values.
Type: Object
Properties
lonlat.types.InvalidCoordinateException
(exception type)
An error that is thrown upon providing invalid coordinates.
Type: Error
conveyal/lonlat
Parse an unknown type of input.
Parameters
unknown
lonlat.types.input
Examples
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
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
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromCoordinates([12, 34]) // { lon: 12, lat: 34 }
position = lonlat.fromGeoJSON([12, 34]) // { lon: 12, lat: 34 }
Returns lonlat.types.output
fromLatlng
aliases: fromLeaflet
Tries to parse from an object.
Parameters
lonlat
Object An object with alon
,lng
orlongitude
attribute and alat
orlatitude
attribute
Examples
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 }
Returns lonlat.types.output
fromPoint
Tries to parse from an object.
Parameters
point
Object An object with ax
attribute representinglongitude
and ay
attribute representinglatitude
Examples
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromPoint({ x: 12, y: 34 }) // { lon: 12, lat: 34 }
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
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 }
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
var lonlat = require('@conveyal/lonlat')
var position = lonlat.fromLatFirstString('12,34') // { lon: 34, lat: 12 }
Returns lonlat.types.output
isEqual
Determine if two inputs are equal to each other
Parameters
lonlat1
lonlat.types.inputlonlat2
lonlat.types.inputepsilon
number The maximum acceptable deviation to be considered equal. (optional, default0
)
Examples
var lonlat = require('@conveyal/lonlat')
var isEqual = lonlat.isEqual('12,34', [12, 34]) // true
Returns boolean
Parameters
input
lonlat.types.inputfixed
number The number of decimal places to round to. (optional, default5
)
Examples
var lonlat = require('@conveyal/lonlat')
var pretty = lonlat.print('12.345678,34') // '12.34568, 34.00000'
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
var lonlat = require('@conveyal/lonlat')
var coords = lonlat.toCoordinates('12,34') // [12, 34]
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
var lonlat = require('@conveyal/lonlat')
var position = lonlat.toLeaflet({ lat: 12, long: 34 }) // Leaflet LatLng object
Returns Object A Leaflet LatLng object
toPoint
Translates to point Object.
Parameters
input
lonlat.types.input
Examples
var lonlat = require('@conveyal/lonlat')
var point = lonlat.toPoint('12,34') // { x: 12, y: 34 }
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
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'
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
var lonlat = require('@conveyal/lonlat')
var str = lonlat.toLatFirstString({ lat: 12, longitude: 34 }) // '12,34'
Returns string A string in the format 'longitude,latitude'
toPixel
Convert a coordinate to a pixel.
Parameters
input
lonlat.types.inputzoom
number
Examples
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.pointzoom
Number
Examples
var ll = lonlat.fromPixel({x: 40000, y: 50000}, 9) //= {lon: -70.13671875, lat: 39.1982053488948}
Returns lonlat.types.output
PIXELS_PER_TILE
Pixel conversions and constants taken from https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Implementations
PIXELS_PER_TILE
Pixels per tile.
longitudeToPixel
Convert a longitude to it's pixel value given a zoom
level.
Parameters
Examples
var xPixel = lonlat.longitudeToPixel(-70, 9) //= 40049.77777777778
Returns number pixel
latitudeToPixel
Convert a latitude to it's pixel value given a zoom
level.
Parameters
Examples
var yPixel = lonlat.latitudeToPixel(40, 9) //= 49621.12736343896
Returns number pixel
MAX_LAT
Maximum Latitude for valid Mercator projection conversion.
pixelToLongitude
Convert a pixel to it's longitude value given a zoom level.
Parameters
Examples
var lon = lonlat.pixelToLongitude(40000, 9) //= -70.13671875
Returns number longitude
pixelToLatitude
Convert a pixel to it's latitude value given a zoom level.
Parameters
Examples
var lat = lonlat.pixelToLatitude(50000, 9) //= 39.1982053488948
Returns number latitude