Miss any of our Open RFC calls?Watch the recordings here! »

@conveyal/lonlat

1.4.0 • Public • Published

lonlat

NPM version Build status

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

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

lonlat.types.output

(type)

Standardized lon/lat object.

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

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 a lon, lng or longitude attribute and a lat or latitude 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 a x attribute representing longitude and a y attribute representing latitude
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
Examples
var lonlat = require('@conveyal/lonlat')
 
var isEqual = lonlat.isEqual('12,34', [12, 34])   // true

Returns boolean

print

Parameters
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
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
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
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
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
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
Examples
var pixel = lonlat.toPixel({lon: -70, lat: 40}, 9) //= {x: 40049.77777777778, y:49621.12736343896}

Returns Object An object with x and y attributes representing pixel coordinates

fromPixel

From pixel.

Parameters
Examples
var ll = lonlat.fromPixel({x: 40000, y: 50000}, 9) //= {lon: -70.13671875, lat: 39.1982053488948}

Returns lonlat.types.output

lonlat.types.point

(type)

Object with x/y number values.

Type: Object

Properties

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

Install

npm i @conveyal/lonlat

DownloadsWeekly Downloads

128

Version

1.4.0

License

MIT

Unpacked Size

453 kB

Total Files

8

Last publish

Collaborators

  • avatar
  • avatar
  • avatar
  • avatar
  • avatar