pymtiles

Python CLI tools for basic manipulation of PMTiles files containing point data, modeled after the C++ tool pmpoint.

Installation

pip install -e .

Requires Python ≥ 3.10. Dependencies: typer, pmtiles, requests, boto3, shapely.

Commands

pymtiles export

Extracts points from a PMTiles file (vector/MVT point tiles) into TSV and/or newline-delimited GeoJSON, with optional spatial subsetting by bounding box or polygon. The interface mirrors pmpoint export:

# full export at the maximum zoom level (sample data in examples/)
pymtiles export --in examples/genes_bin215.pmtiles --out-tsv genes_bin215.all.tsv.gz

# subset by bounding box (EPSG:3857-style global coordinates)
pymtiles export --in examples/genes_bin215.pmtiles --out-tsv subset.tsv \
    --xmin 1000 --xmax 2000 --ymin 1000 --ymax 2000

# subset by polygon(s) from a GeoJSON file (in EPSG:3857)
pymtiles export --in examples/genes_bin215.pmtiles \
    --polygon examples/glom_2.geojson --out-tsv genes_bin215.glom_2.tsv.gz

# read directly from S3 or HTTP(S) — only the necessary byte ranges are fetched
pymtiles export \
    --in "s3://cartostore/data/batch=2026_07/xenium-human-kidney-igan-healthy-multisample-20260717/xenium-human-kidney-igan-healthy-multisample-20260717-igan/genes_bin215.pmtiles" \
    --polygon examples/glom_2.geojson --out-tsv genes_bin215.glom_2.tsv.gz

See examples/ for the sample data and more runnable commands.

Option	Description
--in	Input PMTiles file: local path, http(s):// URL, or s3:// URI (required)
--out-tsv	Output TSV file; .gz suffix enables gzip compression
--out-json	Output newline-delimited GeoJSON file; .gz for gzip
--zoom	Zoom level (default -1 = maximum zoom level)
--xmin/--xmax/--ymin/--ymax	Bounding-box filter in global coordinates (default: unbounded)
--polygon	GeoJSON file (EPSG:3857) for polygon-based filtering; also accepts non-standard wrappers that nest GeoJSON under a geometry/geometries/features key
--precision	Decimal places for output X/Y coordinates (default 3)

At least one of --out-tsv / --out-json is required. The TSV columns are X, Y, followed by the point property columns taken from the file metadata (tilestats attributes, falling back to vector_layers fields) when declared, or discovered from the first tile otherwise. Features may store properties sparsely; absent values are written as NA.

S3 access uses the standard AWS credential chain and falls back to anonymous (unsigned) requests for public buckets.

Efficiency

pymtiles export avoids reading data it does not need:

• Only leaf directories whose tile-ID span intersects the target zoom level are fetched; tiles outside the bounding box / polygon bounding boxes are skipped before any tile data is read.
• Tile fetches are coalesced into large byte-range requests (up to 8 MB, bridging gaps up to 128 KB), which keeps the number of S3/HTTP round trips small for clustered archives.
• Output is streamed tile by tile, so memory use stays modest regardless of archive size.

Differences from pmpoint export

• Output rows may appear in a different order (tiles are processed in file-offset order; content is identical).
• TSV property columns follow the MVT tag order rather than C++ unordered_map iteration order.
• --out-json writes valid newline-delimited GeoJSON features (pmpoint wraps the same lines in a stray {/} pair).
• A partially-specified bounding box (e.g. only --xmin) constrains only the specified sides.
• Files whose features have heterogeneous (sparse) property sets are supported: the column set comes from the file metadata and missing values are NA (pmpoint aborts on such files with "Incompatible feature names").

Development

pip install -e ".[dev]"
pytest

Status / roadmap

• export for vector (MVT) point tiles
• Polygon feature export
• summarize, count-tiles, and other pmpoint commands

License

Apache-2.0