pmtiles-swarm 0.76.0 → 0.77.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.77.0
+### ✨ Features and improvements
+- **A fade can be written in metres of ground.** `featherMetres` on a source says how far to blend
+  it in as a distance, and the merge works out the pixels for each tile it builds -
+  `40075016.686 x cos(latitude) / 2^zoom / tileSize` of them. What a fade has to hide is two sources
+  disagreeing about the height of the same ground, which is a fixed number of metres, while a fade
+  in pixels is a different distance at every zoom.
+
+  It matters because a hillshade reads slope rather than height. `feather: 8` over a 7 m
+  disagreement is a gradient of 0.08 at z12 and 1.28 at z16 - invisible at one end and a saturated
+  band at the other, wider than the cliff it replaced and no less visible. The same 50 m holds 0.14
+  at every zoom, which is ordinary hillside. Below the zoom where the fade is a pixel wide it rounds
+  to nothing, and it is capped at a quarter of the tile - 128 pixels on a 512px grid, which is where
+  the old 64 came from. `featherMeters` is read as well, and the console's fade field now takes a
+  unit rather than always meaning pixels.
+
+- **A tool that measures the step a fade has to hide.** `tools/coast-step.mjs` reports the height
+  difference where one source hands over to another, and says which kind of disagreement it is.
+  Steps that cluster are a vertical datum offset, which one `heightAdjustment` corrects. Steps that
+  scatter are a coarse source averaging land and water together in every cell that straddles a
+  coast - worst at the shore, gone offshore - which no single number corrects and a fade can only
+  hide.
+
+### 🐞 Bug fixes
+- **A mask range was not an edge to fade at.** A source whose only mask was a `maskRange` was told
+  its `feather` had nothing to act on, and refused - while the merge had been fading exactly that
+  edge all along. The recipe validation and the console's own warning both listed `maskValues` and
+  `maskColors` and neither had been taught about the band.
+
 ## 0.76.0
 ### ✨ Features and improvements
 - **A stopped export stays stopped.** Stopping one left a checkpoint, and a checkpoint says what was

package/docs/tile-stacks.md

