@photivra/engine 2.8.1 → 2.9.0

package/dist/core/version.d.ts

@@ -6,4 +6,4 @@
  * own versions. Release checks confirm it matches package.json and the packed package.
  * @see docs/RELEASE_1_0_1.md
  */
-export declare const ENGINE_API_VERSION: "2.8.1";
+export declare const ENGINE_API_VERSION: "2.9.0";

package/dist/core/version.js

@@ -7,5 +7,5 @@
  * own versions. Release checks confirm it matches package.json and the packed package.
  * @see docs/RELEASE_1_0_1.md
  */
-export const ENGINE_API_VERSION = "2.8.1";
+export const ENGINE_API_VERSION = "2.9.0";
 //# sourceMappingURL=version.js.map

package/dist/core/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/core/version.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAgB,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Version of the engine release. Since 1.0.1 it equals the npm package version.\n *\n * New captures and plans record this version as their creator. Archived records keep the\n * version they were made with. Proof-of-concept (POC), schema and model contracts have their\n * own versions. Release checks confirm it matches package.json and the packed package.\n * @see docs/RELEASE_1_0_1.md\n */\nexport const ENGINE_API_VERSION = \"2.8.1\" as const;\n"]}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/core/version.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAgB,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Version of the engine release. Since 1.0.1 it equals the npm package version.\n *\n * New captures and plans record this version as their creator. Archived records keep the\n * version they were made with. Proof-of-concept (POC), schema and model contracts have their\n * own versions. Release checks confirm it matches package.json and the packed package.\n * @see docs/RELEASE_1_0_1.md\n */\nexport const ENGINE_API_VERSION = \"2.9.0\" as const;\n"]}

package/dist/facade/expected-signal.d.ts

