New CLI feature: pmtiles merge

The pmtiles CLI now includes the highly requested merge command for combining multiple tilesets into a single archive.

As an example use case: the Mapterhorn project distributes several archives:

• planet.pmtiles for the full planet terrain mosaic, from zoom levels 0 to 12.
• 6-20-28.pmtiles, 6-21-29.pmtiles, etc for zoom 13 and above in specific areas. These archives can contain up to zoom level 17.

These archives are split to ensure each one is at most a few hundred gigabytes: the total size of all tilesets is over 2 TB.

If you need to combine both low resolution and high resolution tiles into a single archive for one area like Interlaken, you can accomplish this now with pmtiles extract followed by pmtiles merge:

pmtiles extract \
  --bbox=7.74,46.60,7.96,46.75 \
  https://download.mapterhorn.com/planet.pmtiles \
  planet.pmtiles

pmtiles extract \
  --bbox=7.74,46.60,7.96,46.75 \
  https://download.mapterhorn.com/6-33-22.pmtiles \
  6-33-22.pmtiles

pmtiles merge planet.pmtiles 6-33-22.pmtiles interlaken.pmtiles

This results in a single archive, hostable as a single file on cloud storage, enabling smooth zoom from 0 to 17.

Requirements

The merge command currently works for both raster and vector tilesets.

• All input archives must be clustered.
• All input archives must be the same tile type. It’s not possible to combine raster with vector tiles, or PNG with JPEG, for example.
• All input archives must have the same compression method.
• For now, inputs must be disjoint with 0 overlapping tiles. The easiest way to satisfy this is with non-overlapping zoom levels.

Disjoint inputs

The current implementation of pmtiles merge does not work with overlapping inputs. The PMTiles CLI is a tool for reading and writing with general tile archives, not a tool for editing individual tiles.

Consider two tilesets that contain zoom 0 to zoom 12 of two different regions of the world, like a square region around Tokyo and Paris. All tilesets that form a complete pyramid contain tile 0,0,0:

     0, 0, 0           0, 0, 0     
┌───────────────┐ ┌───────────────┐
│      ┌───┐    │ │               │
│      │ P │    │ │               │
│      └───┘    │ │               │
│               │ │          ┌───┐│
│               │ │          │ T ││
│               │ │          └───┘│
└───────────────┘ └───────────────┘

The logical merging of the two tilesets should result in a brand new 0,0,0 tile combining the geometry (vector), or compositing the pixels (raster):

     0, 0, 0     
┌───────────────┐
│      ┌───┐    │
│      │ P │    │
│      └───┘    │
│          ┌───┐│
│          │ T ││
│          └───┘│
└───────────────┘

However, combining geometry or image compositing operations are both outside the current scope of the PMTiles CLI.

Recommendations

If your project requires merging different tilesets that are overlapping, it’s recommended to instead pre-generate or extract the tilesets from the source data.

• For raster archives, use the rio-pmtiles command line tool to generate a PMTiles directly from a GeoTIFF or other GDAL-readable source.
• For vector basemaps, use pmtiles extract with a multipolygon input.
• For other vector datasets, use tippecanoe on the combined source data directly or use a Planetiler profile like protomaps/basemaps on combined source data.

Future work

A future enhancement to pmtiles merge will allow overlapping input tilesets only in the case for vector tilesets with non-overlapping input layers.

This is especially useful for combining overlay data like bike lanes or choropleths with basemap tiles into a single archive, which can halve the number of requests for a mapping application and speed up the map browsing experience.