Map: exporting a map as a PDF, and a page for each part of the map

The Map page is five pages: the map itself, its files, terrain, overlays, and the new PDF export.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Roland 2026-11-20 17:11:05 -07:00
parent deda0b7ce7
commit 0fbbf18253
No known key found for this signature in database
GPG key ID: 1BA620CE6C9A4680
11 changed files with 429 additions and 282 deletions

123
docs/modules/map/export.md Normal file
View file

@ -0,0 +1,123 @@
# Exporting a Map as a PDF
WROLPi can make a PDF of your map to print or to carry on a phone: one 7.5-minute quadrangle at
1:24,000, the size and scale of a USGS topographic sheet. The PDF is made on your WROLPi from the
map files you already have, so it works without the Internet.
![A finished sheet](map-export-sheet.png)
## Making a PDF
> To export a map, click the printer button at the top-right of the map, click the quadrangle you
> want, and click **Export PDF**.
![Choosing a quadrangle to export](map-export-pdf.png)
1. Click the **printer** button. A grid of quadrangles is drawn over the map. If you see
"Zoom in to see the quadrangles", zoom in until the grid appears.
2. Click a quadrangle. The picker shows its name, its southwest corner, and how large it is on the
ground and on paper.
3. Choose your options (below) and click **Export PDF**.
4. WROLPi draws the map, sends it to your WROLPi, and builds the PDF. When it is done your browser
saves the file, named for the quadrangle (e.g. `wrolpi-map_24k_Berthoud_N40.250_W105.125.pdf`).
**Cancel** stops an export at any point. Leaving the map page stops it too.
The PDF shows **what is turned on in the Layer Control**: turn off Buildings and they are not in the
PDF; turn on Contours, Hillshade or an [overlay](overlays.md) and they are.
| Option | What it does |
|--------|--------------|
| **Margins, grid and scale bars** | Puts the map on a sheet (see [What Is on the Sheet](#what-is-on-the-sheet)). Uncheck it to export the map alone, edge to edge. |
| **300 DPI** / **400 DPI** | How sharp the map is. 300 is sharp on paper. 400 is sharper, takes longer, and makes a larger file. |
| **Print** / **Light** / **Dark** | The colors of the map. **Print** is made for paper. **Light** and **Dark** are the maps you see on a screen, for a PDF you will only read on one. |
> While the picker is open the map on your screen is shown in the colors you chose, so what you see
> is what you will get. It goes back to your theme when you close the picker.
Making a PDF takes a minute or two on a Raspberry Pi 4 at 300 DPI, and about three minutes at
400 DPI. The status under the options says how far along it is. If the map can not be made as sharp
as you asked (a browser limits how large a map it will draw), the status says what it is being
drawn at, e.g. "at 330 DPI".
## Print Colors
The maps you see on a screen are made to be lit from behind: pale roads on a pale ground. On paper
they are nearly invisible. The **Print** colors are made for paper: a white ground, roads with dark
edges, dark names, blue streams wide enough to see, and paths and tracks drawn as broken lines.
You can choose the colors yourself. While the picker is open and **Print** is chosen, open the
**Layer Control**: each layer has its color beside it.
> To change a color of the printed map, click the color beside a layer in the Layer Control and
> pick another. The map changes as you choose.
- Most layers have one color. **Land Cover** has three (parks and woods; schools, hospitals and
industry; sand and ice) and **Labels** has two (the name, and the halo around it).
- Streams, rivers and the names of water are drawn in a darker shade of the color you choose for
**Water**, so a thin line can still be seen.
- The dark edge of a road is not chosen; it is what makes a road a line on paper.
- **Reset colors**, under the layers, puts the colors back. It is shown once you have changed one.
Your colors, and whether you last exported in Print, Light or Dark, are saved in your browser, so
each browser and device remembers its own.
> An overlay with a [style](overlays.md#overlay-styles) of its own keeps its own colors, which were made for a
> screen. Check how it looks in the Print colors before you print.
## What Is on the Sheet
![The margin of a sheet](map-export-margin.png)
| Part | What it shows |
|------|---------------|
| **Title** | What the USGS calls the quadrangle, and the scale. Outside the United States, where there is no such name, the title is the coordinates of the southwest corner. |
| **Corners and ticks** | The latitude and longitude of each corner, and ticks every 2.5 minutes between them. |
| **UTM grid** | A 1,000 meter grid in blue, with its eastings and northings in the margin. The grid is not drawn north of 84° or south of 80°, where there are no UTM zones. |
| **Scale bars** | Kilometers, meters, miles and feet. |
| **Norths** | A diagram of true north (the star), grid north (GN) and magnetic north (MN), each with its angle in degrees and in mils. |
| **Contour interval** | How far apart the contour lines are, when Contours are on. It is in feet or meters, whichever the scale bar of your map is set to. |
| **Adjoining quadrangles** | The names of the eight quadrangles around this one (United States only). |
| **Legend** | The lines of the map as they are drawn on this sheet: roads, paths, railways, boundaries and contours. |
| **Notes** | The scale, projection and datum, the grid zone, magnetic declination and the date it is for, where the map data is from, and the day the sheet was made. |
A few things to know:
- **Scale.** The sheet is 1:24,000 at the middle of the map. The map is drawn in the Web Mercator
projection, like the map on your screen.
- **Magnetic north** is calculated for the day you export, from the World Magnetic Model
(WMM2025), which is good from 2025 through 2029. A sheet made after that does not show magnetic
north. Magnetic north moves; the note says how much each year.
- **Alaska.** USGS quadrangles in Alaska are wider than 7.5 minutes, so a sheet there is named
"Part of ..." the quadrangle it is in.
- **Paper.** A sheet is larger than office paper: about 19 by 29 inches (48 by 73 cm) at 40°
north, and narrower further north (12.5 by 29 inches at 61°). Print it on a large-format printer, or use your PDF
reader's "poster" or "tile" printing to print it across several pages at 100% scale.
## Layers in the PDF
Each layer of the Layer Control, and each overlay, is a layer of the PDF, as are the **UTM grid** and
the **Sheet** (the margin). A PDF reader which shows layers (Adobe Acrobat, for one) can turn each
on and off: print the same file with or without buildings, contours or the grid.
## Using the PDF With GPS
The PDF is georeferenced: it says where on the Earth it is. An app which reads georeferenced PDFs
can show your position on it, or lay it over its own map.
| App | Result |
|-----|--------|
| **Adobe Acrobat** (desktop) | Works. **All tools > Measure > Geospatial Location Tool** shows the latitude and longitude under the pointer; right-click the map for **Mark Location**. |
| **iTAK** (iPhone) | Works. The imported PDF is laid over the app's map in the right place. |
| **GDAL** | Works (`gdalinfo` reports the corners of the sheet). |
A place on the sheet is where the PDF says it is to within a few centimeters. How well your phone
knows where *it* is is a much larger error than that.
## Limits
- One scale (1:24,000) and one quadrangle a PDF.
- The names of roads, places and water are part of the picture: they can not be searched or
selected in the PDF.
- Streams are not drawn north of about 65°, where the map files do not have them at this scale.
- The [Standalone Map Viewer](index.md#standalone-map-viewer) can not export.

140
docs/modules/map/files.md Normal file
View file

@ -0,0 +1,140 @@
# Map Files
The map is drawn from PMTiles files in the map directory of your media directory (`map/`). This page
covers getting those files, how WROLPi decides what each one is, and managing them on the Map's
**Manage** tab.
## 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](#special-file-names) and [Overlays](overlays.md). |
| **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`.
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.
## How a Subscription Downloads
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
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.md). 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](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. |
| Any other basemap | Regional vector tiles. Multiple regional files render together on the map. |
| Any other file | An [overlay](overlays.md). |
> 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](https://maps.protomaps.com/builds/) 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:
```shell
# 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](https://maps.protomaps.com/builds/).
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.

View file

@ -6,16 +6,27 @@ in the browser using your device's GPU, providing fast and smooth navigation wit
The module is powered by [Protomaps](https://protomaps.com/) — an open-source system for
self-hosting vector maps from a single PMTiles file.
## More About the Map
| Page | What it covers |
|------|----------------|
| [Map Files](files.md) | Getting map files, subscriptions, the Manage tab, and how file names are handled. |
| [Terrain](terrain.md) | Hillshade and contour lines. |
| [Overlays](overlays.md) | Drawing your own data over the map: power lines, trails, imagery, and their styles and icons. |
| [Exporting a Map as a PDF](export.md) | Printing a 1:24,000 topographic sheet, or carrying it on a phone. |
## 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](#overlays) are listed here too.
land cover, boundaries, labels, [hillshade, contours](terrain.md), and more. Your choices are saved
between sessions. [Overlays](overlays.md) 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.
- **Export** (top-right, the printer) — Make a PDF of a 1:24,000 topographic sheet. See
[Exporting a Map as a PDF](export.md).
- **Scale Bar** (bottom-left) — Distance scale. Click to toggle between metric and imperial.
- **Dark/Light Mode** — The map automatically matches your WROLPi theme.
@ -26,6 +37,8 @@ Right-click (or long-press on mobile) anywhere on the map to open the context me
- **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.
- **Export a 1:24,000 map** — Start a [PDF export](export.md) with the quadrangle
you clicked already chosen.
- **Add Pin** — Place a named pin at that location.
### Sharing Coordinates
@ -79,284 +92,7 @@ The Pins tab shows a table of all your pins with:
## 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](#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`.
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
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` | 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. |
| 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
### 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](https://maps.protomaps.com/builds/) 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:
```shell
# 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](https://maps.protomaps.com/builds/).
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](https://mapterhorn.com/data-access/)
### 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.
![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 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](#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.
The Manage tab lists your map files and your map subscriptions. See [Map Files](files.md).
## Global Search
@ -366,3 +102,9 @@ Map places also appear in WROLPi's global search. When you search from the navig
- 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
## 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 map files, [overlays](overlays.md), styles and icons, with its own layer panel. Its
choices are remembered separately from the main map's. It can not [export a PDF](export.md).

Binary file not shown.

After

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 798 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 331 KiB

View file

@ -0,0 +1,112 @@
# 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 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](files.md#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.

View file

@ -0,0 +1,26 @@
# Terrain
The map supports hillshade and contour overlays when a terrain file is available.
## Downloading
You can download map terrain files from [Mapterhorn](https://mapterhorn.com/data-access/)
## 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](files.md#map-subscriptions) 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.