1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
==========
Mercantile
==========
.. image:: https://travis-ci.com/mapbox/mercantile.svg
:target: https://travis-ci.com/mapbox/mercantile
:alt: Build Status
.. image:: https://coveralls.io/repos/github/mapbox/mercantile/badge.svg?branch=master
:target: https://coveralls.io/github/mapbox/mercantile?branch=master
:alt: Coverage Status
.. image:: https://readthedocs.org/projects/mercantile/badge/?version=latest
:target: http://mercantile.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
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.
.. code-block:: pycon
>>> 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.
.. code-block:: pycon
>>> 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.
.. code-block:: console
$ 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 <https://github.com/mapbox/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 <https://github.com/mapbox/node-sphericalmercator>`__
provides many of the same features for Node.
`tilebelt <https://github.com/mapbox/tilebelt>`__ has some of the GeoJSON
features as mercantile and a few more (tile parents, quadkey).
`morecantile <https://github.com/developmentseed/morecantile>`__ is like mercantile,
but with support for other TileMatrixSet grids.
|
