@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -0,0 +1,161 @@
+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 { place_light } from "../../renderer/light/place_light.js";
+import { ParticipatingMedium } from "../../renderer/medium/ParticipatingMedium.js";
+import { PhaseFournierForand } from "../../renderer/medium/phase/PhaseFournierForand.js";
+import { PhaseHenyeyGreenstein } from "../../renderer/medium/phase/PhaseHenyeyGreenstein.js";
+import { PhaseWaterMolecular } from "../../renderer/medium/phase/PhaseWaterMolecular.js";
+import { absorbing_medium, place_fog, surface } from "./checks.js";
+import { make_wave_pool_geometry } from "./make_wave_pool_geometry.js";
+
+/**
+ * Scenes to look at, not to measure: what the media do in a setting with something to see through
+ * them. `environment: 'sky'` lights them with the playground's default sky when `test_assets/` has
+ * it, and a flat blue one until then.
+ *
+ * @typedef {Object} MediaView
+ * @property {string} name
+ * @property {string} about
+ * @property {number[]|'sky'} environment
+ * @property {{position: number[], target: number[], fov_degrees: number}} camera
+ * @property {function(MediaScene): void} test
+ */
+
+/** a checkerboard of 1 m tiles, so refraction and absorption have a pattern to bend and tint */
+function place_checkerboard({ place, meshlets }) {
+    const tile = meshlets(make_plane_geometry(1, 1, 1, 1));
+    const flat = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
+
+    const light = surface({ albedo: [0.8, 0.8, 0.78], roughness: 0.7 });
+    const dark = surface({ albedo: [0.12, 0.12, 0.13], roughness: 0.7 });
+
+    for (let x = -6; x < 6; x++) {
+        for (let z = -6; z < 5; z++) {
+            place(tile, ((x + z) & 1) === 0 ? light : dark, new Vector3(x + 0.5, 0, z + 0.5), flat);
+        }
+    }
+}
+
+/**
+ * @type {MediaView[]}
+ */
+export const MEDIA_VIEWS = [
+    {
+        name: 'glass, water and fog',
+        about: 'left to right: clear glass (n = 1.5), amber glass that absorbs blue, a milky medium that scatters (n = 1.4), and a tank of water (n = 1.333) holding a red block; fog behind. The sun reaches the block through the water\'s surface, by manifold next-event estimation, which connects through one refracting surface: light through a glass sphere crosses two, so the spheres still cast full shadows.',
+        environment: 'sky',
+        camera: { position: [0, 2.4, 7.2], target: [0, 0.45, 0], fov_degrees: 45 },
+        test(s) {
+            place_checkerboard(s);
+
+            place_light(s.scene, make_sunlight({
+                intensity: 3,
+                direction: new Vector3(-0.5, -1, -0.6),
+                temperature: 5800,
+            }));
+
+            const sphere = s.meshlets(make_octahedron_geometry(0.6, 32));
+
+            s.place(
+                sphere,
+                surface({ transmission: 1, ior: 1.5, medium: new ParticipatingMedium() }),
+                new Vector3(-2.2, 0.6, 0)
+            );
+
+            s.place(
+                sphere,
+                surface({ transmission: 1, ior: 1.5, medium: absorbing_medium([0.2, 1.0, 3.0]) }),
+                new Vector3(-0.8, 0.6, 0)
+            );
+
+            const milk = new ParticipatingMedium();
+
+            milk.absorption = [0.05, 0.1, 0.2];
+            milk.add_lobe([4, 4, 4], new PhaseHenyeyGreenstein({ g: 0.2 }));
+
+            s.place(
+                sphere,
+                surface({ transmission: 1, ior: 1.4, medium: milk }),
+                new Vector3(0.6, 0.6, 0)
+            );
+
+            const water = new ParticipatingMedium();
+
+            water.absorption = [0.6, 0.12, 0.06];
+            water.add_lobe([0.002, 0.004, 0.009], new PhaseWaterMolecular({ depolarization: 0.039 }));
+            water.add_lobe([0.15, 0.15, 0.15], new PhaseFournierForand({ backscatter_fraction: 0.0183 }));
+
+            s.place(
+                s.meshlets(make_box_geometry(1.2, 1, 1.2)),
+                surface({ transmission: 1, ior: 1.333, medium: water }),
+                new Vector3(2.2, 0.51, 0)
+            );
+
+            s.place(
+                s.meshlets(make_box_geometry(0.4, 0.4, 0.4)),
+                surface({ albedo: [0.8, 0.1, 0.08], roughness: 0.6 }),
+                new Vector3(2.2, 0.22, 0)
+            );
+
+            place_fog(s, {
+                position: [0, 1.5, -2.5],
+                scale: [10, 3, 1.5],
+                extinction: [0.25, 0.25, 0.25],
+                scattering: [0.25, 0.25, 0.25],
+                g: 0.6,
+            });
+        },
+    },
+    {
+        name: 'caustics under waves',
+        about: 'a pool of clear water (n = 1.333) whose surface is two crossing sine waves, 2 cm high, the sun 25 degrees from overhead: the light reaching the pool\'s floor is connected through the moving surface by manifold next-event estimation, and the surface\'s curvature focuses and spreads it — the bright web on the floor is caustics, which straight shadow rays cannot make.',
+        environment: 'sky',
+        camera: { position: [0, 3.4, 3.1], target: [0, 0, 0.1], fov_degrees: 45 },
+        test(s) {
+            place_checkerboard(s);
+
+            place_light(s.scene, make_sunlight({
+                intensity: 3,
+                direction: new Vector3(-0.3, -1, -0.25),
+                temperature: 5800,
+            }));
+
+            const water = absorbing_medium([0.25, 0.06, 0.03]);
+
+            s.place(
+                s.meshlets(make_wave_pool_geometry({
+                    width: 3.96,
+                    length: 3.96,
+                    depth: 0.6,
+                    amplitude: 0.02,
+                    wavelength: 0.45,
+                    segments: 96,
+                })),
+                surface({ transmission: 1, ior: 1.333, medium: water }),
+                new Vector3(0, -0.01, 0)
+            );
+
+            // a plain floor under the water, where the focused light shows
+            s.place(
+                s.meshlets(make_plane_geometry(3.96, 3.96, 1, 1)),
+                surface({ albedo: [0.8, 0.8, 0.78], roughness: 0.9 }),
+                new Vector3(0, 0.002, 0),
+                Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2)
+            );
+
+            // the pool's walls, just outside the water
+            const wall = surface({ albedo: [0.85, 0.85, 0.82], roughness: 0.8 });
+            const long_wall = s.meshlets(make_box_geometry(4.4, 0.8, 0.2));
+            const short_wall = s.meshlets(make_box_geometry(0.2, 0.8, 4.0));
+
+            s.place(long_wall, wall, new Vector3(0, 0.4, -2.1));
+            s.place(long_wall, wall, new Vector3(0, 0.4, 2.1));
+            s.place(short_wall, wall, new Vector3(-2.1, 0.4, 0));
+            s.place(short_wall, wall, new Vector3(2.1, 0.4, 0));
+        },
+    },
+];

