wrolpi-help/docs/modules/map/files.md
Roland 0fbbf18253
Map: exporting a map as a PDF, and a page for each part of the map
The Map page is five pages: the map itself, its files, terrain, overlays, and the new PDF export.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-20 17:11:05 -07:00

6.4 KiB

Map Files

The map is drawn from PMTiles files in the map directory of your media directory (map/). This page covers getting those files, how WROLPi decides what each one is, and managing them on the Map's Manage tab.

Manage Tab

The Manage tab has two sections:

Map Files

Lists every .pmtiles file in the map directory of your media directory (map/), including files in sub-directories. A file in a sub-directory is shown with its directory (e.g. extras/infrastructure.pmtiles). Files can be deleted from here.

Column What it shows
File The file's path within the map directory, and the name the file gives itself (when it has one).
Type How the map draws the file: Basemap, Overlay, Overlay (styled), Terrain, or Unreadable. See Special File Names and Overlays.
Size The size of the file.
Search Whether a search index exists (basemap files only).
Visible Whether the map uses the file.

Visible

Turn off a file's Visible toggle to make the map ignore it without deleting it. An ignored file is not drawn, is not offered in the Layer Control, and its places are not found by search. It stays in this list so you can turn it back on.

Ignoring a full planet file makes the map use your regional files again, exactly as if the planet file were not there.

The files you ignore are saved in maps.yaml (see How Configs Work) as their paths within the map directory. Deleting a file also removes it from maps.yaml.

ignored_files:
- extras/satellite.pmtiles

The Search column shows whether a search index exists for each basemap file. Overlays and terrain files have no search index:

  • Built (green) — A search index exists. Place search is available for this file.
  • Build (button) — No search index yet. Click to generate one using tippecanoe-decode. If WROL Mode is not active, the index will also be enriched with region names from Wikidata.

Search indexes are small SQLite databases (typically 1-4 MB per region) stored alongside the PMTiles file with a .search.db extension. They are created automatically when you download a region via subscriptions, or you can build them manually with the Build button.

Map Subscriptions

Subscribe to map regions to download them automatically from the WROLPi CDN.

  • Browse the catalog of available regions (33 regions covering the entire world, plus terrain)
  • Click Subscribe to add a region
  • Click View to preview a region's coverage area on a mini map
  • Click View All Regions to see all available regions on a world map
  • Click Unsubscribe to remove a region

Subscribed regions are downloaded via aria2c and automatically renewed every 180 days to keep your maps up to date.

How a Subscription Downloads

When you subscribe to a region:

  1. WROLPi fetches the map manifest from the CDN and verifies its GPG signature
  2. A download is created for each subscribed region
  3. aria2c downloads the pre-extracted PMTiles file from the CDN
  4. After download, the meta4 file's GPG-signed hash is verified to ensure the file is authentic and untampered
  5. The file is placed in your map directory with a versioned filename (e.g., us-west-20260329.pmtiles)
  6. A pre-built search index (.search.db) is downloaded from the CDN, also with GPG-signed hash verification. This provides instant place search with region names.

Downloads are integrity-verified at multiple levels: the manifest is GPG-signed, each file's SHA-256 hash is GPG-signed in its meta4 file, and aria2c verifies the hash during download.

Special File Names

WROLPi reads each PMTiles file to decide how the map draws it. A file is a basemap when it contains the Protomaps layers (earth, water and roads). Any other readable file is an overlay. A file which is not a PMTiles file is listed as Unreadable and is never drawn.

Some file names are also handled specially:

Pattern Behavior
planet-*.pmtiles A basemap with this name is a full planet file — used as the sole basemap. Regional extracts and the planet overview are skipped. Overlays and terrain are still drawn.
YYYYMMDD.pmtiles (8 digits) Also treated as a full planet file. This is the naming convention used by Protomaps builds.
map-overview.pmtiles Low-zoom base layer (zoom 0-6). Provides a global overview when using regional extracts. Not treated as a full planet.
terrain-*.pmtiles Terrain DEM data for hillshade and contour layers. Not loaded as a vector source.
Any other basemap Regional vector tiles. Multiple regional files render together on the map.
Any other file An overlay.

Map files can be organized in sub-directories of the map directory. Hidden directories (names starting with .) are skipped; WROLPi keeps unfinished downloads in one.

Getting Map Files

The easiest way to get map files is through Map Subscriptions on the Manage tab. WROLPi hosts pre-extracted regions on a CDN that are downloaded automatically.

Full Planet File

For complete global coverage, download the full planet file directly from Protomaps and place it in your map directory. The planet file is approximately 100-135 GB.

WROLPi does not host the planet file due to its size. Download it directly from Protomaps.

Custom Regions with pmtiles CLI

Use the pmtiles command-line tool to extract a custom region:

# Extract a single state (Oregon)
pmtiles extract https://build.protomaps.com/YYYYMMDD.pmtiles /media/wrolpi/map/oregon.pmtiles \
  --bbox="-124.8,42.0,-116.5,46.3"

Replace YYYYMMDD with the latest build date from the Protomaps builds page.

The pmtiles extract command uses HTTP Range Requests to download only the tiles for your selected region, so you do not need to download the entire planet file.

Multiple Regions

You can load multiple PMTiles files at once. For example, download separate files for the contiguous US, Alaska, and Hawaii, and they will all render together on the map.