@@ -79,5 +79,8 @@ export interface DisplayViewExpectedSignal {
  * With diffraction, offsets that share a fractional shift read one lattice, and their kernels are combined in advance:
  * C_c(d) = Σ_members w·Σ_λ A_c(λ)·K_λ(t)·L(λ) over the taps t that reach lattice offset d. A neutral material's radiance
  * is its reflectance times the white radiance, so all neutral materials share one combined kernel per channel.
+ *
+ * `spanColumns`: how many native columns the render's windows move across beyond one window's width (a filled band is never
+ * built wider). Only a speed hint: a window past it rebuilds its band, with the same values.
  */
-export declare function createDisplayViewExpectedSignal(input: DisplayViewExpectedSignalInput): DisplayViewExpectedSignal;
+export declare function createDisplayViewExpectedSignal(input: DisplayViewExpectedSignalInput, spanColumns?: number): DisplayViewExpectedSignal;

package/dist/facade/expected-signal.js

@@ -11,23 +11,14 @@ const CACHE_LIMIT = 1 << 22;
 /** Largest band of looked-up lattice materials per group, in lattice points (a band that would be larger restarts at the window). */
 const BAND_LIMIT = 1 << 22;
 /**
- * Expected photo electrons per site: μ_c(i, j) = Σ_o w_o Σ_λ A_c(λ) Σ_t K_λ(t)·L(p_o(i, j) − t, λ), where p_o is the
- * query point of offset o and K the diffraction kernel (a single unit tap without diffraction). This is the sum the
- * facade's environment chain forms for a still, rectilinear, distortion-free planar scene, where the
- * radiance-to-irradiance factor is the same at every site (docs/DISPLAY_VIEW.md, "Expected signal").
- *
- * With diffraction, offsets that share a fractional shift read one lattice, and their kernels are combined in advance:
- * C_c(d) = Σ_members w·Σ_λ A_c(λ)·K_λ(t)·L(λ) over the taps t that reach lattice offset d. A neutral material's radiance
- * is its reflectance times the white radiance, so all neutral materials share one combined kernel per channel.
+ * Lattice-row ring (refinement windows): rows kept per group, the tallest band that uses it, and the columns kept beyond each
+ * raster edge (kernel radius, demosaic reach and query offsets; columns beyond it are looked up directly).
  */
-export function createDisplayViewExpectedSignal(input) {
-    const W = input.nativeWidth, H = input.nativeHeight, g = 2 / input.outputWidth, nodes = input.wavelengthsNm.length;
-    const R = input.kernels ? input.kernels.radius : 0, size = 2 * R + 1;
-    if (input.kernels && input.kernels.perNode.length !== nodes)
-        throw new InvalidConfigurationError("Display view kernels must match the spectral nodes.");
-    if (!input.kernels && !input.queryPoint)
-        throw new InvalidConfigurationError("Display view needs the environment query points without diffraction.");
-    const A = input.electronsPerRadiance, scene = input.scene, offsets = input.offsets, channelAt = input.channelAt;
+const LATTICE_RING_ROWS = 128, LATTICE_RING_MAXIMUM_BAND_ROWS = 64, LATTICE_RING_MARGIN = 64;
+const PREPARED = new WeakMap();
+function prepareSignal(input) {
+    const nodes = input.wavelengthsNm.length, R = input.kernels ? input.kernels.radius : 0, size = 2 * R + 1;
+    const A = input.electronsPerRadiance, scene = input.scene, offsets = input.offsets;
     const kernelAt = (node, t) => (input.kernels ? input.kernels.perNode[node][t] : 1);
     // Materials: neutral ones by reflectance, spectral ones by index.
     let reflectance = new Float64Array(0), spectralIndex = new Int32Array(0);
@@ -92,6 +83,46 @@ export function createDisplayViewExpectedSignal(input) {
         s += A[c][n] * scene.whiteRadiance[n]; return s; }) : [];
     const spectralDirect = [0, 1, 2].map((c) => spectral.map((radiance) => { let s = 0; for (let n = 0; n < nodes; n++)
         s += A[c][n] * radiance[n]; return s; }));
+    const uniformSite = scene.kind === "materials" && input.kernels ? [0, 1, 2].map((c) => Float64Array.from(scene.materials, (_, m) => {
+        const si = spectralIndex[m];
+        let sum = 0;
+        for (const group of groups) {
+            const nk = group.neutral[c], sk = si < 0 ? nk : group.spectral[c][si];
+            for (let t = 0; t < group.cw * group.ch; t++)
+                sum += si < 0 ? reflectance[m] * nk[t] : sk[t];
+        }
+        return sum;
+    })) : [];
+    const prepared = { reflectance, spectralIndex, spectral, groups, neutralDirect, spectralDirect, uniformSite, rings: groups.map(() => undefined) };
+    PREPARED.set(input, prepared);
+    return prepared;
+}
+/**
+ * Expected photo electrons per site: μ_c(i, j) = Σ_o w_o Σ_λ A_c(λ) Σ_t K_λ(t)·L(p_o(i, j) − t, λ), where p_o is the
+ * query point of offset o and K the diffraction kernel (a single unit tap without diffraction). This is the sum the
+ * facade's environment chain forms for a still, rectilinear, distortion-free planar scene, where the
+ * radiance-to-irradiance factor is the same at every site (docs/DISPLAY_VIEW.md, "Expected signal").
+ *
+ * With diffraction, offsets that share a fractional shift read one lattice, and their kernels are combined in advance:
+ * C_c(d) = Σ_members w·Σ_λ A_c(λ)·K_λ(t)·L(λ) over the taps t that reach lattice offset d. A neutral material's radiance
+ * is its reflectance times the white radiance, so all neutral materials share one combined kernel per channel.
+ *
+ * `spanColumns`: how many native columns the render's windows move across beyond one window's width (a filled band is never
+ * built wider). Only a speed hint: a window past it rebuilds its band, with the same values.
+ */
+export function createDisplayViewExpectedSignal(input, spanColumns = Infinity) {
+    const W = input.nativeWidth, H = input.nativeHeight, g = 2 / input.outputWidth, nodes = input.wavelengthsNm.length;
+    const R = input.kernels ? input.kernels.radius : 0;
+    if (input.kernels && input.kernels.perNode.length !== nodes)
+        throw new InvalidConfigurationError("Display view kernels must match the spectral nodes.");
+    if (!input.kernels && !input.queryPoint)
+        throw new InvalidConfigurationError("Display view needs the environment query points without diffraction.");
+    const A = input.electronsPerRadiance, scene = input.scene, offsets = input.offsets, channelAt = input.channelAt;
+    // The request's tables (materials, lattice groups, combined kernels, per-material sums) are the same for every render of a
+    // prepared view, which passes the same input object: computed once per input. Each render gets its own groups' window caches.
+    const prepared = PREPARED.get(input) ?? prepareSignal(input);
+    const { reflectance, spectralIndex, spectral, neutralDirect, spectralDirect, uniformSite } = prepared;
+    const groups = prepared.groups.map((group) => ({ ...group, cache: new Int32Array(0), cx0: 0, cy0: 0, cpw: 0, cph: 0 }));
     let lookups = 0;
     const point = new Float64Array(2);
     const materialSignalDirect = (m, c) => {
@@ -190,24 +221,31 @@ export function createDisplayViewExpectedSignal(input) {
     // kernelSite, so it is bit-identical. The scene lookup count stays the count kernelSite's lazy window cache makes (each
     // cache point a computed site reads counts once per window, points outside the cache once per read): the rectangles of
     // the sites computed in a window are counted when the window closes (windowLookups).
-    const uniformSite = scene.kind === "materials" && input.kernels ? [0, 1, 2].map((c) => Float64Array.from(scene.materials, (_, m) => {
-        const si = spectralIndex[m];
-        let sum = 0;
-        for (const group of groups) {
-            const nk = group.neutral[c], sk = si < 0 ? nk : group.spectral[c][si];
-            for (let t = 0; t < group.cw * group.ch; t++)
-                sum += si < 0 ? reflectance[m] * nk[t] : sk[t];
-        }
-        return sum;
-    })) : [];
     const allNeutral = spectral.length === 0;
     const bands = groups.map(() => ({ x0: 0, y0: 0, rows: 0, capacity: 0, filled: 0, material: new Int32Array(0), reflectance: new Float64Array(0),
         changeLeft: new Int32Array(0), changeUp: new Int32Array(0), v: new Float64Array(0) }));
+    // Lattice rows of material indices per group, kept across windows (filled windows only): rows LATTICE_RING_ROWS apart share a
+    // slot; columns from −LATTICE_RING_MARGIN. Int16 when every index fits (about 3 MB for four groups of a 6000-site row). A
+    // lattice point's material depends only on the input, so the rings are kept with its prepared tables, across renders.
+    const ringWide = scene.kind === "materials" && scene.materials.length <= 32767;
+    const rings = prepared.rings;
+    function latticeRing(g) {
+        let ring = rings[g];
+        if (!ring) {
+            const width = W + 2 * LATTICE_RING_MARGIN, size = LATTICE_RING_ROWS * width;
+            ring = rings[g] = { width, material: ringWide ? new Int16Array(size) : new Int32Array(size), rowId: new Int32Array(LATTICE_RING_ROWS).fill(-2147483648) };
+        }
+        return ring;
+    }
     /** Makes the band of group g cover lattice columns [x0, x1) of rows [y0, y0 + rows), extending it to the right when it can. */
     function coverBand(g, x0, x1, y0, rows) {
         const group = groups[g], band = bands[g], materials = scene;
-        if (!(band.rows === rows && band.y0 === y0 && x0 >= band.x0 && x1 - band.x0 <= band.capacity)) {
-            const capacity = Math.max(x1 - x0, Math.min(Math.floor(BAND_LIMIT / rows), W + 2 * (x1 - x0)));
+        if (!(y0 >= band.y0 && y0 + rows <= band.y0 + band.rows && x0 >= band.x0 && x1 - band.x0 <= band.capacity)) {
+            // A band with the ring is built twice as tall, so the next display rows' windows (a few lattice rows lower) reuse its
+            // filled columns; a lattice point's material and the change counts inside a rectangle do not depend on the band's origin.
+            if (rows <= LATTICE_RING_MAXIMUM_BAND_ROWS)
+                rows *= 2;
+            const capacity = Math.max(x1 - x0, Math.min(Math.floor(BAND_LIMIT / rows), W + 2 * (x1 - x0), spanColumns + x1 - x0));
             const size = rows * capacity, tables = (rows + 1) * (capacity + 1);
             band.x0 = x0;
             band.y0 = y0;
@@ -234,10 +272,29 @@ export function createDisplayViewExpectedSignal(input) {
                 band.v[j] = latticeV(group, y0 + j);
         }
         const stride = band.capacity, S1 = stride + 1, material = band.material, left = band.changeLeft, up = band.changeUp;
+        rows = band.rows;
+        y0 = band.y0;
+        const ring = rows <= 2 * LATTICE_RING_MAXIMUM_BAND_ROWS ? latticeRing(g) : undefined;
         for (let i = band.filled; i < x1 - band.x0; i++) {
-            const u = latticeU(group, band.x0 + i);
+            const p = band.x0 + i, u = latticeU(group, p), column = p + LATTICE_RING_MARGIN;
             for (let j = 0; j < rows; j++) {
-                const m = materials.materialAt(u, band.v[j]);
+                let m;
+                if (ring && column >= 0 && column < ring.width) {
+                    // A lattice point's material is a function of the point alone, so one looked up for an earlier window (the rows a
+                    // display row shares with the next) is the same material; the ring only spares the repeated lookup.
+                    const q = y0 + j, slot = q & (LATTICE_RING_ROWS - 1), index = slot * ring.width + column;
+                    if (ring.rowId[slot] !== q) {
+                        ring.rowId[slot] = q;
+                        ring.material.fill(-1, slot * ring.width, (slot + 1) * ring.width);
+                    }
+                    m = ring.material[index];
+                    if (m < 0) {
+                        m = materials.materialAt(u, band.v[j]);
+                        ring.material[index] = m;
+                    }
+                }
+                else
+                    m = materials.materialAt(u, band.v[j]);
                 if (spectralIndex[m] === undefined)
                     throw new InvalidConfigurationError("Unknown chart material.");
                 material[j * stride + i] = m;
@@ -391,13 +448,17 @@ export function createDisplayViewExpectedSignal(input) {
             const v = ringRead(x, y, i, j);
             siteCache[j * sw + i] = v;
             windowMaterial[j * sw + i] = lastMaterial;
+            markFilled(i, j);
             return v;
         }
         if (filled && !cached)
             outsideRead(i, j);
         const v = filled ? filledSite(x, y, i, j) : input.kernels ? kernelSite(x, y) : directSite(x, y);
-        if (cached)
+        if (cached) {
             siteCache[j * sw + i] = v;
+            if (filled)
+                markFilled(i, j);
+        }
         return v;
     }
     /**
@@ -406,6 +467,40 @@ export function createDisplayViewExpectedSignal(input) {
      */
     function windowLookups() {
         let total = 0;
+        if (outsideSites.length === 0 && filledCount === 0)
+            return 0;
+        if (outsideSites.length === 0 && sw <= 31) {
+            // Computed sites as a bit mask per window row. Cache point (ci, cj) is covered when a computed site (i, j) has
+            // i ≤ ci < i + cw and j ≤ cj < j + ch; a union of dilations is the dilation of the union, so per cache row the
+            // covered columns are the dilation of the OR of the masks of window rows cj − ch + 1 … cj.
+            for (const group of groups) {
+                const cw = group.cw, ch = group.ch, cpw = group.cpw, cph = group.cph, last = Math.min(cph - 1, fy1 + ch - 1);
+                let previous = -1, width = 0;
+                for (let cj = fy0; cj <= last; cj++) {
+                    let m = 0;
+                    for (let j = Math.max(fy0, cj - ch + 1), top = Math.min(fy1, cj); j <= top; j++)
+                        m |= rowMask[j];
+                    if (m !== previous) {
+                        previous = m;
+                        width = 0;
+                        let end = -1;
+                        for (let i = 0; m >>> i !== 0; i++) {
+                            if (((m >>> i) & 1) === 0)
+                                continue;
+                            const to = Math.min(i + cw - 1, cpw - 1);
+                            if (i > end)
+                                width += to - i + 1;
+                            else if (to > end)
+                                width += to - end;
+                            if (to > end)
+                                end = to;
+                        }
+                    }
+                    total += width;
+                }
+            }
+            return total;
+        }
         for (const group of groups) {
             const cw = group.cw, ch = group.ch, cpw = group.cpw, cph = group.cph, ew = cpw + cw - 1, eh = cph + ch - 1;
             // Top-left marks in extended coordinates (window coordinates + (cw − 1, ch − 1)), and their bounding box.
@@ -466,6 +561,27 @@ export function createDisplayViewExpectedSignal(input) {
         return total;
     }
     let sx0 = 0, sy0 = 0, sw = 0, sh = 0, siteCache = new Float64Array(0);
+    // The computed entries of a filled window's site cache (windowLookups): their count, bounding box and a bit mask per row
+    // (columns below 31).
+    let filledCount = 0, fx0 = 0, fx1 = -1, fy0 = 0, fy1 = -1;
+    let rowMask = new Int32Array(0);
+    function markFilled(i, j) {
+        if (i < 31)
+            rowMask[j] = rowMask[j] | (1 << i);
+        if (filledCount++ === 0) {
+            fx0 = fx1 = i;
+            fy0 = fy1 = j;
+            return;
+        }
+        if (i < fx0)
+            fx0 = i;
+        else if (i > fx1)
+            fx1 = i;
+        if (j < fy0)
+            fy0 = j;
+        else if (j > fy1)
+            fy1 = j;
+    }
     const pilotNode = input.wavelengthsNm[Math.floor(nodes / 2)];
     return {
         get lookups() { return lookups + (filled ? windowLookups() : 0); },
@@ -478,6 +594,8 @@ export function createDisplayViewExpectedSignal(input) {
             filled = false;
             ringOn = false;
             outsideSites = [];
+            filledCount = 0;
+            rowMask.fill(0, 0, sh);
             sx0 = x0;
             sy0 = y0;
             sw = Math.max(0, x1 - x0);
@@ -488,6 +606,8 @@ export function createDisplayViewExpectedSignal(input) {
             }
             if (siteCache.length < sw * sh)
                 siteCache = new Float64Array(sw * sh);
+            if (rowMask.length < sh)
+                rowMask = new Int32Array(sh);
             siteCache.fill(NaN, 0, sw * sh);
             if (!input.kernels) {
                 // A ring of at least twice the window's rows keeps the rows of the previous display row's windows.