PMTiles Generation¶
Overview¶
ras2cng generates PMTiles archives from GeoParquet (vector) or GeoTIFF (raster) inputs. PMTiles is a single-file archive format that enables serverless HTTP range requests — serve flood map tiles directly from S3, Cloudflare R2, or GitHub Pages with no tile server.
Requirements¶
Vector tiles need either the tippecanoe + pmtiles CLIs or the in-process
freestiler tiler (pip install ras2cng[freestiler]); RAS2CNG_VECTOR_TILER
chooses between them (auto, the default, prefers a freestiler build with Arrow
input, then tippecanoe when it is on PATH, then any freestiler).
See MapLibre delivery. External CLI tools:
| Tool | Source | Purpose |
|---|---|---|
tippecanoe |
felt/tippecanoe | GeoParquet/GeoJSON → vector tiles |
pmtiles |
protomaps/go-pmtiles | MBTiles → PMTiles conversion |
gdal_translate |
GDAL | GeoTIFF → raster tiles (raster pipeline only) |
Vector Pipeline (GeoParquet → PMTiles)¶
GeoParquet → GeoJSON (temp) → tippecanoe → PMTiles
GeoParquet → Arrow → freestiler → PMTiles (freestiler with Arrow input)
GeoParquet → GeoDataFrame → freestiler → PMTiles (older freestiler)
Without --min-zoom/--max-zoom, tippecanoe guesses the zoom range (-zg);
freestiler cannot guess and uses 0-14. Archive bbox covering columns (the
bbox struct or the older flat bbox_* columns) are dropped before tiling.
freestiler tiles carry no MVT feature IDs by default (since 0.13); --feature-ids
(or RAS2CNG_VECTOR_TILE_IDS=1) keeps them. See the MapLibre guide for this and
the gzip level.
ras2cng pmtiles max_depth.parquet flood_depth.pmtiles \
--layer flood_depth \
--min-zoom 8 \
--max-zoom 14
Direct HDF mesh export with Rust¶
The optional native backend accepts geometry HDF or a computed plan HDF that contains mesh geometry. It constructs cell rings in Rust, transforms coordinates with pyproj in one batch, and passes packed geometry to freestiler-core. No GeoParquet, GeoJSON or per-cell Python geometry objects are required.
ras2cng pmtiles model.g01.hdf mesh.pmtiles --layer mesh_cells --min-zoom 10 --max-zoom 14 --threads 4
Use repeated --mesh options to select mesh names. --source-crs supplies an
explicit CRS override; otherwise the HDF CRS is required. Default HDF zooms are
10-14. Each feature retains its mesh_name and original cell_id. Output is
staged beside the destination and atomically published only on success.
This route uses the ras-commander-fast-hdf wheel, which ras-commander 0.110.1
and later install by default on Windows x64, Linux x64 and macOS arm64. On
other platforms, ras2cng[fast-hdf] requests it explicitly (a source build).
Installing the freestiler Python extra alone does not supply the HDF reader. The HDF route
explicitly uses the native backend; RAS2CNG_VECTOR_TILER continues to select
backends for GeoParquet/general-layer export.
from ras2cng.pmtiles import generate_mesh_pmtiles
generate_mesh_pmtiles(
"model.g01.hdf", "mesh.pmtiles", layer_name="mesh_cells",
min_zoom=10, max_zoom=14, threads=4,
# Optional result arrays, keyed by mesh, indexed by original cell ID:
# properties={"LockHaven": {"maximum_depth": depth_array}},
)
Cell polygons can collapse at low zoom through tile quantization even with feature dropping disabled. Qualify decoded coverage and validity for the chosen zoom range. This geometry export does not calculate hydraulic results.
Raster Pipeline (GeoTIFF → PMTiles)¶
GeoTIFF → gdal_translate → MBTiles → pmtiles convert → PMTiles (gdal)
GeoTIFF → terrio dem → terrio warp → terrio PMTiles (terrio)
RAS2CNG_RASTER_TILER chooses the backend for every raster PMTiles writer
(terrain, Stored Maps, calculated layers); see ras2cng.raster_tiles.
Streaming terrio tiles¶
With a terrio that streams (capability-detected: terrio.dem takes
max_memory_mib and hillshade_strength; CLB-Engineering-Corporation/terrio #8, #11, #12), no
step holds the raster whole:
- The colour relief is computed path to path, a strip of rows at a time. For
terrain, the hillshade is blended in the same pass (
"shaded-relief"). The result matches the old NumPy blend exactly (0 DN difference). - The warp to Web Mercator runs in chunks when
terrio.warptakesmax_memory_mib(#13). Otherwise the relief is warped in memory. - The PMTiles pyramid is written a tile row at a time from the warped raster, which is opened lazily.
The intermediates are tiled LZW GeoTIFFs in the scratch directory. The tiles
are byte-identical to the in-memory path (pinned by
tests/test_terrio_equivalence.py). A streaming terrio has no pixel ceiling,
so RAS2CNG_TERRIO_MAX_PIXELS only applies to older terrio releases.
RAS2CNG_TERRIO_MAX_MEMORY_MIB bounds the dem and warp strips. When it is
unset, terrio uses its defaults of 256 and 64 MiB. A smaller warp chunk can
change a few pixels, including edge pixels switching between visible and transparent, as gdalwarp -wm does.
Bald Eagle Terrain50 (15,777 × 12,599, z14, hillshaded), peak working set in a fresh process:
| terrio | wall | peak | output |
|---|---|---|---|
| 0.5.0 (in memory, NumPy hillshade) | 81.7 s | 13,372 MiB | 145.5 MB |
| streaming | 38.7 s | 1,008 MiB | byte-identical |
Detection is automatic: .tif / .tiff → raster pipeline; everything else → vector pipeline.
Python API¶
from ras2cng.pmtiles import generate_pmtiles_from_input
from pathlib import Path
generate_pmtiles_from_input(
input_path=Path("max_depth.parquet"),
output_path=Path("flood_depth.pmtiles"),
layer_name="flood_depth",
min_zoom=8,
max_zoom=14,
)
Serving PMTiles¶
Once generated, host the .pmtiles file on any static file host that supports HTTP range requests: