@woosh/meep-engine 3.38.0 → 3.39.0

package/src/shade/playground/path_traced_media/checks.js

@@ -0,0 +1,921 @@
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { make_box_geometry } from "../../renderer/geometry/primitives/make_box_geometry.js";
+import { make_octahedron_geometry } from "../../renderer/geometry/primitives/make_octahedron_geometry.js";
+import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { PointLight } from "../../renderer/light/model/PointLight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { ParticipatingMedium } from "../../renderer/medium/ParticipatingMedium.js";
+import { PhaseHenyeyGreenstein } from "../../renderer/medium/phase/PhaseHenyeyGreenstein.js";
+import { PhaseWaterMolecular } from "../../renderer/medium/phase/PhaseWaterMolecular.js";
+import {
+    ParticipatingMediaVolume,
+    VolumetricsParticleSpec
+} from "../../renderer/volumetrics/ParticipatingMediaVolume.js";
+
+/**
+ * Scenes with a closed-form answer, for the accumulating path tracer to converge to.
+ *
+ * Each check renders one or two variants of a scene and compares rectangles of the image — mean
+ * radiance per channel — with what the scene must produce: an absolute value, or for a `ratio`
+ * region the test variant over the control, which cancels everything the two share (the BRDF, the
+ * light's units, the view). Rectangles are in normalized image coordinates, `[x0, y0, x1, y1]` from
+ * the top left. Where the answer depends on the angle a pixel's ray makes with the camera's axis —
+ * the path length through a slab facing the camera — `expected` is a function of its cosine, and of
+ * the ray's direction in the camera's frame (x right, y up, looking down -z) where the answer is not
+ * symmetric about the axis, evaluated per pixel and averaged over the rectangle like the measurement
+ * is.
+ *
+ * @typedef {Object} MediaCheckRegion
+ * @property {string} name
+ * @property {number[]} rect
+ * @property {number[]|function(number, number[]): number[]} expected RGB, or RGB of the cosine
+ * between a pixel's ray and the camera's axis and of that ray's unit direction
+ * @property {boolean} [ratio]
+ * @property {number} [allowance] relative error tolerated on top of the standard errors, where a
+ * measured residual is known and stated; 0.2% otherwise
+ *
+ * @typedef {Object} MediaCheck
+ * @property {string} name
+ * @property {string} about
+ * @property {number[]} environment flat RGB radiance of the sky
+ * @property {{position: number[], target: number[], fov_degrees: number}} camera
+ * @property {function(MediaScene): void} test
+ * @property {function(MediaScene): void} [control]
+ * @property {MediaCheckRegion[]} regions
+ *
+ * @typedef {Object} MediaScene
+ * @property {import("../../renderer/scene/Scene.js").Scene} scene
+ * @property {function(MeshletGeometry, StandardShadeMaterial, Vector3, Quaternion=): void} place
+ * @property {function(BufferedGeometry): MeshletGeometry} meshlets
+ */
+
+/** absorption of the coloured media below, 1/m: red passes, blue does not */
+const SIGMA = [0.2, 0.5, 1.0];
+
+/**
+ * Unpolarized reflectance of a smooth dielectric interface, light arriving at `cos_i` on the side of
+ * index 1 into index `eta`.
+ *
+ * @param {number} cos_i
+ * @param {number} eta
+ * @returns {number}
+ */
+function fresnel_dielectric(cos_i, eta) {
+    const sin2_t = (1 - cos_i * cos_i) / (eta * eta);
+
+    if (sin2_t >= 1) {
+        return 1;
+    }
+
+    const cos_t = Math.sqrt(1 - sin2_t);
+
+    const parallel = (eta * cos_i - cos_t) / (eta * cos_i + cos_t);
+    const perpendicular = (cos_i - eta * cos_t) / (cos_i + eta * cos_t);
+
+    return 0.5 * (parallel * parallel + perpendicular * perpendicular);
+}
+
+/**
+ * @param {object} options
+ * @param {number[]} [options.albedo]
+ * @param {number[]} [options.emissive]
+ * @param {number} [options.roughness]
+ * @param {number} [options.transmission]
+ * @param {number} [options.ior]
+ * @param {ParticipatingMedium|null} [options.medium]
+ * @returns {StandardShadeMaterial}
+ */
+export function surface({
+                     albedo = [0, 0, 0],
+                     emissive = [0, 0, 0],
+                     roughness = 0.5,
+                     transmission = 0,
+                     ior = 1.5,
+                     medium = null,
+                 }) {
+    const material = new StandardShadeMaterial();
+
+    material.diffuse_color.copy(new Color(albedo[0], albedo[1], albedo[2], 1));
+    material.emissive_factor.copy(new Color(emissive[0], emissive[1], emissive[2]));
+    material.roughness_factor = roughness;
+    material.metallic_factor = 0;
+    material.transmission_factor = transmission;
+    material.ior_factor = ior;
+    material.medium = medium;
+    material.draw_side = ShadeDrawSide.Double;
+
+    return material;
+}
+
+/**
+ * @param {number[]} absorption
+ * @returns {ParticipatingMedium}
+ */
+export function absorbing_medium(absorption) {
+    const medium = new ParticipatingMedium();
+
+    medium.absorption = absorption.slice();
+
+    return medium;
+}
+
+/** an emitter facing +z, black otherwise, filling the view behind whatever is tested */
+function place_backdrop({ place, meshlets }, z, radiance = [1, 1, 1]) {
+    place(
+        meshlets(make_plane_geometry(60, 60, 1, 1)),
+        surface({ emissive: radiance, roughness: 1 }),
+        new Vector3(0, 0, z)
+    );
+}
+
+/** a grey floor at y = 0 under a sun straight overhead */
+function place_floor_in_sun({ scene, place, meshlets }) {
+    place(
+        meshlets(make_plane_geometry(40, 40, 1, 1)),
+        surface({ albedo: [0.5, 0.5, 0.5], roughness: 0.5 }),
+        new Vector3(0, 0, 0),
+        Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2)
+    );
+
+    place_light(scene, make_sunlight({
+        intensity: 3,
+        direction: new Vector3(0, -1, 0),
+        temperature: 6500,
+    }));
+}
+
+/**
+ * A fog volume of uniform density: `extinction` and `scattering` are its coefficients, 1/m.
+ */
+export function place_fog({ scene }, { position, scale, extinction, scattering, g }) {
+    const volume = new ParticipatingMediaVolume();
+
+    volume.transform.setTranslation(position[0], position[1], position[2]);
+    volume.transform.setScale(scale[0], scale[1], scale[2]);
+    volume.transform.updateMatrix();
+
+    volume.fade_distance = 0;
+    volume.particle_spec = VolumetricsParticleSpec.fromJSON({ extinction, scattering, radius: 1e-6, g });
+    volume.density = 1;
+
+    scene.volumetrics.add(volume);
+}
+
+/**
+ * Through a slab of thickness 1 of index `eta` and absorption `sigma`, seen at `cos_i` to its
+ * normal: an interface reflecting F on each side, transmittance T along the refracted ray inside,
+ * every internal round trip summed — (1 - F)² T / (1 - F² T²).
+ *
+ * @param {number} cos_i
+ * @param {number} eta
+ * @param {number} sigma
+ * @returns {number}
+ */
+function slab_transmittance(cos_i, eta, sigma) {
+    const F = fresnel_dielectric(cos_i, eta);
+
+    const sin2_t = (1 - cos_i * cos_i) / (eta * eta);
+    const T = Math.exp(-sigma / Math.sqrt(1 - sin2_t));
+
+    return (1 - F) * (1 - F) * T / (1 - F * F * T * T);
+}
+
+/** a slab 4 x 4 x 1 at the origin, between the camera at +z and the backdrop at -3 */
+const SLAB_CAMERA = { position: [0, 0, 6], target: [0, 0, 0], fov_degrees: 20 };
+
+/** the middle of the frame, where every view ray is within a few degrees of the slab's normal */
+const CENTRE = [0.35, 0.35, 0.65, 0.65];
+
+/** water's index of refraction, and its absorption in 1/m: red goes first */
+const N_WATER = 1.333;
+const WATER_ABSORPTION = [0.1, 0.05, 0.02];
+
+/** how deep the tile lies under the water's flat surface, m */
+const TILE_DEPTH = 1;
+
+/**
+ * A camera above the water, a little off vertical — straight down leaves the view's up undefined — and
+ * how steeply its central ray runs: 4.29 degrees from the vertical in air.
+ */
+const WATER_CAMERA = { position: [0, 4, 0.3], target: [0, 0, 0], fov_degrees: 8 };
+const WATER_VIEW_COS = 4 / Math.hypot(4, 0.3);
+
+/**
+ * What the camera's side of the round trip leaves of the tile's radiance: the surface's transmission
+ * at the view's angle, radiance's 1 / n² going from water into air, and the water along the refracted
+ * view ray down to the tile.
+ *
+ * @returns {number[]}
+ */
+function water_view_factor() {
+    const sin_w = Math.sqrt(1 - WATER_VIEW_COS * WATER_VIEW_COS) / N_WATER;
+    const cos_w = Math.sqrt(1 - sin_w * sin_w);
+
+    return WATER_ABSORPTION.map(a => (1 - fresnel_dielectric(WATER_VIEW_COS, N_WATER)) / (N_WATER * N_WATER) * Math.exp(-a * TILE_DEPTH / cos_w));
+}
+
+/**
+ * A grey tile at the bottom of the check, Lambertian — smooth, where the rough diffuse lobe has no
+ * dependence on angle — and its specular off: its index `ior` is that of what surrounds it, 1 dry
+ * and N_WATER under water, and a surface reflects by the ratio. What it shows is the irradiance on it
+ * times one constant, whichever way the light arrives.
+ */
+function place_tile({ place, meshlets }, ior = 1) {
+    place(
+        meshlets(make_plane_geometry(0.4, 0.4, 1, 1)),
+        surface({ albedo: [0.5, 0.5, 0.5], roughness: 0, ior }),
+        new Vector3(0, 0, 0),
+        Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2)
+    );
+}
+
+/** the water of the checks below: absorbing, its index N_WATER */
+function water() {
+    return surface({ transmission: 1, ior: N_WATER, medium: absorbing_medium(WATER_ABSORPTION) });
+}
+
+/** water from TILE_DEPTH above the tile to well below it, flat on top, wide enough for any of the lights */
+function place_water({ place, meshlets }, material = water()) {
+    place(
+        meshlets(make_box_geometry(40, 4, 40)),
+        material,
+        new Vector3(0, TILE_DEPTH - 2, 0)
+    );
+}
+
+/**
+ * The sun at `zenith` degrees from overhead, low toward -x: its light travels toward +x.
+ */
+function place_sun_at({ scene }, zenith) {
+    const theta = zenith * Math.PI / 180;
+
+    place_light(scene, make_sunlight({
+        intensity: 3,
+        direction: new Vector3(Math.sin(theta), -Math.cos(theta), 0),
+        temperature: 6500,
+    }));
+}
+
+/** a water check under the sun at `zenith` degrees */
+function sun_through_water_check(zenith) {
+    const theta = zenith * Math.PI / 180;
+    const sin_w = Math.sin(theta) / N_WATER;
+    const cos_w = Math.sqrt(1 - sin_w * sin_w);
+
+    const sun_factor = WATER_ABSORPTION.map(a => (1 - fresnel_dielectric(Math.cos(theta), N_WATER)) * Math.exp(-a * TILE_DEPTH / cos_w));
+    const view_factor = water_view_factor();
+
+    return {
+        name: `sun through flat water, ${zenith} degrees`,
+        about: `a tile ${TILE_DEPTH} m under flat water (n = ${N_WATER}), the sun ${zenith} degrees from overhead, seen from above, against the same tile dry: the sun reaches it only through the surface, by manifold next-event estimation — Fresnel, the beam's widening by cos(water) / cos(air), the water along the refracted ray — and the camera sees it through the surface: t(view) / n² and the water down to the tile`,
+        environment: [0, 0, 0],
+        camera: WATER_CAMERA,
+        control(s) {
+            place_tile(s);
+            place_sun_at(s, zenith);
+        },
+        test(s) {
+            place_tile(s, N_WATER);
+            place_sun_at(s, zenith);
+            place_water(s);
+        },
+        regions: [
+            {
+                name: 'the tile',
+                rect: [0.4, 0.4, 0.6, 0.6],
+                expected: sun_factor.map((f, c) => f * view_factor[c]),
+                ratio: true,
+            },
+        ],
+    };
+}
+
+/** how high over the water the lamp hangs, m */
+const LAMP_HEIGHT = 2;
+
+/** a bare point lamp — no range window, no radius — LAMP_HEIGHT over the water, straight over the tile */
+function place_lamp({ scene }) {
+    const lamp = new PointLight();
+
+    lamp.distance = 0;
+    lamp.radius = 0;
+    lamp.intensity = 10;
+    lamp.transform.setTranslation(0, TILE_DEPTH + LAMP_HEIGHT, 0);
+    lamp.transform.updateMatrix();
+
+    place_light(scene, lamp);
+}
+
+/**
+ * What a scattering glass sphere holds past `PATH_INTERFACE_EVENT_LIMIT`, relative: light that
+ * scatters inside and is turned back by total internal reflection at every wall it reaches. Measured,
+ * with the noise taken from the two halves of the run, 0.5% low in the middle and 0.25–0.73% at the
+ * outline at a limit of 16 events, the left and right rims the most; none at 64. The scattering limit
+ * is not it (the same to five digits at 32 and 64 events).
+ * @type {number}
+ */
+const TRAPPED_SCATTERING_ALLOWANCE = 0.006;
+
+/**
+ * The outline of the unit sphere at the origin seen from (0, 0, 6) through 30°, on all four sides. It
+ * sits 0.315 of the image from the centre; each rectangle straddles it, so it holds the most grazing
+ * incidence there is — where an interface goes wrong first — and some sky, which in a furnace reads
+ * the same. The tessellated clear sphere holds 0.1% there, on every side, by total internal
+ * reflection a smooth one would not have: inside the default allowance.
+ */
+const SPHERE_RIMS = [
+    { name: 'the sphere, its left rim', rect: [0.17, 0.42, 0.23, 0.58] },
+    { name: 'the sphere, its right rim', rect: [0.77, 0.42, 0.83, 0.58] },
+    { name: 'the sphere, its top rim', rect: [0.42, 0.17, 0.58, 0.23] },
+    { name: 'the sphere, its bottom rim', rect: [0.42, 0.77, 0.58, 0.83] },
+];
+
+/** how far the slope check's tile leans toward the sun's travel, degrees */
+const SLOPE_DEGREES = 35;
+
+/**
+ * Chandrasekhar's H-function for isotropic scattering of single-scattering albedo `albedo`, at `mu`:
+ * H(mu) = 1 / (1 - (albedo / 2) mu ∫ H(mu') / (mu + mu') dmu' over [0, 1]), iterated to convergence
+ * on 64 Gauss-Legendre nodes.
+ *
+ * @param {number} albedo
+ * @returns {function(number): number}
+ */
+function chandrasekhar_h(albedo) {
+    // Gauss-Legendre on [-1, 1] by Newton on P_n, then mapped to [0, 1]
+    const n = 64;
+    const nodes = [];
+    const weights = [];
+
+    for (let i = 0; i < n; i++) {
+        let x = Math.cos(Math.PI * (i + 0.75) / (n + 0.5));
+        let dp = 0;
+
+        for (let k = 0; k < 100; k++) {
+            let p0 = 1, p1 = x;
+
+            for (let j = 2; j <= n; j++) {
+                const p2 = ((2 * j - 1) * x * p1 - (j - 1) * p0) / j;
+                p0 = p1;
+                p1 = p2;
+            }
+
+            dp = n * (x * p1 - p0) / (x * x - 1);
+            const dx = p1 / dp;
+            x -= dx;
+
+            if (Math.abs(dx) < 1e-15) {
+                break;
+            }
+        }
+
+        nodes.push(0.5 * (x + 1));
+        weights.push(1 / ((1 - x * x) * dp * dp));
+    }
+
+    let h = nodes.map(() => 1);
+
+    const at = (mu, table) => {
+        let integral = 0;
+
+        for (let j = 0; j < n; j++) {
+            integral += weights[j] * table[j] / (mu + nodes[j]);
+        }
+
+        return 1 / (1 - 0.5 * albedo * mu * integral);
+    };
+
+    for (let iteration = 0; iteration < 1000; iteration++) {
+        const next = nodes.map(mu => at(mu, h));
+        const change = Math.max(...next.map((v, j) => Math.abs(v - h[j])));
+
+        h = next;
+
+        if (change < 1e-13) {
+            break;
+        }
+    }
+
+    return mu => at(mu, h);
+}
+
+/** the scattering half-space's single-scattering albedo per channel; its extinction is 1/m */
+const HALF_SPACE_ALBEDO = [0.3, 0.5, 0.7];
+
+/**
+ * @type {MediaCheck[]}
+ */
+export const MEDIA_CHECKS = [
+    {
+        name: 'slab, index-matched, absorbing',
+        about: 'Beer-Lambert through 1 m of a coloured medium entered through an n = 1 surface: no reflection, no bending, exp(-sigma d) per channel',
+        environment: [0, 0, 0],
+        camera: SLAB_CAMERA,
+        test(s) {
+            place_backdrop(s, -3);
+
+            s.place(
+                s.meshlets(make_box_geometry(4, 4, 1)),
+                surface({ transmission: 1, ior: 1, medium: absorbing_medium(SIGMA) }),
+                new Vector3(0, 0, 0)
+            );
+        },
+        regions: [
+            { name: 'through the slab', rect: CENTRE, expected: cos => SIGMA.map(s => slab_transmittance(cos, 1, s)) },
+        ],
+    },
+    {
+        name: 'slab, glass n = 1.5, absorbing',
+        about: 'the same medium behind exact Fresnel at n = 1.5, every internal reflection summed; the radiance carried inside is scaled by 1/n² going in and n² coming out',
+        environment: [0, 0, 0],
+        camera: SLAB_CAMERA,
+        test(s) {
+            place_backdrop(s, -3);
+
+            s.place(
+                s.meshlets(make_box_geometry(4, 4, 1)),
+                surface({ transmission: 1, ior: 1.5, medium: absorbing_medium(SIGMA) }),
+                new Vector3(0, 0, 0)
+            );
+        },
+        regions: [
+            {
+                name: 'through the slab',
+                rect: CENTRE,
+                expected: cos => SIGMA.map(s => slab_transmittance(cos, 1.5, s)),
+            },
+        ],
+    },
+    {
+        name: 'underwater camera',
+        about: 'a camera inside a closed box of absorbing water (n = 1.333) sees an emitter 8 m away through 8 m of it: the path starts inside the medium, which only the probe from its origin can tell it',
+        environment: [0, 0, 0],
+        camera: { position: [0, 0, 5], target: [0, 0, 0], fov_degrees: 20 },
+        test(s) {
+            place_backdrop(s, -3);
+
+            s.place(
+                s.meshlets(make_box_geometry(20, 20, 20)),
+                surface({ transmission: 1, ior: 1.333, medium: absorbing_medium([0.02, 0.05, 0.1]) }),
+                new Vector3(0, 0, 0)
+            );
+        },
+        regions: [
+            { name: 'the emitter', rect: CENTRE, expected: cos => [0.02, 0.05, 0.1].map(s => Math.exp(-8 * s / cos)) },
+        ],
+    },
+    {
+        name: 'underwater camera inside two overlapping meshes of the same water',
+        about: 'the underwater camera, also inside a second, smaller box of the same water overlapping the first: leaving the small box it is still in the large one, which the path knows only if its starting stack counts the two meshes apart',
+        environment: [0, 0, 0],
+        camera: { position: [0, 0, 5], target: [0, 0, 0], fov_degrees: 20 },
+        test(s) {
+            const material = surface({ transmission: 1, ior: 1.333, medium: absorbing_medium([0.02, 0.05, 0.1]) });
+
+            place_backdrop(s, -3);
+
+            s.place(s.meshlets(make_box_geometry(20, 20, 20)), material, new Vector3(0, 0, 0));
+            s.place(s.meshlets(make_box_geometry(6, 6, 6)), material, new Vector3(0, 0, 4));
+        },
+        regions: [
+            { name: 'the emitter', rect: CENTRE, expected: cos => [0.02, 0.05, 0.1].map(s => Math.exp(-8 * s / cos)) },
+        ],
+    },
+    {
+        name: 'slab, glass n = 1.5, absorbing, at 45 degrees',
+        about: 'the glass slab turned 45 degrees about the vertical: Fresnel at 45 degrees, the path inside lengthened by the refracted angle, every internal reflection summed',
+        environment: [0, 0, 0],
+        camera: SLAB_CAMERA,
+        test(s) {
+            place_backdrop(s, -3);
+
+            s.place(
+                s.meshlets(make_box_geometry(4, 4, 1)),
+                surface({ transmission: 1, ior: 1.5, medium: absorbing_medium(SIGMA) }),
+                new Vector3(0, 0, 0),
+                Quaternion.fromAxisAngle(Vector3.up, Math.PI / 4)
+            );
+        },
+        regions: [
+            {
+                name: 'through the slab',
+                rect: CENTRE,
+                // the slab's normal is (sin 45, 0, cos 45); the camera's frame is the world's
+                expected: (cos, direction) => {
+                    const cos_i = Math.abs(direction[0] + direction[2]) * Math.SQRT1_2;
+
+                    return SIGMA.map(s => slab_transmittance(cos_i, 1.5, s));
+                },
+            },
+        ],
+    },
+    {
+        name: 'smooth black tile in air',
+        about: 'a black dielectric tile (n = 1.5) reflecting an emitter behind the camera: a smooth surface reflects the Fresnel fraction of what it faces, 4% head-on — the specular bounce alone, its weight F G2 / G1 one for a smooth lobe',
+        environment: [0, 0, 0],
+        camera: { position: [0, 0, 5], target: [0, 0, 0], fov_degrees: 8 },
+        test(s) {
+            s.place(s.meshlets(make_plane_geometry(2, 2, 1, 1)), surface({ albedo: [0, 0, 0], roughness: 0, ior: 1.5 }), new Vector3(0, 0, 0));
+            s.place(s.meshlets(make_plane_geometry(20, 20, 1, 1)), surface({ emissive: [1, 1, 1], roughness: 1 }), new Vector3(0, 0, 9));
+        },
+        regions: [
+            { name: 'the tile', rect: [0.4, 0.4, 0.6, 0.6], expected: cos => [0, 1, 2].map(() => fresnel_dielectric(cos, 1.5)) },
+        ],
+    },
+    {
+        name: 'smooth black tile under water',
+        about: 'a black dielectric tile (n = 1.5) inside water reflecting an emitter behind the camera: it reflects by the ratio of its index to the water\'s, 1.125 — 0.35% head-on, not the 4% of glass in air',
+        environment: [0, 0, 0],
+        camera: { position: [0, 0, 5], target: [0, 0, 0], fov_degrees: 8 },
+        test(s) {
+            s.place(
+                s.meshlets(make_box_geometry(30, 30, 30)),
+                surface({ transmission: 1, ior: N_WATER, medium: new ParticipatingMedium() }),
+                new Vector3(0, 0, 0)
+            );
+
+            s.place(s.meshlets(make_plane_geometry(2, 2, 1, 1)), surface({ albedo: [0, 0, 0], roughness: 0, ior: 1.5 }), new Vector3(0, 0, 0));
+            s.place(s.meshlets(make_plane_geometry(20, 20, 1, 1)), surface({ emissive: [1, 1, 1], roughness: 1 }), new Vector3(0, 0, 9));
+        },
+        regions: [
+            { name: 'the tile', rect: [0.4, 0.4, 0.6, 0.6], expected: cos => [0, 1, 2].map(() => fresnel_dielectric(cos, 1.5 / N_WATER)) },
+        ],
+    },
+    {
+        name: 'sunlit scattering half-space',
+        about: `a deep, index-matched box of an isotropically scattering medium (extinction 1/m, albedo ${HALF_SPACE_ALBEDO.join(', ')}) under the sun 30 degrees from overhead, against a dry tile: every order of scattering summed, by Chandrasekhar's H-function — omega H(mu_sun) H(mu_view) / (4 rho (mu_sun + mu_view)) — so the sun must reach every scattering point`,
+        environment: [0, 0, 0],
+        camera: WATER_CAMERA,
+        control(s) {
+            place_tile(s);
+            place_sun_at(s, 30);
+        },
+        test(s) {
+            const medium = new ParticipatingMedium();
+
+            medium.absorption = HALF_SPACE_ALBEDO.map(a => 1 - a);
+            medium.add_lobe(HALF_SPACE_ALBEDO.slice(), new PhaseHenyeyGreenstein({ g: 0 }));
+
+            s.place(s.meshlets(make_box_geometry(40, 20, 40)), surface({ transmission: 1, ior: 1, medium }), new Vector3(0, -10, 0));
+            place_sun_at(s, 30);
+        },
+        regions: [
+            {
+                name: 'the medium',
+                rect: [0.4, 0.4, 0.6, 0.6],
+                expected: (() => {
+                    const mu_sun = Math.cos(Math.PI / 6);
+                    const mu_view = WATER_VIEW_COS;
+
+                    // the tile's albedo, 0.5
+                    return HALF_SPACE_ALBEDO.map(a => {
+                        const h = chandrasekhar_h(a);
+                        return a * h(mu_sun) * h(mu_view) / (4 * 0.5 * (mu_sun + mu_view));
+                    });
+                })(),
+                ratio: true,
+            },
+        ],
+    },
+    {
+        name: 'white furnace, clear glass sphere',
+        about: 'a sphere of n = 1.5 enclosing a medium that neither scatters nor absorbs, under a uniform sky: exact Fresnel and the n² law conserve energy, and a sphere traps no light, so it vanishes',
+        environment: [0.5, 0.5, 0.5],
+        camera: { position: [0, 0, 6], target: [0, 0, 0], fov_degrees: 30 },
+        test(s) {
+            s.place(
+                s.meshlets(make_octahedron_geometry(1, 24)),
+                surface({ transmission: 1, ior: 1.5, medium: new ParticipatingMedium() }),
+                new Vector3(0, 0, 0)
+            );
+        },
+        regions: [
+            { name: 'the sphere', rect: [0.4, 0.4, 0.6, 0.6], expected: [0.5, 0.5, 0.5] },
+            ...SPHERE_RIMS.map(rim => ({ ...rim, expected: [0.5, 0.5, 0.5] })),
+        ],
+    },
+    {
+        name: 'white furnace, scattering index-matched sphere',
+        about: 'the scattering medium below behind an n = 1 surface, so nothing reflects or is trapped: the medium alone, bounded by a mesh',
+        environment: [0.5, 0.5, 0.5],
+        camera: { position: [0, 0, 6], target: [0, 0, 0], fov_degrees: 30 },
+        test(s) {
+            const medium = new ParticipatingMedium();
+
+            medium.add_lobe([1.2, 0.8, 0.4], new PhaseHenyeyGreenstein({ g: 0.7 }));
+            medium.add_lobe([0.2, 0.4, 0.8], new PhaseWaterMolecular({ depolarization: 0.039 }));
+
+            s.place(
+                s.meshlets(make_octahedron_geometry(1, 24)),
+                surface({ transmission: 1, ior: 1, medium }),
+                new Vector3(0, 0, 0)
+            );
+        },
+        regions: [
+            { name: 'the sphere', rect: [0.4, 0.4, 0.6, 0.6], expected: [0.5, 0.5, 0.5] },
+            ...SPHERE_RIMS.map(rim => ({ ...rim, expected: [0.5, 0.5, 0.5] })),
+        ],
+    },
+    {
+        name: 'white furnace, scattering glass sphere',
+        about: 'a sphere of n = 1.333 filled with a medium that scatters and does not absorb — chromatic, through two phase lobes — under a uniform sky: nothing is lost, so the sphere vanishes',
+        environment: [0.5, 0.5, 0.5],
+        camera: { position: [0, 0, 6], target: [0, 0, 0], fov_degrees: 30 },
+        test(s) {
+            const medium = new ParticipatingMedium();
+
+            medium.add_lobe([1.2, 0.8, 0.4], new PhaseHenyeyGreenstein({ g: 0.7 }));
+            medium.add_lobe([0.2, 0.4, 0.8], new PhaseWaterMolecular({ depolarization: 0.039 }));
+
+            s.place(
+                s.meshlets(make_octahedron_geometry(1, 24)),
+                surface({ transmission: 1, ior: 1.333, medium }),
+                new Vector3(0, 0, 0)
+            );
+        },
+        regions: [
+            { name: 'the sphere', rect: [0.4, 0.4, 0.6, 0.6], expected: [0.5, 0.5, 0.5], allowance: TRAPPED_SCATTERING_ALLOWANCE },
+            ...SPHERE_RIMS.map(rim => ({ ...rim, expected: [0.5, 0.5, 0.5], allowance: TRAPPED_SCATTERING_ALLOWANCE })),
+            { name: 'the sky', rect: [0, 0, 0.1, 0.1], expected: [0.5, 0.5, 0.5] },
+        ],
+    },
+    {
+        name: 'white furnace, fog volume',
+        about: 'a scene participating-media volume that scatters and does not absorb, under a uniform sky: it vanishes',
+        environment: [0.5, 0.5, 0.5],
+        camera: { position: [0, 0, 6], target: [0, 0, 0], fov_degrees: 30 },
+        test(s) {
+            place_fog(s, {
+                position: [0, 0, 0],
+                scale: [2, 2, 2],
+                extinction: [0.6, 1.2, 2.4],
+                scattering: [0.6, 1.2, 2.4],
+                g: 0.6,
+            });
+        },
+        regions: [
+            { name: 'through the fog', rect: [0.4, 0.4, 0.6, 0.6], expected: [0.5, 0.5, 0.5] },
+            { name: 'the sky', rect: [0, 0, 0.1, 0.1], expected: [0.5, 0.5, 0.5] },
+        ],
+    },
+    {
+        name: 'shadow through an index-matched absorbing box',
+        about: 'sunlight reaching a floor through 1 m of an absorbing medium bounded by an n = 1 mesh: the shadow ray crosses the boundary and is attenuated by exp(-sigma d)',
+        environment: [0, 0, 0],
+        camera: { position: [0, 0.8, 7], target: [0, 0, 0], fov_degrees: 30 },
+        control(s) {
+            place_floor_in_sun(s);
+        },
+        test(s) {
+            place_floor_in_sun(s);
+
+            s.place(
+                s.meshlets(make_box_geometry(8, 1, 8)),
+                surface({ transmission: 1, ior: 1, medium: absorbing_medium(SIGMA) }),
+                new Vector3(0, 2.5, 0)
+            );
+        },
+        regions: [
+            { name: 'the floor under it', rect: [0.4, 0.55, 0.6, 0.62], expected: SIGMA.map(s => Math.exp(-s)), ratio: true },
+        ],
+    },
+    {
+        name: 'shadow through an absorbing fog volume',
+        about: 'the same through a scene participating-media volume that only absorbs',
+        environment: [0, 0, 0],
+        camera: { position: [0, 0.8, 7], target: [0, 0, 0], fov_degrees: 30 },
+        control(s) {
+            place_floor_in_sun(s);
+        },
+        test(s) {
+            place_floor_in_sun(s);
+
+            place_fog(s, {
+                position: [0, 2.5, 0],
+                scale: [8, 1, 8],
+                extinction: SIGMA,
+                scattering: [0, 0, 0],
+                g: 0,
+            });
+        },
+        regions: [
+            { name: 'the floor under it', rect: [0.4, 0.55, 0.6, 0.62], expected: SIGMA.map(s => Math.exp(-s)), ratio: true },
+        ],
+    },
+    sun_through_water_check(30),
+    sun_through_water_check(60),
+    sun_through_water_check(75),
+    sun_through_water_check(85),
+    {
+        name: 'sun on an underwater slope facing away from it',
+        about: `the tile ${TILE_DEPTH} m under flat water leaning ${SLOPE_DEGREES} degrees away from a sun 60 degrees from overhead, against the same tile flat and dry: in air the sun is 5 degrees behind the slope, but refracted to 40.5 degrees it lights it at 75.5 — only if the light is chosen and its connection tried by the refracted direction, not the straight one`,
+        environment: [0, 0, 0],
+        camera: WATER_CAMERA,
+        control(s) {
+            place_tile(s);
+            place_sun_at(s, 60);
+        },
+        test(s) {
+            const phi = SLOPE_DEGREES * Math.PI / 180;
+
+            // its normal (sin phi, cos phi, 0): +z turned a quarter about the axis between them
+            s.place(
+                s.meshlets(make_plane_geometry(0.4, 0.4, 1, 1)),
+                surface({ albedo: [0.5, 0.5, 0.5], roughness: 0, ior: N_WATER }),
+                new Vector3(0, 0, 0),
+                Quaternion.fromAxisAngle(new Vector3(-Math.cos(phi), Math.sin(phi), 0), Math.PI / 2)
+            );
+            place_sun_at(s, 60);
+            place_water(s);
+        },
+        regions: [
+            {
+                name: 'the tile',
+                rect: [0.45, 0.45, 0.55, 0.55],
+                expected: (() => {
+                    const theta = Math.PI / 3, phi = SLOPE_DEGREES * Math.PI / 180;
+                    const sin_w = Math.sin(theta) / N_WATER;
+                    const cos_w = Math.sqrt(1 - sin_w * sin_w);
+                    // toward the sun in water, (-sin_w, cos_w, 0), on the leaning normal
+                    const cos_slope = -Math.sin(phi) * sin_w + Math.cos(phi) * cos_w;
+                    const view_factor = water_view_factor();
+
+                    // the beam's irradiance across itself under water is the flat tile's over cos_w
+                    return WATER_ABSORPTION.map((a, c) => (1 - fresnel_dielectric(Math.cos(theta), N_WATER))
+                        * Math.exp(-a * TILE_DEPTH / cos_w) * cos_slope / cos_w * view_factor[c]);
+                })(),
+                ratio: true,
+            },
+        ],
+    },
+    {
+        name: 'sun through flat water past an index-matched box',
+        about: `the 30-degree water check with a box of the same water between the tile and the surface: its walls are no interface, so it changes nothing — but every probe of the connection's walk meets its walls first, on its way to the surface`,
+        environment: [0, 0, 0],
+        camera: WATER_CAMERA,
+        control(s) {
+            place_tile(s);
+            place_sun_at(s, 30);
+        },
+        test(s) {
+            const material = water();
+
+            place_tile(s, N_WATER);
+            place_sun_at(s, 30);
+            place_water(s, material);
+
+            s.place(s.meshlets(make_box_geometry(2, 0.6, 2)), material, new Vector3(0, 0.5, 0));
+        },
+        regions: [
+            {
+                name: 'the tile',
+                rect: [0.4, 0.4, 0.6, 0.6],
+                expected: sun_through_water_check(30).regions[0].expected,
+                ratio: true,
+            },
+        ],
+    },
+    {
+        name: 'lamp over flat water',
+        about: `the same tile under a point lamp ${LAMP_HEIGHT} m above the water's surface, straight over it: through flat water a point light's beam narrows to (h + z / n)² from (h + z)², so the tile is brighter by ((h + z) / (h + z / n))² than the water's transmission alone would leave it`,
+        environment: [0, 0, 0],
+        camera: WATER_CAMERA,
+        control(s) {
+            place_tile(s);
+            place_lamp(s);
+        },
+        test(s) {
+            place_tile(s, N_WATER);
+            place_lamp(s);
+            place_water(s);
+        },
+        regions: [
+            {
+                name: 'the tile',
+                rect: [0.45, 0.45, 0.55, 0.55],
+                expected: (() => {
+                    const h = LAMP_HEIGHT, z = TILE_DEPTH;
+                    const narrowing = ((h + z) / (h + z / N_WATER)) ** 2;
+                    const view_factor = water_view_factor();
+
+                    return WATER_ABSORPTION.map((a, c) => (1 - fresnel_dielectric(1, N_WATER)) * Math.exp(-a * z) * narrowing * view_factor[c]);
+                })(),
+                ratio: true,
+            },
+        ],
+    },
+];
+
+/**
+ * Mean and standard error per channel over a rectangle of the image, and the mean over the same
+ * pixels of what each should be.
+ *
+ * Given the accumulation read halfway (`half_image`), the standard error is the estimate's own
+ * noise: per pixel, the second half (2 image - half) less the first is noise alone, and the mean of
+ * the whole has a quarter of its variance. Without it, each pixel is taken as one independent
+ * estimate of the rectangle's mean — which counts any structure across the rectangle, a dark arc
+ * where the answer is flat, as noise, and widens the tolerance for exactly the error it should find.
+ *
+ * @param {{rgb: Float32Array, width: number, height: number}} image
+ * @param {number[]} rect
+ * @param {number[]|function(number, number[]): number[]} expected
+ * @param {number} fov_degrees the camera's vertical field of view; the image is square
+ * @param {{rgb: Float32Array}|null} [half_image] the same accumulation after half the frames
+ * @returns {{mean: number[], standard_error: number[], expected: number[], pixels: number, non_finite: number}}
+ */
+export function region_statistics(image, rect, expected, fov_degrees, half_image = null) {
+    const x0 = Math.floor(rect[0] * image.width);
+    const y0 = Math.floor(rect[1] * image.height);
+    const x1 = Math.ceil(rect[2] * image.width);
+    const y1 = Math.ceil(rect[3] * image.height);
+
+    const sum = [0, 0, 0];
+    const sum2 = [0, 0, 0];
+    const sum_expected = [0, 0, 0];
+
+    // second half less first half, per pixel
+    const sum_d = [0, 0, 0];
+    const sum_d2 = [0, 0, 0];
+
+    const tan_half = Math.tan(fov_degrees * Math.PI / 360);
+
+    let pixels = 0;
+    let non_finite = 0;
+
+    for (let y = y0; y < y1; y++) {
+        for (let x = x0; x < x1; x++) {
+            const i = (y * image.width + x) * 3;
+
+            let finite = true;
+
+            for (let c = 0; c < 3; c++) {
+                if (!Number.isFinite(image.rgb[i + c])) {
+                    finite = false;
+                }
+            }
+
+            if (!finite) {
+                non_finite++;
+                continue;
+            }
+
+            // the pixel centre's ray, against the camera's axis; image rows run down, the frame's y up
+            const tx = ((x + 0.5) / image.width * 2 - 1) * tan_half;
+            const ty = ((y + 0.5) / image.height * 2 - 1) * tan_half;
+            const length = Math.sqrt(1 + tx * tx + ty * ty);
+
+            const answer = typeof expected === 'function'
+                ? expected(1 / length, [tx / length, -ty / length, -1 / length])
+                : expected;
+
+            for (let c = 0; c < 3; c++) {
+                const v = image.rgb[i + c];
+
+                sum[c] += v;
+                sum2[c] += v * v;
+                sum_expected[c] += answer[c];
+
+                if (half_image !== null) {
+                    const d = 2 * (v - half_image.rgb[i + c]);
+
+                    sum_d[c] += d;
+                    sum_d2[c] += d * d;
+                }
+            }
+
+            pixels++;
+        }
+    }
+
+    const mean = sum.map(s => s / pixels);
+
+    const standard_error = half_image !== null
+        ? sum_d2.map((s, c) => {
+            const d = sum_d[c] / pixels;
+            const variance = Math.max(0, s - pixels * d * d) / (pixels - 1);
+
+            return Math.sqrt(variance / 4 / pixels);
+        })
+        : sum2.map((s, c) => Math.sqrt(Math.max(0, s / pixels - mean[c] * mean[c]) / pixels));
+
+    return { mean, standard_error, expected: sum_expected.map(s => s / pixels), pixels, non_finite };
+}
+
+/**
+ * Whether a measured value agrees with the expected one: within four standard errors, plus a
+ * relative allowance — by default 0.2%, for what the image's formats and the dithered material
+ * inputs add.
+ *
+ * @param {number} measured
+ * @param {number} standard_error
+ * @param {number} expected
+ * @returns {boolean}
+ */
+export function agrees(measured, standard_error, expected, allowance = 2e-3) {
+    return Math.abs(measured - expected) <= 4 * standard_error + allowance * Math.abs(expected) + 1e-5;
+}