wrolpi-help/docs/modules/map/index.md

Map

The Map module displays offline vector maps using MapLibre GL JS and PMTiles files. Maps are rendered in the browser using your device's GPU, providing fast and smooth navigation with layer control.

The module is powered by Protomaps — an open-source system for self-hosting vector maps from a single PMTiles file.

Map Tab

The Map tab displays an interactive map with the following controls:

• Layer Control (top-left) — Toggle visibility of map layers: roads, water, buildings, land cover, boundaries, labels, hillshade, contours, and more. Your choices are saved between sessions.
• GPS Location (top-right) — Request your device's GPS position and center the map on it.
• Zoom & Navigation (top-right) — Zoom in/out, rotate, and tilt the map.
• Fullscreen (top-right) — Expand the map to fill the entire screen.
• Scale Bar (bottom-left) — Distance scale. Click to toggle between metric and imperial.
• Dark/Light Mode — The map automatically matches your WROLPi theme.

Context Menu

Right-click (or long-press on mobile) anywhere on the map to open the context menu:

• Copy Coordinates — Copy the latitude and longitude to your clipboard.
• Export PNG — Save a screenshot of the current map view as a PNG file. The filename includes the GPS coordinates of the center of the map.
• Add Pin — Place a named pin at that location.

Sharing Coordinates

The URL updates as you navigate the map, encoding the current position and zoom level:

https://your-wrolpi/map?lat=45.5231&lon=-122.6765&z=12

Share this URL to link someone directly to a specific location and zoom level.

Search

Type in the search box at the top center of the map to find places by name.

• Place search — Type a city, town, park, or region name. Results appear in a dropdown showing the place name, administrative region (e.g., "Oregon"), and population.
• Coordinate search — Type coordinates like 45.5, -122.6 to navigate directly to that location.
• Proximity bias — Results are sorted by proximity to your current map view, so nearby places appear first.
• Prefix matching — Typing partial names works (e.g., "Port" finds "Portland").
• Fuzzy fallback — If no exact match is found, a broader substring search is attempted.

Click a result to fly to that location with a marker and popup. Press Escape to close the dropdown.

Search data is extracted from the same PMTiles map files you already have. No additional downloads are needed. When search indexes include Wikidata enrichment, results show administrative regions (state/province) to help distinguish places with the same name.

Pins Tab

Map pins let you mark and name important locations. Pins are stored in map_pins.yaml in your media directory and persist across restarts.

Adding Pins

• Right-click (or long-press on mobile) on the map and select Add Pin
• Enter a name and optional description

Managing Pins

The Pins tab shows a table of all your pins with:

• Filter — Type to search pins by name
• Navigate — Click the location icon to fly the map to that pin
• Edit — Change the pin's name or description
• Delete — Remove the pin

Manage Tab

The Manage tab has two sections:

Map Files

Lists all .pmtiles files in your media directory under /map. Shows the file name, size, search index status, and a delete button. Files can be deleted from here.

The Search column shows whether a search index exists for each file:

• 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.

Map Subscriptions

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

The map viewer detects certain file name patterns and handles them differently:

Pattern	Behavior
planet-*.pmtiles	Full planet file — used as the sole vector source. Regional extracts and the planet overview are skipped.
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.
Everything else	Regional vector tiles. Multiple regional files render together on the map.

Getting Map Files

Via Subscriptions (Recommended)

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.

Terrain

The map supports hillshade and contour overlays when a terrain file is available.

Downloading

You can download map terrain files from Mapterhorn

Setup

Place a terrain PMTiles file (DEM data in Terrarium encoding) in your map directory. The file name must start with terrain- (e.g., terrain-z0-8.pmtiles).

You can subscribe to the Terrain region on the Manage tab to download the terrain file automatically.

Using Terrain Layers

Once a terrain file is detected, two additional layer groups appear in the Layer Control:

• Hillshade — Shaded relief showing elevation changes. Hidden by default.
• Contours — Elevation contour lines with labels. Hidden by default. Labels show elevation in meters or feet depending on the scale bar setting (click the scale bar to toggle).

Terrain layers are hidden by default to keep the map clean. Enable them in the Layer Control when you need elevation information.

Global Search

Map places also appear in WROLPi's global search. When you search from the navigation bar:

• The Map tab shows the number of matching map places alongside Files, Zims, and Other
• Clicking the Map tab displays results as cards with mini map previews showing each location
• Click a card to navigate to that location on the map page
• Results are paginated (12 per page) with the same region and population information