mercantile package¶
Subpackages¶
Module contents¶
Web mercator XYZ tile utilities
-
class
mercantile.
Bbox
(left, bottom, right, top)¶ Bases:
tuple
A web mercator bounding box
Attributes: - left, bottom, right, top : float
Bounding values in meters.
Methods
count
($self, value, /)Return number of occurrences of value. index
($self, value[, start, stop])Return first index of value. -
bottom
¶ Alias for field number 1
-
left
¶ Alias for field number 0
-
right
¶ Alias for field number 2
-
top
¶ Alias for field number 3
-
class
mercantile.
LngLat
(lng, lat)¶ Bases:
tuple
A longitude and latitude pair
Attributes: - lng, lat : float
Longitude and latitude in decimal degrees east or north.
Methods
count
($self, value, /)Return number of occurrences of value. index
($self, value[, start, stop])Return first index of value. -
lat
¶ Alias for field number 1
-
lng
¶ Alias for field number 0
-
class
mercantile.
LngLatBbox
(west, south, east, north)¶ Bases:
tuple
A geographic bounding box
Attributes: - west, south, east, north : float
Bounding values in decimal degrees.
Methods
count
($self, value, /)Return number of occurrences of value. index
($self, value[, start, stop])Return first index of value. -
east
¶ Alias for field number 2
-
north
¶ Alias for field number 3
-
south
¶ Alias for field number 1
-
west
¶ Alias for field number 0
-
class
mercantile.
Tile
(x, y, z)¶ Bases:
tuple
An XYZ web mercator tile
Attributes: - x, y, z : int
x and y indexes of the tile and zoom level z.
Methods
count
($self, value, /)Return number of occurrences of value. index
($self, value[, start, stop])Return first index of value. -
x
¶ Alias for field number 0
-
y
¶ Alias for field number 1
-
z
¶ Alias for field number 2
-
mercantile.
bounding_tile
(*bbox, **kwds)¶ Get the smallest tile containing a geographic bounding box
NB: when the bbox spans lines of lng 0 or lat 0, the bounding tile will be Tile(x=0, y=0, z=0).
Parameters: - bbox : sequence of float
west, south, east, north bounding values in decimal degrees.
Returns: - Tile
-
mercantile.
bounds
(*tile)¶ Returns the bounding box of a tile
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
Returns: - LngLatBBox
Notes
Epsilon is subtracted from the right limit and added to the bottom limit.
-
mercantile.
children
(*tile, **kwargs)¶ Get the children of a tile
The children are ordered: top-left, top-right, bottom-right, bottom-left.
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
- zoom : int, optional
Returns all children at zoom zoom, in depth-first clockwise winding order. If unspecified, returns the immediate (i.e. zoom + 1) children of the tile.
Returns: - list
Examples
>>> children(Tile(0, 0, 0)) [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)]
>>> children(Tile(0, 0, 0), zoom=2) [Tile(x=0, y=0, z=2), Tile(x=0, y=1, z=2), Tile(x=0, y=2, z=2), Tile(x=0, y=3, z=2), ...]
-
mercantile.
feature
(tile, fid=None, props=None, projected='geographic', buffer=None, precision=None)¶ Get the GeoJSON feature corresponding to a tile
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
- fid : str, optional
A feature id.
- props : dict, optional
Optional extra feature properties.
- projected : str, optional
Non-standard web mercator GeoJSON can be created by passing ‘mercator’.
- buffer : float, optional
Optional buffer distance for the GeoJSON polygon.
- precision : int, optional
GeoJSON coordinates will be truncated to this number of decimal places.
Returns: - dict
-
mercantile.
lnglat
(x, y, truncate=False)¶ Convert web mercator x, y to longitude and latitude
Parameters: - x, y : float
web mercator coordinates in meters.
- truncate : bool, optional
Whether to truncate or clip inputs to web mercator limits.
Returns: - LngLat
-
mercantile.
parent
(*tile, **kwargs)¶ Get the parent of a tile
The parent is the tile of one zoom level lower that contains the given “child” tile.
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
- zoom : int, optional
Determines the zoom level of the returned parent tile. This defaults to one lower than the tile (the immediate parent).
Returns: - Tile
Examples
>>> parent(Tile(0, 0, 2)) Tile(x=0, y=0, z=1)
>>> parent(Tile(0, 0, 2), zoom=0) Tile(x=0, y=0, z=0)
-
mercantile.
quadkey
(*tile)¶ Get the quadkey of a tile
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
Returns: - str
-
mercantile.
quadkey_to_tile
(qk)¶ Get the tile corresponding to a quadkey
Parameters: - qk : str
A quadkey string.
Returns: - Tile
-
mercantile.
simplify
(tiles)¶ Reduces the size of the tileset as much as possible by merging leaves into parents.
Parameters: - tiles : Sequence of tiles to merge.
Returns: - list
-
mercantile.
tile
(lng, lat, zoom, truncate=False)¶ Get the tile containing a longitude and latitude
Parameters: - lng, lat : float
A longitude and latitude pair in decimal degrees.
- zoom : int
The web mercator zoom level.
- truncate : bool, optional
Whether or not to truncate inputs to limits of web mercator.
Returns: - Tile
-
mercantile.
tiles
(west, south, east, north, zooms, truncate=False)¶ Get the tiles overlapped by a geographic bounding box
Parameters: - west, south, east, north : sequence of float
Bounding values in decimal degrees.
- zooms : int or sequence of int
One or more zoom levels.
- truncate : bool, optional
Whether or not to truncate inputs to web mercator limits.
Yields: - Tile
Notes
A small epsilon is used on the south and east parameters so that this function yields exactly one tile when given the bounds of that same tile.
-
mercantile.
ul
(*tile)¶ Returns the upper left longitude and latitude of a tile
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
Returns: - LngLat
Examples
>>> ul(Tile(x=0, y=0, z=1)) LngLat(lng=-180.0, lat=85.0511287798066)
>>> mercantile.ul(1, 1, 1) LngLat(lng=0.0, lat=0.0)
-
mercantile.
xy_bounds
(*tile)¶ Get the web mercator bounding box of a tile
Parameters: - tile : Tile or sequence of int
May be be either an instance of Tile or 3 ints, X, Y, Z.
Returns: - Bbox
Notes
Epsilon is subtracted from the right limit and added to the bottom limit.