Python CLI tools for basic manipulation of PMTiles files containing point data, modeled after the C++ tool pmpoint.
pip install -e .Requires Python ≥ 3.10. Dependencies: typer, pmtiles, requests, boto3, shapely.
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.gzSee 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.
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.
- 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_mapiteration order. --out-jsonwrites 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").
pip install -e ".[dev]"
pytestexportfor vector (MVT) point tiles- Polygon feature export
summarize,count-tiles, and other pmpoint commands
Apache-2.0