pmtiles-swarm 0.99.2 → 0.100.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.100.0
+### ✨ Features and improvements
+- **A nested stack takes `maskColors`, and fades into what is under it.** Two things a stack could
+  not do that every other kind of source could, both for the same reason: it is evaluated rather
+  than stored, so it has no bytes. That is a fact about storage, not about meaning, and it was
+  showing up in the recipe as a source with a different set of options.
+
+  A colour is now decoded into the height it names, under the encoding the inner stack packs its
+  own output in, and masked as a height — through `decodeHeights` rather than arithmetic written a
+  second time. `maskColors: ["#0186a0"]` and `maskValues: [0]` say the same thing to a
+  mapbox-encoded stack, so a source keeps its mask when it is swapped between an archive and a
+  stack. `encoding`, `baseVal`, `interval` and the custom factors stay refused: those describe how
+  to unpack channels into a number, and the number arrived already made.
+
+  Feathering a nested source now works rather than silently doing nothing. A ramp is measured in
+  pixels and the pixels that say how far a hole reaches are partly in the next tile — which for an
+  archive means reading its parent and for a stack means evaluating it again, which was never
+  implemented. Validation also stopped asking a nested source for a mask before it would accept a
+  feather: its holes are already an edge, and the mask being demanded would have made a second one.
+
+  The representation is unchanged. A nested stack is still merged as heights, because a hole is
+  `NaN` and no encoding has one — encoding it would turn every hole into a sentinel the recipe
+  above had to mask back out, which is the problem nesting avoids by construction.
+
+### 🐞 Bug fixes
+
 ## 0.99.2
 ### ✨ Features and improvements
 

package/docs/tile-stacks.md

