mapbox / mercantile

Spherical mercator tile and coordinate utilities

Mercantile

Spherical mercator coordinate and tile utilities

Documentation: http://mercantile.readthedocs.io/en/latest/

The mercantile module provides ul(xtile, ytile, zoom) and bounds(xtile, ytile, zoom) functions that respectively return the upper left corner and bounding longitudes and latitudes for XYZ tiles, a xy(lng, lat) function that returns spherical mercator x and y coordinates, a tile(lng, lat, zoom) function that returns the tile containing a given point, and quadkey conversion functions quadkey(xtile, ytile, zoom) and quadkey_to_tile(quadkey) for translating between quadkey and tile coordinates.

>>> import mercantile
>>> mercantile.ul(486, 332, 10)
LngLat(lng=-9.140625, lat=53.33087298301705)
>>> mercantile.bounds(486, 332, 10)
LngLatBbox(west=-9.140625, south=53.12040528310657, east=-8.7890625, north=53.33087298301705)
>>> mercantile.xy(*mercantile.ul(486, 332, 10))
(-1017529.7205322663, 7044436.526761846)
>> mercantile.xy_bounds(486, 332, 10)
Bbox(left=-1017529.7205322663, bottom=7005300.768279833, right=-978393.962050256, top=7044436.526761846)
>>> mercantile.tile(*mercantile.ul(486, 332, 10) + (10,))
Tile(x=486, y=332, z=10)
>>> mercantile.quadkey(486, 332, 10)
'0313102310'
>>> mercantile.quadkey_to_tile('0313102310')
Tile(x=486, y=332, z=10)

Also in mercantile are functions to traverse the tile stack.

>>> mercantile.parent(486, 332, 10)
Tile(x=243, y=166, z=9)
>>> mercantile.children(mercantile.parent(486, 332, 10))
[Tile(x=486, y=332, z=10), Tile(x=487, y=332, z=10), Tile(x=487, y=333, z=10), Tile(x=486, y=333, z=10)]

Named tuples are used to represent tiles, coordinates, and bounding boxes.

Mercantile CLI

Mercantile's command line interface, named "mercantile", has commands for getting the shapes of Web Mercator tiles as GeoJSON and getting the tiles that intersect with a GeoJSON bounding box.

$ mercantile --help
Usage: mercantile [OPTIONS] COMMAND [ARGS]...

  Command line interface for the Mercantile Python package.

Options:
  -v, --verbose  Increase verbosity.
  -q, --quiet    Decrease verbosity.
  --version      Show the version and exit.
  --help         Show this message and exit.

Commands:
  bounding-tile  Print the bounding tile of a lng/lat point, bounding box, or
                 GeoJSON objects.
  children       Print the children of the tile.
  neighbors      Print the neighbors of the tile.
  parent         Print the parent tile.
  quadkey        Convert to/from quadkeys.
  shapes         Print the shapes of tiles as GeoJSON.
  tiles          Print tiles that overlap or contain a lng/lat point, bounding
                 box, or GeoJSON objects.

See Also

supermercado is another python lib with added tile logic functionality (union tile shapes, find edge tiles, and find tile intersections for complex geometries).

node-sphericalmercator provides many of the same features for Node.

tilebelt has some of the GeoJSON features as mercantile and a few more (tile parents, quadkey).

morecantile is like mercantile, but with support for other TileMatrixSet grids.

mercantile's Issues

0.4 Release

0.6 release

For the bounding_tile() function.

Allow setting of shape properties

Let's extend mercantile so that it can accept not only [x, y, z] tile arrays but {"tile": [x, y, z], "properties": {...}} objects. Output shapes would get the input properties attached to them. If the properties dict has a "title" item it will override the default.

Emulate JS >>>

So we get the same results as tilebelt, eg [0,0,0] bounding tiles for things that cross the antimeridian.

1.0.0 release

I'd like to get this started with one alpha release, target: Thursday 2017-11-16. Followed by a beta release(s) the week after that, and a final 1.0.0 around 2017-12-01.

• close issues
• tag and upload dists

Any comments or last requests @dnomadb @perrygeo @youngpm @jwass @brendan-ward @kapadia @steko ?

geojson.io example needs fix?

The final example in the command line docs seems to throw an error.

$ echo "[-105, 39.99, -104.99, 40]" \
> | mercantile tiles 14 \
> | mercantile shapes --compact \
> | geojsonio
# SyntaxError: Unexpected token { in JSON at position 399..

which can be fixed by using geojsonify

$ npm install -g geojsonify
$ echo "[-105, 39.99, -104.99, 40]" \
| mercantile tiles 14 \
| mercantile shapes --compact \
| geojsonify \
| geojsonio

in the second, slightly updated, example I have removed the > characters because I think it makes it easier to read, and easier to copy and paste into a terminal.

Extract core function of mercantile-shapes

