global-mercator

Global Mercator

A set of tools geospatial tools to help with TMS, Google (XYZ) Tiles.

This library is insipered by GDAL2Tiles, Google Summer of Code 2007 & 2008

Installation

Using npm:

$ npm install --save global-mercator

In Node.js:

import * as mercator from 'global-mercator'

import { latLngToMeters } from 'global-mercator'

latLngToMeters

Converts LatLng coordinates to Meters coordinates.

Parameters

• lat number Latitude (Parallels) in decimal degrees
• lng number Longitude (Meridians) in decimal degrees
• zoom [number] Zoom level

Examples

latLngToMeters({lat: 37, lng: 126})
//= Meters { mx: 14026255.83995247, my: 4439106.787250587 }

Returns Object Meters coordinates

metersToLatLng

Converts Meters coordinates to LatLng coordinates.

Parameters

• mx number Longitudes (Meridians) in meters
• my number Latitudes (Parallels) in decimal degrees
• zoom [number] Zoom level

Examples

metersToLatLng({ mx: 14026255, my: 4439106 })
//= LatLng { lat: 36.99999435205559, lng: 125.99999245457859 }

Returns Object LatLng coordinates

metersToPixels

Converts Meters coordinates to Pixels coordinates.

Parameters

• mx number Longitudes (Meridians) in meters
• my number Latitudes (Parallels) in decimal degrees
• zoom number Zoom level

Examples

metersToPixels({ mx: 14026255, my: 4439106, zoom: 13 })
//= Pixels { px: 1782579.1560447346, py: 1280877.3387406059, zoom: 13 }

Returns Object Pixels coordinates

latLngToTile

Converts LatLng coordinates to TMS Tile.

Parameters

• lat number Latitude (Parallels) in decimal degrees
• lng number Longitude (Meridians) in decimal degrees
• zoom number Zoom level

Examples

latLngToTile({lat: 37, lng: 126, zoom: 13 })
//= Tile { tx: 6963, ty: 5003, zoom: 13 }

Returns Object TMS Tile

latLngToGoogle

Converts LatLng coordinates to Google (XYZ) Tile.

Parameters

• lat number Latitude (Parallels) in decimal degrees
• lng number Longitude (Meridians) in decimal degrees
• zoom number Zoom level

Examples

latLngToGoogle({lat: 37, lng: 126, zoom: 13 })
//= Google { x: 6963, y: 3188, zoom: 13 }

Returns Object Google (XYZ) Tile

metersToTile

Converts Meters coordinates to TMS Tile.

Parameters

• mx number Longitudes (Meridians) in meters
• my number Latitudes (Parallels) in decimal degrees
• zoom number Zoom level

Examples

metersToTile({ mx: 14026255, my: 4439106, zoom: 13 })
//= Tile { tx: 6963, ty: 5003, zoom: 13 }

Returns Object TMS Tile

pixelsToMeters

Converts Pixels coordinates to Meters coordinates.

Parameters

• px number Pixels X
• py number Pixels Y
• zoom number Zoom level

Examples

pixelsToMeters({ px: 1782579, py: 1280877, zoom: 13 })
//= Meters { mx: 14026252.018101055, my: 4439099.526918683, zoom: 13 }

Returns Object Meters coordinates

pixelsToTile

Converts Pixels coordinates to TMS Tile.

Parameters

• px number Pixels X
• py number Pixels Y
• zoom number Zoom level

Examples

pixelsToTile({ px: 1782579, py: 1280877, zoom: 13 })
//= Tile { tx: 6963, ty: 5003, zoom: 13 }

Returns Object TMS Tile

tileBbox

Converts TMS Tile to bbox in Meters coordinates.

Parameters

• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Examples

tileBbox({ tx: 6963, ty: 5003, zoom: 13 })
//= [ 14025277.445990417, 4437016.617897913, 14030169.415800672, 4441908.587708164 ]

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

tileLatLngBbox

Converts TMS Tile to bbox in LatLng coordinates.

Parameters

• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Examples

tileLatLngBbox({ tx: 6963, ty: 5003, zoom: 13 })
//= [ 125.99121093749999, 36.98500309285596, 126.03515625, 37.020098201368135 ]

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

googleBbox

Converts Google (XYZ) Tile to bbox in Meters coordinates.

Parameters

• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

googleBbox({ x: 6963, y: 3188, zoom: 13 })
//= [ 14025277.445990417, 4437016.617897913, 14030169.415800672, 4441908.587708164 ]

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

googleLatLngBbox

Converts Google (XYZ) Tile to bbox in LatLng coordinates.

Parameters

• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

googleLatLngBbox({ x: 6963, y: 3188, zoom: 13 })
//= [ 125.99121093749999, 36.98500309285596, 126.03515625, 37.020098201368135 ]

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

tileGoogle

Converts TMS Tile to Google (XYZ) Tile.

Parameters

• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Examples

tileGoogle({ tx: 6963, ty: 5003, zoom: 13 })
//= Google { x: 6963, y: 3188, zoom: 13 }

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

googleTile

Converts Google (XYZ) Tile to TMS Tile.

Parameters

• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

