diff --git a/docs/modules/map/index.md b/docs/modules/map/index.md index 70f601c..5b9eab6 100644 --- a/docs/modules/map/index.md +++ b/docs/modules/map/index.md @@ -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 | +|----------------------------|------------| +| `.style.json` | The file `.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: diff --git a/docs/modules/map/map-overlays.png b/docs/modules/map/map-overlays.png new file mode 100644 index 0000000..36049c0 Binary files /dev/null and b/docs/modules/map/map-overlays.png differ diff --git a/docs/system/configs.md b/docs/system/configs.md index f064f8a..5e3b58d 100644 --- a/docs/system/configs.md +++ b/docs/system/configs.md @@ -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. |