@woosh/meep-engine 3.38.0 → 3.39.0

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_design_row.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The reflection `r = reflect(-view, normal)` and the half-reflection `h_r = normalize(normal + r)`
+ * of Silvennoinen et al.'s reflection-half-reflection parametrization, written as
+ * `[r.xyz, h_r.xyz]`.
+ *
+ * @param {number[]|Float64Array} output length 6
+ * @param {number} nx unit normal
+ * @param {number} ny
+ * @param {number} nz
+ * @param {number} vx unit direction towards the viewer, `dot(normal, view) > 0`
+ * @param {number} vy
+ * @param {number} vz
+ */
+export function sh_exp_reflection_frame(output: number[] | Float64Array, nx: number, ny: number, nz: number, vx: number, vy: number, vz: number): void;
+/**
+ * One row of the SH-exponential least-squares system (the "row constraint" of Silvennoinen et al.,
+ * HPG 2025, https://doi.org/10.1111/cgf.70219):
+ *
+ *     [ vMF(1/alpha) ⊙ Y(r),  vMF(1/alpha) ⊙ Y(h_r) ] · [p; q] = log E0(view, normal, alpha)
+ *
+ * with Q's band 0 dropped (it is P's; see `sh_exp_coefficient_count`). `vMF(kappa)` is the per-band
+ * window `sh_vmf_window`. The GPU encoder builds the same row one coefficient at a time with
+ * `sh_basis_function`; this is the CPU form the system matrix and the specs use.
+ *
+ * @param {number[]|Float64Array|Float32Array} output written at `[output_offset, output_offset + coefficient_count)`
+ * @param {number} output_offset
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @param {number[]|Float64Array} frame `[r.xyz, h_r.xyz]` from {@link sh_exp_reflection_frame}
+ * @param {number} alpha GGX alpha
+ */
+export function sh_exp_design_row(output: number[] | Float64Array | Float32Array, output_offset: number, p_band_count: number, q_band_count: number, frame: number[] | Float64Array, alpha: number): void;
+//# sourceMappingURL=sh_exp_design_row.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_design_row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_exp_design_row.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/sh_exp_design_row.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;GAYG;AACH,gDARW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAqBhB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,0CAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,gBACN,MAAM,gBACN,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,QA8BhB"}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_design_row.js

