global-mercator v3.1.0
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.
Another great simplistic tile library is tilebelt
.
Install
npm
$ npm install --save global-mercator
web
<script src="https://wzrd.in/standalone/global-mercator@latest"></script>
Quickstart
var globalMercator = require('global-mercator')
var tile = [10, 15, 8] // [x, y, zoom]
globalMercator.tileToBBox(tile)
// [ -165.937, -82.853, -164.531, -82.676 ]
Features
Function | Description |
---|---|
lngLatToMeters(LngLat) | Converts LngLat coordinates to Meters coordinates. |
metersToLngLat(Meters) | Converts Meters coordinates to LngLat coordinates. |
metersToPixels(Meters, zoom) | Converts Meters coordinates to Pixels coordinates. |
lngLatToTile(LngLat, zoom) | Converts LngLat coordinates to TMS Tile. |
lngLatToGoogle(LngLat, zoom) | Converts LngLat coordinates to Google (XYZ) Tile. |
metersToTile(Meters, zoom) | 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. |
hash(tile) | Hash tile for unique id key |
validateTile(tile) | Validates TMS Tile |
validateZoom(zoom) | Validates Zoom level |
validateLngLat(LngLat) | Validates LngLat coordinates |
validatePixels(Pixels) | Validates Pixels coordinates |
maxBBox(BBox[]) | Maximum extent of BBox |
validTile(tile) | Valid Tile |
longitude(degree) | Modifies a Longitude to fit within +/-180 degrees. |
latitude(degree) | Modifies a Latitude to fit within +/-90 degrees. |
pointToTile(lnglat, zoom) | Get the tile for a point at a specified zoom level |
pointToTileFraction(lnglat, zoom) | Get the precise fractional tile location for a point at a zoom level |
wrapTile(tile) | Handles tiles which crosses the 180th meridian |
bboxToTile(bbox) | Get the smallest tile to cover a bbox |
API
Table of Contents
- hash
- pointToTile
- pointToTileFraction
- bboxToCenter
- lngLatToMeters
- metersToLngLat
- metersToPixels
- lngLatToTile
- lngLatToGoogle
- metersToTile
- pixelsToMeters
- pixelsToTile
- tileToBBoxMeters
- tileToBBox
- googleToBBoxMeters
- googleToBBox
- tileToGoogle
- googleToTile
- googleToQuadkey
- tileToQuadkey
- quadkeyToTile
- quadkeyToGoogle
- bboxToMeters
- validateTile
- wrapTile
- validateZoom
- validateLngLat
- maxBBox
- validTile
- latitude
- longitude
- bboxToTile
hash
Hash tile for unique id key
Parameters
tile
Tile x, y, z
Examples
var id = globalMercator.hash([312, 480, 4])
//=5728
Returns number hash
pointToTile
Get the tile for a point at a specified zoom level https://github.com/mapbox/tilebelt
Parameters
lnglat
[number, number] Longitude, Latitudezoom
number Zoom levelvalidate
boolean validates LatLng coordinates (optional, defaulttrue
)
Examples
var tile = globalMercator.pointToTile([1, 1], 12)
//= [ 2059, 2036, 12 ]
Returns Google Google (XYZ) Tile
pointToTileFraction
Get the precise fractional tile location for a point at a zoom level https://github.com/mapbox/tilebelt
Parameters
lnglat
[number, number] Longitude, Latitudezoom
number Zoom levelvalidate
boolean validates LatLng coordinates (optional, defaulttrue
)
Examples
var tile = globalMercator.pointToTileFraction([1, 1], 12)
//= [ 2059.3777777777777, 2036.6216445333432, 12 ]
Returns Google Google (XYZ) Tile
bboxToCenter
Converts BBox to Center
Parameters
bbox
BBox west, south, east, north coordinatesaccurancy
Object { enable: true, decimal: 6} (optional, default{enable:true,decimal:6}
)
Examples
var center = globalMercator.bboxToCenter([90, -45, 85, -50])
//= [ 87.5, -47.5 ]
Returns LngLat center
lngLatToMeters
Converts LngLat coordinates to Meters coordinates.
Parameters
lnglat
[number, number] Longitude, Latitudevalidate
boolean validates LatLng coordinates (optional, defaulttrue
)accurancy
Object { enable: true, decimal: 6} (optional, default{enable:true,decimal:1}
)
Examples
var meters = globalMercator.lngLatToMeters([126, 37])
//=[ 14026255.8, 4439106.7 ]
Returns Meters Meters coordinates
metersToLngLat
Converts Meters coordinates to LngLat coordinates.
Parameters
meters
Meters Meters in Mercator x, yaccurancy
Object { enable: true, decimal: 6} (optional, default{enable:true,decimal:6}
)
Examples
var lnglat = globalMercator.metersToLngLat([14026255, 4439106])
//=[ 126, 37 ]
Returns LngLat LngLat coordinates
metersToPixels
Converts Meters coordinates to Pixels coordinates.
Parameters
meters
Meters Meters in Mercator x, yzoom
number Zoom leveltileSize
number Tile size (optional, default256
)
Examples
var pixels = globalMercator.metersToPixels([14026255, 4439106], 13)
//=[ 1782579.1, 1280877.3, 13 ]
Returns Pixels Pixels coordinates
lngLatToTile
Converts LngLat coordinates to TMS Tile.
Parameters
lnglat
[number, number] Longitude, Latitudezoom
number Zoom levelvalidate
boolean validates LatLng coordinates (optional, defaulttrue
)
Examples
var tile = globalMercator.lngLatToTile([126, 37], 13)
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
lngLatToGoogle
Converts LngLat coordinates to Google (XYZ) Tile.
Parameters
lnglat
[number, number] Longitude, Latitudezoom
number Zoom levelvalidate
boolean validates LatLng coordinates (optional, defaulttrue
)
Examples
var google = globalMercator.lngLatToGoogle([126, 37], 13)
//=[ 6963, 3188, 13 ]
Returns Google Google (XYZ) Tile
metersToTile
Converts Meters coordinates to TMS Tile.
Parameters
Examples
var tile = globalMercator.metersToTile([14026255, 4439106], 13)
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
pixelsToMeters
Converts Pixels coordinates to Meters coordinates.
Parameters
pixels
Pixels Pixels x, y, zoomtileSize
number Tile size (optional, default256
)accurancy
Object { enable: true, decimal: 6} (optional, default{enable:true,decimal:6}
)
Examples
var meters = globalMercator.pixelsToMeters([1782579, 1280877, 13])
//=[ 14026252.0, 4439099.5 ]
Returns Meters Meters coordinates
pixelsToTile
Converts Pixels coordinates to TMS Tile.
Parameters
pixels
Pixels Pixels x, y, zoomtileSize
number Tile size (optional, default256
)validate
boolean validates Pixels coordinates (optional, defaulttrue
)
Examples
var tile = globalMercator.pixelsToTile([1782579, 1280877, 13])
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
tileToBBoxMeters
Converts TMS Tile to bbox in Meters coordinates.
Parameters
tile
Tile Tile x, y, zoomtileSize
number Tile size (optional, default256
)validate
boolean validates Tile (optional, defaulttrue
)x
number TMS Tile Xy
number TMS Tile Yzoom
number Zoom level
Examples
var bbox = globalMercator.tileToBBoxMeters([6963, 5003, 13])
//=[ 14025277.4, 4437016.6, 14030169.4, 4441908.5 ]
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, zoomvalidate
boolean validates Tile (optional, defaulttrue
)x
number TMS Tile Xy
number TMS Tile Yzoom
number Zoom level
Examples
var bbox = globalMercator.tileToBBox([6963, 5003, 13])
//=[ 125.991, 36.985, 126.035, 37.020 ]
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
Examples
var bbox = globalMercator.googleToBBoxMeters([6963, 3188, 13])
//=[ 14025277.4, 4437016.6, 14030169.4, 4441908.5 ]
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
Examples
var bbox = globalMercator.googleToBBox([6963, 3188, 13])
//=[ 125.991, 36.985, 126.035, 37.020 ]
Returns BBox bbox extent in minX, minY, maxX, maxY order
tileToGoogle
Converts TMS Tile to Google (XYZ) Tile.
Parameters
tile
Tile Tile x, y, zoomvalidate
boolean validates Tile (optional, defaulttrue
)
Examples
var google = globalMercator.tileToGoogle([6963, 5003, 13])
//=[ 6963, 3188, 13 ]
Returns Google Google (XYZ) Tile
googleToTile
Converts Google (XYZ) Tile to TMS Tile.
Parameters
google
Google Google x, y, zoom
Examples
var tile = globalMercator.googleToTile([6963, 3188, 13])
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
googleToQuadkey
Converts Google (XYZ) Tile to Quadkey.
Parameters
google
Google Google x, y, zoom
Examples
var quadkey = globalMercator.googleToQuadkey([6963, 3188, 13])
//='1321102330211'
Returns string Microsoft's Quadkey schema
tileToQuadkey
Converts TMS Tile to QuadKey.
Parameters
tile
Tile Tile x, y, zoomvalidate
boolean validates Tile (optional, defaulttrue
)
Examples
var quadkey = globalMercator.tileToQuadkey([6963, 5003, 13])
//='1321102330211'
Returns string Microsoft's Quadkey schema
quadkeyToTile
Converts Quadkey to TMS Tile.
Parameters
quadkey
string Microsoft's Quadkey schema
Examples
var tile = globalMercator.quadkeyToTile('1321102330211')
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
quadkeyToGoogle
Converts Quadkey to Google (XYZ) Tile.
Parameters
quadkey
string Microsoft's Quadkey schema
Examples
var google = globalMercator.quadkeyToGoogle('1321102330211')
//=[ 6963, 3188, 13 ]
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
var meters = globalMercator.bboxToMeters([ 125, 35, 127, 37 ])
//=[ 13914936.3, 4163881.1, 14137575.3, 4439106.7 ]
Returns BBox bbox extent in minX, minY, maxX, maxY order
validateTile
Validates TMS Tile.
Parameters
tile
Tile Tile x, y, zoomvalidate
boolean validates Tile (optional, defaulttrue
)
Examples
globalMercator.validateTile([60, 80, 12])
//=[60, 80, 12]
globalMercator.validateTile([60, -43, 5])
//= Error: Tile <y> must not be less than 0
globalMercator.validateTile([25, 60, 3])
//= Error: Illegal parameters for tile
- Throws Error Will throw an error if TMS Tile is not valid.
Returns Tile TMS Tile
wrapTile
Wrap Tile -- Handles tiles which crosses the 180th meridian or 90th parallel
Parameters
Examples
globalMercator.wrapTile([0, 3, 2])
//= [0, 3, 2] -- Valid Tile X
globalMercator.wrapTile([4, 2, 2])
//= [0, 2, 2] -- Tile 4 does not exist, wrap around to TileX=0
Returns [number, number, number] Wrapped Tile
validateZoom
Validates Zoom level
Parameters
Examples
globalMercator.validateZoom(12)
//=12
globalMercator.validateZoom(-4)
//= Error: <zoom> cannot be less than 0
globalMercator.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
validateLngLat
Validates LngLat coordinates
Parameters
lnglat
[number, number] Longitude, Latitudevalidate
boolean validates LatLng coordinates (optional, defaulttrue
)
Examples
globalMercator.validateLngLat([-115, 44])
//= [ -115, 44 ]
globalMercator.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
maxBBox
Maximum extent of BBox
Parameters
array
(BBox | Array<BBox>) BBox west, south, east, north
Examples
var bbox = globalMercator.maxBBox([[-20, -30, 20, 30], [-110, -30, 120, 80]])
//=[-110, -30, 120, 80]
Returns BBox Maximum BBox
validTile
Valid TMS Tile
Parameters
tile
Tile Tile x, y, zoom
Examples
globalMercator.validTile([60, 80, 12])
//= true
globalMercator.validTile([60, -43, 5])
//= false
globalMercator.validTile([25, 60, 3])
//= false
Returns boolean valid tile true/false
latitude
Modifies a Latitude to fit within +/-90 degrees.
Parameters
lat
number latitude to modify
Examples
globalMercator.latitude(100)
//= -80
Returns number modified latitude
longitude
Modifies a Longitude to fit within +/-180 degrees.
Parameters
lng
number longitude to modify
Examples
globalMercator.longitude(190)
//= -170
Returns number modified longitude
bboxToTile
Get the smallest tile to cover a bbox
Parameters
Examples
var tile = bboxToTile([-178, 84, -177, 85])
//=tile
5 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago