diff --git a/docs/index.md b/docs/index.md index d5148d3..afe3bf7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,6 +42,10 @@ Information about the parts of the WROLPi interface. * [SingleFile Extension](modules/archives/singlefile-extension.md) * [Docs](modules/docs/index.md) * [Map](modules/map/index.md) + * [Map Files](modules/map/files.md) + * [Terrain](modules/map/terrain.md) + * [Overlays](modules/map/overlays.md) + * [Exporting a Map as a PDF](modules/map/export.md) * [Zim](modules/zim/index.md) * [Repos](modules/repos/index.md) * [Bookmarks](modules/bookmarks/index.md) diff --git a/docs/modules/downloads/index.md b/docs/modules/downloads/index.md index f7d8ed8..76f4f22 100644 --- a/docs/modules/downloads/index.md +++ b/docs/modules/downloads/index.md @@ -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 diff --git a/docs/modules/map/export.md b/docs/modules/map/export.md new file mode 100644 index 0000000..8e0cf29 --- /dev/null +++ b/docs/modules/map/export.md @@ -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. diff --git a/docs/modules/map/files.md b/docs/modules/map/files.md new file mode 100644 index 0000000..3f2ac07 --- /dev/null +++ b/docs/modules/map/files.md @@ -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. diff --git a/docs/modules/map/index.md b/docs/modules/map/index.md index d442ebf..33a76b5 100644 --- a/docs/modules/map/index.md +++ b/docs/modules/map/index.md @@ -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 | -|----------------------------|------------| -| `.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. +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). diff --git a/docs/modules/map/map-export-margin.png b/docs/modules/map/map-export-margin.png new file mode 100644 index 0000000..39bc0cb Binary files /dev/null and b/docs/modules/map/map-export-margin.png differ diff --git a/docs/modules/map/map-export-pdf.png b/docs/modules/map/map-export-pdf.png new file mode 100644 index 0000000..43cd8fc Binary files /dev/null and b/docs/modules/map/map-export-pdf.png differ diff --git a/docs/modules/map/map-export-sheet.png b/docs/modules/map/map-export-sheet.png new file mode 100644 index 0000000..cac6d53 Binary files /dev/null and b/docs/modules/map/map-export-sheet.png differ diff --git a/docs/modules/map/overlays.md b/docs/modules/map/overlays.md new file mode 100644 index 0000000..c1da927 --- /dev/null +++ b/docs/modules/map/overlays.md @@ -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 | +|----------------------------|------------| +| `.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. diff --git a/docs/modules/map/terrain.md b/docs/modules/map/terrain.md new file mode 100644 index 0000000..d2fdbc0 --- /dev/null +++ b/docs/modules/map/terrain.md @@ -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. diff --git a/docs/system/configs.md b/docs/system/configs.md index 77f7a3d..6471c93 100644 --- a/docs/system/configs.md +++ b/docs/system/configs.md @@ -26,7 +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). | +| `maps.yaml` | The [Map](../modules/map/files.md#visible) files the map ignores (the Visible toggle on the Map's Manage tab). | | `sync.yaml` | This WROLPi's [Sync](sync.md) role, its primary, its sync window, and its [Backup](backup.md) drive. Never copied to a secondary. | | `sync_state.yaml` | When the last [Sync](sync.md) ran and what it did. Written by the Controller. | | `bookmarks.yaml` | Your [Bookmarks](../modules/bookmarks/index.md), including their directories and order. |