@@ -0,0 +1,90 @@
+import { assert } from "../../../../../core/assert.js";
+import { sh_basis_at } from "../../../../../core/geom/3d/sphere/harmonics/sh_basis_at.js";
+import { sh_vmf_window } from "../../../../../core/geom/3d/sphere/harmonics/sh_vmf_window.js";
+
+/**
+ * Scratch for the two bases. Ten bands is the most the generated chunks reconstruct.
+ * @type {Float64Array}
+ */
+const scratch_basis = new Float64Array(100);
+
+/**
+ * The reflection `r = reflect(-view, normal)` and the half-reflection `h_r = normalize(normal + r)`
+ * of Silvennoinen et al.'s reflection-half-reflection parametrization, written as
+ * `[r.xyz, h_r.xyz]`.
+ *
+ * @param {number[]|Float64Array} output length 6
+ * @param {number} nx unit normal
+ * @param {number} ny
+ * @param {number} nz
+ * @param {number} vx unit direction towards the viewer, `dot(normal, view) > 0`
+ * @param {number} vy
+ * @param {number} vz
+ */
+export function sh_exp_reflection_frame(output, nx, ny, nz, vx, vy, vz) {
+    const k = 2 * (nx * vx + ny * vy + nz * vz);
+
+    const rx = k * nx - vx;
+    const ry = k * ny - vy;
+    const rz = k * nz - vz;
+
+    const hx = nx + rx;
+    const hy = ny + ry;
+    const hz = nz + rz;
+
+    const h_length = Math.hypot(hx, hy, hz);
+
+    output[0] = rx;
+    output[1] = ry;
+    output[2] = rz;
+    output[3] = hx / h_length;
+    output[4] = hy / h_length;
+    output[5] = hz / h_length;
+}
+
+/**
+ * One row of the SH-exponential least-squares system (the "row constraint" of Silvennoinen et al.,
+ * HPG 2025, https://doi.org/10.1111/cgf.70219):
+ *
+ *     [ vMF(1/alpha) ⊙ Y(r),  vMF(1/alpha) ⊙ Y(h_r) ] · [p; q] = log E0(view, normal, alpha)
+ *
+ * with Q's band 0 dropped (it is P's; see `sh_exp_coefficient_count`). `vMF(kappa)` is the per-band
+ * window `sh_vmf_window`. The GPU encoder builds the same row one coefficient at a time with
+ * `sh_basis_function`; this is the CPU form the system matrix and the specs use.
+ *
+ * @param {number[]|Float64Array|Float32Array} output written at `[output_offset, output_offset + coefficient_count)`
+ * @param {number} output_offset
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @param {number[]|Float64Array} frame `[r.xyz, h_r.xyz]` from {@link sh_exp_reflection_frame}
+ * @param {number} alpha GGX alpha
+ */
+export function sh_exp_design_row(output, output_offset, p_band_count, q_band_count, frame, alpha) {
+    // the scratch holds ten bands, the most the reconstruction chunks are generated for
+    assert.lessThanOrEqual(p_band_count, 10, 'p_band_count');
+    assert.lessThanOrEqual(q_band_count, 10, 'q_band_count');
+
+    const kappa = 1 / alpha;
+
+    sh_basis_at(scratch_basis, 0, p_band_count, frame[0], frame[1], frame[2]);
+
+    for (let l = 0; l < p_band_count; l++) {
+        const w = sh_vmf_window(l, kappa);
+
+        for (let i = l * l; i < (l + 1) * (l + 1); i++) {
+            output[output_offset + i] = w * scratch_basis[i];
+        }
+    }
+
+    const q_offset = output_offset + p_band_count * p_band_count - 1;
+
+    sh_basis_at(scratch_basis, 0, q_band_count, frame[3], frame[4], frame[5]);
+
+    for (let l = 1; l < q_band_count; l++) {
+        const w = sh_vmf_window(l, kappa);
+
+        for (let i = l * l; i < (l + 1) * (l + 1); i++) {
+            output[q_offset + i] = w * scratch_basis[i];
+        }
+    }
+}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_fit_samples.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The fixed set of shading configurations `(normal, view, alpha)` the SH-exponential fit is solved
+ * over. Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) sample view and normal
+ * directions uniformly and roughness uniformly over a range relaxed below the one used (Section 5.1:
+ * 64 x 64 directions, 4 roughness values in [0.20, 1.0]); this draws the same distribution from a
+ * five-dimensional Halton sequence, so that the system matrix is a constant of the configuration
+ * (see {@link sh_exp_solve_matrix}), built once rather than per environment.
+ *
+ * - `normal`: uniform over the sphere;
+ * - `view`: uniform over the hemisphere about the normal; floored at {@link MINIMUM_COS_VIEW};
+ * - `alpha`: GGX alpha (roughness squared), uniform over `[alpha_min, alpha_max]`.
+ *
+ * Until 2026-10-03 views were cosine-weighted about the normal (the screen footprint of a sphere) and
+ * alpha spanned [0.25, 1]. Measured with this module's fit on the Venice-sunset map (held-out views
+ * cosine-weighted, alpha in [0.25, 1], tonemapped error by roughness third), the paper's distribution
+ * is better at the low end, where reflections are sharpest, and worse at the rough end: 0.048 / 0.038 /
+ * 0.091 against 0.063 / 0.035 / 0.073; Rustig-Koppie the same way, smaller. Changed to the paper's on
+ * that trade.
+ *
+ * Written as `(normal.xyz, alpha, view.xyz, 0)` per sample ({@link SH_EXP_FIT_SAMPLE_FLOATS}).
+ *
+ * @param {Float32Array} output length at least `sample_count * SH_EXP_FIT_SAMPLE_FLOATS`
+ * @param {number} sample_count
+ * @param {number} alpha_min
+ * @param {number} alpha_max
+ */
+export function sh_exp_fit_samples(output: Float32Array, sample_count: number, alpha_min: number, alpha_max: number): void;
+//# sourceMappingURL=sh_exp_fit_samples.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_fit_samples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_exp_fit_samples.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/sh_exp_fit_samples.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CALW,YAAY,gBACZ,MAAM,aACN,MAAM,aACN,MAAM,QAuDhB"}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_fit_samples.js

