mirror of
https://github.com/wrolpi/wrolpi-help.git
synced 2026-11-20 23:16:20 -05:00
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:
parent
deda0b7ce7
commit
0fbbf18253
11 changed files with 429 additions and 282 deletions
|
|
@ -26,7 +26,7 @@ The Download menu offers a form for each kind of download:
|
|||
|
||||
**Warning!** Scraping can be exponential — each level of depth can multiply the number of pages visited.
|
||||
|
||||
[Zim subscriptions](../zim/index.md) and [Map subscriptions](../map/index.md) also create recurring downloads; they
|
||||
[Zim subscriptions](../zim/index.md) and [Map subscriptions](../map/files.md#map-subscriptions) also create recurring downloads; they
|
||||
are managed from their own pages but appear in the Downloads page like everything else.
|
||||
|
||||
## Once vs Recurring
|
||||
|
|
|
|||
123
docs/modules/map/export.md
Normal file
123
docs/modules/map/export.md
Normal 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.
|
||||
|
||||

|
||||
|
||||
## 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**.
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
| 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
140
docs/modules/map/files.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
||||

|
||||
|
||||
> 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).
|
||||
|
|
|
|||
BIN
docs/modules/map/map-export-margin.png
Normal file
BIN
docs/modules/map/map-export-margin.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
BIN
docs/modules/map/map-export-pdf.png
Normal file
BIN
docs/modules/map/map-export-pdf.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 798 KiB |
BIN
docs/modules/map/map-export-sheet.png
Normal file
BIN
docs/modules/map/map-export-sheet.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 331 KiB |
112
docs/modules/map/overlays.md
Normal file
112
docs/modules/map/overlays.md
Normal 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.
|
||||
|
||||

|
||||
|
||||
> 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.
|
||||
26
docs/modules/map/terrain.md
Normal file
26
docs/modules/map/terrain.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue