Document map overlays, their styles and icons, and ignoring a map file

The map draws any PMTiles file which is not a basemap as an overlay, from
any sub-directory of the map directory.  Document the Overlays section of the
Layer Control, how an overlay is drawn, the style which can sit beside a file
and what WROLPi takes from it, WROLPi's own icons and how a style's names
match them, the Type and Visible columns of the Manage tab, and maps.yaml.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Roland 2026-11-13 18:23:14 -07:00
parent 9cf3296b12
commit 5e7771adf7
No known key found for this signature in database
GPG key ID: 1BA620CE6C9A4680
3 changed files with 161 additions and 7 deletions

View file

@ -12,7 +12,7 @@ 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.
between sessions. [Overlays](#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.
@ -83,10 +83,39 @@ 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.
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.
The **Search** column shows whether a search index exists for each file:
| 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](#special-file-names) and [Overlays](#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](../../system/configs.md)) as their
paths within the map directory. Deleting a file also removes it from `maps.yaml`.
```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`.
@ -129,15 +158,23 @@ When you subscribe to a region:
## Special File Names
The map viewer detects certain file name patterns and handles them differently:
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](#overlays). 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` | Full planet file — used as the sole vector source. Regional extracts and the planet overview are skipped. |
| `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](https://maps.protomaps.com/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. |
| Any other basemap | Regional vector tiles. Multiple regional files render together on the map. |
| Any other file | An [overlay](#overlays). |
> 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
@ -202,6 +239,122 @@ Once a terrain file is detected, two additional layer groups appear in the Layer
> 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.
![The Overlays section of the Layer Control](map-overlays.png)
> 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 **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](#visible).
### How an Overlay Is Drawn
A PMTiles file contains shapes and their attributes, but not how they should look. Without a
[style](#overlay-styles), 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](https://maplibre.org/maplibre-style-spec/)
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](#overlay-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. |
```json
{
"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](https://github.com/mapbox/maki) and
[Temaki](https://github.com/rapideditor/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_station` and `fire-station` are the same icon.
- Other common names for it: `ham_radio` and `repeater` are the antenna, `post_office` is the post
icon, `campground` is 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:

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

View file

@ -26,6 +26,7 @@ All configs are stored in the `config` directory of your media directory: `/medi
| `archives_downloader.yaml` | Archive downloader settings. |
| `download_cache.yaml` | Cached video durations (safe to ignore). |
| `map_pins.yaml` | Your [Map](../modules/map/index.md) pins. |
| `maps.yaml` | The [Map](../modules/map/index.md) files the map ignores (the Visible toggle on the Map's Manage tab). |
| `bookmarks.yaml` | Your [Bookmarks](../modules/bookmarks/index.md), including their directories and order. |
| `recently_viewed.yaml` | Your 1,000 most recently viewed files, and [where you left off](viewing-progress.md) in each. |
| `inventory/*.yaml` | One file per [Inventory](../modules/inventory/index.md), plus the food catalog. |