And make a module function from it. Like

def shape(x, y, z):
    """Returns a GeoJSON Polygon corresponding to the tile"""
    return {'type': 'Polygon', 'coordinates': ...}

0.7 Release

New features.

0.5 Release

New CLI features.

mercantile.tile gives incorrect results with global extents

>>> import mercantile

>>> list(mercantile.tiles(-180, -85, 180, 85, [1]))
[Tile(x=0, y=0, z=1), Tile(x=0, y=1, z=1), Tile(x=1, y=0, z=1), Tile(x=1, y=1, z=1)]

>>> list(mercantile.tiles(-180, -90, 180, 90, [1]))
[Tile(x=0, y=-12, z=1), Tile(x=0, y=-11, z=1), Tile(x=0, y=-10, z=1), Tile(x=0, y=-9, z=1), Tile(x=0, y=-8, z=1), Tile(x=0, y=-7, z=1), Tile(x=0, y=-6, z=1), Tile(x=0, y=-5, z=1), Tile(x=0, y=-4, z=1), Tile(x=0, y=-3, z=1), Tile(x=0, y=-2, z=1), Tile(x=0, y=-1, z=1), Tile(x=0, y=0, z=1), Tile(x=1, y=-12, z=1), Tile(x=1, y=-11, z=1), Tile(x=1, y=-10, z=1), Tile(x=1, y=-9, z=1), Tile(x=1, y=-8, z=1), Tile(x=1, y=-7, z=1), Tile(x=1, y=-6, z=1), Tile(x=1, y=-5, z=1), Tile(x=1, y=-4, z=1), Tile(x=1, y=-3, z=1), Tile(x=1, y=-2, z=1), Tile(x=1, y=-1, z=1), Tile(x=1, y=0, z=1)]

Not sure what the correct behavior is in this case.

0.11 release

Adding the new lnglat method.

Add option for Mercator output

Bypassing WGS84.

Clip long/lat to limits of the globe when computing tiles and xy

Otherwise we

mercantile.bounding_tile(-179.99999999999997, -90.00000000000003, 180.00000000000014, -63.27066048950458) raises ValueError: math domain error.

Compute bbox from GeoJSON piped to mercantile

If input GeoJSON doesn't have a precomputed bounding box, do the computation.

0.5.1 Release

Small bug and doc fixes.

Roll mercantile.tool command into mercantile script

