Morecantile

7.0.3 · active · verified Wed Apr 15

Morecantile is a Python library for constructing and using map tile grids, also known as TileMatrixSet (TMS). It extends the functionality of libraries like mercantile by supporting a wider range of TileMatrixSet grids beyond just Web Mercator. The library is currently at version 7.0.3 and maintains an active release cadence, providing tools to work with OGC TMS specifications (currently TMS 2.0).

Warnings

breaking Morecantile 7.0.0 dropped support for Python versions 3.8, 3.9, and 3.10. It now requires Python 3.11 or newer.
Fix: Upgrade your Python environment to version 3.11 or later to use morecantile 7.x.
breaking Starting with version 7.0.0, the default CRS for GeoJSON outputs from methods like `TileMatrixSet.feature` is now WGS84 (EPSG:4326) as per specification. Additionally, property names like `grid_name` and `grid_crs` were renamed to `tms` and `tms_crs` respectively within GeoJSON responses.
Fix: Update your code to expect WGS84 for GeoJSON outputs, and adjust property access for `tms` and `tms_crs` if you were consuming `grid_name` or `grid_crs`. If you need a different CRS, explicitly set the `geographic_crs` option in the relevant methods.
gotcha The `TileMatrixSet.is_valid` method became strict by default in 7.0.0. This means it will raise an error if a requested tile's zoom level is beyond the TMS's `maxzoom` and a corresponding `TileMatrix` is not explicitly defined, whereas previous versions might have issued a `UserWarning`.
Fix: If your application relies on the previous, more lenient behavior, you can pass `strict=False` to the `is_valid` method: `tms.is_valid(x, y, z, strict=False)`.
breaking Morecantile versions 4.0.0 and above adopted the OGC TMS 2.0 specification, which introduced several breaking changes to the TMS JSON document structure. Key field renames include `identifier` to `id`, `supportedCRS` to `crs`, `tileMatrix` to `tileMatrices`, and `topLeftCorner` to `pointOfOrigin`.
Fix: If you are defining custom TileMatrixSets using JSON files, update your JSON documents to conform to the TMS 2.0 specification. Alternatively, for older TMS v1 JSONs, use the `TileMatrixSet.from_v1` class method to parse them.

Install

pip install morecantile Install stable version

Imports

tms
```
import morecantile
tms = morecantile.tms.get('WebMercatorQuad')
```
The 'tms' object is the primary entry point for accessing default and custom TileMatrixSets.
Tile
```
from morecantile import Tile
```
Represents a single map tile with x, y, z coordinates.
TileMatrixSet
```
from morecantile.models import TileMatrixSet
```
The Pydantic model for defining custom TileMatrixSets.

Quickstart

This quickstart demonstrates how to load a predefined TileMatrixSet, create a Tile object, and retrieve its bounding box in both the TMS's native CRS and in a geographic CRS.

import morecantile

# Get a default TileMatrixSet (TMS) like WebMercatorQuad
tms = morecantile.tms.get("WebMercatorQuad")

# Define a tile (Z, X, Y)
tile = morecantile.Tile(x=10, y=10, z=4)

# Get the bounding box of the tile in the TMS's CRS (e.g., EPSG:3857 for WebMercatorQuad)
xy_bounds = tms.xy_bounds(tile)
print(f"Tile {tile} XY Bounds: {xy_bounds}")

# Get the bounding box of the tile in Geographic CRS (e.g., EPSG:4326)
geographic_bounds = tms.bounds(tile)
print(f"Tile {tile} Geographic Bounds: {geographic_bounds}")

# List available default TileMatrixSets
print(f"Available TMS grids: {morecantile.tms.list()[:3]}...")

view raw JSON →