@@ -0,0 +1,92 @@
+import { assert } from "../../../../../core/assert.js";
+import { halton_sequence } from "../../../../../core/math/statistics/halton_sequence.js";
+import { SH_EXP_FIT_SAMPLE_FLOATS } from "./sh_exp_layout.js";
+
+/**
+ * Smallest `dot(normal, view)` a sample is given. At exactly grazing the reflection lies in the
+ * tangent plane and the reference integral has nothing to say that a sample a hair above does not.
+ *
+ * @type {number}
+ */
+const MINIMUM_COS_VIEW = 0.01;
+
+/**
+ * The fixed set of shading configurations `(normal, view, alpha)` the SH-exponential fit is solved
+ * over. Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) sample view and normal
+ * directions uniformly and roughness uniformly over a range relaxed below the one used (Section 5.1:
+ * 64 x 64 directions, 4 roughness values in [0.20, 1.0]); this draws the same distribution from a
+ * five-dimensional Halton sequence, so that the system matrix is a constant of the configuration
+ * (see {@link sh_exp_solve_matrix}), built once rather than per environment.
+ *
+ * - `normal`: uniform over the sphere;
+ * - `view`: uniform over the hemisphere about the normal; floored at {@link MINIMUM_COS_VIEW};
+ * - `alpha`: GGX alpha (roughness squared), uniform over `[alpha_min, alpha_max]`.
+ *
+ * Until 2026-10-03 views were cosine-weighted about the normal (the screen footprint of a sphere) and
+ * alpha spanned [0.25, 1]. Measured with this module's fit on the Venice-sunset map (held-out views
+ * cosine-weighted, alpha in [0.25, 1], tonemapped error by roughness third), the paper's distribution
+ * is better at the low end, where reflections are sharpest, and worse at the rough end: 0.048 / 0.038 /
+ * 0.091 against 0.063 / 0.035 / 0.073; Rustig-Koppie the same way, smaller. Changed to the paper's on
+ * that trade.
+ *
+ * Written as `(normal.xyz, alpha, view.xyz, 0)` per sample ({@link SH_EXP_FIT_SAMPLE_FLOATS}).
+ *
+ * @param {Float32Array} output length at least `sample_count * SH_EXP_FIT_SAMPLE_FLOATS`
+ * @param {number} sample_count
+ * @param {number} alpha_min
+ * @param {number} alpha_max
+ */
+export function sh_exp_fit_samples(output, sample_count, alpha_min, alpha_max) {
+    assert.isNonNegativeInteger(sample_count, 'sample_count');
+    assert.greaterThanOrEqual(output.length, sample_count * SH_EXP_FIT_SAMPLE_FLOATS, 'output.length');
+    assert.greaterThan(alpha_min, 0, 'alpha_min');
+    assert.greaterThanOrEqual(alpha_max, alpha_min, 'alpha_max');
+
+    for (let i = 0; i < sample_count; i++) {
+        // index 0 is the origin in every base; start at 1
+        const u_normal_z = halton_sequence(2, i + 1);
+        const u_normal_phi = halton_sequence(3, i + 1);
+        const u_view_cos = halton_sequence(5, i + 1);
+        const u_view_phi = halton_sequence(7, i + 1);
+        const u_alpha = halton_sequence(11, i + 1);
+
+        const nz = 1 - 2 * u_normal_z;
+        const n_sin = Math.sqrt(Math.max(0, 1 - nz * nz));
+        const n_phi = 2 * Math.PI * u_normal_phi;
+
+        const nx = n_sin * Math.cos(n_phi);
+        const ny = n_sin * Math.sin(n_phi);
+
+        // Duff et al., "Building an Orthonormal Basis, Revisited", JCGT 6(1), 2017
+        const sign = nz >= 0 ? 1 : -1;
+        const a = -1 / (sign + nz);
+        const b = nx * ny * a;
+
+        const tx = 1 + sign * nx * nx * a;
+        const ty = sign * b;
+        const tz = -sign * nx;
+
+        const bx = b;
+        const by = sign + ny * ny * a;
+        const bz = -ny;
+
+        // uniform over the hemisphere: cos_theta is uniform
+        const v_cos = Math.max(MINIMUM_COS_VIEW, u_view_cos);
+        const v_sin = Math.sqrt(1 - v_cos * v_cos);
+        const v_phi = 2 * Math.PI * u_view_phi;
+
+        const vt = v_sin * Math.cos(v_phi);
+        const vb = v_sin * Math.sin(v_phi);
+
+        const o = i * SH_EXP_FIT_SAMPLE_FLOATS;
+
+        output[o] = nx;
+        output[o + 1] = ny;
+        output[o + 2] = nz;
+        output[o + 3] = alpha_min + (alpha_max - alpha_min) * u_alpha;
+        output[o + 4] = tx * vt + bx * vb + nx * v_cos;
+        output[o + 5] = ty * vt + by * vb + ny * v_cos;
+        output[o + 6] = tz * vt + bz * vb + nz * v_cos;
+        output[o + 7] = 0;
+    }
+}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_layout.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Unknowns of the fit, per colour channel: every P coefficient and every Q coefficient but Q's band
+ * 0. Band 0 of either term is the same constant function — `exp(a) * exp(b)` cannot tell `a` from `b`
+ * — so the least-squares system is singular unless one of them goes; P keeps it, as the paper does
+ * (Section 4.1.1 omits Q's DC term). Its five-and-three-band configuration (degrees 4 and 2) is
+ * 25 + 9 - 1 = 33, the "33 coefficients per color channel" of its Figure 1.
+ *
+ * Index `j < p_band_count²` is P's coefficient `j`; past that, `j - p_band_count² + 1` is Q's.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_coefficient_count(p_band_count: number, q_band_count: number): number;
+/**
+ * `vec4<f32>` elements of an encoded probe:
+ *
+ * - `[0]`: `(alpha_min, alpha_max, p_band_count, q_band_count)`, the roughness range the probe was
+ *   fitted over (reconstruction clamps to it) and its shape;
+ * - `[1, 1 + P)`: P's coefficients, RGB in `.xyz`, band-major (`sh_index`), `P = p_band_count²`;
+ * - `[1 + P, 1 + P + Q)`: Q's, the same way, `Q = q_band_count²`. Q's band 0 is stored, always zero,
+ *   so that both terms are a plain `array<vec3<f32>, N²>` for the generated `sh{N}_color_evaluate_vmf`.
+ *
+ * A `vec3` array in WGSL strides 16 bytes, so the layout is that of a struct of a `vec4` header and two
+ * `array<vec3<f32>, N²>` — what `SH_EXP_P4Q2_PROBE_STRUCT` declares for the default configuration.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_probe_vec4_count(p_band_count: number, q_band_count: number): number;
+/**
+ * Floats per fit sample in the buffer {@link sh_exp_fit_samples} fills and the encoder's kernels read
+ * as two `vec4<f32>`: `(normal.xyz, alpha)` then `(view.xyz, unused)`.
+ *
+ * @type {number}
+ */
+export const SH_EXP_FIT_SAMPLE_FLOATS: number;
+//# sourceMappingURL=sh_exp_layout.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_exp_layout.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/sh_exp_layout.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,uDAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,sDAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAIlB;AA3CD;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B"}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_layout.js

@@ -0,0 +1,44 @@
+/**
+ * Floats per fit sample in the buffer {@link sh_exp_fit_samples} fills and the encoder's kernels read
+ * as two `vec4<f32>`: `(normal.xyz, alpha)` then `(view.xyz, unused)`.
+ *
+ * @type {number}
+ */
+export const SH_EXP_FIT_SAMPLE_FLOATS = 8;
+
+/**
+ * Unknowns of the fit, per colour channel: every P coefficient and every Q coefficient but Q's band
+ * 0. Band 0 of either term is the same constant function — `exp(a) * exp(b)` cannot tell `a` from `b`
+ * — so the least-squares system is singular unless one of them goes; P keeps it, as the paper does
+ * (Section 4.1.1 omits Q's DC term). Its five-and-three-band configuration (degrees 4 and 2) is
+ * 25 + 9 - 1 = 33, the "33 coefficients per color channel" of its Figure 1.
+ *
+ * Index `j < p_band_count²` is P's coefficient `j`; past that, `j - p_band_count² + 1` is Q's.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_coefficient_count(p_band_count, q_band_count) {
+    return p_band_count * p_band_count + q_band_count * q_band_count - 1;
+}
+
+/**
+ * `vec4<f32>` elements of an encoded probe:
+ *
+ * - `[0]`: `(alpha_min, alpha_max, p_band_count, q_band_count)`, the roughness range the probe was
+ *   fitted over (reconstruction clamps to it) and its shape;
+ * - `[1, 1 + P)`: P's coefficients, RGB in `.xyz`, band-major (`sh_index`), `P = p_band_count²`;
+ * - `[1 + P, 1 + P + Q)`: Q's, the same way, `Q = q_band_count²`. Q's band 0 is stored, always zero,
+ *   so that both terms are a plain `array<vec3<f32>, N²>` for the generated `sh{N}_color_evaluate_vmf`.
+ *
+ * A `vec3` array in WGSL strides 16 bytes, so the layout is that of a struct of a `vec4` header and two
+ * `array<vec3<f32>, N²>` — what `SH_EXP_P4Q2_PROBE_STRUCT` declares for the default configuration.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_probe_vec4_count(p_band_count, q_band_count) {
+    return 1 + p_band_count * p_band_count + q_band_count * q_band_count;
+}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_solve_matrix.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The matrix that takes the fit's right-hand side to its coefficients: `(AᵀA / S + λD)⁻¹`, where row
+ * `i` of `A` is {@link sh_exp_design_row} at fit sample `i`, `S` is the sample count, and `D` is the
+ * identity but for a zero at the constant band.
+ *
+ * The least-squares system of Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) is
+ * linear in log space, and its matrix depends on the samples alone — never on the environment. With
+ * the samples fixed ({@link sh_exp_fit_samples}), this is a constant of the configuration: built once,
+ * in f64, and handed to the GPU, so that encoding an environment is a reduction and a matrix-vector
+ * product there rather than a factorization in f32. The encoder's right-hand side is
+ * `Aᵀ log E0 / S` to match.
+ *
+ * Inverted rather than factored: the GPU applies it with one dot product per coefficient. At the
+ * condition numbers {@link SH_EXP_RIDGE} leaves, applying it in f32 moves coefficients by ~5e-5
+ * (measured, five-and-three bands, coefficients up to 9).
+ *
+ * @param {Float32Array} output `coefficient_count²`, row-major (it is symmetric)
+ * @param {Float32Array} samples as written by {@link sh_exp_fit_samples} — the same values the GPU reads
+ * @param {number} sample_count
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ */
+export function sh_exp_solve_matrix(output: Float32Array, samples: Float32Array, sample_count: number, p_band_count: number, q_band_count: number): void;
+/**
+ * Ridge term, as a fraction of the normal matrix' mean diagonal.
+ *
+ * Wherever the view is near the normal, `h_r` is near `r`, so the P and Q columns of one `(l, m)` are
+ * nearly collinear. Over {@link sh_exp_fit_samples}' set the normal matrix' condition number is 1.1e3
+ * at the paper's five-and-three bands and 1.8e10 at ten-and-ten (2026-10-03; the matrix does not
+ * depend on the environment). Under the cosine-weighted views the set used before, an unregularized
+ * ten-and-ten fit of the Venice-sunset map ran coefficients to 2.4e4 (f64 prototype). With this ridge,
+ * this module's own fit of that map (quadrature `E0` over a 64 grid, 4096 and 8192 samples) keeps the
+ * largest coefficient at 4.7 for five-and-three and 13.7 for ten-and-ten, at a tonemapped
+ * reconstruction error by roughness third of 0.048 / 0.038 / 0.091 for both. On a target the model
+ * represents exactly, the ridge moves coefficients by up to 2.3e-3 (five-and-three) and 0.11
+ * (ten-and-ten) along those near-collinear directions, and the reconstruction at the fit samples by at
+ * most 4e-4 and 1.6e-3 in log space.
+ *
+ * @type {number}
+ */
+export const SH_EXP_RIDGE: number;
+//# sourceMappingURL=sh_exp_solve_matrix.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_solve_matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_exp_solve_matrix.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/sh_exp_solve_matrix.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CANW,YAAY,WACZ,YAAY,gBACZ,MAAM,gBACN,MAAM,gBACN,MAAM,QA6EhB;AApHD;;;;;;;;;;;;;;;;GAgBG;AACH,2BAFU,MAAM,CAEiB"}

package/src/shade/renderer/light/environment/sh_exponential/sh_exp_solve_matrix.js

@@ -0,0 +1,123 @@
+import { assert } from "../../../../../core/assert.js";
+import { lu_factor_linear_system } from "../../../../../core/math/linalg/lu_factor_linear_system.js";
+import { lu_solve_linear_system } from "../../../../../core/math/linalg/lu_solve_linear_system.js";
+import { sh_exp_design_row, sh_exp_reflection_frame } from "./sh_exp_design_row.js";
+import { SH_EXP_FIT_SAMPLE_FLOATS, sh_exp_coefficient_count } from "./sh_exp_layout.js";
+
+/**
+ * Ridge term, as a fraction of the normal matrix' mean diagonal.
+ *
+ * Wherever the view is near the normal, `h_r` is near `r`, so the P and Q columns of one `(l, m)` are
+ * nearly collinear. Over {@link sh_exp_fit_samples}' set the normal matrix' condition number is 1.1e3
+ * at the paper's five-and-three bands and 1.8e10 at ten-and-ten (2026-10-03; the matrix does not
+ * depend on the environment). Under the cosine-weighted views the set used before, an unregularized
+ * ten-and-ten fit of the Venice-sunset map ran coefficients to 2.4e4 (f64 prototype). With this ridge,
+ * this module's own fit of that map (quadrature `E0` over a 64 grid, 4096 and 8192 samples) keeps the
+ * largest coefficient at 4.7 for five-and-three and 13.7 for ten-and-ten, at a tonemapped
+ * reconstruction error by roughness third of 0.048 / 0.038 / 0.091 for both. On a target the model
+ * represents exactly, the ridge moves coefficients by up to 2.3e-3 (five-and-three) and 0.11
+ * (ten-and-ten) along those near-collinear directions, and the reconstruction at the fit samples by at
+ * most 4e-4 and 1.6e-3 in log space.
+ *
+ * @type {number}
+ */
+export const SH_EXP_RIDGE = 1e-4;
+
+/**
+ * The matrix that takes the fit's right-hand side to its coefficients: `(AᵀA / S + λD)⁻¹`, where row
+ * `i` of `A` is {@link sh_exp_design_row} at fit sample `i`, `S` is the sample count, and `D` is the
+ * identity but for a zero at the constant band.
+ *
+ * The least-squares system of Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) is
+ * linear in log space, and its matrix depends on the samples alone — never on the environment. With
+ * the samples fixed ({@link sh_exp_fit_samples}), this is a constant of the configuration: built once,
+ * in f64, and handed to the GPU, so that encoding an environment is a reduction and a matrix-vector
+ * product there rather than a factorization in f32. The encoder's right-hand side is
+ * `Aᵀ log E0 / S` to match.
+ *
+ * Inverted rather than factored: the GPU applies it with one dot product per coefficient. At the
+ * condition numbers {@link SH_EXP_RIDGE} leaves, applying it in f32 moves coefficients by ~5e-5
+ * (measured, five-and-three bands, coefficients up to 9).
+ *
+ * @param {Float32Array} output `coefficient_count²`, row-major (it is symmetric)
+ * @param {Float32Array} samples as written by {@link sh_exp_fit_samples} — the same values the GPU reads
+ * @param {number} sample_count
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ */
+export function sh_exp_solve_matrix(output, samples, sample_count, p_band_count, q_band_count) {
+    assert.isPositiveInteger(sample_count, 'sample_count');
+    assert.isPositiveInteger(p_band_count, 'p_band_count');
+    assert.isPositiveInteger(q_band_count, 'q_band_count');
+
+    const N = sh_exp_coefficient_count(p_band_count, q_band_count);
+
+    assert.greaterThanOrEqual(output.length, N * N, 'output.length');
+
+    const M = new Float64Array(N * N);
+    const row = new Float64Array(N);
+    const frame = new Float64Array(6);
+
+    for (let s = 0; s < sample_count; s++) {
+        const o = s * SH_EXP_FIT_SAMPLE_FLOATS;
+
+        sh_exp_reflection_frame(
+            frame,
+            samples[o], samples[o + 1], samples[o + 2],
+            samples[o + 4], samples[o + 5], samples[o + 6]
+        );
+
+        sh_exp_design_row(row, 0, p_band_count, q_band_count, frame, samples[o + 3]);
+
+        for (let i = 0; i < N; i++) {
+            const ri = row[i];
+
+            for (let j = i; j < N; j++) {
+                M[i * N + j] += ri * row[j];
+            }
+        }
+    }
+
+    let trace = 0;
+
+    for (let i = 0; i < N; i++) {
+        for (let j = i; j < N; j++) {
+            const value = M[i * N + j] / sample_count;
+
+            M[i * N + j] = value;
+            M[j * N + i] = value;
+        }
+
+        trace += M[i * N + i];
+    }
+
+    const ridge = SH_EXP_RIDGE * trace / N;
+
+    // Not on coefficient 0, P's constant band — ridge regression leaves the intercept alone. Then the
+    // inverse maps the constant column of the design straight back to itself, so an environment k
+    // times brighter (log E0 + log k everywhere) moves that one coefficient by log k / Y(0, 0) and no
+    // other.
+    for (let i = 1; i < N; i++) {
+        M[i * N + i] += ridge;
+    }
+
+    const pivots = new Uint32Array(N);
+
+    if (!lu_factor_linear_system(M, pivots, N)) {
+        throw new Error(`SH-exponential system matrix (${N}x${N}) did not factor`);
+    }
+
+    const column = new Float64Array(N);
+
+    for (let j = 0; j < N; j++) {
+        column.fill(0);
+        column[j] = 1;
+
+        lu_solve_linear_system(M, pivots, column, N);
+
+        // column j of the inverse; the inverse of a symmetric matrix is symmetric, so this is row j too
+        for (let i = 0; i < N; i++) {
+            output[j * N + i] = column[i];
+        }
+    }
+}

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_environment_cells.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Most source texels a cell reads along one side, so 64 x 64 = 4096 a cell and 16 a lane. Maps up to
+ * 64 times the grid (4096 at the default 64 grid) are read texel by texel; past that every stride-th
+ * texel is read, standing for its stride x stride block by the solid angle of its middle texel —
+ * an 8192 map at a 64 grid reads one texel in four. A smooth field keeps its cell means to 1e-3 that
+ * way (the spec reads a 2048 map at an 8 grid, stride 4); a feature smaller than the stride can be
+ * missed or counted for its whole block.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_TEXELS_PER_CELL_SIDE: number;
+/**
+ * First pass of the SH-exponential encoder: integrates the octahedral environment's level 0 down to a
+ * coarse octahedral grid of `cell_resolution²` cells, each a direction and its radiance times solid
+ * angle — the quadrature the reference reflectance is integrated over.
+ *
+ * Writes two `vec4` per cell into `cells`: `(direction, 0)`, then `(radiance * solid_angle, solid_angle)`.
+ * Radiance is the solid-angle-weighted mean of the source texels whose centres fall in the cell
+ * (`octahedral_solid_angle` per texel, so the octahedral map's area distortion is accounted for), or
+ * of the texel under the cell's centre where a map coarser than the grid leaves none; past
+ * {@link SH_EXP_MAX_TEXELS_PER_CELL_SIDE} texels a side it is read with a stride. The cell's solid
+ * angle is its own, so the grid sums to 4π whatever the source resolution.
+ *
+ * Dispatch `cell_resolution²` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_environment_cells: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_sh_exp_environment_cells.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_environment_cells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_sh_exp_environment_cells.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_environment_cells.js"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,8CAFU,MAAM,CAEkC;AA0GlD;;;;;;;;;;;;;;;GAeG;AACH,8CAFU,aAAa,CAMpB;8BA/I2B,kCAAkC"}