@@ -55,6 +55,7 @@ of its parts.
 - [What a mask has to match](#what-a-mask-has-to-match)
 - [Feathering a seam](#feathering-a-seam)
 - [A stack as a source](#a-stack-as-a-source)
+  - [A colour is a height said another way](#a-colour-is-a-height-said-another-way)
 - [A source read straight from a URL](#a-source-read-straight-from-a-url)
 - [Importing a list of URLs](#importing-a-list-of-urls)
   - [Exporting on a schedule](#exporting-on-a-schedule)
@@ -1539,6 +1540,27 @@ height mask has to round; a stack that was never stored has no such channels to
 compare, and masking the heights it decoded to would be a different operation
 wearing the same name.
 
+### A colour is a height said another way
+
+`maskColors` compares the bytes a source was stored as, and a nested stack has
+none — it is evaluated, so what arrives is already metres. Refusing the field
+there would leave one kind of source unable to say a thing every other kind can,
+for a reason that is about storage rather than about meaning.
+
+So the colour is decoded into the height it names, under the encoding the inner
+stack packs its own output in, and masked as a height. Through `decodeHeights`
+rather than arithmetic written a second time: it is the same question the merge
+asks of every pixel, and a second copy of it is a second thing to keep in step
+with `terrarium` and the custom factors.
+
+`maskColors: ["#0186a0"]` and `maskValues: [0]` therefore say the same thing to
+a mapbox-encoded stack, which is what lets a source keep its mask when it is
+swapped between an archive and a stack.
+
+What stays refused is the rest of that family — `encoding`, `baseVal`,
+`interval` and the custom factors. Those describe how to unpack channels into a
+number, and there are no channels: the number arrived already made.
+
 ### Nothing passes through
 
 The short-circuit that hands back a source's own bytes cannot apply: there are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.99.2",
+  "version": "0.100.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/elevation.js

@@ -187,6 +187,42 @@ export function rangesOf(maskRange) {
   return out;
 }
 
+/**
+ * The heights a list of colours stands for, under one encoding.
+ *
+ * `maskColors` compares the bytes a source was stored as, which a nested stack
+ * has none of: it is evaluated, so what arrives is already metres. Rather than
+ * refuse the field there -- leaving one kind of source unable to say a thing
+ * every other kind can -- the colour is decoded into the height it names, and
+ * the mask is applied as a height like any other.
+ *
+ * Through `decodeHeights` rather than arithmetic written again here. It is the
+ * same question the merge asks of every pixel, and a second implementation of
+ * it is a second thing to keep in step with `terrarium` and the custom factors.
+ * @param {Array<string|number[]>} [colours] - What the recipe named.
+ * @param {object} [encoding] - `encoding`, and the factors a custom one needs.
+ * @returns {number[]|undefined} - Those heights, or undefined for no colours.
+ */
+export function heightsForColors(colours, encoding = {}) {
+  const packed = (colours ?? [])
+    .map((colour) => parseColor(colour))
+    .filter((value) => value !== null);
+  if (!packed.length) return undefined;
+
+  const data = new Uint8Array(packed.length * 3);
+  packed.forEach((value, i) => {
+    data[i * 3] = (value >> 16) & 255;
+    data[i * 3 + 1] = (value >> 8) & 255;
+    data[i * 3 + 2] = value & 255;
+  });
+  return [
+    ...decodeHeights(
+      { data, channels: 3, width: packed.length, height: 1 },
+      encoding,
+    ),
+  ];
+}
+
 /**
  * Blanks every height inside a band.
  *
@@ -719,6 +755,11 @@ export function mergeElevation(contributions, options) {
     maskHeights(heights, source.maskValues);
     if (contribution.raster) {
       maskColors(heights, contribution.raster, source.maskColors);
+    } else {
+      // A nested stack has no bytes to compare a colour against, so the
+      // colours it named were decoded into the heights they stand for before
+      // this. Same field, same meaning, asked of what there is.
+      maskHeights(heights, contribution.colorHeights);
     }
     // A band as well as, not instead of: a source may have a sentinel it names
     // exactly and a range of ground it does not want either.

package/src/stack-tile.js

@@ -3,6 +3,7 @@ import {
   decodeHeights,
   encodeHeights,
   fillNodata,
+  heightsForColors,
   maskColors,
   maskHeights,
   maskRanges,
@@ -504,6 +505,19 @@ async function gather({
         source: read.source.source,
         heights: inner.heights,
         width: inner.width,
+        // Kept so a feather can measure its ramp past this tile's border. The
+        // heights above are this tile only; where the hole continues is a
+        // question only the parent can answer, and for a stack that means
+        // evaluating it again rather than reading bytes.
+        nested: read.source.nested,
+        // A colour named against something that was never stored as pixels.
+        // Read as the height it stands for, under the encoding the inner
+        // stack packs its own output in -- which is the encoding those bytes
+        // would have been, had there been any.
+        colorHeights: heightsForColors(
+          read.source.source?.maskColors,
+          read.source.nested?.stack?.output ?? {},
+        ),
       });
       continue;
     }
@@ -598,7 +612,17 @@ async function gather({
     });
   }
 
-  await readMaskEdges({ contributions, z, x, y, size, tiles, codec, signal });
+  await readMaskEdges({
+    contributions,
+    z,
+    x,
+    y,
+    size,
+    tiles,
+    codec,
+    signal,
+    cutlines,
+  });
   return { contributors, contributions };
 }
 
@@ -640,6 +664,7 @@ async function readMaskEdges({
   tiles,
   codec,
   signal,
+  cutlines,
 }) {
   if (!codec) return;
   await Promise.all(
@@ -648,9 +673,13 @@ async function readMaskEdges({
       const recipe = contribution.source ?? {};
       // 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 grid = contribution.raster?.width ?? contribution.width ?? size;
       const feather = featherFor(recipe, { z, y, size: grid });
-      if (!feather || !masksAnything(recipe)) return;
+      if (!feather) return;
+      // A nested stack arrives with its holes already in it -- they are where
+      // its own sources stopped -- so it has an edge whether or not the recipe
+      // above it masks anything. Everything else needs a mask to have made one.
+      if (!contribution.nested && !masksAnything(recipe)) return;
       const layout = parentsFor({ z, x, y }, grid, feather);
       if (!layout) return;
 
@@ -658,6 +687,43 @@ async function readMaskEdges({
       let parentSize = grid;
       await Promise.all(
         layout.tiles.map(async (parent) => {
+          // A nested stack has no bytes to read: what its holes are is the
+          // answer to evaluating it, so it is evaluated. One level up and at
+          // most four tiles, and only for a source that actually fades --
+          // which is what keeps this from being the whole recipe again on
+          // every tile.
+          if (contribution.nested) {
+            const inner = await stackHeights({
+              resolved: contribution.nested,
+              z: parent.z,
+              x: parent.x,
+              y: parent.y,
+              tiles,
+              codec,
+              signal,
+              size: grid,
+              cutlines,
+            }).catch(() => null);
+            if (!inner?.heights) return;
+
+            // The masks the recipe above applies to it, on a copy: the ramp
+            // has to be measured against the same idea of a hole the merge
+            // will use, and stackHeights hands back an array we do not own.
+            // Colours included, as the heights they were read into.
+            const heights = Float32Array.from(inner.heights);
+            maskHeights(heights, recipe.maskValues);
+            maskHeights(heights, contribution.colorHeights);
+            maskRanges(heights, recipe.maskRange);
+
+            const flags = new Uint8Array(heights.length);
+            for (let i = 0; i < flags.length; i += 1) {
+              flags[i] = Number.isNaN(heights[i]) ? 0 : 1;
+            }
+            parentSize = inner.width;
+            known.set(`${parent.column},${parent.row}`, flags);
+            return;
+          }
+
           const tile = await (
             contribution.remote
               ? tiles.getRemoteTile(

package/src/stacks.js

@@ -132,7 +132,6 @@ const NOT_ON_A_NESTED_SOURCE = Object.freeze([
   'greenFactor',
   'blueFactor',
   'baseShift',
-  'maskColors',
 ]);
 
 /**
@@ -292,7 +291,13 @@ export function validateStack(stack) {
     // 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
     // most of these recipes actually stop.
+    //
+    // A nested stack always has one. Its holes are where its own sources
+    // stopped, and it hands them up unfilled precisely so the recipe above can
+    // show through -- so requiring a mask here asked for a second edge on top
+    // of the one it already brought.
     const fades =
+      source?.stack ||
       source?.cutline ||
       source?.bounds ||
       source?.maskValues?.length ||