https://github.com/mapbox/mercantile

Spherical mercator tile and coordinate utilities
https://github.com/mapbox/mercantile

imagery pxm satellite

Last synced: 3 months ago
JSON representation

Spherical mercator tile and coordinate utilities

• Host: GitHub
• URL: https://github.com/mapbox/mercantile
• Owner: mapbox
• License: bsd-3-clause
• Created: 2014-02-12T23:04:35.000Z (over 10 years ago)
• Default Branch: main
• Last Pushed: 2024-04-27T11:25:09.000Z (6 months ago)
• Last Synced: 2024-06-11T17:04:29.349Z (5 months ago)
• Topics: imagery, pxm, satellite
• Language: Python
• Size: 234 KB
• Stars: 397
• Watchers: 131
• Forks: 64
• Open Issues: 8
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.txt
  • License: LICENSE.txt
  • Code of conduct: CODE_OF_CONDUCT.md
  • Authors: AUTHORS.txt

Awesome Lists containing this project

README

        
==========

Mercantile

==========

.. image:: https://app.travis-ci.com/mapbox/mercantile.svg?branch=main

   :target: https://app.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 `__ 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.