@woosh/meep-engine 2.163.11 → 2.165.0

package/src/engine/graphics/sh3/lightmap/LIGHTMAPPER_REVIEW.md

@@ -0,0 +1,183 @@
+# Review: ands/lightmapper vs. our lightmap baker
+
+Reference: https://github.com/ands/lightmapper (`lightmapper.h`, Andreas Mantler).
+Our code: `engine/graphics/sh3/lightmap/`.
+
+Context: we run **mixed mode** — the lightmap stores *indirect + sky only*
+(`lightmap_gather.js` has no direct term); direct light comes from realtime lights.
+
+## Status (2026-06): implemented from this review
+
+- **Adaptive hierarchical sampling** — `bake_lightmap_for_scene.js` bakes a coarse grid
+  (`adaptive_step`), then bilinearly interpolates interior texels whose coarse
+  neighbourhood agrees within `interpolation_threshold` and fully path-traces only the
+  edges. `adaptive_step = 1` disables. (P0)
+- **Conservative rasterization + clamp-into-triangle** — `lightmap_rasterize_triangle.js`
+  `conservative` mode covers edge/sliver texels with a sample clamped onto the triangle. (P1)
+- **Texel-size-relative bias** — the off-surface nudge is `surface_bias × (world size of one
+  texel)`, computed per triangle from world-area ÷ uv-area. (P1)
+- **Confidence mask** — `lightmap_gather.js` returns `1 − (fraction of short probes hitting a
+  BACK face)`; buried texels (`< valid_threshold`) become holes filled from neighbours.
+  Deliberately backface-based, **not** openness-based, so enclosed-but-valid texels (a floor
+  in a room) stay confident. (P2)
+- **Variance-driven denoise** — `lightmap_denoise.js` is an edge-stopping filter gated by the
+  per-texel Monte-Carlo variance (`lightmap_gather` returns variance-of-the-mean in `out[3]`):
+  it blends differences consistent with noise and preserves real gradients. Not a blind blur. (P1)
+- **Doc** — the "direct" term wording is gone from the gather/bake docstrings.
+
+Specs: `lightmap_*.spec.js` (rasterize incl. conservative, gather incl. confidence, denoise
+incl. edge-preservation, build_geometry, pack, end-to-end incl. adaptive≈full).
+
+### Deliberately NOT done (and why)
+- **Shared stratified directions** — rejected: a fixed direction set shared across texels
+  couples samples and shows as structured bias on flats, worst at low sample counts. Each
+  texel draws independent random directions; variance is handled by adaptive sampling + the
+  variance-driven denoiser instead.
+- **Directional / L1-SH lightmaps** — out of scope: staying within three.js limits (flat RGB).
+- **Progressive multi-bounce (re-bake as emissive)** — deferred: without per-step seam/border
+  fixups and a ping-pong buffer it would accumulate noise and leaks.
+- **Web-worker parallelism** — non-goal for now.
+
+The remainder of this document is the original analysis.
+
+---
+
+## 1. How the two differ (so we know what ports and what doesn't)
+
+| | ands/lightmapper | ours |
+|---|---|---|
+| Integrator | GPU **hemicube rasterization**: render the scene into a 5-side hemicube per texel, integrate with a precomputed weight map | CPU **Monte-Carlo path tracing**: N cosine-weighted rays per texel through `PathTracer` |
+| Samples/texel | **1 hemisphere capture** = the whole integral, noise-free per bounce | `samples_per_texel` random rays → stochastic noise (prototype is at **64**) |
+| Multi-bounce | progressive: re-bake feeding the previous lightmap back as emissive | true path bounces inside one gather (`max_bounce`) |
+| UVs | **you bring your own** (suggests xatlas/thekla) | **we generate them** (xatlas charter + shared multi-mesh atlas) |
+| Renderer | needs a live GL context + your scene shaders | headless, renderer-agnostic, unit-testable |
+| Weighting | `cos³θ` per hemicube pixel (Lambert × hemicube foreshortening) | cosine-importance sampling (`getBiasedNormalSample`, power 1) — same radiometry, just via MC |
+| Post | `lmImageDilate` / `lmImageSmooth` / `lmImageDownsample` | `lmImageDilate` equivalent only |
+
+**Takeaway:** ands' core advantage is *variance-free capture* and *work-skipping*
+(adaptive interpolation). Almost every ands win lands on our side as either
+**variance reduction** or **work reduction** — both very welcome for a CPU tracer.
+Our advantages (auto-UV, headless, true PT, shared atlas) are things ands does *not* do.
+
+---
+
+## 2. What we already match or beat
+
+- **UV generation + shared atlas** — ands explicitly punts UVs to xatlas/thekla; we
+  do the unwrap and pack many meshes into one atlas.
+- **Headless / renderer-independent** — our bake needs no GL context and is covered by
+  specs; ands requires you to wire your renderer into `lmBegin/lmEnd`.
+- **Correct cosine weighting** — our `getBiasedNormalSample(power=1)` MC estimator is
+  the unbiased equivalent of ands' `cos³θ` hemicube weights. No change needed here.
+- **Seam dilation** — `lightmap_dilate.js` ≈ `lmImageDilate`.
+
+---
+
+## 3. Improvements, prioritized
+
+### P0 — Adaptive hierarchical sampling (ands `interpolationPasses` / `interpolationThreshold`)
+**ands:** first pass samples only every `1 << interpolationPasses`-th texel; later passes
+fully sample a texel only if a neighbour deviates by more than `interpolationThreshold`,
+otherwise interpolate. Reported **3.3×–10×** speedup at no visible cost.
+
+**Ours:** `bake_lightmap_for_scene.js` `cycle()` fully path-traces **every** covered texel.
+
+**Why it's our #1:** path tracing per texel is our dominant cost, and in **mixed mode the
+lightmap is indirect-only ⇒ very low frequency ⇒ huge smooth regions** that interpolate
+almost perfectly. This is the single biggest win and it's *more* effective for us than for ands.
+
+Sketch: bake on a coarse texel grid, store value+confidence per sampled texel; refine
+(full-sample) only texels whose coarse neighbourhood gradient exceeds a threshold;
+bilinearly fill the rest. Fits our existing job-list/`TaskGroup` cycle model.
+
+### P0 — Stratified / jittered hemisphere directions (variance, free win)
+**Ours:** `lightmap_gather.js` draws each direction from raw `random()` → white-noise
+variance, which is exactly why the prototype had to push `samples_per_texel` to 64.
+
+**Fix:** we *already ship* `path_tracer/sampling/generate_stratified_samples_2d.js`. Draw
+`Nx×Ny` stratified `(u1,u2)` pairs per texel and map each to a cosine hemisphere direction
+(needs a `getBiasedNormalSample` variant that takes `(u1,u2)` instead of calling `random()`
+internally — trivial refactor). Same sample count, markedly less noise; or same quality at
+far fewer samples. Pair with a per-texel jittered base rotation for inter-texel decorrelation.
+
+### P1 — Conservative rasterization + clamp the sample into the triangle
+**ands:** clips the texel quad against the triangle (`lm_convexClip`) and samples the
+**centroid of the clipped polygon** — i.e. every partially-covered texel gets a *valid,
+inside-the-triangle* sample point.
+
+**Ours:** `lightmap_rasterize_triangle.js` uses a **texel-center-inside** test
+(`if (wA<0||wB<0||wC<0) continue`). Texels straddling an edge (thin features, chart borders)
+are dropped entirely and left to dilation, and a center that sits just inside an edge can
+sample a near-degenerate spot → leaks/seams.
+
+**Fix:** add a conservative coverage mode that, for any texel overlapping the triangle,
+clamps the barycentric sample to the nearest point inside the triangle (or uses the clipped
+centroid). Cuts seam/black-edge artifacts and reduces reliance on dilation. Keep the current
+fast path for interiors.
+
+### P1 — Supersample + downsample, and/or a smoothing pass (`lmImageDownsample` / `lmImageSmooth`)
+**ands:** offers `lmImageDownsample` (bake at 2× then box-downsample = cheap AA + denoise)
+and `lmImageSmooth` (3×3 box over valid texels).
+
+**Ours:** only dilation. Add a downsample step (bake N× then average) and/or a valid-only
+3×3 smooth before dilation. Especially valuable while we're still MC-noisy. Cheap, isolated,
+high perceived-quality gain.
+
+### P1 — Texel-size-relative self-occlusion bias
+**ands:** offsets the camera by `(1+cameraToSurfaceDistanceModifier)·zNear·√2` along the
+interpolated normal; bias is tied to scene/near-plane scale.
+
+**Ours:** `surface_bias * max(1,|P|)` in `bake_lightmap_for_scene.js`. Magnitude-relative bias
+over- or under-biases depending on where the geometry sits in world space (peter-panning vs.
+acne). **Better:** derive the bias from the *world size of one lightmap texel* (we know each
+chart's surface-area↔UV-area ratio and the atlas resolution), so the offset scales with local
+texel footprint, not absolute coordinates.
+
+### P2 — Validity / confidence mask (ands' alpha-coverage discard)
+**ands:** accumulates per-hemicube solid-angle "validity" in alpha and discards texels with
+< 0.9 coverage (mostly self-occluded / out-of-bounds), then fills them from neighbours.
+**Ours:** no notion of a bad texel. Track a per-texel confidence (fraction of rays that didn't
+immediately self-/back-hit); mark low-confidence texels invalid so dilation fills them from good
+neighbours instead of baking in leaks.
+
+### P2 — Progressive multi-bounce via irradiance reuse
+**ands:** extra bounces = re-bake with the previous lightmap as emissive (each pass is 1 bounce).
+**Ours:** N bounces per path per texel — correct but cost ∝ bounces×samples. For *many* bounces,
+a progressive scheme (bake bounce-1, then feed the baked atlas back as an emissive/irradiance
+source so later passes need only 1 bounce) is much cheaper. Low urgency in mixed mode with small
+`max_bounce`, but it's the scalable path.
+
+### P2 — Parallelize the bake across Web Workers
+ands gets parallelism for free on the GPU; we're single-threaded. The bake is embarrassingly
+parallel per texel/chart and meep already has worker infrastructure. Biggest raw throughput win
+after adaptive sampling, orthogonal to all of the above.
+
+### P3 — Tuning nits
+- For a fixed small `max_bounce`, the path tracer's Russian roulette adds variance; raising
+  `min_bounce ≥ max_bounce` (disable RR) gives lower-variance fixed-depth estimates for baking.
+- Bound gather rays with a finite `tMax` (ands' `zFar`) on large scenes.
+
+---
+
+## 4. Mixed-mode specifics
+
+- **Indirect-only ⇒ smooth ⇒ adaptive sampling (P0) pays off the most.** Prioritize it.
+- **Directional indirect:** plain RGB indirect ignores per-pixel normals. If normal-mapped
+  surfaces should respond to baked indirect, store an **L1 SH / dominant-direction** lightmap
+  (Enlighten/Unity "directional") instead of flat irradiance. Bigger feature, but the natural
+  next quality step for mixed mode.
+- **Optional AO channel:** a cheap cosine-AO bake alongside indirect is common in mixed setups.
+- **Doc drift:** `lightmap_gather.js` and `bake_lightmap_for_scene.js` docstrings still describe
+  a direct-lighting term that's been removed — update them to "indirect + sky (mixed mode)".
+
+---
+
+## 5. Suggested order of work
+
+1. **Stratified hemisphere sampling** (P0, ~hours, pure variance win, primitive already exists).
+2. **Adaptive hierarchical sampling** (P0, biggest speedup, synergizes with indirect-only).
+3. **Conservative raster + sample clamp** (P1, kills edge seams/leaks).
+4. **Downsample/smooth post-pass + texel-relative bias** (P1, quick quality).
+5. **Confidence mask, worker parallelism, directional/AO** (P2+, as needed).
+
+Fix the stale docstrings whenever the gather is next touched.

package/src/engine/graphics/sh3/lightmap/bake_lightmap_for_scene.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Bake a single shared **indirect** lightmap for every {@link ShadedGeometry} in a
+ * scene (mixed-mode lighting: direct light stays realtime) using the engine's own
+ * UV-atlas charter ({@link atlas_compute_charts} + {@link atlas_pack_charts}) and
+ * the {@link PathTracer}.
+ *
+ * The returned {@link TaskGroup} runs the bake incrementally on an executor: its
+ * initializer conditions every mesh (build topology → compute UV charts), packs
+ * all charts from all meshes into ONE atlas, swaps each mesh's geometry for a
+ * re-charted one carrying a `uv2` lightmap channel, points every material at the
+ * shared lightmap texture (initially black), and rasterizes the covered texels
+ * conservatively into a bake job list. Subsequent cycles bake the texels and
+ * upload the partial result each cycle for a live preview.
+ *
+ * Quality/perf techniques (see LIGHTMAPPER_REVIEW.md):
+ *  - **Adaptive sampling** — a coarse grid is fully path-traced first; interior
+ *    texels whose coarse neighbourhood agrees are bilinearly interpolated, and
+ *    only edges/discontinuities are fully sampled (`adaptive_step` = 1 disables).
+ *  - **Conservative rasterization** — edge-overlapping texels get a sample clamped
+ *    onto the triangle, so thin features and chart borders are covered.
+ *  - **World-space off-surface bias** — a small fixed world-space nudge (scaled only
+ *    by coordinate magnitude for float precision), NOT coupled to lightmap resolution.
+ *  - **Confidence mask** — buried/over-occluded texels are left as holes and filled
+ *    from good neighbours instead of baking in leaks.
+ *  - **Variance-guided denoise** — noisy texels blend with consistent neighbours;
+ *    real gradients are preserved.
+ *
+ * The lightmap stores cosine-weighted mean radiance (`E / π`, linear); three.js's
+ * lightmap path multiplies it back by `π · albedo / π = albedo`, so each surface
+ * keeps its colour modulated by the baked indirect light.
+ *
+ * @param {object} options
+ * @param {EntityComponentDataset} options.ecd the scene to bake
+ * @param {number} [options.lightmap_resolution] square atlas size in texels (default 2048)
+ * @param {number} [options.samples_per_texel] minimum hemisphere gather samples per fully-baked texel (default 32)
+ * @param {number} [options.max_samples] adaptive ceiling: noisy texels (contacts/edges) sample up to this (default 128)
+ * @param {number} [options.sample_variance_target] relative variance-of-mean to stop adaptive sampling; 0 = fixed count (default 0.02)
+ * @param {number} [options.min_bounce] path-tracer roulette start depth (default 2)
+ * @param {number} [options.max_bounce] path-tracer maximum depth (default 6)
+ * @param {number} [options.padding] atlas gutter texels, also the dilation radius (default 4)
+ * @param {number} [options.ray_batch] approximate number of gather/probe rays to cast per
+ *   executor cycle (default 40000). The per-cycle texel count is derived from this and the
+ *   per-texel ray cost (samples, bounce depth, confidence probes), so a cycle stays roughly
+ *   constant work regardless of those — raising `samples_per_texel` shrinks the texel batch
+ *   instead of lengthening each cycle, keeping the bake from hitching the frame rate.
+ * @param {number} [options.light_map_intensity] material lightMapIntensity to set (default 1)
+ * @param {number} [options.surface_bias] off-surface nudge as a fraction of the point's world-coordinate
+ *   magnitude (a small world-space offset, decoupled from lightmap resolution); default 0.001
+ * @param {number} [options.adaptive_step] coarse grid spacing in texels; 1 = full sampling everywhere (default 4)
+ * @param {number} [options.interpolation_threshold] relative luminance agreement that marks an interior texel "smooth" (default 0.1)
+ * @param {number} [options.min_sample_fraction] fraction of `samples_per_texel` spent on smooth texels; 0 = pure bilinear (default 0.25)
+ * @param {number} [options.supersample] sub-texel ray-origin jitter as a fraction of a texel (anti-aliasing); 0 disables (default 1)
+ * @param {number} [options.confidence_probes] short backface probes per baked texel; 0 disables (default 6)
+ * @param {number} [options.inside_probe_texels] backface probe reach in texels (default 4)
+ * @param {number} [options.valid_threshold] minimum confidence to keep a texel; below it becomes a hole (default 0.15)
+ * @param {boolean} [options.denoise] run the variance-guided denoise pass (default true)
+ * @param {number} [options.seam_fix_iterations] UV-seam blend passes; 0 disables (default 4)
+ * @param {boolean} [options.debug] also expose per-texel world positions and the
+ *   pre-dilation baked coverage on `group.lightmap` (extra buffers; default false)
+ * @param {function(out:number[], out_offset:number, direction:number[], direction_offset:number):void} [options.background]
+ *   environment radiance sampler for sky/ambient fill (default {@link make_sky_rtiw})
+ * @param {number} [options.seed] PRNG seed for reproducible bakes (default 1)
+ * @returns {TaskGroup} a group whose single task performs the bake; it also exposes
+ *   `.lightmap = { texture, sampler, scene }` for inspection
+ */
+export function bake_lightmap_for_scene({ ecd, lightmap_resolution, samples_per_texel, max_samples, sample_variance_target, min_bounce, max_bounce, padding, ray_batch, light_map_intensity, surface_bias, adaptive_step, interpolation_threshold, min_sample_fraction, supersample, confidence_probes, inside_probe_texels, valid_threshold, denoise, seam_fix_iterations, debug, background, seed, }: {
+    ecd: EntityComponentDataset;
+    lightmap_resolution?: number;
+    samples_per_texel?: number;
+    max_samples?: number;
+    sample_variance_target?: number;
+    min_bounce?: number;
+    max_bounce?: number;
+    padding?: number;
+    ray_batch?: number;
+    light_map_intensity?: number;
+    surface_bias?: number;
+    adaptive_step?: number;
+    interpolation_threshold?: number;
+    min_sample_fraction?: number;
+    supersample?: number;
+    confidence_probes?: number;
+    inside_probe_texels?: number;
+    valid_threshold?: number;
+    denoise?: boolean;
+    seam_fix_iterations?: number;
+    debug?: boolean;
+}): TaskGroup;
+import TaskGroup from "../../../../core/process/task/TaskGroup.js";
+//# sourceMappingURL=bake_lightmap_for_scene.d.ts.map

package/src/engine/graphics/sh3/lightmap/bake_lightmap_for_scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bake_lightmap_for_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/lightmap/bake_lightmap_for_scene.js"],"names":[],"mappings":"AAuEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;IAjC2C,GAAG;IAClB,mBAAmB,GAApC,MAAM;IACW,iBAAiB,GAAlC,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,sBAAsB,GAAvC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,OAAO,GAAxB,MAAM;IACW,SAAS,GAA1B,MAAM;IAKW,mBAAmB,GAApC,MAAM;IACW,YAAY,GAA7B,MAAM;IAEW,aAAa,GAA9B,MAAM;IACW,uBAAuB,GAAxC,MAAM;IACW,mBAAmB,GAApC,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,iBAAiB,GAAlC,MAAM;IACW,mBAAmB,GAApC,MAAM;IACW,eAAe,GAAhC,MAAM;IACY,OAAO,GAAzB,OAAO;IACU,mBAAmB,GAApC,MAAM;IACY,KAAK,GAAvB,OAAO;IAKL,SAAS,CAgiBrB;sBArpBqB,4CAA4C"}