package/src/shade/playground/sh_exponential/README.md

@@ -0,0 +1,43 @@
+# SH exponential reflection probes — playground
+
+Visual check of `renderer/light/environment/sh_exponential/`, the spherical-harmonic-exponential
+reflection probes of Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai, "Spherical Harmonic
+Exponentials for Efficient Glossy Reflections", HPG 2025 (https://doi.org/10.1111/cgf.70219,
+talk: https://www.youtube.com/watch?v=THVMMNZ68iA).
+
+Open `/src/shade/playground/sh_exponential/` on the dev server (`npm run dev` in `packages/meep-engine`).
+It needs the octahedral `.hdr` maps under `test_assets/environments/octahedral/` (see
+`test_assets/README.md`); `?env=<url>` loads any other octahedral `.hdr`. Besides the engine's two
+maps, the list holds the eight the paper evaluates on (its Figures 4 and 5): Poly Haven 2k HDRIs,
+converted by `tools/environment/convert_equirectangular_to_octahedral.mjs`.
+
+## What it shows
+
+The environment is encoded once on the GPU (`SHExpEncoder`, the paper's P = 4, Q = 2 configuration
+fitted for GGX alpha in [0.20, 1], its range relaxed below the [0.25, 1] it is used over) and every
+sphere reads that one probe. Columns are roughness 0.3 to 1.0 (alpha 0.09 to 1.0, the sweep of the
+paper's Figure 6); the two leftmost are below the fitted range, where reconstruction clamps alpha to
+0.20. Rows:
+
+1. **reference** — `E0 = ∫ L f_DV ⟨l,n⟩ dl` by quadrature over a 128×128 octahedral grid of the map,
+   accumulated over 256 frames (the status line shows progress). The encoder fits against a 64×64 grid,
+   so this is not its own quadrature.
+2. **SH exponential** — `sh_exp_p4q2_base_reflectance`.
+3. **engine IBL** — what the forward path does today with the prefiltered map, single scattering:
+   `get_ibl_radiance` times the split-sum LUT's `A + B`, i.e. the same `E0` (no Fresnel) under the split
+   sum's `v = n` assumption. The engine's LUT carries `A + B` to within 0.06% of the albedo.
+4. **error** — SH exponential minus reference on the tonemapped scale, times the error gain: red is too
+   bright, blue too dark.
+
+The orthographic camera turns with yaw and pitch about the world's +Y; turning restarts the reference.
+
+The status line shows the encode's GPU time by timestamps, the mean of 16 encodes in one submission;
+on an adapter without `timestamp-query` it says so. Not submit-to-done wall time, which here is
+mostly Chrome's completion latency (a 256-byte `clearBuffer` alone reads 0.5–4.6 ms that way).
+
+## Driving it
+
+`globalThis.sh_exp_playground.verify()` waits for the reference to converge and returns, per column,
+the RMSE of tonemapped luminance of the SH exponential and of the engine IBL against the reference,
+over the sphere, at the page's exposure. `read_probe()` returns the encoded probe. Both are what the
+headless device check drives.

package/src/shade/playground/sh_exponential/index.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — SH exponential reflection probes</title>
+    <style>
+        :root { color-scheme: dark; }
+        html, body { margin: 0; background: #0d0f12; color: #d6dae0; font: 13px/1.5 ui-monospace, Consolas, monospace; }
+        main { padding: 16px 20px; }
+        h1 { font-size: 15px; margin: 0 0 4px; }
+        p { color: #8b939f; margin: 0 0 10px; max-width: 110ch; }
+        a { color: #8fb4e8; }
+        #status { color: #e5b54a; margin-bottom: 8px; }
+        .fail { color: #e0573e !important; }
+        .ok { color: #6fbf5b !important; }
+        .grid { display: grid; grid-template-columns: auto auto; gap: 0 8px; align-items: start; }
+        #rows div { display: flex; align-items: center; justify-content: flex-end; color: #8b939f; text-align: right; }
+        #columns { display: flex; grid-column: 2; }
+        #columns div { text-align: center; color: #8b939f; }
+        #columns div.outside { color: #e5b54a; }
+        canvas { display: block; image-rendering: pixelated; }
+        .controls { display: flex; flex-wrap: wrap; gap: 6px 18px; margin: 10px 0; }
+        .controls label { display: flex; gap: 6px; align-items: center; }
+        #probe { white-space: pre; color: #8b939f; margin-top: 10px; }
+    </style>
+</head>
+<body>
+<main>
+    <h1>Spherical harmonic exponentials for glossy reflections</h1>
+    <p>
+        Silvennoinen, Sloan, Iwanicki, Nowrouzezahrai, HPG 2025
+        (<a href="https://doi.org/10.1111/cgf.70219">paper</a>,
+        <a href="https://www.youtube.com/watch?v=THVMMNZ68iA">talk</a>).
+        The environment is encoded on the GPU into 33 coefficients per channel (P to degree 4, Q to degree 2),
+        fitted for GGX alpha in [0.20, 1] — the paper's range relaxed below the [0.25, 1] it is used over; every
+        sphere reads that one probe. Shown is the base reflectance <code>E0 = ∫ L f_DV &lt;l,n&gt;</code>, no
+        Fresnel. The reference integrates a 128×128 octahedral grid, progressively; the encoder fits against a
+        64×64 one. Columns in amber are below the fitted range, where reconstruction clamps to alpha 0.20 — the
+        paper's Figure 6 shows the same.
+    </p>
+    <div id="status">starting…</div>
+    <div class="controls">
+        <label>environment <select id="environment"></select></label>
+        <label>yaw <input id="yaw" type="range" min="-180" max="180" step="1" value="0"></label>
+        <label>pitch <input id="pitch" type="range" min="-89" max="89" step="1" value="0"></label>
+        <label>exposure (EV) <input id="exposure" type="range" min="-6" max="6" step="0.25" value="0"></label>
+        <label>error gain <input id="error_gain" type="range" min="1" max="16" step="1" value="4"></label>
+    </div>
+    <div class="grid">
+        <div></div>
+        <div id="columns"></div>
+        <div id="rows"></div>
+        <canvas id="view"></canvas>
+    </div>
+    <div id="probe"></div>
+</main>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

package/src/shade/playground/sh_exponential/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/sh_exponential/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/sh_exponential/main.js"],"names":[],"mappings":""}