@@ -50,6 +50,8 @@ of its parts.
   - [Starting one, and watching it](#starting-one-and-watching-it)
   - [What exists now](#what-exists-now)
 - [Clipping a source to a shape](#clipping-a-source-to-a-shape)
+- [What a mask has to match](#what-a-mask-has-to-match)
+- [Feathering a seam](#feathering-a-seam)
 - [Finding a stack](#finding-a-stack)
 - [Syncing a stack to another node](#syncing-a-stack-to-another-node)
 - [What the offline merge got wrong](#what-the-offline-merge-got-wrong)
@@ -233,19 +235,20 @@ it differs from the snake_case rio-rgbify-merge uses.
 
 ### Source fields
 
-| Field                  | Meaning                                                                                                    |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `category`             | Resolve to the newest build in this category.                                                              |
-| `archive`              | Or pin one infohash. Exactly one of the two.                                                               |
-| `required`             | A tile fails rather than being served without this source. Defaults true for the bottom-most, false above. |
-| `encoding`             | `mapbox` or `terrarium`. Elevation space only.                                                             |
-| `baseVal` / `interval` | Mapbox decode offset and step. Default `-10000` and `0.1`.                                                 |
-| `maskValues`           | Decoded heights meaning "no data here". Elevation space only.                                              |
-| `maskRange`            | `[low, high]` in metres, or a list of them. Everything inside is nodata. Elevation space only.             |
-| `heightAdjustment`     | Metres, added **after** masking. Elevation space only.                                                     |
-| `feather`              | Pixels to fade in over at the edge of the source's shape. Needs a `cutline` or `bounds`. Max 64.           |
-| `opacity`              | `0`–`1`, scales the source alpha. RGBA space only.                                                         |
-| `blend`                | `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`. RGBA space only.                           |
+| Field                  | Meaning                                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `category`             | Resolve to the newest build in this category.                                                                |
+| `archive`              | Or pin one infohash. Exactly one of the two.                                                                 |
+| `required`             | A tile fails rather than being served without this source. Defaults true for the bottom-most, false above.   |
+| `encoding`             | `mapbox` or `terrarium`. Elevation space only.                                                               |
+| `baseVal` / `interval` | Mapbox decode offset and step. Default `-10000` and `0.1`.                                                   |
+| `maskValues`           | Decoded heights meaning "no data here". Elevation space only.                                                |
+| `maskRange`            | `[low, high]` in metres, or a list of them. Everything inside is nodata. Elevation space only.               |
+| `heightAdjustment`     | Metres, added **after** masking. Elevation space only.                                                       |
+| `feather`              | Pixels to fade in over wherever the source stops: a `cutline`, `bounds`, or the holes a mask leaves. Max 64. |
+| `featherMetres`        | The same fade written as metres of ground, worked out per tile. Usually the one to reach for.                |
+| `opacity`              | `0`–`1`, scales the source alpha. RGBA space only.                                                           |
+| `blend`                | `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`. RGBA space only.                             |
 
 `attribution` is not optional in practice. A stack is a derived work of every
 source in it, and the thing that reliably gets lost when tiles are combined is
@@ -1085,8 +1088,8 @@ standing clear of their neighbours, which is the shape this makes.
 
 ## Feathering a seam
 
-_Built for a cutline and for `bounds`. A mask edge is not feathered yet, and
-the last section says what that still needs._
+_Built for a cutline, for `bounds`, and for the holes a mask leaves. A source
+that vanishes at a tile edge is still open, and the last section says why._
 
 Smoothing hides the terracing **inside** an upscaled area. It does nothing about
 the artefact the original discussion actually named — "artefacts at tiles and
@@ -1236,18 +1239,40 @@ lookup rather than a decode — and it is not done.
 
 `feather` on a source, in pixels, `0` and absent meaning the edge is a switch as
 before. It fades that source in over that many pixels measured inward from
-wherever it stops — the holes `maskValues` and `maskColors` leave, and the edge
-of a `cutline` or `bounds`:
+wherever it stops — the holes `maskValues`, `maskRange` and `maskColors` leave,
+and the edge of a `cutline` or `bounds`:
 
 ```json
 { "archive": "swissalti", "maskValues": [0], "feather": 16 }
 ```
 
-The step left at the seam is the height difference divided by the feather, which
-is what makes the number predictable: two sources 40 m apart at the border, faded
-over 16 pixels, step 2.5 m a pixel instead of 40 m at once. Sixty-four is the
-most it takes — past that the ramp does not reach full weight anywhere inside a
-256px tile, and the source is being turned down rather than blended in.
+The step left at the seam is the height difference divided by the feather: two
+sources 40 m apart at the border, faded over 16 pixels, step 2.5 m a pixel
+instead of 40 m at once. Sixty-four is the most it takes — past that the ramp
+does not reach full weight anywhere inside a 256px tile, and the source is being
+turned down rather than blended in.
+
+**A smaller step is not the same as an invisible one**, and that is the thing to
+know before picking a number. A hillshade does not read height, it reads slope:
+the drop divided by the ground underneath it. What decides whether a seam
+disappears is therefore metres per metre rather than metres per pixel — and a
+pixel is a different number of metres at every zoom. The same `feather: 8`, over
+the same 7 m disagreement, at 55°N:
+
+| zoom | m/pixel | gradient |
+| ---- | ------- | -------- |
+| z12  | 11.0    | 0.08     |
+| z13  | 5.5     | 0.16     |
+| z14  | 2.7     | 0.32     |
+| z15  | 1.4     | 0.64     |
+| z16  | 0.7     | 1.28     |
+
+Natural terrain is rarely over about 0.5 and a hillshade saturates around there,
+so a fade that vanishes at z12 is a bright band by z15 — wider than the cliff it
+replaced and no less visible. Widening it does help at any one zoom, since the
+gradient is the drop over the whole fade; the difficulty is that the number
+which works at z16 is eight times the one that works at z13, and a recipe has
+one number.
 
 Three things fall out of the implementation and are worth stating.
 
@@ -1268,22 +1293,52 @@ envelope — linear in the tile's width, and chosen over a chamfer approximation
 because a chamfer's error is largest on diagonals and a national boundary is
 mostly diagonals.
 
-### What it does not do yet
+### A fade in metres
+
+`featherMetres` says the same thing as a distance on the ground, and the merge
+works out the pixels for each tile it builds:
 
-**A mask edge.** `maskValues` and `maskColors` are where most seams actually come
-from, and they are not feathered. The reason is the margin: a cutline is known in
-full, so the ramp beside a tile can be computed by rasterising a few extra rows,
-while a mask edge lives in the source's own pixels and the ramp needs the
-neighbouring tiles to be read and decoded — up to eight of them, for that source,
-on that tile.
-
-That is the piece with a real cost attached, and the one to measure before
-building. Two things make it more tractable than it looks: in a bake the tiles
-are walked in Hilbert order, which is chosen for locality, so a cache of decoded
-source tiles would be hit far more often than missed; and the ramp is smooth by
-construction, so it can be computed from the source's _parent_ at half resolution
-and upscaled, which turns eight reads at this zoom into a handful at the one
-above, shared between four children.
+```json
+{ "archive": "gebco", "maskRange": [-1, 0], "featherMetres": 50 }
+```
+
+Web Mercator makes that arithmetic rather than a lookup: one pixel covers
+`40075016.686 × cos(latitude) / 2^zoom / tileSize` metres, so the conversion
+needs a multiply and the coordinates of the tile being built. `featherMeters` is
+read as well, because a key that quietly does nothing when spelled the other way
+is the failure this feature is most prone to.
+
+Fifty metres, over the same 7 m disagreement, at 55°N on 512px tiles:
+
+| zoom | m/pixel | pixels | ground | gradient |
+| ---- | ------- | ------ | ------ | -------- |
+| z12  | 11.0    | 5      | 55 m   | 0.13     |
+| z13  | 5.5     | 9      | 49 m   | 0.14     |
+| z14  | 2.7     | 18     | 49 m   | 0.14     |
+| z15  | 1.4     | 36     | 49 m   | 0.14     |
+| z16  | 0.7     | 73     | 50 m   | 0.14     |
+
+One number, the same slope at every zoom, and 0.14 is ordinary hillside rather
+than an edge.
+
+It stops being exact at both ends, benignly. Below the zoom where the fade is a
+pixel wide it rounds to nothing — 50 m at z8 is a sixth of a pixel, and the whole
+coastline is inside one pixel there anyway. Above a quarter of the tile it is
+capped, which is 128 pixels on a 512px grid and is where the old 64 came from:
+past that the ramp reaches full weight nowhere inside the tile. At 55°N the cap
+first binds at z17.
+
+**Picking the number.** It is the disagreement being hidden that sets it, not the
+coastline being drawn across. `tools/coast-step.mjs` measures the first against a
+real tile: it reports the step where one source hands over to the other, and
+whether those steps cluster — in which case they are a datum offset and
+`heightAdjustment` is the honest fix — or scatter, in which case nothing corrects
+them and a fade is for hiding what cannot be corrected. Divide the step by the
+gradient wanted: 7 m at 0.15 is about 50 m, and the same step at 0.05 would need
+140 m, which is wide enough to start flattening ground either side of the coast
+that was never wrong.
+
+### What it does not do yet
 
 **A source that vanishes at a tile edge.** A sparse archive simply has no tile
 outside its extent, so the seam lands exactly on a tile boundary — the most

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.76.0",
+  "version": "0.77.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/cutline.js

@@ -45,6 +45,31 @@ export function worldY(lat) {
   );
 }
 
+/** The world across the equator, in metres: what a zoom 0 tile spans. */
+const EQUATOR = 40075016.686;
+
+/**
+ * How much ground one pixel of a tile covers, at that tile's latitude.
+ *
+ * Web Mercator holds a pixel to a fixed fraction of the world, so the ground
+ * under it shrinks toward the poles and halves at every zoom. That is why a
+ * fade written in pixels is a different width of ground everywhere it is used,
+ * and this is the conversion that lets one written in metres mean the same
+ * thing. Taken at the middle of the tile: the scale changes across it, but a
+ * tile is a small piece of the world at any zoom where a fade is more than a
+ * pixel wide.
+ * @param {number} z - Zoom.
+ * @param {number} y - Row.
+ * @param {number} size - Pixels per side of the tile.
+ * @returns {number} - Metres per pixel.
+ */
+export function metresPerPixel(z, y, size) {
+  const tiles = 2 ** z;
+  const middle = (y + 0.5) / tiles;
+  const latitude = Math.atan(Math.sinh(Math.PI * (1 - 2 * middle)));
+  return (EQUATOR * Math.cos(latitude)) / (tiles * size);
+}
+
 /**
  * Reads the rings out of GeoJSON, whatever shape it arrived in.
  *

package/src/cutlines.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fromBounds, fromGeoJSON } from './cutline.js';
+import { fromBounds, fromGeoJSON, metresPerPixel } from './cutline.js';
 
 /**
  * The cutlines a node has, by name.
@@ -101,16 +101,63 @@ export class CutlineStore {
  */
 export const MAX_FEATHER = 64;
 
+/** Past this a fade in metres is a typo rather than a distance. */
+export const MAX_FEATHER_METRES = 100000;
+
+/**
+ * The widest fade a grid of this size will take.
+ *
+ * A quarter of the tile, which is where 64 came from and what it still means on
+ * a 512px one: past that the ramp reaches full weight nowhere inside the tile,
+ * and the source is being turned down rather than blended in. It binds on a
+ * fade in metres, which asks for more pixels at every zoom.
+ * @param {number} size - Pixels per side of the grid the ramp runs on.
+ * @returns {number} - The most pixels a fade may be.
+ */
+function capFor(size) {
+  return Math.max(MAX_FEATHER, Math.round((size ?? 0) / 4));
+}
+
 /**
- * How far a source fades in at the edge of its shape.
+ * How far a source fades in, as metres of ground, if it is written that way.
+ *
+ * Both spellings are read. A recipe key that does nothing when it is spelled
+ * the other way is the failure this whole feature is most prone to, and the
+ * prose here says metres while half the world's config files say meters.
+ * @param {object} recipe - One source out of a recipe.
+ * @returns {number} - Metres, 0 when the fade is not written in them.
+ */
+export function featherMetresFor(recipe) {
+  const asked = Number(recipe?.featherMetres ?? recipe?.featherMeters);
+  return Number.isFinite(asked) && asked > 0 ? asked : 0;
+}
+
+/**
+ * How far a source fades in at the edge of its shape, in this tile's pixels.
  *
  * Zero is the old behaviour and the default: the shape is a switch, and a pixel
  * is either the source or what is underneath it. Anything more makes it a ramp.
- * See docs/tile-stacks.md -- "Feathering a seam".
+ *
+ * A fade in metres is converted here, which is why this wants the tile. What
+ * the fade has to hide is two sources disagreeing about the height of the same
+ * ground, which is a fixed number of metres -- so the same number of pixels is
+ * too wide at one zoom and too steep at the next. See docs/tile-stacks.md --
+ * "Feathering a seam".
  * @param {object} recipe - One source out of a recipe.
+ * @param {object} [tile] - `{z, y, size}` of the tile being built.
  * @returns {number} - Pixels, 0 when it does not fade.
  */
-export function featherFor(recipe) {
+export function featherFor(recipe, tile) {
+  const size = tile?.size > 0 ? tile.size : 256;
+  const metres = featherMetresFor(recipe);
+  if (metres > 0) {
+    // With no tile there is no scale to convert against, and a fade that
+    // guessed one would be a different width from the tiles beside it.
+    if (!Number.isFinite(tile?.z)) return 0;
+    const perPixel = metresPerPixel(tile.z, tile.y ?? 0, size);
+    return Math.min(Math.round(metres / perPixel), capFor(size));
+  }
+
   const asked = Number(recipe?.feather);
   if (!Number.isFinite(asked) || asked <= 0) return 0;
   return Math.min(Math.round(asked), MAX_FEATHER);

package/src/stack-tile.js

@@ -151,7 +151,7 @@ export function clipsFor(resolved, cutlines, z, x, y, size = 256) {
     // The feather reaches inward from the edge, so a tile wholly inside but
     // near it still has a ramp across part of itself and cannot take the cheap
     // answer.
-    const feather = featherFor(recipe);
+    const feather = featherFor(recipe, { z, y, size });
     return {
       shape,
       feather,
@@ -524,10 +524,11 @@ async function readMaskEdges({
     contributions.map(async (contribution) => {
       if (!contribution) return;
       const recipe = contribution.source ?? {};
-      const feather = featherFor(recipe);
-      if (!feather || !masksAnything(recipe)) return;
-
+      // On the source's own grid rather than the output's, because that is
+      // what the ramp will be measured on.
       const grid = contribution.raster?.width ?? size;
+      const feather = featherFor(recipe, { z, y, size: grid });
+      if (!feather || !masksAnything(recipe)) return;
       const layout = parentsFor({ z, x, y }, grid, feather);
       if (!layout) return;
 
@@ -612,10 +613,14 @@ async function merge({
     // decides what the pixels inside it weigh. The shape is known in full, so
     // this costs the extra rows and nothing else -- unlike a mask read out of
     // a source's own pixels, which would need its neighbours.
-    const margin = clip.feather ?? 0;
+    //
+    // Asked again rather than taken from the clip: `clipsFor` may have been
+    // given a grid the merge did not end up using, and a fade in metres is a
+    // different number of pixels on each of them.
+    const margin = featherFor(contribution.source, { z, y, size: grid });
     const mask = rasterizeTile(clip.shape, z, x, y, grid, margin);
     contribution.coverage = cropMask(
-      featherMask(mask, grid + margin * 2, clip.feather ?? 0),
+      featherMask(mask, grid + margin * 2, margin),
       grid,
       margin,
     );
@@ -729,7 +734,8 @@ export async function answerStackTile(options) {
   // 256 where the request did not say, which is the cautious guess: the
   // margin is in pixels of the output grid, so assuming a smaller grid makes
   // it wider on the ground, and too wide only costs a rasterise that was not
-  // needed while too narrow misses a ramp.
+  // needed while too narrow misses a ramp. A fade in metres does not mind
+  // either way -- fewer pixels each covering more ground is the same ground.
   const clips = clipsFor(resolved, cutlines, z, x, y, size);
   const format = options.format ?? outputFormat(resolved);
   const rgba = resolved.stack.space === 'rgba';

package/src/stacks.js

@@ -8,7 +8,11 @@ import {
   isResampling,
   parseColor,
 } from './elevation.js';
-import { MAX_FEATHER } from './cutlines.js';
+import {
+  MAX_FEATHER,
+  MAX_FEATHER_METRES,
+  featherMetresFor,
+} from './cutlines.js';
 import { normalizeCategories } from './catalog.js';
 import { BLEND_MODES, isBlendMode } from './rgba.js';
 
@@ -42,6 +46,8 @@ import { BLEND_MODES, isBlendMode } from './rgba.js';
  * @property {number} [heightAdjustment] - Metres, added after masking.
  * @property {number} [feather] - Pixels to fade in over at the edge of the
  *   source's shape. 0, the default, makes the edge a switch.
+ * @property {number} [featherMetres] - Metres of ground to fade in over
+ *   instead, worked out per tile. `featherMeters` is read as well.
  * @property {number} [opacity] - 0-1, scales source alpha. RGBA only.
  * @property {string} [blend] - Blend operator. RGBA only.
  * @typedef {object} Stack
@@ -159,6 +165,18 @@ export function validateStack(stack) {
         );
       }
     }
+    const metres = source?.featherMetres ?? source?.featherMeters;
+    if (metres !== undefined) {
+      // Loose, because the pixel cap is what actually bounds the ramp at any
+      // one zoom. This only has to catch a number nobody meant to type.
+      const width = Number(metres);
+      if (!Number.isFinite(width) || width < 0 || width > MAX_FEATHER_METRES) {
+        problems.push(
+          `sources[${index}].featherMetres must be between 0 and ` +
+            `${MAX_FEATHER_METRES}`,
+        );
+      }
+    }
     // A fade with no edge to fade at. Refused rather than ignored: it reads as
     // a source that blends into what is under it, and it does nothing at all.
     // A mask is an edge as much as a cutline is -- the hole it leaves is where
@@ -167,8 +185,9 @@ export function validateStack(stack) {
       source?.cutline ||
       source?.bounds ||
       source?.maskValues?.length ||
-      source?.maskColors?.length;
-    if (source?.feather && !fades) {
+      source?.maskColors?.length ||
+      source?.maskRange?.length;
+    if ((source?.feather || featherMetresFor(source)) && !fades) {
       problems.push(
         `sources[${index}].feather needs a cutline, bounds, or a mask to fade at`,
       );

package/src/web/index.html

@@ -7545,6 +7545,18 @@ Every piece is hashed against the ` +
        */
       const renderDraftSource = (source, index, rgba) => {
         const last = index === stackDraft.sources.length - 1;
+        // A fade is written in one unit or the other, never both: the box
+        // shows whichever the recipe used and the choice beside it says which.
+        const featherMetres = source.featherMetres ?? source.featherMeters;
+        const featherUnit =
+          featherMetres === undefined && source.feather ? 'px' : 'm';
+        const featherWidth = featherMetres ?? source.feather ?? '';
+        const fadesAt =
+          source.cutline ||
+          source.bounds ||
+          (source.maskValues ?? []).length ||
+          (source.maskColors ?? []).length ||
+          (source.maskRange ?? []).length;
         const role =
           stackDraft.sources.length === 1
             ? ''
@@ -7710,19 +7722,23 @@ Every piece is hashed against the ` +
                   : ''
               }
               <label class="choice"
-                     title="Fade this source in over this many pixels wherever it stops — the holes a mask leaves, and the edge of a cutline or box. Where a high-resolution source meets a coarser one the two disagree, by their survey and by their vertical datum, and the step between them reads as a wall under a hillshade. The drop is divided by this: 40 m across an 8 px fade is 5 m a pixel. 0 is a hard edge.">
+                     title="Fade this source in wherever it stops — the holes a mask leaves, and the edge of a cutline or box. Where a high-resolution source meets a coarser one the two disagree, by their survey and by their vertical datum, and the step between them reads as a wall under a hillshade. Metres of ground is usually the one to pick: a hillshade reads slope, so a fade written in pixels is gentle at one zoom and a bright band at the next, while a distance on the ground holds the same slope at every zoom. 50 m suits a coastline where two sources are a few metres apart. 0 is a hard edge.">
                 Fade in
-                <input type="number" min="0" max="64" step="1" style="width:4.5rem"
+                <input type="number" min="0" step="any" style="width:4.5rem"
                        placeholder="0"
                        data-stack-field="feather" data-stack-index="${index}"
-                       value="${source.feather ?? ''}" />
-                <span class="sub">px${
-                  source.feather &&
-                  !source.cutline &&
-                  !source.bounds &&
-                  !(source.maskValues ?? []).length &&
-                  !(source.maskColors ?? []).length
-                    ? ' — nothing to fade at yet: mask something, or clip it'
+                       value="${featherWidth}" />
+                <select data-stack-field="featherUnit" data-stack-index="${index}">
+                  <option value="m"${
+                    featherUnit === 'm' ? ' selected' : ''
+                  }>m of ground</option>
+                  <option value="px"${
+                    featherUnit === 'px' ? ' selected' : ''
+                  }>px</option>
+                </select>
+                <span class="sub">${
+                  featherWidth && !fadesAt
+                    ? 'nothing to fade at yet: mask something, or clip it'
                     : ''
                 }</span>
               </label>
@@ -7792,10 +7808,24 @@ Every piece is hashed against the ` +
           } else if (low === null && high === null) {
             delete source.maskRange;
           }
-        } else if (field === 'feather') {
-          const pixels = Number(event.target.value);
-          if (event.target.value === '' || !(pixels > 0)) delete source.feather;
-          else source.feather = Math.min(64, Math.round(pixels));
+        } else if (field === 'feather' || field === 'featherUnit') {
+          // The width and its unit are read together and only one key is
+          // written, because a source carrying a fade in both would be asking
+          // the merge a question it has no answer to.
+          const row = event.target.closest('.card');
+          const box = row?.querySelector('[data-stack-field="feather"]');
+          const unit = row?.querySelector('[data-stack-field="featherUnit"]');
+          const width = Number(box?.value);
+          delete source.feather;
+          delete source.featherMetres;
+          delete source.featherMeters;
+          if (box && box.value.trim() !== '' && width > 0) {
+            if (unit?.value === 'px') {
+              source.feather = Math.min(64, Math.round(width));
+            } else {
+              source.featherMetres = width;
+            }
+          }
         } else if (field === 'baseVal' || field === 'interval') {
           // Blank means "the default", not zero -- an interval of 0 would make
           // every height the base value.
@@ -7833,6 +7863,12 @@ Every piece is hashed against the ` +
           renderStackDraft();
           return;
         }
+        // Redrawn so the row's own warning about having nothing to fade at
+        // follows the unit rather than the value it was drawn with.
+        if (event.target.dataset.stackField === 'featherUnit') {
+          renderStackDraft();
+          return;
+        }
         if (event.target.dataset.stackField !== 'encoding') return;
         // Redrawn so the four custom fields appear or disappear with the
         // choice, rather than sitting there meaning nothing.

package/tools/coast-step.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * How far two sources disagree where one hands over to the other.
+ *
+ * A land DEM says its shoreline is about zero. A global bathymetry at 450 m
+ * cells averages land and water together in every cell that straddles a coast,
+ * so its shoreline sits well below that -- and the merge steps between them in
+ * one pixel. Feathering spreads that step without reducing it, and a hillshade
+ * reads slope, so at high zoom a spread step is a wider bright band rather
+ * than a fainter one.
+ *
+ * Two quite different things produce that step and they look identical in a
+ * picture. A vertical datum offset is the same wherever the two meet, and one
+ * `heightAdjustment` fixes it. Averaging is wrong by whatever each cell
+ * happened to cover -- worst at the shore, gone offshore -- and no single
+ * number fixes that; subtracting the median would meet the coast and lift the
+ * open ocean with it.
+ *
+ * They are told apart by how much the steps scatter, which is what this
+ * prints. It is worth knowing that the measurement is taken exactly where a
+ * coarse source is least trustworthy, so a clustered result is evidence and a
+ * scattered one is close to proof.
+ *
+ *   node tools/coast-step.mjs --stack <url> --land <url> [--range -1,0] [--values 0]
+ *
+ * `--stack` is the merged tile and `--land` the source that wins on land, both
+ * at the same z/x/y. The mask arguments are that source's, so the tool knows
+ * which of its pixels are sea.
+ */
+
+import { loadCodec } from '../src/codec.js';
+import { decodeHeights, maskHeights, maskRanges } from '../src/elevation.js';
+
+const args = process.argv.slice(2);
+
+/**
+ * One named option off the command line.
+ * @param {string} name - Its name, without the dashes.
+ * @param {string} [fallback] - What it is when absent.
+ * @returns {string|undefined} - The value.
+ */
+const option = (name, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at >= 0 && args[at + 1] ? args[at + 1] : fallback;
+};
+
+const stackUrl = option('stack');
+const landUrl = option('land');
+if (!stackUrl || !landUrl) {
+  console.error(
+    'usage: node tools/coast-step.mjs --stack <url> --land <url> [--range low,high] [--values a,b]',
+  );
+  process.exit(2);
+}
+
+/** The masks the land source is configured with, so its sea can be found. */
+const values = option('values')
+  ? option('values').split(',').map(Number)
+  : undefined;
+const range = option('range')
+  ? option('range').split(',').map(Number)
+  : undefined;
+if (!values && !range) {
+  console.error(
+    'give --values, --range, or both: without them no pixel is sea',
+  );
+  process.exit(2);
+}
+
+const codec = await loadCodec();
+if (!codec) {
+  console.error('this needs sharp: npm install sharp');
+  process.exit(1);
+}
+
+/**
+ * One tile, decoded to metres.
+ * @param {string} url - Where it is.
+ * @returns {Promise<object>} - `{heights, width}`.
+ */
+async function tileAt(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.error(`${url} answered ${response.status}`);
+    process.exit(1);
+  }
+  const raster = await codec.decode(Buffer.from(await response.arrayBuffer()), {
+    channels: 3,
+  });
+  return { heights: decodeHeights(raster, {}), width: raster.width };
+}
+
+const merged = await tileAt(stackUrl);
+const land = await tileAt(landUrl);
+if (merged.width !== land.width) {
+  console.error(
+    `different sizes: the stack is ${merged.width}px and the land source ${land.width}px`,
+  );
+  process.exit(1);
+}
+
+// The land source's own idea of where it has nothing, which is where the other
+// source shows through in the merged tile.
+const sea = Float32Array.from(land.heights);
+maskHeights(sea, values);
+maskRanges(sea, range);
+
+const { width } = merged;
+const steps = [];
+for (let row = 1; row < width - 1; row += 1) {
+  for (let column = 1; column < width - 1; column += 1) {
+    const at = row * width + column;
+    // A pixel the land source covers, beside one it does not: the handover,
+    // found from that source rather than guessed from the merged heights.
+    if (Number.isNaN(sea[at])) continue;
+    for (const step of [-1, 1, -width, width]) {
+      if (!Number.isNaN(sea[at + step])) continue;
+      const above = merged.heights[at];
+      const below = merged.heights[at + step];
+      if (Number.isFinite(above) && Number.isFinite(below)) {
+        steps.push(above - below);
+      }
+    }
+  }
+}
+
+if (steps.length === 0) {
+  console.log('no handover in this tile: it is all land, or all sea');
+  process.exit(0);
+}
+
+steps.sort((one, two) => one - two);
+
+/**
+ * A value at a percentile of the sorted steps.
+ * @param {number} share - Where to look, 0 to 1.
+ * @returns {number} - Metres.
+ */
+const at = (share) =>
+  steps[Math.min(steps.length - 1, Math.floor(steps.length * share))];
+
+const median = at(0.5);
+const spread = at(0.75) - at(0.25);
+
+console.log(`${steps.length} pixels where one source hands over to the other`);
+console.log('\n  the step across it, land minus what is underneath:');
+for (const [label, share] of [
+  ['a quarter are under', 0.25],
+  ['half are under', 0.5],
+  ['three quarters under', 0.75],
+  ['the worst', 1],
+]) {
+  console.log(`   ${label.padEnd(24)} ${at(share).toFixed(1).padStart(8)} m`);
+}
+
+console.log(
+  `\n  median ${median.toFixed(1)} m, middle half spread over ${spread.toFixed(1)} m`,
+);
+
+// Whether one number could fix it. A datum offset is the same wherever the two
+// meet, so the steps cluster; a coarse source averaging land and water is wrong
+// by whatever its cell covered, so they scatter.
+if (Math.abs(spread) < Math.abs(median) * 0.5) {
+  console.log(
+    [
+      '',
+      '  -> the steps cluster, so the two disagree by about the same amount',
+      '     wherever they meet. That looks like a datum offset, which one',
+      '     number fixes. On the source underneath, not the land:',
+      '',
+      `       "heightAdjustment": ${median.toFixed(1)}`,
+      '',
+      '     It shifts that source everywhere, so the deep ocean floor moves by',
+      '     the same amount -- against thousands of metres, nothing. Re-run',
+      '     afterwards and the median should come out near zero.',
+      '',
+      '     Worth one check first: this was measured at the coastline, which is',
+      '     the one place a coarse source is guaranteed to be wrong. If its',
+      '     cells are much larger than a pixel here, a clustered result can',
+      '     still be averaging rather than datum -- compare a stretch of steep',
+      '     coast against a flat one, and a real offset will agree.',
+    ].join('\n'),
+  );
+} else {
+  console.log(
+    [
+      '',
+      '  -> the steps scatter more than they cluster, so this is not one offset.',
+      '     A coarse source averages land and water together in the cells that',
+      '     straddle a coast, so how wrong it is depends on what each cell',
+      '     happened to cover: worst at the shore, gone offshore. Subtracting',
+      '     the median would meet the coast and lift the open ocean with it,',
+      '     trading a seam you can see for an error you cannot.',
+      '',
+      '     What helps is a nearshore source that has the detail, or leaving the',
+      '     line alone. At this zoom the coarse source is being asked something',
+      '     its cells cannot answer, and no adjustment invents the answer.',
+    ].join('\n'),
+  );
+}