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

Works well using tilebelt.

Install

$ npm install --save global-mercator

Quickstart

import * as mercator from 'global-mercator'

const tile = [10, 15, 8] // x, y, zoom

console.log(mercator.tileToBBox(tile))
console.log(mercator.tileToGoogle(tile))

Tests

$ npm test

Documentation

$ npm run docs

Features

Function	Description
lngLatToMeters(lnglat)	Converts LngLat coordinates to Meters coordinates.
metersToLngLat(meters)	Converts Meters coordinates to LngLat coordinates.
metersToPixels(meters)	Converts Meters coordinates to Pixels coordinates.
lngLatToTile(lnglat)	Converts LngLat coordinates to TMS Tile.
lngLatToGoogle(lnglat)	Converts LngLat coordinates to Google (XYZ) Tile.
metersToTile(meters)	Converts Meters coordinates to TMS Tile.
pixelsToMeters(pixels)	Converts Pixels coordinates to Meters coordinates.
pixelsToTile(pixels)	Converts Pixels coordinates to TMS Tile.
tileToBBoxMeters(tile)	Converts TMS Tile to bbox in Meters coordinates.
tileToBBox(tile)	Converts TMS Tile to bbox in LngLat coordinates.
googleToBBoxMeters(google)	Converts Google (XYZ) Tile to bbox in Meters coordinates.
googleToBBox(google)	Converts Google (XYZ) Tile to bbox in LngLat coordinates.
tileToGoogle(tile)	Converts TMS Tile to Google (XYZ) Tile.
googleToTile(google)	Converts Google (XYZ) Tile to TMS Tile.
googleToQuadkey(google)	Converts Google (XYZ) Tile to Quadkey.
tileToQuadkey(tile)	Converts TMS Tile to QuadKey.
quadkeyToTile(quadkey)	Converts Quadkey to TMS Tile.
quadkeyToGoogle(quadkey)	Converts Quadkey to Google (XYZ) Tile.
bboxToMeters(bbox)	Converts BBox from LngLat coordinates to Meters coordinates

lngLatToMeters

Converts LngLat coordinates to Meters coordinates.

Parameters

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

Examples

const meters = lngLatToMeters([37, 126, 13])
//=meters

Returns Meters Meters coordinates

metersToLngLat

Converts Meters coordinates to LngLat coordinates.

Parameters

• meters Meters Meters [x, y, zoom]
• x number Longitudes (Meridians) in meters
• y number Latitudes (Parallels) in decimal degrees
• zoom number Zoom level

Examples

const lnglat = metersToLngLat([14026255, 4439106, 13])
//=lnglat

Returns LngLat LngLat coordinates

metersToPixels

Converts Meters coordinates to Pixels coordinates.

Parameters

• meters Meters Meters [x, y, zoom]
• x number Longitudes (Meridians) in meters
• y number Latitudes (Parallels) in decimal degrees
• zoom number Zoom level

Examples

const pixels = metersToPixels([14026255, 4439106, 13])
//=pixels

Returns Pixels Pixels coordinates

lngLatToTile

Converts LngLat coordinates to TMS Tile.

Parameters

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

Examples

const tile = lngLatToTile([37, 126, 13])
//=tile

Returns Tile TMS Tile

lngLatToGoogle

Converts LngLat coordinates to Google (XYZ) Tile.

Parameters

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

Examples

const google = lngLatToGoogle([37, 126, 13])
//=google

Returns Google Google (XYZ) Tile

metersToTile

Converts Meters coordinates to TMS Tile.

Parameters

• meters Meters Meters [x, y, zoom]
• x number Longitudes (Meridians) in meters
• y number Latitudes (Parallels) in decimal degrees
• zoom number Zoom level

Examples

const tile = metersToTile([14026255, 4439106, 13])
//=tile

Returns Tile TMS Tile

pixelsToMeters

Converts Pixels coordinates to Meters coordinates.

Parameters

• pixels Pixels Pixels [x, y, zoom]
• x number Pixels X
• y number Pixels Y
• zoom number Zoom level

Examples

const meters = pixelsToMeters([1782579, 1280877, 13])
//=meters

Returns Meters Meters coordinates

pixelsToTile

Converts Pixels coordinates to TMS Tile.

Parameters

• pixels Pixels Pixels [x, y, zoom]
• px number Pixels X
• py number Pixels Y
• zoom number Zoom level

Examples

const tile = pixelsToTile([1782579, 1280877, 13])
//=tile

Returns Tile TMS Tile

tileToBBoxMeters

