mirror of
https://github.com/wrolpi/wrolpi-help.git
synced 2026-11-19 22:46:23 -05:00
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:
parent
9cf3296b12
commit
5e7771adf7
3 changed files with 161 additions and 7 deletions
|
|
@ -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.
|
||||
|
||||

|
||||
|
||||
> 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:
|
||||
|
|
|
|||
BIN
docs/modules/map/map-overlays.png
Normal file
BIN
docs/modules/map/map-overlays.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 97 KiB |
|
|
@ -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. |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue