pmtiles-swarm 0.102.0 → 0.103.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.103.0
+### ✨ Features and improvements
+- **Elevation at a coordinate.** `GET /stacks/<id>/elevation?lon=&lat=&zoom=` answers the height
+  under a point, and `POST` of `{"points": [...]}` answers up to a thousand of them in the order
+  asked. The same two under `/archives/<infohash>/` and `/latest/<category>/`, since an archive of
+  terrain is already heights.
+
+  The shape follows tileserver-gl's endpoint deliberately, so a client written against that keeps
+  working — see [NOTICE.md](NOTICE.md). What differs is that `"elevation": null` is an answer: the
+  height is read from the `Float32Array` a stack merges, where a hole is `NaN`, so "there is no data
+  here" and "this is at sea level" stay different answers. Anything reading encoded pixels has to
+  invent a height for ground nothing covers, because every triple of bytes in a terrain tile is one.
+
+  Points are grouped by the tile they fall in and each tile is read once, so a track down one valley
+  costs the few merges its tiles are worth rather than one per point.
+
+- **Contour endpoints describe themselves.** `GET /stacks/<id>/contours/tiles.json`, and the same
+  under `/archives/` and `/latest/`. The zoom range is the thresholds' rather than the source's: a
+  stack with ground from z0 draws its first line at z9, and a client told otherwise spends eight
+  zooms of requests on tiles that can only answer 404.
+
+- **Hillshade and contours can be switched off in the preview.** Two boxes in the header, for the
+  layers that page actually drew. Not only cosmetic for the contours: MapLibre stops fetching from a
+  source once no visible layer draws from it, so unticking the box really does stop the nine merges
+  each contour tile costs. The contour link is gone from the console and the catalogue with it —
+  a hidden layer never asks its source for a tile, so there was nothing left for a separate page to
+  save. `?contours=1` still works, now as the box's starting state, and the box keeps it current so
+  the lines survive the raw/terrain switch.
+
+- **Terrain has its own document.** [docs/terrain.md](docs/terrain.md) covers the encodings,
+  contours and elevation across all three ways terrain is served. They were under tile stacks, which
+  stopped being true once the same endpoints answered for an archive and a category.
+
+### 🐞 Bug fixes
+- **An archive or category elevation reading ignored the archive's zoom range.** The summary
+  spells it `minZoom`/`maxZoom` and everything downstream reads the TileJSON spelling, so passing
+  the summary straight through left both undefined and every reading clamped to a hardcoded
+  0-14. An archive stopping at z8 was read at z14, where it has no tile, and answered `null` for
+  ground it covers. Caught before release; the stack path was never affected, since it takes its
+  range from the resolved recipe.
+
 ## 0.102.0
 ### ✨ Features and improvements
 - **Hillshade and contours can be switched off in the preview.** Two boxes in the header, shown only
@@ -43,7 +84,7 @@
   Worth knowing what it costs: a contour tile is traced from its own tile **plus its eight
   neighbours**, because a line crossing an edge has to be traced from the ground on both sides or it
   will not meet the line next door. Roughly nine merged terrain tiles each. See
-  [tile-stacks.md](docs/tile-stacks.md) — "Contours from a stack".
+  [terrain.md](docs/terrain.md) — "Contours".
 
   A **Contours** button sits beside Preview and Terrain on any stack that draws as terrain, and the
   preview draws the lines over the hillshade rather than instead of it — a contour on its own says

package/NOTICE.md

@@ -80,6 +80,30 @@ Mapbox's.
 No code is copied either way. `src/elevation.js` and `src/rgba.js` are JavaScript written against
 the same rules, and `docs/tile-stacks.md` records where those rules differ from the fork's and why.
 
+## TileServer GL — BSD-2-Clause
+
+> Copyright (c) 2023, MapTiler.com
+> Copyright (c) 2016, Klokan Technologies GmbH
+> https://github.com/maptiler/tileserver-gl
+
+The elevation endpoints follow tileserver-gl's. `src/elevation-lookup.js` implements the same
+Web Mercator projection as its `lonLatToTilePixel` — including the `±0.9999` clamp on `sin(lat)`,
+which is where it cuts a projection that sends the poles to infinity — and the endpoints keep its
+request and response shapes: a `GET` for one reading, a `POST` of `{points: [...]}` answered by a
+plain array in the order asked, and `long`/`lat`/`elevation`/`z`/`x`/`y`/`pixelX`/`pixelY` in the
+body. That is deliberate, so a client written against tileserver-gl keeps working.
+
+Two things are ours and differ. The height is read from the `Float32Array` a stack merges rather
+than from one archive's pixels, so masks, clips and layer priority all apply — and a hole is
+`NaN`, which is reported as `"elevation": null`. Anything reading encoded pixels has to return a
+height for every coordinate, because every triple of bytes in a terrain tile is one; this can say
+there is no data. Following from that, a point with no data answers `200` with a null elevation
+rather than tileserver-gl's `204`, since the tile and pixel it looked at are still worth reporting
+and a `204` has no body to put them in.
+
+No code is copied: `src/elevation-lookup.js` is written against the same rules. See
+[docs/terrain.md](docs/terrain.md) — "Elevation at a point".
+
 ## qBittorrent — GPL-2.0-or-later
 
 > https://github.com/qbittorrent/qBittorrent

package/README.md

@@ -810,6 +810,9 @@ which the endpoint answers 501.
 | `POST` | `/api/stacks/:id/import` | Import a provider's list of PMTiles URLs as sources on this stack. An index with an `items` list, or a plain list of addresses; `dryRun` says what it would write without writing it |
 | `POST`, `DELETE` | `/api/stacks/:id/bake` | Run the stack over its sources and write the result as an archive, or stop one that is running. Answers as soon as the job starts; watch it on `/api/stacks` |
 | `GET` | `/stacks/:id/preview` | A map of a stack, for looking at it — **public** |
+| `GET` | `/stacks/:id/contours/{z}/{x}/{y}.pbf`, `/archives/:infoHash/contours/…`, `/latest/:category/contours/…` | Contour lines traced from merged heights, as a vector tile — **public**. `?interval=` or `?thresholds=` overrides what the recipe names |
+| `GET` | `/stacks/:id/contours/tiles.json`, and the same under `/archives/:infoHash/` and `/latest/:category/` | What the contour endpoint covers — **public**. The zoom range is the thresholds', not the source's: a stack with ground from z0 draws its first line at z9 |
+| `GET`, `POST` | `/stacks/:id/elevation`, `/archives/:infoHash/elevation`, `/latest/:category/elevation` | The height under a coordinate — **public**. `GET ?lon=&lat=&zoom=` for one reading; `POST {"points": [...]}` for up to 1000, answered in the order asked. `"elevation": null` means no data there, which an encoded tile cannot express. Follows tileserver-gl's shape — see [docs/terrain.md](docs/terrain.md#elevation-at-a-point) |
 | `GET` | `/stacks/:id/tiles.json` | TileJSON for a stack — **public**. `maxzoom` is the maximum over its sources, not the minimum |
 | `GET` | `/stacks/:id/:size/:z/:x/:y.:ext` | The same tile at 256 or 512 px. A tile's coordinates are an extent rather than a pixel count, so this is the same ground on a finer or coarser grid |
 | `GET` | `/stacks/:id/:z/:x/:y.:ext` | One tile of a stack — **public**. Answered by the topmost source holding it; `X-Stack-Sources` says which were asked and what each said |

package/docs/terrain.md

@@ -0,0 +1,239 @@
+# Terrain
+
+Terrain is a raster tile whose pixels are a packed elevation rather than a
+colour. `pmtiles-swarm` serves it three ways -- one archive, the newest build in
+a category, or a stack merged from several -- and everything in this document
+works the same across all three, because all three end up handing over the same
+thing: metres in a `Float32Array`, with `NaN` where nothing covered the ground.
+
+That last part is why these endpoints live here rather than being left to a
+client. An encoded terrain tile cannot say "no data": every triple of bytes is a
+height, so a reader has to invent one for ground nothing covers, and the usual
+invention is the encoding's base -- which reads as -10000 m or as sea level
+depending on which convention wrote the file. Decoding to heights first means a
+hole stays a hole all the way to the answer.
+
+- [Encodings](#encodings)
+- [Contours](#contours)
+- [Elevation at a point](#elevation-at-a-point)
+
+For how a stack merges several sources into one surface -- layer priority,
+masking, feathering, nested stacks -- see [tile-stacks.md](tile-stacks.md).
+
+## Encodings
+
+Three, and an archive states which in its own metadata:
+
+| Encoding    | Height from a pixel                                            | Base                                          |
+| ----------- | -------------------------------------------------------------- | --------------------------------------------- |
+| `mapbox`    | `-10000 + (R * 256 * 256 + G * 256 + B) * 0.1`                 | `#000000` is -10000 m; sea level is `#0186a0` |
+| `terrarium` | `(R * 256 + G + B / 256) - 32768`                              | `#800000` is 0 m                              |
+| `custom`    | `R * redFactor + G * greenFactor + B * blueFactor - baseShift` | whatever the four factors say                 |
+
+All three are the same formula: `encodingFactors` in `src/elevation.js` derives
+the four factors for the named ones rather than branching on the name, so
+`custom` is not a separate code path. Note that `baseShift` is **subtracted**,
+following MapLibre's style-spec — a `mapbox` config writing `baseVal: -10000` is
+the same quantity spelled with the opposite sign.
+
+A `custom` archive that does not carry all four factors is unreadable as
+terrain by anything, this node included, and is drawn as an ordinary raster
+instead -- the preview says so rather than showing a plausible-looking wrong
+map.
+
+The `#0186a0` above is worth keeping in mind when reading a stack recipe (only
+a stack masks; an archive is read as written): a
+`mapbox` source whose nodata was written as its base is black, so it masks with
+`maskColors: ["#000000"]` or with `maskValues: [-10000]`, while one whose nodata
+was written as zero metres masks with `maskValues: [0]`. Those are different
+files and the same-looking recipe does different things to each.
+
+## Contours
+
+    GET /stacks/<id>/contours/{z}/{x}/{y}.pbf
+    GET /archives/<infohash>/contours/{z}/{x}/{y}.pbf
+    GET /latest/<category>/contours/{z}/{x}/{y}.pbf
+
+A contour tile is traced from heights rather than from an encoded terrain tile,
+and where those heights come from is the interesting part.
+
+All three read through the same tracer. What differs is what supplies the
+heights: a stack merges its sources, applying everything its recipe says, while
+an archive and a category decode one file's pixels and nothing else — no recipe
+to resolve, no masks, no merge. **That difference decides how good the holes
+are**, which is the next section.
+
+A tool that reads archives has to answer "what is the elevation here?" for
+ground no archive covers, and an encoded terrain tile has no way to say
+"nothing" — every triple of bytes is some height. So it invents one. A constant
+beside real terrain is a **cliff**, and a cliff under a contour tracer comes out
+as lines packed arbitrarily tight along the seam. Filling with `-10000` rather
+than `0` only moves the cliff and makes it taller. That is not a fault in the
+tool; it is the shape of its input.
+
+Nothing here fills anything in. A tile that is absent is passed as `undefined`
+and reads as no-data, and `maplibre-contour` already understands that:
+`HeightTile.fromRawDem` maps anything invalid to `NaN`, the tracer skips it, and
+`combineNeighbors` answers `NaN` for a missing neighbour rather than throwing.
+So a line stops at the edge of the data instead of diving off a cliff.
+
+How much that buys you depends on the source, and the two cases are worth
+keeping apart:
+
+- **A stack** merges to `NaN` wherever nothing covered the ground — the same
+  property that lets one stack show through another — so a void _inside_ a
+  source's coverage is a hole too, provided the recipe masks it. That is what
+  `maskValues` and `maskColors` are for, and for contours they are load-bearing
+  rather than cosmetic.
+- **An archive or a category** is decoded as written. Every pixel of a tile that
+  exists is a finite height, including whatever the file used for nodata, so the
+  only hole available is a missing tile. An archive that void-filled its oceans
+  with its encoding base will draw contours across them, and there is no recipe
+  in the request to say otherwise. Point a stack at it if that matters.
+
+Where you want contours to run on past the coast, put a base under them in a
+stack — the merge is what makes them continuous, and `featherMetres` is what
+stops the seam between two sources becoming its own little cliff.
+
+### Nine tiles per tile
+
+A contour crossing a tile edge has to be traced from the ground on both sides,
+or it will not meet the line in the next tile. So a contour tile is drawn from
+its own tile plus its eight neighbours: **nine terrain tiles each**, asked for
+together rather than in turn.
+
+What those nine cost is the difference between the two paths. Over a stack each
+one is a full merge of every source, which is why a run of contour tiles is
+expensive; over an archive it is nine reads and nine decodes.
+
+Either way every one of those tiles is also wanted by a neighbouring contour
+tile, so a cache in front of the heights is what decides whether a run of these
+is affordable — not an optimisation to add later. Baking deliberately bypasses
+the merged-tile cache, which is right for terrain, where each tile is written
+once and never wanted again. It is not right here.
+
+### How far apart the lines go
+
+Per zoom, because one interval is wrong at both ends of a map: at z8 a 20 m
+contour is a band of ink, and at z15 a 500 m one is a blank tile through most of
+the world. A recipe says either a number, meaning that interval wherever
+contours are drawn at all, or a table of zoom to intervals. A request says the
+same through `?interval=` or `?thresholds=`, which is the only way to set them
+for an archive or a category, since neither has a recipe to write them in.
+Saying nothing gets a built-in table.
+
+Contours are a view of terrain rather than a property of it — the same ground is
+wanted at 10 m on a walking map and 100 m on an atlas — which is why the request
+can always override what the recipe says.
+
+A level may name more than one interval. `[100, 500]` draws a line every hundred
+metres and marks every fifth, and each feature carries `level` — how many of the
+intervals its height divides by, so 500 outranks 100. A style reads that to draw
+the major lines thicker and label only those, from one layer rather than two
+passes. The convention is `maplibre-contour`'s, so a style written against its
+tiles works against these.
+
+A zoom the table skips reads as the entry above it: a table naming 12 and 14
+means 12 and 13 share a setting. Below the shallowest entry nothing is drawn at
+all, and that is checked _before_ the nine merges — at z5 a tile is most of a
+continent, and nine merges is an expensive way to answer nothing.
+
+### What the endpoint claims
+
+    GET /stacks/<id>/contours/tiles.json
+    GET /archives/<infohash>/contours/tiles.json
+    GET /latest/<category>/contours/tiles.json
+
+The zoom range is the thresholds', not the source's. Terrain serving z0–z16
+draws no contours at z2, and a client told otherwise fetches empty tiles all the
+way down. It is never deeper than there is ground for either: a contour traced
+from an upscaled parent is the parent's line drawn twice as thick, not new
+detail.
+
+Worth pointing a source at rather than declaring a range by hand — that is what
+the preview does, and it is why the preview stops asking for tiles below the
+zoom the first line is drawn at.
+
+### Why the encoding is written here
+
+`maplibre-contour` has a vector tile encoder and does not export it, and
+`vt-pbf` — the obvious dependency — is built against `pbf` 3 while this tree
+resolves `pbf` 5, whose `Pbf` default export no longer exists. So `contour-mvt.js`
+writes the tile directly against `pbf` 5. It is narrow enough to be worth
+owning: one layer of line strings with two numeric properties, where a general
+encoder carries polygons, points, mixed property types and many layers.
+
+Heights are written in ascending order, so two runs over the same contours
+produce the same bytes whatever order the tracer closed its fragments in — which
+is what lets an export be resumed and a tile be keyed by content. A tile no
+contour crossed is no tile at all rather than an empty layer, which a client
+would pay to fetch and draw nothing from.
+
+`maplibre-contour` itself is loaded through `createRequire`: the published 0.1.0
+declares no `import` condition, so `import 'maplibre-contour'` fails outright.
+The fix is in upstream main and unreleased. A git dependency would push that
+requirement onto everyone installing this package, so the `require` path is
+taken instead, and becomes an ordinary import when a release carries the fix.
+
+## Elevation at a point
+
+Contours answer "where is 500 m?" across a tile. The elevation endpoints answer
+the other question — "how high is _here_?" — from the same heights, so whatever
+is true of one is true of the other.
+
+    GET  /stacks/<id>/elevation?lon=-3.1883&lat=55.9533&zoom=12
+    POST /stacks/<id>/elevation      {"points": [{"lon": …, "lat": …, "zoom": …}]}
+
+    GET  /archives/<infohash>/elevation?lon=…&lat=…&zoom=…
+    GET  /latest/<category>/elevation?lon=…&lat=…&zoom=…
+
+with `POST` on all three. A stack applies its recipe; an archive and a category
+decode one file, since terrain is already heights and needs no recipe to read
+one.
+
+The shape follows tileserver-gl's endpoint, deliberately, so a client written
+against that keeps working — see [NOTICE.md](../NOTICE.md). A single reading
+answers an object; a batch answers a plain array in the order asked.
+
+    {"long": -3.1883, "lat": 55.9533, "elevation": 78.2,
+     "z": 12, "x": 2010, "y": 1283, "pixelX": 91, "pixelY": 204}
+
+**`null` is an answer**, and how often you get one depends on the source. It
+means "no height here", never "zero". A client that treats the two as the same
+will put a track at sea level down a valley it has no data for.
+
+Over a stack a hole is anywhere the merge came out `NaN` — outside every
+source's coverage, or masked by the recipe. Over an archive or a category it is
+a missing tile and nothing else: every pixel of a tile that exists decodes to a
+finite number, including whatever the file wrote for nodata.
+
+That much cannot survive an encoded tile at all. Every triple of bytes in
+terrain-RGB is a height, so anything reading pixels has to invent one for ground
+nothing covers, and the usual invention is the encoding's base — which reads as
+−10000 m or as sea level depending on which convention wrote the file. Reading
+heights first is what keeps "there is no data here" and "this is at sea level"
+different answers.
+
+Two things are clamped rather than refused. The zoom is clamped into the range
+the source declares: asking for z18 of terrain that stops at z12 answers from
+z12, because past that there is no more detail, only a parent upscaled — so the
+`z` in the reply is not always the `z` in the request. And the pixel is clamped
+to the tile, because a coordinate exactly on the far edge rounds to one past the
+last pixel.
+
+That range comes from the recipe's coverage for a stack and from the archive's
+own header for the other two. Getting it from the wrong place is not a small
+bug: read at a zoom the source has no tile at, an archive answers `null` for
+ground it actually covers.
+
+Points are grouped by the tile they land in and each tile is read once, so a
+track of a thousand coordinates down one valley costs the handful of tiles it
+crosses rather than a thousand reads. That grouping is why the batch endpoint is
+worth having at all, and why it is capped at 1000 points — over a stack each
+distinct tile is a full merge, and a request should not be able to ask for
+hundreds of them by accident.
+
+The zoom matters more than it looks. It is not a level of detail to be picked
+generously: it decides which tile is read, and which sources a stack draws from
+can differ between zooms. The deepest zoom available is the default because that
+is where the best data is.

package/docs/tile-stacks.md

@@ -63,7 +63,6 @@ of its parts.
 - [Syncing a stack to another node](#syncing-a-stack-to-another-node)
 - [What the offline merge got wrong](#what-the-offline-merge-got-wrong)
 - [The stack editor](#the-stack-editor)
-- [Contours from a stack](#contours-from-a-stack)
 - [Merging vector sources](#merging-vector-sources)
 - [Staging](#staging)
 - [Open questions](#open-questions)
@@ -2321,94 +2320,6 @@ Debounced, and it should not follow the map past the stack's `maxzoom`: above
 that the client overzooms and there is nothing new to see, but the tiles are
 still requested and still composited.
 
-## Contours from a stack
-
-A contour tile is drawn from the heights a stack merges, not from an archive of
-terrain. That distinction is the whole reason to do it here.
-
-A tool that reads archives has to answer "what is the elevation here?" for
-ground no archive covers, and an encoded terrain tile has no way to say
-"nothing" — every triple of bytes is some height. So it invents one. A constant
-beside real terrain is a **cliff**, and a cliff under a contour tracer comes out
-as lines packed arbitrarily tight along the seam. Filling with `-10000` rather
-than `0` only moves the cliff and makes it taller. That is not a fault in the
-tool; it is the shape of its input.
-
-A stack has `NaN`, and `stackHeights` deliberately leaves its holes unfilled —
-the same property that lets one stack show through another. `maplibre-contour`
-already understands it: `HeightTile.fromRawDem` maps anything invalid to `NaN`,
-the tracer skips it, and `combineNeighbors` answers `NaN` for a neighbour that
-is missing altogether rather than throwing. So a tile the stack covers none of
-is passed as `undefined` and reads as no-data. Nothing is invented anywhere, and
-a line stops at the edge of the data instead of diving off a cliff.
-
-Where you want contours to run on past the coast, put a base under them — the
-merge is what makes them continuous, and `featherMetres` is what stops the seam
-between two sources becoming its own little cliff. For contours that feather is
-load-bearing rather than cosmetic.
-
-### Nine tiles per tile
-
-A contour crossing a tile edge has to be traced from the ground on both sides,
-or it will not meet the line in the next tile. So a contour tile is drawn from
-its own tile plus its eight neighbours: **roughly nine merged terrain tiles
-each**, asked for together rather than in turn.
-
-Every one of those is a tile some neighbouring contour tile also wants, so a
-cache in front of the merge is what decides whether a run of these is affordable
-— not an optimisation to add later. Baking deliberately bypasses the merged-tile
-cache, which is right for terrain, where each tile is written once and never
-wanted again. It is not right here.
-
-### How far apart the lines go
-
-Per zoom, because one interval is wrong at both ends of a map: at z8 a 20 m
-contour is a band of ink, and at z15 a 500 m one is a blank tile through most of
-the world. A recipe says either a number, meaning that interval wherever
-contours are drawn at all, or a table of zoom to intervals. Saying nothing gets
-a built-in table.
-
-A level may name more than one interval. `[100, 500]` draws a line every hundred
-metres and marks every fifth, and each feature carries `level` — how many of the
-intervals its height divides by, so 500 outranks 100. A style reads that to draw
-the major lines thicker and label only those, from one layer rather than two
-passes. The convention is `maplibre-contour`'s, so a style written against its
-tiles works against these.
-
-A zoom the table skips reads as the entry above it: a table naming 12 and 14
-means 12 and 13 share a setting. Below the shallowest entry nothing is drawn at
-all, and that is checked _before_ the nine merges — at z5 a tile is most of a
-continent, and nine merges is an expensive way to answer nothing.
-
-### What the endpoint claims
-
-The zoom range is the thresholds', not the stack's. A stack serving z0–z16 draws
-no contours at z2, and a client told otherwise fetches empty tiles all the way
-down. It is never deeper than the stack has ground for either: a contour traced
-from an upscaled parent is the parent's line drawn twice as thick, not new
-detail.
-
-### Why the encoding is written here
-
-`maplibre-contour` has a vector tile encoder and does not export it, and
-`vt-pbf` — the obvious dependency — is built against `pbf` 3 while this tree
-resolves `pbf` 5, whose `Pbf` default export no longer exists. So `contour-mvt.js`
-writes the tile directly against `pbf` 5. It is narrow enough to be worth
-owning: one layer of line strings with two numeric properties, where a general
-encoder carries polygons, points, mixed property types and many layers.
-
-Heights are written in ascending order, so two runs over the same contours
-produce the same bytes whatever order the tracer closed its fragments in — which
-is what lets an export be resumed and a tile be keyed by content. A tile no
-contour crossed is no tile at all rather than an empty layer, which a client
-would pay to fetch and draw nothing from.
-
-`maplibre-contour` itself is loaded through `createRequire`: the published 0.1.0
-declares no `import` condition, so `import 'maplibre-contour'` fails outright.
-The fix is in upstream main and unreleased. A git dependency would push that
-requirement onto everyone installing this package, so the `require` path is
-taken instead, and becomes an ordinary import when a release carries the fix.
-
 ## Merging vector sources
 
 **Not built.** This is the design, written down before anything is started so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.102.0",
+  "version": "0.103.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/api.js

@@ -59,11 +59,13 @@ import {
 import { bakeRevision } from './bake.js';
 import zlib from 'node:zlib';
 import {
+  contourCoverage,
   contourTile,
   heightsFromArchive,
   heightsFromStack,
 } from './contour-tile.js';
 import { contourProblems } from './contour-options.js';
+import { elevationsAt, pointProblems } from './elevation-lookup.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
@@ -4175,7 +4177,7 @@ export function createApp({
    * nine merges a tile rather than one. Sharing a route would mean one set of
    * headers describing two things.
    *
-   * See docs/tile-stacks.md -- "Contours from a stack".
+   * See docs/terrain.md -- "Contours".
    */
   /**
    * Answers one contour tile, for whatever produced the resolution.
@@ -4288,7 +4290,7 @@ export function createApp({
    * nine merges a tile rather than one. Sharing a route would mean one set of
    * headers describing two things.
    *
-   * See docs/tile-stacks.md -- "Contours from a stack".
+   * See docs/terrain.md -- "Contours".
    */
   const serveStackContours = route(async (req, res) => {
     await stacks?.refresh();
@@ -4362,6 +4364,265 @@ export function createApp({
     });
   });
 
+  /**
+   * The height under a coordinate, from whatever provides the heights.
+   *
+   * The same `heightsAt` the contour routes are built on, for the same reason:
+   * a stack's merged `Float32Array` carries `NaN` where nothing covered the
+   * ground, so this can answer "no data" rather than inventing a height the
+   * way anything reading encoded pixels has to.
+   * @param {object} req - The request.
+   * @param {object} res - The response.
+   * @param {object} options - `points`, `coverage` and `heightsAt`.
+   * @returns {Promise<void>}
+   */
+  const answerElevation = async (req, res, options) => {
+    const codec = await loadCodec();
+    if (!codec) {
+      return res.status(501).json({
+        error:
+          'reading a height means decoding pixels, and this node has no codec',
+        hint: 'npm install sharp',
+      });
+    }
+
+    const wrong = pointProblems(options.points);
+    if (wrong.length) return res.status(400).json({ error: wrong.join('; ') });
+
+    const controller = new AbortController();
+    res.on('close', () => {
+      if (!res.writableEnded) controller.abort();
+    });
+
+    let found;
+    try {
+      found = await elevationsAt({
+        heightsAt: options.heightsAt(codec, controller.signal),
+        points: options.points,
+        minzoom: options.coverage.minzoom ?? 0,
+        maxzoom: options.coverage.maxzoom ?? 14,
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (error?.name === 'AbortError') return;
+      throw error;
+    }
+
+    res.setHeader('access-control-allow-origin', '*');
+    // Short-lived rather than immutable even for pinned content: this is a
+    // reading rather than a tile, and it is cheap to take again.
+    res.setHeader('cache-control', 'public, max-age=300');
+    return res.json(elevationBody(req, found));
+  };
+
+  /**
+   * The points one request is asking about.
+   *
+   * Two shapes, because there are two callers. A batch POSTs `{points: [...]}`
+   * -- a track, a route, a set of markers. A single reading is a GET with the
+   * coordinate in the query, which is what a browser's address bar and `curl`
+   * can both produce.
+   * @param {object} req - The request.
+   * @returns {unknown} - Whatever was asked for, for `pointProblems` to judge.
+   */
+  const pointsOf = (req) => {
+    if (req.method === 'POST') return req.body?.points;
+    const { lon, long, lat, zoom, z } = req.query;
+    return [{ lon: lon ?? long, lat, zoom: zoom ?? z }];
+  };
+
+  /**
+   * A single reading answers one object; a batch answers an array.
+   *
+   * The batch keeps tileserver-gl's shape, which is a plain array in the order
+   * asked -- see NOTICE.md. A GET for one point answering a one-element array
+   * would make every caller unwrap it.
+   * @param {object} req - The request.
+   * @param {object[]} found - What was read.
+   * @returns {object|object[]} - The body to send.
+   */
+  const elevationBody = (req, found) =>
+    req.method === 'POST' ? found : found[0];
+
+  /**
+   * What a contour endpoint covers, as a TileJSON.
+   *
+   * Worth serving rather than leaving a client to guess, because the zoom
+   * range is the thresholds' and not the source's: a stack with ground from z0
+   * draws its first line at z9 under the default table. A client told the
+   * source's range instead fetches nothing but 404s all the way down, and a
+   * map showing only contours looks broken rather than empty.
+   * @param {object} where - `root` for the URL, `name`, `coverage`, and the
+   *   `thresholds` that decide which zooms are drawn.
+   * @returns {object} - A TileJSON document.
+   */
+  const contourTileJson = ({ root, name, coverage, thresholds }) => {
+    const drawn = contourCoverage(coverage, thresholds);
+    return {
+      tilejson: '3.0.0',
+      scheme: 'xyz',
+      tiles: [`${root}/contours/{z}/{x}/{y}.pbf`],
+      name,
+      minzoom: drawn.minzoom,
+      maxzoom: drawn.maxzoom,
+      bounds: drawn.bounds,
+      // Named here because a vector source is unusable without them: a style
+      // needs the `source-layer`, and `level` is what draws the major lines
+      // thicker without a second layer.
+      vector_layers: [
+        {
+          id: 'contours',
+          fields: { ele: 'Number', level: 'Number' },
+        },
+      ],
+    };
+  };
+
+  app.get(
+    '/stacks/:id/contours/tiles.json',
+    route(async (req, res) => {
+      await stacks?.refresh();
+      const resolved = stackOr404(req, res);
+      if (!resolved) return;
+      if (resolved.stack.space === 'rgba') {
+        return res.status(400).json({
+          error: 'this stack is imagery, and a colour has no contours to trace',
+        });
+      }
+      res.setHeader('access-control-allow-origin', '*');
+      return res.json(
+        contourTileJson({
+          root: `${baseUrl(req)}/stacks/${encodeURIComponent(req.params.id)}`,
+          name: `${resolved.stack.title ?? resolved.stack.id} contours`,
+          coverage: stackCoverage(resolved),
+          thresholds: contourThresholdsFor(resolved.stack, req.query),
+        }),
+      );
+    }),
+  );
+
+  app.get(
+    '/archives/:infoHash/contours/tiles.json',
+    route(async (req, res) => {
+      const entry = catalog.get(req.params.infoHash);
+      if (!entry) return res.status(404).json({ error: 'unknown archive' });
+      if (!tracesAsTerrain(entry)) {
+        return res.status(400).json({
+          error: 'this archive is not terrain, so it has no heights to trace',
+        });
+      }
+      const doc = buildTileJson(entry, baseUrl(req));
+      res.setHeader('access-control-allow-origin', '*');
+      return res.json(
+        contourTileJson({
+          root: `${baseUrl(req)}/archives/${encodeURIComponent(entry.infoHash)}`,
+          name: `${doc.name ?? entry.name} contours`,
+          coverage: doc,
+          thresholds: contourThresholdsFor({}, req.query),
+        }),
+      );
+    }),
+  );
+
+  app.get(
+    '/latest/:category/contours/tiles.json',
+    route(async (req, res) => {
+      const entry = newestIn(req.params.category, req);
+      if (!entry) return res.status(404).json({ error: 'no such category' });
+      if (!tracesAsTerrain(entry)) {
+        return res.status(400).json({
+          error: 'this archive is not terrain, so it has no heights to trace',
+        });
+      }
+      const doc = buildTileJson(entry, baseUrl(req));
+      res.setHeader('access-control-allow-origin', '*');
+      return res.json(
+        contourTileJson({
+          root: `${baseUrl(req)}/latest/${encodeURIComponent(req.params.category)}`,
+          name: `${req.params.category} contours`,
+          coverage: doc,
+          thresholds: contourThresholdsFor({}, req.query),
+        }),
+      );
+    }),
+  );
+
+  const serveStackElevation = route(async (req, res) => {
+    await stacks?.refresh();
+    const resolved = stackOr404(req, res);
+    if (!resolved) return;
+    if (resolved.stack.space === 'rgba') {
+      return res.status(400).json({
+        error: 'this stack is imagery, and a colour has no height to read',
+      });
+    }
+    const points = pointsOf(req);
+    return answerElevation(req, res, {
+      points,
+      coverage: stackCoverage(resolved),
+      heightsAt: (codec, signal) =>
+        heightsFromStack({
+          resolved,
+          tiles,
+          codec,
+          cutlines,
+          signal,
+          heightsCache,
+        }),
+    });
+  });
+
+  const serveArchiveElevation = route(async (req, res) => {
+    const entry = catalog.get(req.params.infoHash);
+    if (!entry) return res.status(404).json({ error: 'unknown archive' });
+    if (!tracesAsTerrain(entry)) {
+      return res.status(400).json({
+        error: 'this archive is not terrain, so it has no heights to read',
+      });
+    }
+    return answerElevation(req, res, {
+      points: pointsOf(req),
+      // The summary spells these `minZoom`/`maxZoom`; everything downstream
+      // reads the TileJSON spelling. Passed straight through they were both
+      // undefined, so every reading clamped to 0-14 whatever the archive held.
+      coverage: {
+        minzoom: entry.pmtiles?.minZoom,
+        maxzoom: entry.pmtiles?.maxZoom,
+      },
+      heightsAt: (codec, signal) =>
+        heightsFromArchive({ entry, tiles, codec, signal, heightsCache }),
+    });
+  });
+
+  const serveCategoryElevation = route(async (req, res) => {
+    const entry = newestIn(req.params.category, req);
+    if (!entry) return res.status(404).json({ error: 'no such category' });
+    if (!tracesAsTerrain(entry)) {
+      return res.status(400).json({
+        error: 'this archive is not terrain, so it has no heights to read',
+      });
+    }
+    return answerElevation(req, res, {
+      points: pointsOf(req),
+      // The summary spells these `minZoom`/`maxZoom`; everything downstream
+      // reads the TileJSON spelling. Passed straight through they were both
+      // undefined, so every reading clamped to 0-14 whatever the archive held.
+      coverage: {
+        minzoom: entry.pmtiles?.minZoom,
+        maxzoom: entry.pmtiles?.maxZoom,
+      },
+      heightsAt: (codec, signal) =>
+        heightsFromArchive({ entry, tiles, codec, signal, heightsCache }),
+    });
+  });
+
+  app.get('/stacks/:id/elevation', serveStackElevation);
+  app.post('/stacks/:id/elevation', serveStackElevation);
+  app.get('/archives/:infoHash/elevation', serveArchiveElevation);
+  app.post('/archives/:infoHash/elevation', serveArchiveElevation);
+  app.get('/latest/:category/elevation', serveCategoryElevation);
+  app.post('/latest/:category/elevation', serveCategoryElevation);
+
   /**
    * The three ways in. A contour tile is a vector tile whatever produced it,
    * so the extension is checked once and in one place.

package/src/contour-tile.js

@@ -26,7 +26,7 @@ import { stackHeights } from './stack-tile.js';
  * anywhere: where the stack has ground there are contours, and where it has a
  * hole the line simply stops.
  *
- * See docs/tile-stacks.md -- "Contours from a stack".
+ * See docs/terrain.md -- "Contours".
  */
 
 const require = createRequire(import.meta.url);

package/src/elevation-lookup.js

@@ -0,0 +1,159 @@
+/**
+ * Reading one height out of terrain, at a coordinate rather than a tile.
+ *
+ * The projection maths follows tileserver-gl's `lonLatToTilePixel` -- see
+ * NOTICE.md. What is different here is the answer for ground nothing covers.
+ * A server reading encoded tiles has to return something for every pixel,
+ * because every triple of bytes in a terrain tile is a height; this reads the
+ * merged `Float32Array` a stack produces, where a hole is `NaN`, so "there is
+ * no data here" is a thing it can actually say.
+ *
+ * See docs/terrain.md -- "Elevation at a point".
+ */
+
+/** More than one request should turn into, since each unique tile is a merge. */
+export const MAX_POINTS = 1000;
+
+/**
+ * Where a coordinate falls on the tile grid at one zoom.
+ *
+ * Returned as a tile plus a fraction across it rather than as a pixel, because
+ * the pixel depends on the tile's width and that is not known until the tile
+ * has been read -- a stack serves whatever size its recipe says, and an
+ * archive whatever size it was written at.
+ * @param {number} lon - Longitude in degrees.
+ * @param {number} lat - Latitude in degrees.
+ * @param {number} zoom - The zoom to land on.
+ * @returns {object} - `{tileX, tileY, fracX, fracY}`.
+ */
+export function tilePixelFor(lon, lat, zoom) {
+  // Limits latitude to 89.189, about a third of a tile past the edge of the
+  // world tile. Web Mercator sends the poles to infinity, so there has to be a
+  // cut somewhere and this is where tileserver-gl puts it.
+  const siny = Math.min(
+    Math.max(Math.sin((lat * Math.PI) / 180), -0.9999),
+    0.9999,
+  );
+
+  const xWorld = 0.5 + lon / 360;
+  const yWorld = 0.5 - Math.log((1 + siny) / (1 - siny)) / (4 * Math.PI);
+
+  const scale = 2 ** zoom;
+  const fx = xWorld * scale;
+  const fy = yWorld * scale;
+  const tileX = Math.floor(fx);
+  const tileY = Math.floor(fy);
+
+  return { tileX, tileY, fracX: fx - tileX, fracY: fy - tileY };
+}
+
+/**
+ * The pixel a fraction across a tile lands on.
+ * @param {number} fraction - Where across the tile, 0 to 1.
+ * @param {number} size - The tile's width in pixels.
+ * @returns {number} - A pixel index inside the tile.
+ */
+function pixelIn(fraction, size) {
+  // Clamped because a fraction of exactly 1 is reachable through rounding at
+  // the far edge, and `size` is one past the last pixel.
+  return Math.min(size - 1, Math.max(0, Math.floor(fraction * size)));
+}
+
+/**
+ * What is wrong with the points asked for, if anything.
+ * @param {unknown} points - What the request carried.
+ * @returns {string[]} - Problems, empty when usable.
+ */
+export function pointProblems(points) {
+  if (!Array.isArray(points) || points.length === 0) {
+    return ['points must be a non-empty array of {lon, lat, zoom}'];
+  }
+  if (points.length > MAX_POINTS) {
+    return [`no more than ${MAX_POINTS} points in one request`];
+  }
+
+  const wrong = [];
+  points.forEach((point, at) => {
+    const lon = Number(point?.lon ?? point?.long);
+    const lat = Number(point?.lat);
+    if (!Number.isFinite(lon) || lon < -180 || lon > 180) {
+      wrong.push(`point ${at}: lon must be between -180 and 180`);
+    }
+    if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+      wrong.push(`point ${at}: lat must be between -90 and 90`);
+    }
+    const zoom = point?.zoom ?? point?.z;
+    if (zoom !== undefined && zoom !== null && zoom !== '') {
+      const level = Number(zoom);
+      if (!Number.isInteger(level) || level < 0 || level > 26) {
+        wrong.push(`point ${at}: zoom must be a whole number from 0 to 26`);
+      }
+    }
+  });
+  // Named all at once rather than one a request: fixing a batch of points one
+  // round trip at a time is the slowest way to find out about the second one.
+  return wrong;
+}
+
+/**
+ * The height under each point.
+ *
+ * Points are grouped by the tile they land in and each tile is read once, so a
+ * track of a thousand coordinates along a valley costs the handful of merges
+ * its tiles are worth rather than a thousand.
+ * @param {object} options - `heightsAt`, `points`, and the zoom range to clamp
+ *   into. `signal` aborts the reads.
+ * @returns {Promise<object[]>} - One result per point, in the order asked.
+ */
+export async function elevationsAt(options) {
+  const { heightsAt, points, minzoom = 0, maxzoom = 14, signal } = options;
+
+  const groups = new Map();
+  const asked = points.map((point, at) => {
+    const lon = Number(point.lon ?? point.long);
+    const lat = Number(point.lat);
+    // Clamped rather than refused: a client asking for z18 over a stack that
+    // stops at z12 wants the best height available there, not an error.
+    const wanted = Number(point.zoom ?? point.z ?? maxzoom);
+    const zoom = Math.min(Math.max(wanted, minzoom), maxzoom);
+
+    const { tileX, tileY, fracX, fracY } = tilePixelFor(lon, lat, zoom);
+    const key = `${zoom}/${tileX}/${tileY}`;
+    if (!groups.has(key)) groups.set(key, { zoom, tileX, tileY, wants: [] });
+    groups.get(key).wants.push({ at, fracX, fracY });
+    return { lon, lat, zoom, tileX, tileY };
+  });
+
+  const results = asked.map((one) => ({
+    long: one.lon,
+    lat: one.lat,
+    elevation: null,
+    z: one.zoom,
+    x: one.tileX,
+    y: one.tileY,
+    pixelX: null,
+    pixelY: null,
+  }));
+
+  for (const { zoom, tileX, tileY, wants } of groups.values()) {
+    signal?.throwIfAborted?.();
+    const tile = await heightsAt(zoom, tileX, tileY);
+    if (!tile?.data) continue;
+
+    const width = tile.width;
+    const height = tile.height ?? width;
+    for (const { at, fracX, fracY } of wants) {
+      const pixelX = pixelIn(fracX, width);
+      const pixelY = pixelIn(fracY, height);
+      const metres = tile.data[pixelY * width + pixelX];
+      results[at].pixelX = pixelX;
+      results[at].pixelY = pixelY;
+      // NaN is a hole the recipe left unfilled, which is not a height. Left as
+      // null so a caller can tell "no data here" from "sea level", which an
+      // encoded tile can never express.
+      results[at].elevation = Number.isFinite(metres) ? metres : null;
+    }
+  }
+
+  return results;
+}

package/src/web/index.html

@@ -5368,13 +5368,10 @@ Every piece is hashed against the ` +
         const open = (href, text) =>
           `<a href="${href}" target="_blank" rel="noreferrer"><button type="button">${text}</button></a>`;
         if (!drawsAsTerrain(summary)) return open(base, label);
-        // Anything that draws as terrain can be traced, whether the heights
-        // are merged out of a recipe or read straight out of one archive.
-        return (
-          open(`${base}?raw=1`, label) +
-          open(base, 'Terrain') +
-          open(`${base}?contours=1`, 'Contours')
-        );
+        // No contour button: the preview carries a checkbox for them, and a
+        // hidden layer never asks its source for a tile, so there is nothing
+        // to be saved by keeping them behind a page of their own.
+        return open(`${base}?raw=1`, label) + open(base, 'Terrain');
       }
 
       const SETTINGS_GROUPS = [

package/src/web/preview.html

@@ -160,13 +160,32 @@
       // a hole in the data -- a missing tile reads as flat, not as missing.
       const asked = new URLSearchParams(location.search);
       const raw = asked.has('raw');
-      // Offered wherever there is terrain. The endpoint sits beside the
-      // preview for all three -- a stack, one archive, and whichever build a
-      // category points at -- so the source URL below is the same rewrite in
-      // every case.
-      const contours = asked.has('contours') && terrainReady;
+      // Built wherever there is terrain, and switched on by the checkbox in
+      // the header rather than by opening a different page. A hidden layer
+      // leaves its source unused -- `isHidden()` is true for any layer whose
+      // evaluated visibility is `none`, however it got that way -- so the
+      // layer costs nothing at all until it is ticked, which is what makes it
+      // a checkbox rather than a second link.
+      //
+      // The endpoint sits beside the preview for all three -- a stack, one
+      // archive, and whichever build a category points at -- so the rewrite
+      // below is the same in every case.
+      const contours = terrainReady;
+      const contoursOn = contours && asked.has('contours');
       const terrain = terrainReady && !raw;
 
+      // Fetched rather than assumed, because the zooms a stack draws lines at
+      // are its recipe's and not this page's to know. Failing is not fatal:
+      // the layer still works, it is only the range beside the box that goes.
+      let contourJson = null;
+      if (contours) {
+        contourJson = await fetch(
+          location.pathname.replace(/\/preview\/?$/, '/contours/tiles.json'),
+        )
+          .then((response) => (response.ok ? response.json() : null))
+          .catch(() => null);
+      }
+
       $('name').textContent = tilejson.name ?? tileJsonUrl;
       $('summary').textContent =
         `${vector ? 'vector' : 'raster'} · z${tilejson.minzoom ?? 0}–${tilejson.maxzoom ?? 14}` +
@@ -255,22 +274,28 @@
         );
         style.sources.contours = {
           type: 'vector',
+          // The thresholds' range, not the stack's. A stack with ground from
+          // z0 draws its first line at z9 by default, and a source claiming z0
+          // asks for eight zooms of tiles that can only ever answer 404.
+          ...(contourJson
+            ? {
+                minzoom: contourJson.minzoom,
+                maxzoom: contourJson.maxzoom,
+              }
+            : {}),
           // Joined to the origin rather than run through `new URL()`, which
           // percent-encodes the braces: `{z}` becomes `%7Bz%7D`, MapLibre
           // never substitutes it, and every request asks the server for a tile
           // at the literal coordinates "{z}". `source` is already an absolute
           // path, so there is nothing to resolve.
           tiles: [location.origin + source],
-          // The endpoint answers 404 above and below what its thresholds draw
-          // at, which MapLibre reads as an empty tile rather than an error.
-          minzoom: 0,
-          maxzoom: 16,
         };
         style.layers.push({
           id: 'contours',
           type: 'line',
           source: 'contours',
           'source-layer': 'contours',
+          layout: { visibility: contoursOn ? 'visible' : 'none' },
           paint: {
             'line-color': 'rgba(255,255,255,0.45)',
             // `level` counts the intervals a height divides by, so the major
@@ -295,11 +320,17 @@
           // Assembled at click time so the hash, which is where the map keeps
           // the position it is currently showing, survives the reload.
           //
-          // The contour flag rides along, because it is a thing drawn *over*
-          // the terrain rather than a mode instead of it -- switching to raw
-          // tiles and losing the lines would be answering a different question
-          // than the one that was asked.
-          const flags = [terrain ? 'raw=1' : '', contours ? 'contours=1' : '']
+          // Read off the address bar rather than off the value this page
+          // loaded with, because the contour box writes there as it is
+          // ticked. The lines are drawn *over* the terrain rather than being a
+          // mode instead of it, so switching to raw tiles and losing them
+          // would answer a different question than the one that was asked.
+          const flags = [
+            terrain ? 'raw=1' : '',
+            new URLSearchParams(location.search).has('contours')
+              ? 'contours=1'
+              : '',
+          ]
             .filter(Boolean)
             .join('&');
           location.href =
@@ -374,13 +405,15 @@
        * already on the map, one row up on the left.
        * @param {string} id - The layer to show and hide.
        * @param {string} label - What to call it.
+       * @param {object} [options] - `on` for the starting state, and `flag` to
+       *   mirror that state into the query string.
        * @returns {void}
        */
-      function layerToggle(id, label) {
+      function layerToggle(id, label, { on = true, flag = '' } = {}) {
         const box = document.createElement('label');
         const input = document.createElement('input');
         input.type = 'checkbox';
-        input.checked = true;
+        input.checked = on;
         // `setLayoutProperty` calls `_checkLoaded()`, which throws before the
         // style has finished loading, so the box is not offered until it has.
         input.disabled = true;
@@ -393,6 +426,20 @@
             'visibility',
             input.checked ? 'visible' : 'none',
           );
+          if (!flag) return;
+          // Replaced rather than pushed: this is what the page is showing, not
+          // somewhere the back button should return to. It makes the state
+          // survive the raw/terrain switch, which reloads, and makes a preview
+          // with the lines on a link that can be sent to somebody.
+          const query = new URLSearchParams(location.search);
+          if (input.checked) query.set(flag, '1');
+          else query.delete(flag);
+          const search = query.toString();
+          history.replaceState(
+            null,
+            '',
+            location.pathname + (search ? `?${search}` : '') + location.hash,
+          );
         });
         box.append(input, document.createTextNode(label));
         $('layers').append(box);
@@ -401,7 +448,19 @@
       // Only for the layers this page actually put in the style. A checkbox
       // for a layer that is not there is a control that does nothing.
       if (terrain) layerToggle('hillshade', 'hillshade');
-      if (contours) layerToggle('contours', 'contours');
+      if (contours) {
+        // The range is in the label because without it an empty map is
+        // indistinguishable from a broken one: contours start at z9 under the
+        // default thresholds, so a preview opened at z4 with the hillshade off
+        // draws nothing at all and says nothing about why.
+        const range = contourJson
+          ? ` z${contourJson.minzoom}–${contourJson.maxzoom}`
+          : '';
+        layerToggle('contours', `contours${range}`, {
+          on: contoursOn,
+          flag: 'contours',
+        });
+      }
 
       if (vector) {
         // MapLibre's own inspect control, rather than something equivalent

package/src/web/public.html

@@ -464,7 +464,6 @@
               // hole, since a missing DEM tile hillshades as flat ground.
               add(`${root}/preview?raw=1`, 'preview');
               add(`${root}/preview`, 'terrain');
-              add(`${root}/preview?contours=1`, 'contours');
             } else {
               add(`${root}/preview`, 'preview');
             }