Converts TMS Tile to bbox in Meters coordinates.

Parameters

• tile Tile Tile [x, y, zoom]
• x number TMS Tile X
• y number TMS Tile Y
• zoom number Zoom level

Examples

const bbox = tileToBBoxMeters([6963, 5003, 13])
//=bbox

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

tileToBBox

Converts TMS Tile to bbox in LngLat coordinates.

Parameters

• tile Tile Tile [x, y, zoom]
• x number TMS Tile X
• y number TMS Tile Y
• zoom number Zoom level

Examples

const bbox = tileToBBox([6963, 5003, 13])
//=bbox

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

googleToBBoxMeters

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

Parameters

• google Google Google [x, y, zoom]
• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

const bbox = googleToBBoxMeters([6963, 3188, 13])
//=bbox

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

googleToBBox

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

Parameters

• google Google Google [x, y, zoom]
• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

const bbox = googleToBBox([6963, 3188, 13])
//=bbox

Returns BBox bbox extent in [minX, minY, maxX, maxY] order

tileToGoogle

Converts TMS Tile to Google (XYZ) Tile.

Parameters

• tile Tile Tile [x, y, zoom]
• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Examples

const google = tileToGoogle([6963, 5003, 13])
//=google

Returns Google Google (XYZ) Tile

googleToTile

Converts Google (XYZ) Tile to TMS Tile.

Parameters

• google Google Google [x, y, zoom]
• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

const tile = googleToTile([6963, 3188, 13])
//=tile

Returns Tile TMS Tile

googleToQuadkey

Converts Google (XYZ) Tile to Quadkey.

Parameters

• google Google Google [x, y, zoom]
• x number Google (XYZ) Tile X
• y number Google (XYZ) Tile Y
• zoom number Zoom level

Examples

const quadkey = googleToQuadkey([6963, 3188, 13])
//=quadkey

Returns string Microsoft's Quadkey schema

tileToQuadkey

Converts TMS Tile to QuadKey.

Parameters

• tile Tile Tile [x, y, zoom]
• tx number TMS Tile X
• ty number TMS Tile Y
• zoom number Zoom level

Examples

const quadkey = tileToQuadkey([6963, 5003, 13])
//=quadkey

Returns string Microsoft's Quadkey schema

quadkeyToTile

Converts Quadkey to TMS Tile.

Parameters

• quadkey string Microsoft's Quadkey schema

Examples

const tile = quadkeyToTile('1321102330211')
//=tile

Returns Tile TMS Tile

quadkeyToGoogle

Converts Quadkey to Google (XYZ) Tile.

Parameters

• quadkey string Microsoft's Quadkey schema

Examples

const google = quadkeyToGoogle('1321102330211')
//=google

Returns Google Google (XYZ) Tile

bboxToMeters

Converts BBox from LngLat coordinates to Meters coordinates

Parameters

• bbox BBox extent in [minX, minY, maxX, maxY] order

Examples

const meters = bboxToMeters([ 125, 35, 127, 37 ])
//=meters

Returns BBox 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

• tile Tile Tile [x, y, zoom]
• x number TMS Tile X
• y number TMS Tile Y
• zoom number Zoom level

Examples

validateTile([60, 80, 5])
validateTile([60, -43, 5])
//= Error: Tile <y> must not be less than 0

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

Returns Tile TMS Tile

validateZoom

Validates Zoom level.

Parameters

• zoom number Zoom level

Examples

validateZoom(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 Pixels Pixels [x, y, zoom]
• x number Pixels X
• y number Pixels Y
• zoom [number] Zoom level

Examples

validatePixels([-115, 44])

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

Returns Pixels Pixels coordinates

validateMeters

Validates Meters coordinates.

Parameters

• meters Meters Meters [x, y, zoom]
• x number Longitudes (Meridians) in meters
• y number Latitudes (Parallels) in decimal degrees
• zoom [number] Zoom level

Examples

validateMeters([-115, 44])
validateMeters([-230, 999000000])
//= Error: Meters [y] cannot be greater than 20037508.342789244

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

Returns Meters Meters coordinates

validateLngLat

Validates LngLat coordinates.

Parameters

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

Examples

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

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

Returns LngLat LngLat coordinates

range

Generate an integer Array containing an arithmetic progression. A port of the native Python range() function. See the Python documentation.

Parameters

• start [number] Start (optional, default 0)
• stop number Stop
• step [number] Step (optional, default 1)

Examples

range(20)
range(10, 20)
range(20, 10, -1)

Returns Array<number> range