signalk-underkeel 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to signalk-underkeel are documented here.
 
+## [0.2.0] - 2026-10-27
+
+### Added
+
+- Inland ENC cells (issue #50). A cell whose name and `DSID_INTU` give no usage band 1–6, as
+  Inland ENC cells give 7, takes its band from its compilation scale by the IHO S-65 ranges:
+  Rijkswaterstaat's Waddenzee cells, 1:2 000, are berthing. Before they were rejected ("usage
+  band unknown"). The Inland ENC low-water references (VERDAT 31, 36, 38) and approximate LAT
+  (42) count as low-water datums, so with no water-level source chart datum applies on them as
+  on LAT. Cells are found down to six folders below a folder holding the exchange set's
+  `CATALOG.031`, so an unzipped Inland ENC download (`ENC_ROOT/1R/7/<cell>/<cell>.000`) can be
+  set as the cells directory as it is.
+
+### Changed
+
+- Survey shadow: a charted shoal beyond the boat's buffer counts by the chance the chart is off
+  by its distance, and now also by the chance that the water charted closer is off as far: what
+  that water's survey measured lies under the boat unless it is. A CATZOC D drying flat 300 m
+  beyond 250 m of CATZOC B water no longer counts, nor do its no-coverage or unassessed flags;
+  in D water alone nothing changes. The explanation names the water that bounded it ("behind
+  30 m of water placed ±50 m"), and the navigation-safety schema carries it as
+  `chartPosition.shadow`. The UKC overlay does not apply it yet and stays at least as severe.
+- Two cells, or two survey-quality zones, that meet along one line with their vertices split
+  differently, overlapping or up to 0.5 m apart now cover the leaves on that seam. Before,
+  every such leaf read no coverage or unassessed. The index is rebuilt once (pyramid version 11).
+
 ## [0.1.0] - 2026-10-25
 
 ### Added

package/README.md

@@ -94,10 +94,14 @@ cells.
 The plugin reads unencrypted S-57 ENC cells as they are delivered: each `.000` base cell with
 its `.001`, `.002`, … updates beside it. Copy the exchange set, for example its `ENC_ROOT`
 folder, under one directory and set **ENC cells directory** to it; `.000` files are found down
-to three folders deep. The cells are read in place with GDAL compiled to WebAssembly
+to three folders deep, and down to six below a folder holding the exchange set's `CATALOG.031`,
+so an unzipped Inland ENC download (`<set>/ENC_ROOT/1R/7/1R7WAD07/1R7WAD07.000`) can be pointed
+at as it is. The cells are read in place with GDAL compiled to WebAssembly
 (gdal3.js), which the plugin installs with it, and the updates are applied as they are read.
 Nothing is converted or written next to the cells. A cell without an `M_COVR` coverage layer
-is rejected.
+is rejected. A cell's usage band comes from the third character of its name, else from its
+`DSID_INTU`, else from its compilation scale by the IHO ranges: Inland ENC cells, purpose 7 in
+both, at 1:2 000 are berthing (6).
 
 Land, shoreline and depth areas are placed by the cell's compilation scale (6 m at 1:12 000,
 or inside an `M_CSCL` area that area's smaller scale) rather than by the survey's CATZOC (500 m
@@ -195,7 +199,9 @@ style.
 
 The chart gives depths below chart datum; the water level is how far the sea stands above it.
 
-- `none`: chart datum, with σ 0.3 m for the unknown tide. On a chart whose datum is not a
+- `none`: chart datum, with σ 0.3 m for the unknown tide. Low-water datums include the Inland
+  ENC low-water references (VERDAT 31, 36, 38) and approximate LAT (42, Rijkswaterstaat's
+  Waddenzee cells). On a chart whose datum is not a
   low-water datum, such as the Finnish mean-water ENCs (VERDAT 3, 19 and 26), this is a degraded
   level: the state is at best `alert`, route legs at best `unverified`, nothing `clear`, and
   acknowledgements and own soundings are not used until a source is configured. The reason names

package/lib/engine/explain.js

@@ -33,7 +33,10 @@ function explain(tile, extras, v, wl) {
                 distance: Math.round(c.distance),
                 sigmaP: r2(c.sigmaP),
                 weight: Math.round(c.weight * 10000) / 10000,
-                source: c.source
+                source: c.source,
+                ...(c.shadow && {
+                    shadow: { distance: Math.round(c.shadow.distance), sigmaP: r2(c.shadow.sigmaP) }
+                })
             }
         }),
         mean: finite(u.mean),
@@ -106,7 +109,10 @@ function sentence(e) {
     const p = e.chartPosition;
     if (p) {
         const what = p.source === "topography" ? "chart drawing" : "survey";
-        terms[0] = `${terms[0]} ${m(p.distance)} away, placed ±${m(2 * p.sigmaP)} by its ${what} (${pct(p.weight)} % under the keel)`;
+        const behind = p.shadow
+            ? `, behind ${m(p.shadow.distance)} of water placed ±${m(2 * p.shadow.sigmaP)}`
+            : "";
+        terms[0] = `${terms[0]} ${m(p.distance)} away, placed ±${m(2 * p.sigmaP)} by its ${what}${behind} (${pct(p.weight)} % under the keel)`;
     }
     const mean = e.mean === null ? "−∞ m" : m(e.mean).replace(/^-/, "−");
     return `${terms.join(" ")} → μ = ${mean}, σ = ${m(e.sigma)}, P = ${pct(e.risk)} %`;

package/lib/foundation/geometry.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEAM_TOLERANCE = void 0;
 exports.geomBounds = geomBounds;
 exports.shiftGeom = shiftGeom;
 exports.pointInRing = pointInRing;
@@ -307,27 +308,142 @@ function collectEdges(poly, r, sides) {
     return true;
 }
 /**
- * True only when the areas together cover the closed rectangle. Every edge
- * that touches it must have area on both sides, which holds where two
- * polygons share the edge vertex for vertex; with no boundary of the union
- * crossing the rectangle, its centre decides. An edge split differently on
- * each side, or two areas that overlap rather than meet, returns false:
- * callers read false as "not covered", so it costs precision, never safety.
+ * Gaps between areas no wider than this, in Mercator metres (at most as
+ * many metres on the ground), count as covered by `areasCoverRect`. Two
+ * cells, or two quality zones, that meet along one line are often drawn
+ * with their vertices split differently along it, or a few centimetres
+ * apart: Rijkswaterstaat's Inland ENC cells 1R7WAD07 and 1R7WAD10 meet so,
+ * and their CATZOC A1 and B zones leave a sliver under 10 cm. Read exactly,
+ * every tile on such a seam had no coverage or no assessed survey.
+ */
+exports.SEAM_TOLERANCE = 0.5;
+/** Where segment a→b crosses segment c→d, as a fraction along a→b; undefined when it does not. */
+function crossingAt(a, b, c, d) {
+    const rx = b[0] - a[0];
+    const ry = b[1] - a[1];
+    const sx = d[0] - c[0];
+    const sy = d[1] - c[1];
+    const den = rx * sy - ry * sx;
+    if (den === 0) {
+        return undefined;
+    }
+    const qx = c[0] - a[0];
+    const qy = c[1] - a[1];
+    const t = (qx * sy - qy * sx) / den;
+    const u = (qx * ry - qy * rx) / den;
+    return t >= 0 && t <= 1 && u >= 0 && u <= 1 ? t : undefined;
+}
+/**
+ * Whether the line SEAM_TOLERANCE off edge a→b on its `outward` side (+1
+ * left, −1 right) lies in the areas wherever the edge is in `r`. Along that
+ * line the areas only start or stop where it crosses one of their edges, so
+ * the midpoint between each pair of crossings decides its stretch.
+ */
+function outsideCovered(a, b, len, outward, polys, r) {
+    if (!segmentIntersectsRect(a, b, r)) {
+        return true;
+    }
+    const [t0, t1] = [span.t0, span.t1];
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const nx = (-dy / len) * exports.SEAM_TOLERANCE * outward;
+    const ny = (dx / len) * exports.SEAM_TOLERANCE * outward;
+    const p = [a[0] + dx * t0 + nx, a[1] + dy * t0 + ny];
+    const q = [a[0] + dx * t1 + nx, a[1] + dy * t1 + ny];
+    const ts = crossings(p, q, polys);
+    for (let k = 0; k + 1 < ts.length; k++) {
+        const m = (ts[k] + ts[k + 1]) / 2;
+        const x = p[0] + (q[0] - p[0]) * m;
+        const y = p[1] + (q[1] - p[1]) * m;
+        if (!polys.some((poly) => inPolygon(x, y, poly))) {
+            return false;
+        }
+    }
+    return true;
+}
+/** 0, 1 and every fraction along p→q where it crosses an edge of the areas, in order. */
+function crossings(p, q, polys) {
+    const [minX, maxX] = [Math.min(p[0], q[0]), Math.max(p[0], q[0])];
+    const [minY, maxY] = [Math.min(p[1], q[1]), Math.max(p[1], q[1])];
+    const ts = [0, 1];
+    for (const poly of polys) {
+        for (const ring of [poly.outer, ...poly.holes]) {
+            const n = ring.length;
+            for (let i = 0, j = n - 1; i < n; j = i++) {
+                const c = ring[j];
+                const d = ring[i];
+                if (Math.max(c[0], d[0]) < minX ||
+                    Math.min(c[0], d[0]) > maxX ||
+                    Math.max(c[1], d[1]) < minY ||
+                    Math.min(c[1], d[1]) > maxY) {
+                    continue;
+                }
+                const t = crossingAt(p, q, c, d);
+                if (t !== undefined) {
+                    ts.push(t);
+                }
+            }
+        }
+    }
+    return ts.sort((x, y) => x - y);
+}
+/**
+ * `areasCoverRect` across seams: every edge touching `r` that bounds its own
+ * area on one side has the areas, within SEAM_TOLERANCE, on the other, so no
+ * boundary of the union, seams aside, crosses `r`. Then an edge touching it
+ * puts it inside the union; with none, its centre decides.
+ */
+function coverAcrossSeams(polys, r) {
+    let touched = false;
+    for (const poly of polys) {
+        for (const ring of [poly.outer, ...poly.holes]) {
+            const n = ring.length;
+            for (let i = 0, j = n - 1; i < n; j = i++) {
+                const a = ring[j];
+                const b = ring[i];
+                const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+                if (len === 0 || !segmentIntersectsRect(a, b, r)) {
+                    continue;
+                }
+                const sides = interiorSides(a, b, len, poly);
+                // An edge with area on both sides of its own, or on neither (a spike), bounds nothing.
+                if (sides === LEFT || sides === RIGHT) {
+                    touched = true;
+                    if (!outsideCovered(a, b, len, sides === LEFT ? -1 : 1, polys, r)) {
+                        return false;
+                    }
+                }
+            }
+        }
+    }
+    const cx = (r.minX + r.maxX) / 2;
+    const cy = (r.minY + r.maxY) / 2;
+    return touched || polys.some((poly) => inPolygon(cx, cy, poly));
+}
+/**
+ * True only when the areas together cover the closed rectangle, gaps no
+ * wider than SEAM_TOLERANCE aside. Where two polygons share each edge vertex
+ * for vertex, every edge that touches the rectangle has area on both sides;
+ * with no boundary of the union crossing the rectangle, its centre decides.
+ * Otherwise each such edge is followed across, `SEAM_TOLERANCE` out, so an
+ * edge split differently on each side, two areas that overlap, or a seam
+ * narrower than that still cover. Callers read false as "not covered".
  */
 function areasCoverRect(geoms, r) {
     const sides = new Map();
     const polys = geoms.flatMap((g) => (g.type === "polygon" ? g.polygons : []));
+    let shared = true;
     for (const poly of polys) {
         if (!collectEdges(poly, r, sides)) {
-            return false;
+            shared = false;
+            break;
         }
     }
-    for (const s of sides.values()) {
-        if (s !== (LEFT | RIGHT)) {
-            return false;
-        }
+    if (shared && [...sides.values()].every((s) => s === (LEFT | RIGHT))) {
+        const cx = (r.minX + r.maxX) / 2;
+        const cy = (r.minY + r.maxY) / 2;
+        return polys.some((poly) => inPolygon(cx, cy, poly));
     }
-    const cx = (r.minX + r.maxX) / 2;
-    const cy = (r.minY + r.maxY) / 2;
-    return polys.some((poly) => inPolygon(cx, cy, poly));
+    // One area alone has no seam: an edge of it touching the rectangle is the union's.
+    return polys.length > 1 && coverAcrossSeams(polys, r);
 }

package/lib/ingest/cell-reader.js

@@ -33,16 +33,17 @@ const positive = (n) => n !== undefined && n > 0 ? n : undefined;
 function cellInfoFromDsid(props, fallbackName) {
     const dsnm = typeof props.DSID_DSNM === "string" ? props.DSID_DSNM : fallbackName;
     const name = dsnm.replace(/\.\d{3}$/, "");
+    const compilationScale = positive(numeric(props.DSPM_CSCL));
     return {
         name,
         edition: numeric(props.DSID_EDTN) ?? 0,
         update: numeric(props.DSID_UPDN) ?? 0,
         issueDate: typeof props.DSID_ISDT === "string" ? props.DSID_ISDT : undefined,
-        band: (0, cells_1.usageBandFromName)(name),
+        band: (0, cells_1.usageBandOf)(name, numeric(props.DSID_INTU), compilationScale),
         verticalDatum: numeric(props.DSPM_VDAT),
         soundingDatum: numeric(props.DSPM_SDAT),
         source: typeof props.UK_SOURCE === "string" ? props.UK_SOURCE : undefined,
-        compilationScale: positive(numeric(props.DSPM_CSCL))
+        compilationScale
     };
 }
 /** The layers of an exported cell directory, one `<LAYER>.geojson` each. */
@@ -91,7 +92,7 @@ function readCellLayers(layers, fallbackName, cellRef, bandOverride, where = fal
     const partial = cellInfoFrom(layers, fallbackName);
     const band = bandOverride ?? partial.band;
     if (band === undefined) {
-        throw new Error(`cell ${partial.name}: usage band unknown; set it explicitly`);
+        throw new Error(`cell ${partial.name}: usage band unknown: no band 1–6 in its name or DSID_INTU, and no compilation scale`);
     }
     const info = { ...partial, band };
     const advisory = info.source === wfs_1.WFS_SOURCE ? true : undefined;

package/lib/ingest/cell-source.js

@@ -43,6 +43,14 @@ function readCell(source, cellRef) {
 }
 /** How deep below the cells directory S-57 cells are looked for: ENC_ROOT/<cell>/<cell>.000. */
 const MAX_DEPTH = 4;
+/**
+ * How many folders below an exchange set's root, the directory holding its
+ * CATALOG.031, a cell may sit (as MAX_DEPTH − 1 below the cells directory).
+ * S-57 leaves the layout under it to the producer: Rijkswaterstaat's Inland
+ * ENC sets hold ENC_ROOT/1R/7/1R7WAD07/1R7WAD07.000, three folders down.
+ */
+const EXCHANGE_SET_DEPTH = 6;
+const isCatalogue = (name) => /^catalog\.031$/i.test(name);
 function isDirectory(p) {
     try {
         return fs_1.default.statSync(p).isDirectory();
@@ -53,8 +61,12 @@ function isDirectory(p) {
 }
 /**
  * The S-57 cells under `cellsDir`: every `.000` file down to MAX_DEPTH, such
- * as in an ENC_ROOT exchange set. A name met twice keeps its first file in
- * path order.
+ * as in an ENC_ROOT exchange set, and down to EXCHANGE_SET_DEPTH below any
+ * directory holding a CATALOG.031 within it. A name met twice keeps its first
+ * file in path order; one file met again through a link counts once. A
+ * directory is read again only when reached with more depth left than
+ * before, and never from within itself, so a linked loop ends where it comes
+ * back.
  */
 function scanCellSources(cellsDir) {
     const scan = { sources: [], skipped: [] };
@@ -62,7 +74,18 @@ function scanCellSources(cellsDir) {
         return scan;
     }
     const seen = new Set();
+    const files = new Set();
+    /** Folders named like a cell, by real path: skipped unless a cell is read from under one. */
+    const named = new Map();
+    /** Real paths of the folders a `.000` was met in; a linked file's target may lie elsewhere. */
+    const holding = new Set();
     const add = (source) => {
+        holding.add(fs_1.default.realpathSync(path_1.default.dirname(source)));
+        const real = fs_1.default.realpathSync(source);
+        if (files.has(real)) {
+            return;
+        }
+        files.add(real);
         const name = sourceName(source);
         if (seen.has(name)) {
             scan.skipped.push(path_1.default.relative(cellsDir, source));
@@ -71,34 +94,57 @@ function scanCellSources(cellsDir) {
         seen.add(name);
         scan.sources.push(source);
     };
-    const walk = (dir, depth) => {
+    /** Depth left when each real directory was read, and those being read now. */
+    const left = new Map();
+    const open = new Set();
+    const take = (dir, e, depth, limit) => {
+        const full = path_1.default.join(dir, e.name);
+        const directory = e.isDirectory() || (e.isSymbolicLink() && isDirectory(full));
+        if (directory) {
+            if ((0, cells_1.usageBandFromName)(e.name) !== undefined) {
+                named.set(path_1.default.relative(cellsDir, full), fs_1.default.realpathSync(full));
+                scan.skipped.push(path_1.default.relative(cellsDir, full));
+            }
+            if (depth < limit) {
+                walk(full, depth + 1, limit);
+            }
+        }
+        else if ((0, exports.isEncFile)(e.name) && fs_1.default.existsSync(full)) {
+            add(full);
+        }
+        else if (e.isSymbolicLink() && !fs_1.default.existsSync(full)) {
+            // A dangling link is most likely a cell the user expects read.
+            scan.skipped.push(path_1.default.relative(cellsDir, full));
+        }
+    };
+    /** Reads the entries of `dir`, at `depth`, and its directories down to `deepest` (deeper below a CATALOG.031). */
+    function walk(dir, depth, deepest) {
+        // A link back up an exchange set would otherwise raise the limit at every turn.
+        const real = fs_1.default.realpathSync(dir);
+        if (open.has(real) || (left.get(real) ?? -1) >= deepest - depth) {
+            return;
+        }
+        left.set(real, deepest - depth);
+        open.add(real);
         const entries = fs_1.default
             .readdirSync(dir, { withFileTypes: true })
             .sort((a, b) => (a.name < b.name ? -1 : 1));
+        const limit = entries.some((e) => isCatalogue(e.name))
+            ? Math.max(deepest, depth + EXCHANGE_SET_DEPTH)
+            : deepest;
         for (const e of entries) {
-            if (e.name.startsWith(".")) {
-                continue;
-            }
-            const full = path_1.default.join(dir, e.name);
-            const directory = e.isDirectory() || (e.isSymbolicLink() && isDirectory(full));
-            if (directory) {
-                const before = scan.sources.length;
-                if (depth < MAX_DEPTH) {
-                    walk(full, depth + 1);
-                }
-                if (scan.sources.length === before && (0, cells_1.usageBandFromName)(e.name) !== undefined) {
-                    scan.skipped.push(path_1.default.relative(cellsDir, full));
-                }
-            }
-            else if ((0, exports.isEncFile)(e.name) && fs_1.default.existsSync(full)) {
-                add(full);
-            }
-            else if (e.isSymbolicLink() && !fs_1.default.existsSync(full)) {
-                // A dangling link is most likely a cell the user expects read.
-                scan.skipped.push(path_1.default.relative(cellsDir, full));
+            if (!e.name.startsWith(".")) {
+                take(dir, e, depth, limit);
             }
         }
-    };
-    walk(cellsDir, 1);
+        open.delete(real);
+    }
+    walk(cellsDir, 1, MAX_DEPTH);
+    // Decided once every path is read: a folder reached too deep by one path may be read by another.
+    const holds = (dir) => [...holding].some((d) => d === dir || d.startsWith(dir + path_1.default.sep));
+    scan.skipped = scan.skipped.filter((entry) => {
+        const real = named.get(entry);
+        return real === undefined || !holds(real);
+    });
     return scan;
 }

package/lib/ingest/cells.js

@@ -6,6 +6,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compilationSigma = compilationSigma;
 exports.usageBandFromName = usageBandFromName;
+exports.usageBandFromScale = usageBandFromScale;
+exports.usageBandOf = usageBandOf;
 exports.parseCatalogue = parseCatalogue;
 /**
  * Plotting accuracy of a chart compiled at scale 1:`scale`, as a 1σ in
@@ -20,9 +22,32 @@ function compilationSigma(scale) {
  * undefined so the caller must supply the band explicitly.
  */
 function usageBandFromName(name) {
-    const c = name.charAt(2);
-    const band = Number(c);
-    return Number.isInteger(band) && band >= 1 && band <= 6 ? band : undefined;
+    return usageBand(Number(name.charAt(2)));
+}
+function usageBand(n) {
+    return n !== undefined && Number.isInteger(n) && n >= 1 && n <= 6 ? n : undefined;
+}
+/**
+ * The usage band of a compilation scale 1:`scale`, by the IHO S-65 scale
+ * ranges: overview below 1:1 500 000, general to 1:350 000, coastal to
+ * 1:90 000, approach to 1:22 000, harbour to 1:4 000, berthing above it.
+ */
+function usageBandFromScale(scale) {
+    if (scale === undefined || !(scale > 0)) {
+        return undefined;
+    }
+    const limits = [1_500_000, 350_000, 90_000, 22_000, 4_000];
+    const i = limits.findIndex((limit) => scale >= limit);
+    return i < 0 ? 6 : i + 1;
+}
+/**
+ * A cell's usage band: the third character of its name, else the intended
+ * usage of its DSID record (`DSID_INTU`), else its compilation scale. Inland
+ * ENC cells carry 7 in both (Rijkswaterstaat's 1R7WAD07, 1:2 000), so they
+ * fall to the scale: berthing.
+ */
+function usageBandOf(name, intu, scale) {
+    return usageBandFromName(name) ?? usageBand(intu) ?? usageBandFromScale(scale);
 }
 function finiteOrUndefined(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;

package/lib/model/water-level.js

@@ -165,8 +165,14 @@ function iso(t) {
 /**
  * S-57 VERDAT codes of low-water datums: the tide seldom leaves less water
  * than charted, so chart datum with σ 0.3 m stands in for an unknown level.
+ * The Inland ENC encoding guide adds 31 (local low water reference level),
+ * 36 (the Danube Commission's low water level), 38 (the Dutch river low
+ * water reference level, OLR) and 42 (approximate LAT, Rijkswaterstaat's
+ * Waddenzee cells).
  */
-const LOW_WATER_DATUMS = new Set([1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 22, 23, 27]);
+const LOW_WATER_DATUMS = new Set([
+    1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 22, 23, 27, 31, 36, 38, 42
+]);
 function isLowWaterDatum(verdat) {
     return LOW_WATER_DATUMS.has(verdat);
 }

package/lib/spatial/pyramid.js

@@ -9,6 +9,7 @@ const geometry_1 = require("../foundation/geometry");
 const node_store_1 = require("./node-store");
 const walk_1 = require("./walk");
 const chart_position_1 = require("./chart-position");
+const survey_shadow_1 = require("./survey-shadow");
 /** A footprint ring in WGS84, as a Mercator polygon. */
 function footprintGeom(ring) {
     const outer = ring.map((p) => (0, geo_1.toMercator)(p[0], p[1]));
@@ -87,6 +88,10 @@ function bathyRisk(w, bathy, sigmaD, bound) {
     }
     return (0, walk_1.riskAt)(w, bathy, sigmaD);
 }
+/** Whether node i's flags reach the footprint from `ground` metres beyond the buffer. */
+function flagsReach(w, i, ground) {
+    return ground <= (0, chart_position_1.flagReach)(w.store.surveySigma(i)) && !(0, survey_shadow_1.flagsShadowed)(w.shadow, ground);
+}
 /**
  * The weighted P a tile beyond the buffer adds, `ground` metres past it:
  * its survey depth's P times the chance its survey is off that far, or its
@@ -101,11 +106,14 @@ function reachRisk(w, i, v, ground, bound) {
     // tile just past the buffer would then read a higher P than within it.
     const bathy = Math.max(w.store.bathyDMinOf(i), v.dMin);
     let best;
+    // The shadow is only searched for a P that could raise the footprint's, past
+    // RISK_STOP_BELOW or the P found so far, as the walk only stops below one.
+    const floor = Math.max(w.maxRisk, exports.RISK_STOP_BELOW);
     // A split node's flags hold NO_DEPTH when any leaf under it has no depth;
     // its bathyDMin is Infinity only when none has any.
     if (survey > 0 && bathy !== Infinity) {
-        const weight = (0, chart_position_1.chartWeight)(ground, survey);
-        const risk = bathyRisk(w, bathy, v.sigmaD, bound) * weight;
+        const p = bathyRisk(w, bathy, v.sigmaD, bound);
+        const { risk, weight, shadow } = (0, survey_shadow_1.shadedWeight)(w.shadow, ground, survey, p, floor);
         best = {
             risk,
             dMin: bathy,
@@ -114,15 +122,16 @@ function reachRisk(w, i, v, ground, bound) {
                 distance: ground,
                 sigmaP: Math.min(chart_position_1.MAX_CHART_SIGMA, survey),
                 weight,
-                source: "survey"
+                source: "survey",
+                ...(shadow && { shadow })
             }
         };
     }
     // Land reads −Infinity, which v.dMin then is too; float32 rounding as for the survey depth.
     const drawn = Math.max(w.store.topoDMinOf(i), v.dMin);
     if (topo > 0 && drawn !== Infinity) {
-        const weight = (0, chart_position_1.chartWeight)(ground, topo);
-        const risk = bathyRisk(w, drawn, v.sigmaD, bound) * weight;
+        const p = bathyRisk(w, drawn, v.sigmaD, bound);
+        const { risk, weight, shadow } = (0, survey_shadow_1.shadedWeight)(w.shadow, ground, topo, p, floor);
         if (!best || risk > best.risk) {
             best = {
                 risk,
@@ -131,7 +140,8 @@ function reachRisk(w, i, v, ground, bound) {
                     distance: ground,
                     sigmaP: Math.min(chart_position_1.MAX_CHART_SIGMA, topo),
                     weight,
-                    source: "topography"
+                    source: "topography",
+                    ...(shadow && { shadow })
                 }
             };
         }
@@ -140,7 +150,7 @@ function reachRisk(w, i, v, ground, bound) {
 }
 /** Counts a leaf, or a stand-in, beyond the buffer by its chart position. */
 function takeBeyond(w, i, v, flags, ground, bound, z, x, y) {
-    if (ground <= (0, chart_position_1.flagReach)(w.store.surveySigma(i))) {
+    if (flagsReach(w, i, ground)) {
         (0, walk_1.foldFlags)(w, v, flags);
     }
     if (!w.risk) {
@@ -172,7 +182,7 @@ function visitBeyond(w, i, ground, z, x, y) {
         takeBeyond(w, i, v, v.flags, ground, false, z, x, y);
         return;
     }
-    const inFlags = ground <= (0, chart_position_1.flagReach)(w.store.surveySigma(i));
+    const inFlags = flagsReach(w, i, ground);
     const bound = w.risk ? (reachRisk(w, i, v, ground, true)?.risk ?? 0) : 0;
     const settled = bound <= Math.max(w.maxRisk, exports.RISK_STOP_BELOW);
     if (settled && (!inFlags || (v.flags & PRECISE_FLAGS) === 0)) {
@@ -229,7 +239,7 @@ function negligible(w, i, gap) {
         return false;
     }
     const ground = (gap - w.reachBase) / w.perMetre;
-    if (ground <= (0, chart_position_1.flagReach)(w.store.surveySigma(i))) {
+    if (flagsReach(w, i, ground)) {
         return false;
     }
     if (!w.risk) {
@@ -330,6 +340,8 @@ function walkFor(store, geom, opts) {
     // past the threshold: there P rises with σ, so the parent's widest σ
     // bounds every child's P from above.
     const clearAbove = Math.max(opts.clearAbove ?? (opts.risk ? -Infinity : Infinity), opts.risk?.threshold ?? -Infinity);
+    const reachBase = graded ? perMetre * bufferMetres : maxReach;
+    const toGround = (d) => Math.max(0, (d - reachBase) / perMetre);
     return {
         store,
         geom,
@@ -337,7 +349,7 @@ function walkFor(store, geom, opts) {
         hold: bounds,
         // The plain walk's buffer, so the tiles within it are the same with chart position or not.
         buffer: graded ? mercatorBuffer(bounds, bufferMetres) * exports.REACH_SLACK : maxReach,
-        reachBase: graded ? perMetre * bufferMetres : maxReach,
+        reachBase,
         maxReach,
         perMetre,
         graded,
@@ -349,7 +361,10 @@ function walkFor(store, geom, opts) {
         rect: { minX: 0, minY: 0, maxX: 0, maxY: 0 },
         coveredDMin: Infinity,
         cells: new Set(),
-        visits: 0
+        visits: 0,
+        shadow: graded
+            ? (0, survey_shadow_1.shadowFor)(store, geom, (0, geo_1.expandRect)(bounds, maxReach), maxReach, toGround)
+            : undefined
     };
 }
 /**

package/lib/spatial/store.js

@@ -41,11 +41,11 @@ const pyramid_blocks_1 = require("./pyramid-blocks");
  * assessed water no longer burned; version 8: tiles split no finer than 1 mm
  * at their cells' compilation scale; version 9: the drawn-depth column, depth areas placed by
  * the chart's drawing; version 10: an M_CSCL area's drawing σ applied only on the leaves the
- * area reaches), so an index built under
- * older rules is rebuilt rather than reused.
+ * area reaches; version 11: coverage and quality zones covering a tile across seams no wider
+ * than SEAM_TOLERANCE), so an index built under older rules is rebuilt rather than reused.
  */
 const MAGIC = "underkeel-pyramid";
-exports.PYRAMID_VERSION = 10;
+exports.PYRAMID_VERSION = 11;
 function columnsOf(count) {
     return {
         z: new Uint8Array(count),

package/lib/spatial/survey-shadow.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SurveyShadow = void 0;
+exports.shadowFor = shadowFor;
+exports.shadedWeight = shadedWeight;
+exports.flagsShadowed = flagsShadowed;
+const geo_1 = require("../foundation/geo");
+const geometry_1 = require("../foundation/geometry");
+const stats_1 = require("../foundation/stats");
+const chart_position_1 = require("./chart-position");
+const walk_1 = require("./walk");
+/** The σ bound for a tile's subtree as the shadow reads it (MAX_CHART_SIGMA when not modelled). */
+function levelOf(store, i, z, x, y) {
+    if (i < 0 || (store.isSplit(i) && store.standIn(i, z, x, y))) {
+        return chart_position_1.MAX_CHART_SIGMA;
+    }
+    const sigma = store.surveySigma(i);
+    if (sigma <= 0 || (store.values(i).flags & walk_1.REACH_FLAGS) !== 0) {
+        return chart_position_1.MAX_CHART_SIGMA;
+    }
+    return Math.min(sigma, chart_position_1.MAX_CHART_SIGMA);
+}
+/**
+ * The running maximum S(r) around one footprint, found nearest first: a
+ * best-first search over the pyramid that descends only nodes whose widest σ
+ * (or flags) could raise it, and stops once it reaches MAX_CHART_SIGMA or
+ * the distance asked. A walk asks for growing distances; the search resumes
+ * where it stopped.
+ */
+class SurveyShadow {
+    store;
+    geoms;
+    ground;
+    limit;
+    heap = [];
+    steps = [];
+    level = 0;
+    /** Every tile nearer than this has been read. */
+    searched = 0;
+    /**
+     * @param geoms the footprint, and its copies one world over where its reach crosses ±180°
+     * @param reach Mercator box holding every tile within the widest reach of the footprint
+     * @param ground ground metres beyond the buffer of a Mercator distance from the footprint
+     * @param limit Mercator distance beyond which no tile is read
+     */
+    constructor(store, geoms, reaches, ground, limit) {
+        this.store = store;
+        this.geoms = geoms;
+        this.ground = ground;
+        this.limit = limit;
+        for (const reach of reaches) {
+            const range = (0, geo_1.tileRange)(store.minZoom, reach);
+            for (let x = range.minX; x <= range.maxX; x++) {
+                for (let y = range.minY; y <= range.maxY; y++) {
+                    this.offer(store.minZoom, x, y);
+                }
+            }
+        }
+    }
+    /** Queues a tile within the limit, by its ground distance. */
+    offer(z, x, y) {
+        const rect = (0, geo_1.tileRect)(z, x, y);
+        let d = Infinity;
+        for (const g of this.geoms) {
+            d = Math.min(d, (0, geometry_1.geomRectDistance)(g, rect, this.limit));
+        }
+        if (d <= this.limit) {
+            this.push({ d: this.ground(d), z, x, y });
+        }
+    }
+    /** Reads tiles nearest first until every tile nearer than `g` is read. */
+    extend(g) {
+        while (this.heap.length > 0 && this.level < chart_position_1.MAX_CHART_SIGMA) {
+            const top = this.heap[0];
+            if (top.d >= g) {
+                this.searched = Math.max(this.searched, g);
+                return;
+            }
+            this.pop();
+            const { d, z, x, y } = top;
+            const i = this.store.find(z, x, y);
+            const level = levelOf(this.store, i, z, x, y);
+            if (level <= this.level) {
+                continue;
+            }
+            if (i >= 0 && this.store.isSplit(i) && !this.store.standIn(i, z, x, y)) {
+                this.offer(z + 1, 2 * x, 2 * y);
+                this.offer(z + 1, 2 * x + 1, 2 * y);
+                this.offer(z + 1, 2 * x, 2 * y + 1);
+                this.offer(z + 1, 2 * x + 1, 2 * y + 1);
+                continue;
+            }
+            this.steps.push({ at: d, sigma: level });
+            this.level = level;
+        }
+        // Nothing left, or S(r) at the widest σ: no tile further out changes it.
+        this.searched = Infinity;
+    }
+    /** ρ(g) for a tile `g` ground metres beyond the buffer, and the water that set it. */
+    at(g) {
+        if (!(g > 0)) {
+            return { ratio: 0, distance: 0, sigmaP: 0 };
+        }
+        if (this.searched < g) {
+            this.extend(g);
+        }
+        let best = { ratio: 0, distance: 0, sigmaP: 0 };
+        let sigma = chart_position_1.MAX_CHART_SIGMA;
+        for (let k = 0; k < this.steps.length; k++) {
+            const step = this.steps[k];
+            if (step.at >= g) {
+                break;
+            }
+            sigma = step.sigma;
+            const next = this.steps[k + 1];
+            // S(r) = sigma on (step.at, end]: r/S(r) is largest at the end.
+            const end = next !== undefined && next.at < g ? next.at : g;
+            if (end / sigma > best.ratio) {
+                best = { ratio: end / sigma, distance: end, sigmaP: sigma };
+            }
+        }
+        // No tile nearer than g at all: the water in between is not modelled.
+        if (this.steps.length === 0 || this.steps[0].at >= g) {
+            const ratio = g / sigma;
+            return ratio > best.ratio ? { ratio, distance: g, sigmaP: sigma } : best;
+        }
+        return best;
+    }
+    push(e) {
+        const a = this.heap;
+        a.push(e);
+        let i = a.length - 1;
+        while (i > 0) {
+            const p = (i - 1) >> 1;
+            if (a[p].d <= e.d) {
+                break;
+            }
+            a[i] = a[p];
+            i = p;
+        }
+        a[i] = e;
+    }
+    pop() {
+        const a = this.heap;
+        const last = a.pop();
+        if (a.length === 0) {
+            return;
+        }
+        let i = 0;
+        for (;;) {
+            const l = 2 * i + 1;
+            const r = l + 1;
+            let m = i;
+            let md = last.d;
+            if (l < a.length && a[l].d < md) {
+                m = l;
+                md = a[l].d;
+            }
+            if (r < a.length && a[r].d < md) {
+                m = r;
+            }
+            if (m === i) {
+                break;
+            }
+            a[i] = a[m];
+            i = m;
+        }
+        a[i] = last;
+    }
+}
+exports.SurveyShadow = SurveyShadow;
+/**
+ * The shadow around a footprint out to Mercator distance `limit`, its widest
+ * reach, within the box `reach`, with its copy one world over where that box
+ * crosses ±180°; not searched until a walk asks (`SurveyShadow`).
+ */
+function shadowFor(store, geom, reach, limit, ground) {
+    let shadow;
+    return () => (shadow ??= new SurveyShadow(store, (0, geo_1.worldShifts)(reach).map((s) => (s === 0 ? geom : (0, geometry_1.shiftGeom)(geom, s))), (0, geo_1.worldShifts)(reach).map((s) => (0, geo_1.shiftRect)(reach, s)), ground, limit));
+}
+/**
+ * A tile's chart position weight `ground` metres beyond the buffer, placed
+ * with σ, and the P it adds at P(UKC < 0) `p`, bounded by the shadow. A P
+ * at most `floor` is returned unbounded without searching: the caller only
+ * reads one above it.
+ */
+function shadedWeight(shadow, ground, sigma, p, floor) {
+    const weight = (0, chart_position_1.chartWeight)(ground, sigma);
+    const risk = p * weight;
+    // A tile at the buffer's edge counts in full: nothing lies between to shadow it.
+    if (!shadow || ground <= 0 || risk <= floor) {
+        return { risk, weight };
+    }
+    const s = shadow().at(ground);
+    const cap = (0, stats_1.normalCdf)(-s.ratio);
+    if (cap >= weight) {
+        return { risk, weight };
+    }
+    return { risk: p * cap, weight: cap, shadow: { distance: s.distance, sigmaP: s.sigmaP } };
+}
+/**
+ * Whether the water charted closer keeps a tile's flags from the footprint:
+ * they count within FLAG_SIGMAS·σ of its survey (`flagReach`), and here
+ * only where ρ(ground) is at most FLAG_SIGMAS too.
+ */
+function flagsShadowed(shadow, ground) {
+    return shadow !== undefined && shadow().at(ground).ratio > chart_position_1.FLAG_SIGMAS;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-underkeel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Under-keel clearance awareness for Signal K: look-ahead grounding risk, route checks and a living chart.",
   "main": "lib/index.js",
   "files": [