@woosh/meep-engine 2.164.0 → 2.165.0

package/src/engine/graphics/sh3/lightmap/bake_lightmap_for_scene.js

@@ -0,0 +1,678 @@
+import { LinearMipmapLinearFilter } from "three";
+import { assert } from "../../../../core/assert.js";
+import { rgb_to_luminance } from "../../../../core/color/rgb_to_luminance.js";
+import { atlas_compute_charts } from "../../../../core/geom/3d/atlas/atlas_compute_charts.js";
+import { atlas_pack_charts } from "../../../../core/geom/3d/atlas/pack/atlas_pack_charts.js";
+import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
+import { BinaryTopology } from "../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import {
+    bt_mesh_from_indexed_geometry
+} from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.js";
+import { v3_matrix4_multiply } from "../../../../core/geom/vec3/v3_matrix4_multiply.js";
+import { v3_normalize_array } from "../../../../core/geom/vec3/v3_normalize_array.js";
+import { seededRandom } from "../../../../core/math/random/seededRandom.js";
+import Task from "../../../../core/process/task/Task.js";
+import TaskGroup from "../../../../core/process/task/TaskGroup.js";
+import { TaskSignal } from "../../../../core/process/task/TaskSignal.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { ShadedGeometry } from "../../ecs/mesh-v2/ShadedGeometry.js";
+import { Sampler2D } from "../../texture/sampler/Sampler2D.js";
+import { sampler2d_to_float32_texture } from "../../texture/sampler/sampler2d_to_float32_texture.js";
+import { make_sky_rtiw } from "../path_tracer/make_sky_rtiw.js";
+import { PathTracedScene } from "../path_tracer/PathTracedScene.js";
+import { PathTracer } from "../path_tracer/PathTracer.js";
+import { populate_path_traced_scene_from_ecd } from "../path_tracer/populate_path_traced_scene_from_ecd.js";
+import { lightmap_build_geometry } from "./lightmap_build_geometry.js";
+import { lightmap_denoise } from "./lightmap_denoise.js";
+import { lightmap_dilate } from "./lightmap_dilate.js";
+import { lightmap_gather } from "./lightmap_gather.js";
+import { lightmap_rasterize_triangle } from "./lightmap_rasterize_triangle.js";
+import { lightmap_seam_fix } from "./lightmap_seam_fix.js";
+
+const PHASE_COARSE = 0;
+const PHASE_FINE = 1;
+
+/**
+ * Geometric-mean scale of a column-major affine 4x4, used to weight a chart's
+ * texel density by its WORLD surface area so density is roughly uniform across
+ * the scene regardless of per-entity scale.
+ *
+ * @param {Float32Array|number[]} m
+ * @returns {number}
+ */
+function mat4_mean_scale(m) {
+    const sx = v3_length(m[0], m[1], m[2]);
+    const sy = v3_length(m[4], m[5], m[6]);
+    const sz = v3_length(m[8], m[9], m[10]);
+    return Math.cbrt(sx * sy * sz);
+}
+
+/**
+ * Read a geometry's index buffer, generating a trivial sequential one (without
+ * mutating the geometry) when it is non-indexed.
+ *
+ * @param {THREE.BufferGeometry} geometry
+ * @param {number} vertex_count
+ * @returns {number[]|Uint8Array|Uint16Array|Uint32Array}
+ */
+function geometry_indices(geometry, vertex_count) {
+    const index = geometry.getIndex();
+    if (index !== null && index !== undefined) {
+        return index.array;
+    }
+    const indices = new Uint32Array(vertex_count);
+    for (let i = 0; i < vertex_count; i++) {
+        indices[i] = i;
+    }
+    return indices;
+}
+
+/**
+ * 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 = 2048,
+                                            samples_per_texel = 32,
+                                            max_samples = 128,
+                                            sample_variance_target = 0.02,
+                                            min_bounce = 2,
+                                            max_bounce = 6,
+                                            padding = 4,
+                                            ray_batch = 40000,
+                                            light_map_intensity = 1,
+                                            surface_bias = 0.001,
+                                            adaptive_step = 4,
+                                            interpolation_threshold = 0.1,
+                                            min_sample_fraction = 0.25,
+                                            supersample = 1,
+                                            confidence_probes = 6,
+                                            inside_probe_texels = 4,
+                                            valid_threshold = 0.15,
+                                            denoise = true,
+                                            seam_fix_iterations = 4,
+                                            debug = false,
+                                            background = make_sky_rtiw(),
+                                            seed = 1,
+                                        }) {
+    assert.defined(ecd, 'ecd');
+
+    const resolution = lightmap_resolution;
+    const random = seededRandom(seed);
+
+    // Derive how many texels to process per executor cycle so a cycle's ray count
+    // stays bounded by ~ray_batch regardless of the cost knobs. Budget against the
+    // WORST case a full texel can incur — variance-adaptive sampling can grow a
+    // noisy texel up to max_samples — so a batch that lands on a cluster of noisy
+    // texels still can't blow past the budget and hitch the frame. Fine (reduced/
+    // interpolated) texels are cheaper, so this is a safe upper bound.
+    const avg_bounces = Math.max(1, 0.5 * (min_bounce + max_bounce));
+    const worst_samples = Math.max(samples_per_texel, max_samples);
+    const rays_per_texel = worst_samples * avg_bounces + confidence_probes;
+    const texel_batch = Math.max(1, Math.floor(ray_batch / rays_per_texel));
+
+    const atlas = Sampler2D.float32(4, resolution, resolution);
+    const coverage = new Uint8Array(resolution * resolution);
+    const variance = new Float32Array(resolution * resolution);
+    const texel_normals = new Float32Array(resolution * resolution * 3); // world normal per committed texel, for normal-aware denoise
+    const texel_world_pos = debug ? new Float32Array(resolution * resolution * 3) : null; // world position per committed texel (debug only)
+    const texture = sampler2d_to_float32_texture(atlas);
+    texture.generateMipmaps = true;
+    texture.minFilter = LinearMipmapLinearFilter;
+    texture.magFilter = LinearMipmapLinearFilter;
+
+    const scene = new PathTracedScene();
+    const path_tracer = new PathTracer();
+
+    // full texels sample adaptively: at least `samples_per_texel`, up to
+    // `max_samples`, drawing more where the relative noise is high (contacts,
+    // occlusion edges, high-frequency bounce).
+    const gather_cfg_full = {
+        samples: samples_per_texel,
+        max_samples: Math.max(samples_per_texel, max_samples),
+        variance_target: sample_variance_target,
+        min_bounce,
+        max_bounce,
+        confidence_probes,
+        inside_probe_texels,
+        supersample,
+    };
+
+    // smooth (interior) texels: a reduced real estimate rather than a pure lerp —
+    // catches small features a lerp would erase, denoise cleans the extra noise.
+    // 0 -> pure bilinear interpolation. Fixed count (no adaptive growth).
+    const reduced_samples = min_sample_fraction > 0
+        ? Math.max(4, Math.round(samples_per_texel * min_sample_fraction))
+        : 0;
+    const gather_cfg_reduced = {
+        ...gather_cfg_full,
+        samples: reduced_samples,
+        max_samples: reduced_samples,
+        variance_target: 0
+    };
+
+    // bake jobs, filled by the initializer: one entry per covered atlas texel
+    let job_x = new Int32Array(0);
+    let job_y = new Int32Array(0);
+    let job_position = new Float32Array(0); // 3 per job, off-surface world point
+    let job_normal = new Float32Array(0);   // 3 per job, world normal
+    let job_texel_size = new Float32Array(0); // 1 per job, world size of one texel
+    let coarse_indices = new Int32Array(0);
+    let fine_indices = new Int32Array(0);
+    let chart_groups = []; // one packed-chart list per mesh, for seam fixing
+    let baked_coverage = null; // snapshot of coverage before dilation (debug/tests)
+
+    let phase = PHASE_COARSE;
+    let coarse_cursor = 0;
+    let fine_cursor = 0;
+
+    const gather_out = new Float32Array(4);
+
+    function is_coarse(x, y) {
+        return adaptive_step <= 1 || (x % adaptive_step === 0 && y % adaptive_step === 0);
+    }
+
+    function prepare() {
+        // ensure transform matrices are current and consistent between the
+        // ray-traced scene and our own world-space sampling
+        ecd.traverseEntities([ShadedGeometry, Transform], (sg, transform) => {
+            transform.updateMatrix();
+        });
+
+        scene.__background_sampler = background;
+        populate_path_traced_scene_from_ecd(ecd, scene);
+        scene.optimize();
+
+        const entries = [];
+        const all_charts = [];
+
+        ecd.traverseEntities([ShadedGeometry, Transform], (sg, transform) => {
+            const geometry = sg.geometry;
+            if (geometry === null || geometry === undefined) {
+                return;
+            }
+
+            const position_attribute = geometry.getAttribute('position');
+            if (position_attribute === undefined) {
+                return;
+            }
+
+            const positions = position_attribute.array;
+            const indices = geometry_indices(geometry, position_attribute.count);
+
+            const mesh = new BinaryTopology();
+            bt_mesh_from_indexed_geometry(mesh, indices, positions);
+
+            const { charts } = atlas_compute_charts(mesh, { weld: true });
+            if (charts.length === 0) {
+                return;
+            }
+
+            const matrix = transform.matrix;
+            const normal_matrix = new Float32Array(9);
+            m4_normal_matrix3(normal_matrix, matrix);
+
+            const area_factor = mat4_mean_scale(matrix) ** 2;
+            for (let i = 0; i < charts.length; i++) {
+                charts[i].surface_area *= area_factor;
+                all_charts.push(charts[i]);
+            }
+
+            // keep the source normals/indices to carry continuous shading normals
+            // across chart seams (see lightmap_build_geometry)
+            const normal_attribute = geometry.getAttribute('normal');
+            const source_normals = normal_attribute !== undefined ? normal_attribute.array : null;
+
+            entries.push({ sg, matrix, normal_matrix, charts, source_normals, source_indices: indices });
+        });
+
+        if (all_charts.length === 0) {
+            return;
+        }
+
+        // pack every chart from every mesh into one shared atlas. atlas_pack_charts
+        // is mesh-free (works purely at the Chart level), so charts from all meshes
+        // pack together and each chart's `uv` is rewritten into shared-atlas space.
+        atlas_pack_charts(all_charts, {
+            maxResolution: resolution,
+            maxPages: 1,
+            padding,
+        });
+
+        const jx = [];
+        const jy = [];
+        const jp = [];
+        const jn = [];
+        const jt = [];
+
+        const local_position = new Float32Array(3);
+        const local_normal = new Float32Array(3);
+        const world_position = new Float32Array(3);
+        const world_normal = new Float32Array(3);
+        const wa = new Float32Array(3);
+        const wb = new Float32Array(3);
+        const wc = new Float32Array(3);
+
+        for (let e = 0; e < entries.length; e++) {
+            const entry = entries[e];
+            const built = lightmap_build_geometry(entry.charts, entry.source_normals, entry.source_indices);
+
+            // swap in the re-charted, lightmap-UV geometry and point the material
+            // at the shared lightmap
+            entry.sg.geometry = built.geometry;
+            chart_groups.push(entry.charts);
+
+            const material = entry.sg.material;
+            if (material !== null && material !== undefined) {
+                material.lightMap = texture;
+                material.lightMapIntensity = light_map_intensity;
+                material.needsUpdate = true;
+            }
+
+            const built_positions = built.positions;
+            const built_normals = built.normals;
+            const offsets = built.chart_vertex_offset;
+            const matrix = entry.matrix;
+            const normal_matrix = entry.normal_matrix;
+            const charts = entry.charts;
+
+            for (let ci = 0; ci < charts.length; ci++) {
+                const chart = charts[ci];
+                const base = offsets[ci];
+                const tri_local = chart.tri_local;
+                const uv = chart.uv;
+                const triangle_count = chart.triangle_count;
+
+                for (let t = 0; t < triangle_count; t++) {
+                    const la = tri_local[t * 3];
+                    const lb = tri_local[t * 3 + 1];
+                    const lc = tri_local[t * 3 + 2];
+
+                    const ga = base + la;
+                    const gb = base + lb;
+                    const gc = base + lc;
+
+                    // world-space size of one lightmap texel for this triangle =
+                    // sqrt(worldArea / texelArea); used by the gather for the
+                    // confidence-probe reach and sub-texel supersample jitter (both
+                    // legitimately footprint-sized). skip degenerate (zero-area) triangles.
+                    const ua = uv[la * 2], va = uv[la * 2 + 1];
+                    const ub = uv[lb * 2], vb = uv[lb * 2 + 1];
+                    const uc = uv[lc * 2], vc = uv[lc * 2 + 1];
+                    const uv_area = 0.5 * Math.abs((ub - ua) * (vc - va) - (vb - va) * (uc - ua));
+                    const texels_in_tri = uv_area * resolution * resolution;
+                    if (!(texels_in_tri > 1e-9)) {
+                        continue;
+                    }
+
+                    v3_matrix4_multiply(wa, 0, built_positions, ga * 3, matrix);
+                    v3_matrix4_multiply(wb, 0, built_positions, gb * 3, matrix);
+                    v3_matrix4_multiply(wc, 0, built_positions, gc * 3, matrix);
+                    const e1x = wb[0] - wa[0], e1y = wb[1] - wa[1], e1z = wb[2] - wa[2];
+                    const e2x = wc[0] - wa[0], e2y = wc[1] - wa[1], e2z = wc[2] - wa[2];
+                    const crx = e1y * e2z - e1z * e2y;
+                    const cry = e1z * e2x - e1x * e2z;
+                    const crz = e1x * e2y - e1y * e2x;
+                    const world_area = 0.5 * v3_length(crx, cry, crz);
+                    const texel_world_size = Math.sqrt(world_area / texels_in_tri);
+                    if (!(texel_world_size > 0)) {
+                        continue;
+                    }
+
+                    lightmap_rasterize_triangle(
+                        ua * resolution, va * resolution,
+                        ub * resolution, vb * resolution,
+                        uc * resolution, vc * resolution,
+                        resolution, resolution,
+                        (texel_x, texel_y, wA, wB, wC) => {
+                            for (let k = 0; k < 3; k++) {
+                                local_position[k] =
+                                    wA * built_positions[ga * 3 + k] +
+                                    wB * built_positions[gb * 3 + k] +
+                                    wC * built_positions[gc * 3 + k];
+                                local_normal[k] =
+                                    wA * built_normals[ga * 3 + k] +
+                                    wB * built_normals[gb * 3 + k] +
+                                    wC * built_normals[gc * 3 + k];
+                            }
+
+                            v3_matrix4_multiply(world_position, 0, local_position, 0, matrix);
+                            v3_matrix3_rotate(world_normal, 0, local_normal[0], local_normal[1], local_normal[2], normal_matrix);
+                            v3_normalize_array(world_normal, 0, world_normal, 0);
+
+                            // Small WORLD-SPACE off-surface nudge so the first gather ray
+                            // doesn't self-intersect the originating surface. Deliberately
+                            // NOT coupled to lightmap resolution / texel size: a texel-scaled
+                            // offset over-pushes (clips through nearby geometry) on low-res
+                            // maps, under-pushes (self-occludes) on dense maps, and varies
+                            // per-triangle under UV distortion. Scaled by coordinate magnitude
+                            // only to stay above the float32 ULP at large coordinates.
+                            const mag = Math.max(1, Math.abs(world_position[0]), Math.abs(world_position[1]), Math.abs(world_position[2]));
+                            const bias = surface_bias * mag;
+
+                            jx.push(texel_x);
+                            jy.push(texel_y);
+                            jp.push(
+                                world_position[0] + world_normal[0] * bias,
+                                world_position[1] + world_normal[1] * bias,
+                                world_position[2] + world_normal[2] * bias
+                            );
+                            jn.push(world_normal[0], world_normal[1], world_normal[2]);
+                            jt.push(texel_world_size);
+                        },
+                        true // conservative
+                    );
+                }
+            }
+        }
+
+        const job_count = jx.length;
+        job_x = Int32Array.from(jx);
+        job_y = Int32Array.from(jy);
+        job_position = Float32Array.from(jp);
+        job_normal = Float32Array.from(jn);
+        job_texel_size = Float32Array.from(jt);
+
+        // split into coarse (fully baked first) and fine (interpolated or refined)
+        const coarse = [];
+        const fine = [];
+        for (let j = 0; j < job_count; j++) {
+            if (is_coarse(job_x[j], job_y[j])) {
+                coarse.push(j);
+            } else {
+                fine.push(j);
+            }
+        }
+        coarse_indices = Int32Array.from(coarse);
+        fine_indices = Int32Array.from(fine);
+    }
+
+    /**
+     * Path-trace one texel; commit it only if confident enough.
+     * @param {number} j job index
+     * @param {object} cfg gather config (full or reduced sample count)
+     */
+    function bake_texel(j, cfg) {
+        const p3 = j * 3;
+        const confidence = lightmap_gather(
+            gather_out,
+            job_position[p3], job_position[p3 + 1], job_position[p3 + 2],
+            job_normal[p3], job_normal[p3 + 1], job_normal[p3 + 2],
+            job_texel_size[j],
+            scene, path_tracer, cfg, random
+        );
+
+        const pixel = job_y[j] * resolution + job_x[j];
+        if (confidence >= valid_threshold) {
+            const texel = pixel * 4;
+            atlas.data[texel] = gather_out[0];
+            atlas.data[texel + 1] = gather_out[1];
+            atlas.data[texel + 2] = gather_out[2];
+            atlas.data[texel + 3] = 1;
+            variance[pixel] = gather_out[3];
+            const n3 = pixel * 3;
+            texel_normals[n3] = job_normal[p3];
+            texel_normals[n3 + 1] = job_normal[p3 + 1];
+            texel_normals[n3 + 2] = job_normal[p3 + 2];
+            if (texel_world_pos !== null) {
+                texel_world_pos[n3] = job_position[p3];
+                texel_world_pos[n3 + 1] = job_position[p3 + 1];
+                texel_world_pos[n3 + 2] = job_position[p3 + 2];
+            }
+            coverage[pixel] = 1;
+        }
+    }
+
+    /**
+     * Luminance of a committed atlas texel.
+     * @param {number} pixel
+     * @returns {number}
+     */
+    function texel_luminance(pixel) {
+        const t = pixel * 4;
+        return rgb_to_luminance(atlas.data[t], atlas.data[t + 1], atlas.data[t + 2]);
+    }
+
+    /**
+     * Whether a fine texel sits inside a "smooth" cell: its four surrounding
+     * coarse-grid texels are all committed and agree within the threshold.
+     * @param {number} j job index
+     * @returns {boolean}
+     */
+    function smooth_cell(j) {
+        const x = job_x[j];
+        const y = job_y[j];
+        const gx0 = Math.floor(x / adaptive_step) * adaptive_step;
+        const gy0 = Math.floor(y / adaptive_step) * adaptive_step;
+        const gx1 = gx0 + adaptive_step;
+        const gy1 = gy0 + adaptive_step;
+        if (gx1 >= resolution || gy1 >= resolution) {
+            return false;
+        }
+
+        const p00 = gy0 * resolution + gx0;
+        const p10 = gy0 * resolution + gx1;
+        const p01 = gy1 * resolution + gx0;
+        const p11 = gy1 * resolution + gx1;
+        if (!coverage[p00] || !coverage[p10] || !coverage[p01] || !coverage[p11]) {
+            return false;
+        }
+
+        const l00 = texel_luminance(p00);
+        const l10 = texel_luminance(p10);
+        const l01 = texel_luminance(p01);
+        const l11 = texel_luminance(p11);
+        const max_l = Math.max(l00, l10, l01, l11);
+        const min_l = Math.min(l00, l10, l01, l11);
+        return max_l - min_l <= interpolation_threshold * (max_l + 1e-6);
+    }
+
+    /**
+     * Fill a fine texel by bilinear interpolation of its four coarse-grid corners
+     * (used only when `min_sample_fraction === 0`). Assumes {@link smooth_cell}.
+     * @param {number} j job index
+     */
+    function interpolate(j) {
+        const x = job_x[j];
+        const y = job_y[j];
+        const gx0 = Math.floor(x / adaptive_step) * adaptive_step;
+        const gy0 = Math.floor(y / adaptive_step) * adaptive_step;
+        const gx1 = gx0 + adaptive_step;
+        const gy1 = gy0 + adaptive_step;
+
+        const p00 = gy0 * resolution + gx0;
+        const p10 = gy0 * resolution + gx1;
+        const p01 = gy1 * resolution + gx0;
+        const p11 = gy1 * resolution + gx1;
+
+        const fx = (x - gx0) / adaptive_step;
+        const fy = (y - gy0) / adaptive_step;
+        const pixel = y * resolution + x;
+        const t = pixel * 4;
+        for (let c = 0; c < 3; c++) {
+            const a = atlas.data[p00 * 4 + c] * (1 - fx) + atlas.data[p10 * 4 + c] * fx;
+            const b = atlas.data[p01 * 4 + c] * (1 - fx) + atlas.data[p11 * 4 + c] * fx;
+            atlas.data[t + c] = a * (1 - fy) + b * fy;
+        }
+        atlas.data[t + 3] = 1;
+        variance[pixel] = 0;
+        const j3 = j * 3;
+        const n3 = pixel * 3;
+        texel_normals[n3] = job_normal[j3];
+        texel_normals[n3 + 1] = job_normal[j3 + 1];
+        texel_normals[n3 + 2] = job_normal[j3 + 2];
+        if (texel_world_pos !== null) {
+            texel_world_pos[n3] = job_position[j3];
+            texel_world_pos[n3 + 1] = job_position[j3 + 1];
+            texel_world_pos[n3 + 2] = job_position[j3 + 2];
+        }
+        coverage[pixel] = 1;
+    }
+
+    /**
+     * Bake one fine texel: a reduced real estimate in smooth cells (or a pure lerp
+     * when `min_sample_fraction === 0`), full sampling on edges/discontinuities.
+     * @param {number} j job index
+     */
+    function bake_fine(j) {
+        if (smooth_cell(j)) {
+            if (reduced_samples > 0) {
+                bake_texel(j, gather_cfg_reduced);
+            } else {
+                interpolate(j);
+            }
+        } else {
+            bake_texel(j, gather_cfg_full);
+        }
+    }
+
+    function finish() {
+        // the committed (baked) set, before dilation grows it into the gutter
+        if (debug) {
+            baked_coverage = coverage.slice();
+        }
+
+        if (denoise) {
+            const filtered = new Float32Array(atlas.data.length);
+            lightmap_denoise(filtered, atlas.data, variance, texel_normals, coverage, resolution, resolution, 4);
+            atlas.data.set(filtered);
+        }
+        // grow lighting into the gutter / holes so bilinear sampling at seams and
+        // discarded (low-confidence) texels does not read black
+        lightmap_dilate(atlas.data, coverage, resolution, resolution, 4, padding + 2);
+        // blend the two atlas-space sides of each smooth UV seam so they match
+        // (normal-aware: hard creases like a cube edge are left alone)
+        if (seam_fix_iterations > 0 && chart_groups.length > 0) {
+            lightmap_seam_fix(atlas.data, texel_normals, coverage, resolution, resolution, 4, chart_groups, {
+                iterations: seam_fix_iterations,
+            });
+        }
+        texture.needsUpdate = true;
+    }
+
+    function cycle() {
+        if (phase === PHASE_COARSE) {
+            if (coarse_cursor >= coarse_indices.length) {
+                phase = PHASE_FINE;
+            } else {
+                const end = Math.min(coarse_cursor + texel_batch, coarse_indices.length);
+                for (; coarse_cursor < end; coarse_cursor++) {
+                    bake_texel(coarse_indices[coarse_cursor], gather_cfg_full);
+                }
+                texture.needsUpdate = true;
+                return TaskSignal.Continue;
+            }
+        }
+
+        if (fine_cursor >= fine_indices.length) {
+            finish();
+            return TaskSignal.EndSuccess;
+        }
+
+        const end = Math.min(fine_cursor + texel_batch, fine_indices.length);
+        for (; fine_cursor < end; fine_cursor++) {
+            bake_fine(fine_indices[fine_cursor]);
+        }
+        texture.needsUpdate = true;
+
+        if (fine_cursor >= fine_indices.length) {
+            finish();
+            return TaskSignal.EndSuccess;
+        }
+
+        return TaskSignal.Continue;
+    }
+
+    const task = new Task({
+        name: `bake lightmap ${resolution}x${resolution}`,
+        initializer: prepare,
+        cycleFunction: cycle,
+        computeProgress() {
+            const total = coarse_indices.length + fine_indices.length;
+            return total === 0 ? 0 : (coarse_cursor + fine_cursor) / total;
+        },
+        estimatedDuration: 60,
+    });
+
+    const group = new TaskGroup([task], 'lightmap bake');
+
+    // expose the baked artifacts for inspection / debugging
+    group.lightmap = {
+        texture,
+        sampler: atlas,
+        scene,
+        coverage,
+        variance,
+        normals: texel_normals,
+        world_pos: texel_world_pos,
+        get baked_coverage() {
+            return baked_coverage;
+        }
+    };
+
+    return group;
+}