global-mercator
Advanced tools
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.
npm
$ npm install --save global-mercator
web
<script src="https://wzrd.in/standalone/global-mercator@latest"></script>
var globalMercator = require('global-mercator')
var tile = [10, 15, 8] // [x, y, zoom]
globalMercator.tileToBBox(tile)
// [ -165.937, -82.853, -164.531, -82.676 ]
| 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 |
Hash tile for unique id key
Parameters
tile Tile [x, y, z]Examples
var id = globalMercator.hash([312, 480, 4])
//=5728
Returns number hash
Get the tile for a point at a specified zoom level https://github.com/mapbox/tilebelt
Parameters
lnglat [number, number] [Longitude, Latitude]zoom number Zoom levelvalidate boolean validates LatLng coordinates (optional, default true)Examples
var tile = globalMercator.pointToTile([1, 1], 12)
//= [ 2059, 2036, 12 ]
Returns Google Google (XYZ) Tile
Get the precise fractional tile location for a point at a zoom level https://github.com/mapbox/tilebelt
Parameters
lnglat [number, number] [Longitude, Latitude]zoom number Zoom levelvalidate boolean validates LatLng coordinates (optional, default true)Returns Google Google (XYZ) Tile var tile = globalMercator.pointToTileFraction([1, 1], 12) //= [ 2059.3777777777777, 2036.6216445333432, 12 ]
Converts BBox to Center
Parameters
bbox BBox [west, south, east, north] coordinatesExamples
var center = globalMercator.bboxToCenter([90, -45, 85, -50])
//= [ 87.5, -47.5 ]
Returns LngLat center
Converts LngLat coordinates to Meters coordinates.
Parameters
lnglat [number, number] [Longitude, Latitude]validate boolean validates LatLng coordinates (optional, default true)Examples
var meters = globalMercator.lngLatToMeters([126, 37])
//=[ 14026255.8, 4439106.7 ]
Returns Meters Meters coordinates
Converts Meters coordinates to LngLat coordinates.
Parameters
meters Meters Meters in Mercator [x, y]Examples
var lnglat = globalMercator.metersToLngLat([14026255, 4439106])
//=[ 126, 37 ]
Returns LngLat LngLat coordinates
Converts Meters coordinates to Pixels coordinates.
Parameters
meters Meters Meters in Mercator [x, y]zoom number Zoom leveltileSize number Tile size (optional, default 256)Examples
var pixels = globalMercator.metersToPixels([14026255, 4439106], 13)
//=[ 1782579.1, 1280877.3, 13 ]
Returns Pixels Pixels coordinates
Converts LngLat coordinates to TMS Tile.
Parameters
lnglat [number, number] [Longitude, Latitude]zoom number Zoom levelvalidate boolean validates LatLng coordinates (optional, default true)Examples
var tile = globalMercator.lngLatToTile([126, 37], 13)
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
Converts LngLat coordinates to Google (XYZ) Tile.
Parameters
lnglat [number, number] [Longitude, Latitude]zoom number Zoom levelvalidate boolean validates LatLng coordinates (optional, default true)Examples
var google = globalMercator.lngLatToGoogle([126, 37], 13)
//=[ 6963, 3188, 13 ]
Returns Google Google (XYZ) Tile
Converts Meters coordinates to TMS Tile.
Parameters
meters Meters Meters in Mercator [x, y]zoom number Zoom levelExamples
var tile = globalMercator.metersToTile([14026255, 4439106], 13)
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
Converts Pixels coordinates to Meters coordinates.
Parameters
pixels Pixels Pixels [x, y, zoom]tileSize number Tile size (optional, default 256)Examples
var meters = globalMercator.pixelsToMeters([1782579, 1280877, 13])
//=[ 14026252.0, 4439099.5 ]
Returns Meters Meters coordinates
Converts Pixels coordinates to TMS Tile.
Parameters
pixels Pixels Pixels [x, y, zoom]tileSize number Tile size (optional, default 256)validate boolean validates Pixels coordinates (optional, default true)Examples
var tile = globalMercator.pixelsToTile([1782579, 1280877, 13])
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
Converts TMS Tile to bbox in Meters coordinates.
Parameters
tile Tile Tile [x, y, zoom]tileSize number Tile size (optional, default 256)validate boolean validates Tile (optional, default true)x number TMS Tile Xy number TMS Tile Yzoom number Zoom levelExamples
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
Converts TMS Tile to bbox in LngLat coordinates.
Parameters
tile Tile Tile [x, y, zoom]validate boolean validates Tile (optional, default true)x number TMS Tile Xy number TMS Tile Yzoom number Zoom levelExamples
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
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
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
Converts TMS Tile to Google (XYZ) Tile.
Parameters
tile Tile Tile [x, y, zoom]validate boolean validates Tile (optional, default true)Examples
var google = globalMercator.tileToGoogle([6963, 5003, 13])
//=[ 6963, 3188, 13 ]
Returns Google Google (XYZ) Tile
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
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
Converts TMS Tile to QuadKey.
Parameters
tile Tile Tile [x, y, zoom]validate boolean validates Tile (optional, default true)Examples
var quadkey = globalMercator.tileToQuadkey([6963, 5003, 13])
//='1321102330211'
Returns string Microsoft's Quadkey schema
Converts Quadkey to TMS Tile.
Parameters
quadkey string Microsoft's Quadkey schemaExamples
var tile = globalMercator.quadkeyToTile('1321102330211')
//=[ 6963, 5003, 13 ]
Returns Tile TMS Tile
Converts Quadkey to Google (XYZ) Tile.
Parameters
quadkey string Microsoft's Quadkey schemaExamples
var google = globalMercator.quadkeyToGoogle('1321102330211')
//=[ 6963, 3188, 13 ]
Returns Google Google (XYZ) Tile
Converts BBox from LngLat coordinates to Meters coordinates
Parameters
bbox BBox extent in [minX, minY, maxX, maxY] orderExamples
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
Validates TMS Tile.
Parameters
tile Tile Tile [x, y, zoom]validate boolean validates Tile (optional, default true)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
Returns Tile TMS Tile
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
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
Returns number zoom Zoom level
Validates LngLat coordinates
Parameters
lnglat [number, number] [Longitude, Latitude]validate boolean validates LatLng coordinates (optional, default true)Examples
globalMercator.validateLngLat([-115, 44])
//= [ -115, 44 ]
globalMercator.validateLngLat([-225, 44])
//= Error: LngLat [lng] must be within -180 to 180 degrees
Returns LngLat LngLat coordinates
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
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
Modifies a Latitude to fit within +/-90 degrees.
Parameters
lat number latitude to modifyExamples
dateline.latitude(100)
//= -80
Returns number modified latitude
Modifies a Longitude to fit within +/-180 degrees.
Parameters
lng number longitude to modifyExamples
dateline.longitude(190)
//= -170
Returns number modified longitude
FAQs
Tools to help with TMS, Quadkey & Google (XYZ) Tiles
We found that global-mercator demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.