For 0.2 (#5)

0.7.1 Release

So that mercantile tiles --bounding-tile reproduces tilebelt's results.

Add features of tilebelt

Mercantile is the natural place for features like these:

• get the tile for a point at a particular zoom super fast
• get the 4 tiles below a particular tile
• get the tile one zoom up from a particular tile

Add quadkey conversion to CLI

I often parse quadkeys out of some file and would like to get them converted to [x, y, z] so I can send them in to the various tools already in the cli. Might as well add support for going the other direction as well.

PR on its way. Let me know what you think of the sub-command I added.

0.6.1 release

Bug fixes.

Port quadkey indexes from tilebelt

At https://github.com/mapbox/tilebelt/blob/master/index.js#L89 are two functions to be ported to mercantile.

• get the quadkey index for a particular tile
• convert a quadkey index back to a tile

Link to node-sphericalmercator?

This is kind of similar to node-sphericalmercator, just very cool. I've added it to the See Also for that project, maybe it should go both ways?

(See Also sections are kind of an experiment, so that might not be up your alley. The jist is that they provide known connections between good code that does similar stuff)

Separate mercantile-tiles and --bounding-tile

These are actually rather different features.

mercantile tiles gives incorrect results for points

At any zoom level, a point can only intersect a single tile. The help text of mercantile tiles claims to take "lng/lat point, bounding box, or GeoJSON objects". But the results are incorrect for points.

$ echo '{"type":"geometry","coordinates":[14.0859, 5.798]}' | mercantile tiles 5 | wc -l
      33
$ echo "[14.0859, 5.798]" | mercantile tiles 5 | wc -l
      33

If we create a tiny bounding box using the point coordinate, we get the correct results.

$ echo "[14.0859, 5.798, 14.0860, 5.799]" | mercantile tiles 5 | wc -l
       1

0.8.1 Release

Bug fix.

Transparent handling of file, stream, and text input

As in geomet.

Port bboxToTile from tilebelt

0.8.2 release

Bug fixes.

Add --collection option to CLI tiles command

Retroactively added. Document this next.

Add script to get tiles from input bbox

See rasterio/rasterio#124.

$ echo "[$west, $south, $east, $north]" | mercantile tiles --zoom 9
X1, Y1, W1, S1, E1, N1
X2, Y2, W2, S2, E2, N2
...

Make truncation optional

Currently, mercantile truncates bounding boxes and points to keep them within the limits of the globe: [-180,-90, 180, 90]. Possible cases for not truncating, at least at the antimeridian, are cropping up, eg, mapbox/cardboard#87. Making the truncation optional may be useful.

Return the tiles at a zoom level that cover a feature

Tiles() returns the tiles that cover a feature's bounding box. This is more particular. I've already implemented Bresenham's algorithm elsewhere. I'll repurpose it here so that we can get a sequence of tiles at a zoom level that cover a feature.

0.3 release

To get the --mercator option and new README out there.

Include full table of context in docs sidebar?

Hey @sgillies! Love the docs for this project 🎉

I was taking a peek and noticed the sidebar doesn't have the full table of contents, which makes navigating a tad bit difficult. Any chance they could be added? I've never used RTD before, so not sure how to go about doing this.

0.10 release

New xy_bounds() method, etc.

Check mercantile tiles --mercator against ogr2ogr

Comparison:

mercantile shapes $TILE --mercator

vs

mercantile shapes $TILE --geographic \
| ogr2ogr -f "GeoJSON" -s_srs EPSG:4326 -t_srs EPSG:3857 /vsistdout/ /vsistdin/

Check gdalwarp using mercantile shapes --mercator (no CRS) as cutline

Follow up from #14 (comment).

Add CRS to geojson output

Add the CRS info to the geojson output.

Currently the workaround is this:

mercantile shapes - --x-json-seq  --mercator | \
sed -E 's/\}$/,"crs": \{"type": "EPSG","properties": \{"code": 3857 \}\}\}/g'

cc @hrwgc

Transfer to Mapbox

Hey @steko, any objection to me moving this to the Mapbox org? There would be no changes in license or anything? The move would be just to lower barriers to use at Mapbox, which is really the only place I employ the package.

converting tiles between zoom levels behaves unexpectedly

@sgillies just ran into unexpected behavior when piping output of mercantile shapes back into mercantile tiles:

I was intending to take the zoom 12 tile, grab the $z level tiles within it, and pipe each through mercantile shapes again:

mercantile shapes '[2331,1185,12]' | mercantile tiles 13 # | dosomething

But mercantile tiles output 6 zoom 13 tiles instead of the four I expected:

[4662, 2370, 13]
[4662, 2371, 13]
[4663, 2370, 13]
[4663, 2371, 13]
[4664, 2370, 13]
[4664, 2371, 13]

Is this expected/desired behavior?

Streamline CLI options

JSON Sequence is being finalized, so I'm going to alias --x-json-seq to --seq. Additionally, I'm going to alias --extent to --bbox, which is more like the Fiona and Rasterio CLI.

Furthermore, I'm going to make sequences the default for mercantile-shapes. To get a feature collection instead, use --collect. I've done a GitHub survey of mercantile users and don't see anything that will be broken by this change.

Accept mercator bounds as well as geographic

Something like mercantile tiles - 9 --mercator should work.

Buffer a region

When tiling and processing adjacent images, it is often needed to buffer these cutlines. It would be great to have an option to buffer directly with mercantile.

Currently we are buffering using this, which is not ideal:

width=10
bbox=(`ogrinfo -al  $cutline.geojson 2>&1 | grep Extent | sed -E "s/[^0-9\.\-]+/ /g;s/ - / /g"`)
bufferedbbox="`echo ${bbox[0]}-$width | bc -l` `echo ${bbox[1]}-$width | bc -l` `echo ${bbox[2]}+$width | bc -l` `echo ${bbox[3]}+$width | bc -l`"

cc @hrwgc

Mercantile CLI "tiles" errors when given GeoJSON with whitespace as an input

This command succeeds:

$ echo "[106, 193, 9]" | mercantile shapes | mercantile tiles 10
[212, 386, 10]
[212, 387, 10]
[213, 386, 10]
[213, 387, 10]

This fails:

$ echo "[106, 193, 9]" | mercantile shapes --indent 2 | mercantile tiles 10
json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 2 column 1 (char 2)

For anyone coming across this error with GeoJSON "in the wild", my current workaround is to use tr to remove the whitespace:

$ echo "[106, 193, 9]" | mercantile shapes --indent 2 | tr -d " \t\n\r" | mercantile tiles 10
[212, 386, 10]
[212, 387, 10]
[213, 386, 10]
[213, 387, 10]

Move PyPI credentials to Travis web settings

To allow remote password rotation.

Customization of shape id

As in #30, allow customization of the output feature id.

0.9 release

The new quadkeys feature warrants a release. How about tomorrow? @dnomadb @perrygeo: want to make a scan of open issues and see if there's anything else that could ship by tomorrow morning?

0.2 release

To go with Rasterio 0.11.1. See rasterio/rasterio#125.

Mercantile on Read the Docs

For 1.0.0.

Add support for quadkey/tile conversions

I'm in need of a handy way to to convert back and forth from quadkeys and tiles like you can see here.

PR on its way!