Overview
geolith raster downloads a tile pyramid from any {z}/{x}/{y} HTTP
endpoint and packs it into a PMTiles v3 archive with content deduplication.
It exists to produce the imagery layer that drapes over
terrain archives: one self-hosted file instead of a
runtime dependency on someone else's tile server.
geolith raster \
--url-template 'https://tiles.example.com/{z}/{x}/{y}.jpg' \
--output ./data/basemap.pmtiles \
--min-zoom 0 --max-zoom 8 \
--format jpeg \
--attribution '© Imagery provider'
| Flag | Default | Purpose |
|---|---|---|
--url-template | required | Tile URL with {z}, {x}, {y} placeholders |
--output | required | Output PMTiles archive path |
--min-zoom / --max-zoom | 0 / 8 | Zoom range |
--bbox | none | Restrict coverage to min_lon,min_lat,max_lon,max_lat |
--bbox-min-zoom | 0 | First zoom at which --bbox applies (see hybrid pyramids) |
--format | jpeg | Payload type recorded in the archive: jpeg, png, or webp |
--concurrency | 8 | Parallel download workers |
--request-delay-ms | 50 | Delay after each request on every worker |
--attempts | 5 | Download attempts per tile before the build fails |
--cache-dir | <temp>/geolith-raster | Resumable tile cache |
--name / --attribution | raster / none | Archive metadata |
Placeholder order is free-form, so row-major WMTS endpoints work unchanged:
--url-template 'https://server.example.com/wmts/1.0.0/layer/default/g/{z}/{y}/{x}.jpg'
Hybrid pyramids
A full-planet archive is a zoom-budget problem — each level quadruples the tile count:
| Depth | Tiles | Approximate size |
|---|---|---|
| z0–z8 | 87K | 1–2 GB |
| z0–z10 | 1.4M | 20–30 GB |
| z0–z12 | 22M | 350+ GB |
--bbox-min-zoom resolves this: below it the whole planet is fetched, at and
above it only the bounding box. One archive then holds a spinnable globe plus
one deep-zoom region.
geolith raster \
--url-template 'https://tiles.example.com/{z}/{x}/{y}.jpg' \
--output ./data/planet-raster.pmtiles \
--min-zoom 0 --max-zoom 12 \
--bbox 68.0,6.5,97.5,37.2 \
--bbox-min-zoom 9
Planet to z8 plus India to z12 is ~260K tiles (~4 GB) instead of the 22M a uniform z12 planet would need.
The archive header declares the extent the pyramid genuinely covers, not the
--bbox value: a hybrid archive holds planet tiles below the switch zoom, so
it reports world bounds. Only when --bbox-min-zoom is at or below
--min-zoom — meaning every zoom is clipped — does it report the bbox.
Clients that skip tiles outside the declared bounds therefore still request the
global low-zoom tiles.
Because world bounds alone cannot express where the deep zooms live, clipped archives also record the pyramid shape in their metadata:
| Key | Meaning |
|---|---|
geolith:bbox | min_lon,min_lat,max_lon,max_lat the deep zooms cover |
geolith:bbox_min_zoom | First zoom at which that clipping applies |
Both are omitted for unclipped planet archives. Read them with
pmtiles show <archive> to tell which zoom levels are global and which are
regional without knowing the original build flags.
Resumability
Every tile is written to --cache-dir before packing, so an interrupted run
resumes by re-running the same command — cached tiles are skipped and only the
remainder is fetched. Coordinates the upstream has no tile for are recorded as
misses, so they are not retried on later runs either. Re-running a completed
build re-packs from cache in seconds without touching the network.
Choosing a source
Tile endpoints are not automatically redistributable. Before archiving a provider's imagery into a file you will host, confirm their licence permits re-hosting:
- Suitable: sources published under CC-BY (attribution preserved in
archive metadata via
--attribution), public-domain government imagery, or imagery you hold a redistribution licence for. - Not suitable: most commercial basemap APIs, whose terms prohibit bulk download and redistribution — including cases where the tiles are publicly reachable without a key.
Licences also vary between layers of the same service, so check the specific layer rather than the provider.
Rendering
map.addSource('basemap', {
type: 'raster',
url: 'pmtiles://https://example.com/planet-raster.pmtiles',
tileSize: 256,
});
map.addLayer({ id: 'basemap', type: 'raster', source: 'basemap' });
Draped over a terrain archive, the two combine into a 3D basemap:
map.setTerrain({ source: 'terrain', exaggeration: 1.25 });
Serving works through tileserver-rs or any PMTiles host — the archive declares
its raster tile_type with no tile compression, per the PMTiles v3 spec.