16 KiB
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. Overlays are listed here too.
- 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.6to 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 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
Search
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.dbextension. 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:
- WROLPi fetches the map manifest from the CDN and verifies its GPG signature
- A download is created for each subscribed region
- aria2c downloads the pre-extracted PMTiles file from the CDN
- After download, the meta4 file's GPG-signed hash is verified to ensure the file is authentic and untampered
- The file is placed in your map directory with a versioned filename
(e.g.,
us-west-20260329.pmtiles) - 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
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.
Overlays
An overlay is any PMTiles file in your map directory that is not a basemap or a terrain file: power lines, towers, trails, flood zones, satellite imagery, or anything else you have as vector or raster tiles. Overlays are drawn on top of the basemap.
To add an overlay, put the .pmtiles file in the map directory (or a sub-directory of it). No restart
is needed; reload the map.
Showing an Overlay
Overlays are listed in the Overlays section of the Layer Control, under the basemap layers. Each overlay is named by the name stored inside the file, or by its file name when it has none.
To show an overlay, open the Layer Control and check the overlay's box. A new overlay is hidden until you check it.
- A vector overlay has an arrow beside it. Click the arrow to list the layers inside the file, each with its own checkbox, and All / None to check or clear them together.
- A layer of something the basemap already draws (roads, water, buildings, place names, and so on) starts unchecked, so the map is not drawn twice. Check the layer if you want the overlay's version of it.
- A raster overlay (imagery) is a single layer. It is drawn beneath the basemap's labels so place names stay readable.
- The zoom levels the file has tiles for are shown beside its name (e.g.
z0–13). - Click a feature of a vector overlay to see its attributes.
Your choices are saved in your browser, so each browser and device remembers its own.
An overlay which you never want to see can be ignored entirely with its Visible toggle on the Manage tab.
How an Overlay Is Drawn
A PMTiles file contains shapes and their attributes, but not how they should look. Without a style, WROLPi draws each layer of a vector overlay in its own color — areas as translucent fills, lines as lines, and points as dots — and shows that color beside the layer's checkbox.
Overlay Styles
To control how an overlay looks, put a MapLibre style beside the file. The Manage tab then lists the file as Overlay (styled).
| Style file | Applies to |
|---|---|
<name>.style.json |
The file <name>.pmtiles in the same directory. |
style.json |
Every .pmtiles file in the same directory which has no style of its own. |
For example, map/extras/style.json styles both map/extras/roads.pmtiles and
map/extras/towers.pmtiles.
The style can be one written for another map. WROLPi uses only what is safe and meaningful offline:
- Only the layers which draw that file are used. The style's background, and layers which draw other data (hillshade, contours, another tile set), are left out.
- Nothing is fetched from another address. The tile, icon and font addresses in the style are never used.
- Fonts are replaced with the fonts WROLPi has (Noto Sans regular, medium and italic).
- Icons are replaced with WROLPi's icons.
- Patterns (textured fills such as marsh or sand) are drawn as a translucent color.
- A layer the map cannot draw is skipped, and the Layer Control says how many were skipped. The rest of the overlay is still drawn.
A styled overlay lists only the layers its style draws.
Two optional settings can be added to the style's metadata:
| Setting | What it does |
|---|---|
wrolpi:minzoom |
The overlay is only drawn from this zoom level in. Use this for a style designed for one scale (a printed map, for example), which is unreadable when zoomed out. |
wrolpi:source |
The name of the style's source which is this file. Only needed when WROLPi picks the wrong one; it normally picks the source most of the matching layers use. |
{
"version": 8,
"metadata": {"wrolpi:minzoom": 11},
"sources": {"features": {"type": "vector", "url": "..."}},
"layers": [
{
"id": "towers",
"type": "symbol",
"source": "features",
"source-layer": "towers",
"layout": {"icon-image": "tower", "text-field": ["get", "name"]}
}
]
}
A style written for a whole map paints its own land, water and roads, so it covers the basemap beneath it. Uncheck the layers you do not want, or the basemap layers they duplicate.
Overlay Icons
WROLPi comes with over 700 map icons (the Maki and Temaki sets, both in the public domain) and draws these wherever an overlay's style asks for an icon. The icons a style was originally made for are not needed and are not used; a sprite sheet beside the file is ignored.
An icon is matched by the name the style uses for it:
- The icon's own name, with underscores or hyphens:
fire_stationandfire-stationare the same icon. - Other common names for it:
ham_radioandrepeaterare the antenna,post_officeis the post icon,campgroundis the campsite, and so on. - A name WROLPi has no icon for is drawn as a plain dot, so the feature is still marked.
Icons take the color and outline the style gives them. Without a color they are dark with a light outline, so they can be seen on both the light and dark maps. A style's icon size is ignored; WROLPi's icons are all drawn at one size.
Standalone Map Viewer
WROLPi also serves the map by itself on port :8084 (https://your-wrolpi:8084), which keeps working
when the main app is unavailable. It shows the same overlays, styles and icons, in the same
Overlays section of its layer panel. Its choices are remembered separately from the main map's.
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