googleTile({ x: 6963, y: 3188, zoom: 13 })
//= Tile { tx: 6963, ty: 5003, zoom: 13 }

Returns Object TMS Tile

googleQuadkey

Converts Google (XYZ) Tile to Quadkey.

Parameters

• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

googleQuadkey({ x: 6963, y: 3188, zoom: 13 })
//= '1321102330211'

Returns string Microsoft's Quadkey schema

tileQuadkey

Converts TMS Tile to QuadKey.

Parameters

• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Examples

tileQuadkey({ tx: 6963, ty: 5003, zoom: 13 })
//= '1321102330211'

Returns string Microsoft's Quadkey schema

quadkeyTile

Converts Quadkey to TMS Tile.

Parameters

• quadkey string Microsoft's Quadkey schema

Examples

quadkeyTile('1321102330211')
//= Tile { tx: 6963, ty: 5003, zoom: 13 }

Returns Object TMS Tile

quadkeyGoogle

Converts Quadkey to Google (XYZ) Tile.

Parameters

• quadkey string Microsoft's Quadkey schema

Examples

quadkeyGoogle('1321102330211')
//= Google { x: 6963, y: 3188, zoom: 13 }

Returns Object Google (XYZ) Tile

bboxLatLngToMeters

Converts bbox from LatLng coordinates to Meters coordinates

Parameters

• bbox Array<number> extent in [minX, minY, maxX, maxY] order

Examples

bboxLatLngToMeters([ 125, 35, 127, 37 ])
//= [ 13914936.349159198, 4163881.1440642904, 14137575.330745745, 4439106.787250587 ]

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

resolution

Retrieve resolution based on zoom level

Parameters

• zoom number zoom level

Examples

const res = resolution(13)
//=res

Returns number resolution

validateTile

Validates TMS Tile.

Parameters

• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level
• name [string] name used for debugging message (optional, default Tile)

Examples

validateTile({tx: 60, ty: 80, zoom: 5})
//= {tx: 60, ty: 80, zoom: 5}
validateTile({tx: 60, ty: -43, zoom: 5})
//= Error: Tile <ty> must not be less than 0

• Throws Error Will throw an error if TMS Tile is not valid.

Returns Object TMS Tile

validateZoom

Validates Zoom level.

Parameters

• zoom number Zoom level

Examples

validateZoom(12)
//= 12
validateZoom(-4)
//= Error: <zoom> cannot be less than 0
validateZoom(32)
//= Error: <zoom> cannot be greater than 30

• Throws Error Will throw an error if zoom is not valid.

Returns number zoom Zoom level

validatePixels

Validates Pixels coordinates.

Parameters

• Pixels Array<number> coordinates

Examples

validatePixels([-115, 44])
//= [-115, 44]

• Throws Error Will throw an error if Pixels is not valid.

Returns Array<number> Pixels coordinates

validateMeters

Validates Meters coordinates.

Parameters

• Meters Array<number> coordinates

Examples

validateMeters([-115, 44])
//= [-115, 44]

• Throws Error Will throw an error if Meters is not valid.

Returns Array<number> Meters coordinates

validateLatLng

Validates LatLng coordinates.

Parameters

• LatLng Array<number> coordinates

Examples

validateLatLng([60, -125])
//= [60, -125]
validateLatLng([140, -125])
//= Error: LatLng [lat] must be within -90 to 90 degrees

• Throws Error Will throw an error if LatLng is not valid.

Returns Array<number> LatLng coordinates

validateLngLat

Validates LngLat coordinates.

Parameters

• LngLat Array<number> coordinates

Examples

validateLngLat([-115, 44])
//= [-115, 44]
validateLngLat([-225, 44])
//= Error: LatLng [lng] must be within -180 to 180 degrees

• Throws Error Will throw an error if LngLat is not valid.

Returns Array<number> LngLat coordinates

validateBbox

Validates bbox.

Parameters

• bbox Array<number> extent in [minX, minY, maxX, maxY] order

Examples

validateBbox([ -75, 44, -74, 45 ])
//= [ -75, 44, -74, 45 ]
validateBbox([ -75, 44, -74 ])
//= Error: [bbox] must be an Array of 4 numbers

• Throws Error Will throw an error if bbox is not valid.

Returns Array<number> bbox extent in [minX, minY, maxX, maxY] order

assertUndefined

Assert undefined items within object.

Parameters

• items Object
• name [string] name used for debugging message

Examples

assertUndefined({foo: 'bar'})
//= {foo: 'bar'}
assertUndefined({foo: undefined})
//= Error: <foo> is required

• Throws Error Will throw an error if any item in Object is undefined.

Returns Object items

Google

Google (XYZ) Tile

Properties

• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Tile

TMS Tile

Properties

• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Pixels

Pixels coordinates

Properties

• px number Pixels X
• py number Pixels Y
• zoom number Zoom level

Meters

Meters coordinates

Properties

• mx number Longitudes (Meridians) in meters
• my number Latitudes (Parallels) in decimal degrees
• zoom number Zoom level

LatLng

LatLng coordinates

Properties

• lat number Latitude (Parallels) in decimal degrees
• lng number Longitude (Meridians) in decimal degrees
• zoom number Zoom level