morecantile: Python Library for Tile Matrix Sets

Morecantile allows you to construct and use map tile grids (TileMatrixSets / TMS) following the OGC Two Dimensional Tile Matrix Set specification. You can retrieve specific grids using morecantile.tms.get() and then perform spatial operations like retrieving bounding boxes for the entire grid or for specific tiles in different Coordinate Reference Systems (CRS).

import morecantile

tms = morecantile.tms.get("WebMercatorQuad")

# Get the bounding box of the entire TMS
print(tms.xy_bbox)

# Get the bounds for a specific tile in the TMS's native CRS (e.g. epsg:3857)
print(tms.xy_bounds(morecantile.Tile(10, 10, 4)))

# Get the bounds for a specific tile in Geographic CRS (e.g. epsg:4326)
print(tms.bounds(morecantile.Tile(10, 10, 4)))

You can install morecantile from PyPI using pip. To install the latest version from the GitHub repository, use the git URL.

python -m pip install -U pip
python -m pip install morecantile

# Or install from source:
python -m pip install -U pip
python -m pip install git+https://github.com/developmentseed/morecantile.git

Morecantile v4 supports the updated OGC Tile Matrix Sets (TMS) v2.0 specification. If you have an existing TMS JSON document following the older v1 specification, you can convert it to a v2-compliant TileMatrixSet using the TileMatrixSet.from_v1() class method.

This is useful when migrating legacy tile matrix definitions to the new standard which includes renamed properties like id (formerly identifier), crs (formerly supportedCRS), and pointOfOrigin (formerly topLeftCorner).

from morecantile.models import TileMatrixSet
import json

with open("tms_v1.json") as f:
    data = json.load(f)

# Convert the v1 dictionary to a v2 TileMatrixSet
tms_v2 = TileMatrixSet.from_v1(data)

You can change the Geographic CRS used by a TileMatrixSet instance using two different methods:

1. Instance Method: Use set_geographic_crs(crs) to overwrite the geographic CRS for a specific TileMatrixSet instance. This requires a pyproj.CRS object.
2. Environment Variable: Set the MORECANTILE_DEFAULT_GEOGRAPHIC_CRS environment variable to change the default geographic CRS globally for all TileMatrixSet objects loaded after the variable is set.

# Method 1: Using set_geographic_crs
import morecantile
import pyproj

tms = morecantile.tms.get("CanadianNAD83_LCC")
tms.set_geographic_crs(pyproj.CRS.from_epsg(4326))

# Method 2: Using environment variable
import os
os.environ["MORECANTILE_DEFAULT_GEOGRAPHIC_CRS"] = "EPSG:4326"
import morecantile

tms = morecantile.tms.get("CanadianNAD83_LCC")

Use morecantile.tms.get(id) to retrieve a predefined Tile Matrix Set (TMS) by its identifier. Common identifiers include WebMercatorQuad, WGS1984Quad, and WorldMercatorWGS84Quad.

import morecantile

tms = morecantile.tms.get("WebMercatorQuad")

You can compare the performance of morecantile against mercantile and utiles by running the benchmark suite using pytest and pytest-benchmark.

First, install the necessary dependencies:

python -m pip install -r requirements.txt

Then, execute the benchmark script with specific flags to filter for benchmarks and sort the results by minimum execution time:

python -m pytest benchmarks.py --benchmark-only --benchmark-columns 'min, max, mean, median' --benchmark-sort 'min'

Morecantile uses a TileMatrixSets store to manage available grids.

• List grids: Use morecantile.tms.list() to see all currently registered grids.
• Register custom grid: Use morecantile.tms.register({id: tms_object}) to add a custom TileMatrixSet to the store. This returns a new store instance.
• Automatic registration: Set the TILEMATRIXSET_DIRECTORY environment variable to a directory containing .json files. Morecantile will automatically load these.
  • Note: Filenames must match the TMS id and contain only alphanumeric characters or underscores [a-zA-Z0-9_].

import morecantile

# List all
print(morecantile.tms.list())

# Register custom
new_tms_store = morecantile.tms.register({"MyCustomTmsEPSG3031": custom_tms_object})
tms = new_tms_store.get("MyCustomTmsEPSG3031")

The Morecantile CLI provides several commands to interact with TileMatrixSets (TMS), convert tile descriptions to GeoJSON, and find tiles overlapping specific geometries.

Global options include:

• --verbose, -v: Increase verbosity.
• --quiet, -q: Decrease verbosity.
• --version: Show version information.

# Example of using the CLI (assuming it is installed as `morecantile`)
$ morecantile --help

Once you have a TileMatrixSet instance, you can retrieve the spatial bounds of a specific tile using morecantile.Tile(x, y, z).

• Use tms.xy_bounds(tile) to get bounds in the TMS's native coordinate reference system (CRS).
• Use tms.bounds(tile) to get bounds in Geographic CRS (typically Lat/Lon WGS84).

import morecantile

tms = morecantile.tms.get("WebMercatorQuad")
tile = morecantile.Tile(10, 10, 4)

# Bounds in input projection (e.g., EPSG:3857)
xy_bounds = tms.xy_bounds(tile)

# Bounds in LatLon (WGS84)
latlon_bounds = tms.bounds(tile)

To find which tile covers a specific geographic location, use tms.tile(lon, lat, zoom) or tms.xy(x, y) to convert coordinates to the TMS's native CRS.

• tms.tile(lon, lat, zoom): Returns a Tile object.
• tms.xy(x, y): Returns the (x, y) coordinates in the TMS's native CRS.

import morecantile

tms = morecantile.tms.get("WebMercatorQuad")

# Find tile from Lat/Lon
tile = tms.tile(159.31, -42, 4)

# Get native XY coordinates from Lat/Lon
x, y = tms.xy(159.31, -42)