@woosh/meep-engine 2.163.2 → 2.163.3

package/src/engine/graphics/texture/reflection/convolve_equirectangular_reflection.js

@@ -0,0 +1,189 @@
+import { hammersley_sequence_2d } from "../../../../core/math/statistics/hammersley_sequence_2d.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
+import { v3_uniform_sample_cone } from "../../../../core/geom/vec3/v3_uniform_sample_cone.js";
+import { reflection_sample_weight } from "../../../../core/math/physics/brdf/reflection_sample_weight.js";
+import { cone_cosine_from_roughness } from "../../../../core/math/physics/brdf/cone_cosine_from_roughness.js";
+import { equirectangular_uv_to_direction } from "../../../../core/geom/3d/equirectangular/equirectangular_uv_to_direction.js";
+import { sampler2d_sample_equirectangular_direction } from "../sampler/sampler2d_sample_equirectangular_direction.js";
+import { Sampler2D } from "../sampler/Sampler2D.js";
+import {
+    equirectangular_reflection_lod_to_roughness,
+    roughness_from_relative_mip
+} from "./equirectangular_reflection_roughness.js";
+
+/**
+ * Below this we treat the surface as a perfect mirror.
+ * @type {number}
+ */
+const BSDF_ROUGHNESS_MINIMUM = 0.02;
+
+// scratch state (single-threaded, non-reentrant)
+const _basis = new Float32Array(9);
+const _rand = [0, 0];
+const _local = [0, 0, 0];
+const _radiance = [0, 0, 0, 0];
+
+/**
+ * Convolve an equirectangular radiance map for a single output direction,
+ * importance-sampling a cone around it with a spherical-gaussian GGX weight.
+ * This is the per-texel core of the prefilter (extracted for testing).
+ *
+ * @param {Sampler2D} input equirectangular radiance (the previous, sharper mip)
+ * @param {number} out_x output (reflection) direction, unit length, +Y up
+ * @param {number} out_y
+ * @param {number} out_z
+ * @param {number} roughness perceptual roughness for this convolution step
+ * @param {number} sample_count number of cone samples
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function convolve_equirectangular_reflection_direction(
+    input,
+    out_x, out_y, out_z,
+    roughness,
+    sample_count,
+    result,
+    result_offset = 0
+) {
+    const cone_cos = cone_cosine_from_roughness(roughness);
+
+    v3_orthonormal_matrix_from_normal(_basis, 0, out_x, out_y, out_z);
+
+    const t_x = _basis[0], t_y = _basis[1], t_z = _basis[2];
+    const b_x = _basis[3], b_y = _basis[4], b_z = _basis[5];
+    const n_x = _basis[6], n_y = _basis[7], n_z = _basis[8];
+
+    const itemSize = input.itemSize;
+
+    let weight_accum = 0;
+    let r0 = 0, r1 = 0, r2 = 0, r3 = 0;
+
+    for (let i = 0; i < sample_count; i++) {
+        hammersley_sequence_2d(_rand, 0, i, sample_count);
+
+        v3_uniform_sample_cone(_local, 0, _rand[0], _rand[1], cone_cos);
+
+        const lx = _local[0], ly = _local[1], lz = _local[2];
+
+        // world direction = lx * T + ly * B + lz * N
+        let in_x = lx * t_x + ly * b_x + lz * n_x;
+        let in_y = lx * t_y + ly * b_y + lz * n_y;
+        let in_z = lx * t_z + ly * b_z + lz * n_z;
+
+        const len = Math.sqrt(in_x * in_x + in_y * in_y + in_z * in_z);
+        if (len > 0) {
+            const inv_len = 1.0 / len;
+            in_x *= inv_len;
+            in_y *= inv_len;
+            in_z *= inv_len;
+        }
+
+        sampler2d_sample_equirectangular_direction(input, in_x, in_y, in_z, _radiance, 0);
+
+        const weight = reflection_sample_weight(out_x, out_y, out_z, in_x, in_y, in_z, roughness);
+
+        r0 += _radiance[0] * weight;
+        r1 += _radiance[1] * weight;
+        r2 += _radiance[2] * weight;
+        if (itemSize > 3) {
+            r3 += _radiance[3] * weight;
+        }
+
+        weight_accum += weight;
+    }
+
+    const inv = weight_accum === 0 ? 0 : 1.0 / weight_accum;
+
+    result[result_offset] = r0 * inv;
+    result[result_offset + 1] = r1 * inv;
+    result[result_offset + 2] = r2 * inv;
+    if (itemSize > 3) {
+        result[result_offset + 3] = r3 * inv;
+    }
+}
+
+/**
+ * Convolve a whole equirectangular level into `output`.
+ *
+ * @param {Sampler2D} input source radiance (previous mip)
+ * @param {Sampler2D} output destination (this mip)
+ * @param {number} roughness convolution roughness for this step
+ * @param {number} sample_count
+ */
+export function convolve_equirectangular_reflection_level(input, output, roughness, sample_count) {
+    const width = output.width;
+    const height = output.height;
+
+    const direction = [0, 0, 0];
+    const texel = new Float32Array(output.itemSize);
+
+    for (let j = 0; j < height; j++) {
+        const v = (j + 0.5) / height;
+
+        for (let i = 0; i < width; i++) {
+            const u = (i + 0.5) / width;
+
+            equirectangular_uv_to_direction(u, v, direction, 0);
+
+            convolve_equirectangular_reflection_direction(
+                input,
+                direction[0], direction[1], direction[2],
+                roughness,
+                sample_count,
+                texel,
+                0
+            );
+
+            output.write(i, j, texel);
+        }
+    }
+}
+
+/**
+ * Build a prefiltered reflection mip chain from a base equirectangular radiance
+ * map. Mip 0 is the (sharp) base; each subsequent mip is half resolution and
+ * convolved from the previous one, so roughness increases with mip level. This
+ * is the CPU replacement for THREE's PMREMGenerator, decoupled from three.js.
+ *
+ * @param {Sampler2D} base equirectangular RGBA radiance (mip 0)
+ * @param {object} [options]
+ * @param {number} [options.sample_count=32] cone samples per texel (the sky is low frequency)
+ * @param {number} [options.mip_levels] number of levels; defaults to the full chain
+ * @param {number} [options.max_roughness=0.7] roughness reached at the last mip
+ * @returns {Sampler2D[]} mip chain, index 0 = base
+ */
+export function build_equirectangular_reflection_mip_chain(base, options = {}) {
+    const {
+        sample_count = 32,
+        mip_levels,
+        max_roughness = 0.7
+    } = options;
+
+    const full_levels = Math.floor(Math.log2(Math.max(1, Math.min(base.width, base.height)))) + 1;
+    const levels = mip_levels !== undefined ? Math.min(mip_levels, full_levels) : full_levels;
+
+    const mips = [base];
+
+    for (let i = 1; i < levels; i++) {
+        const previous = mips[i - 1];
+
+        const width = Math.max(1, previous.width >> 1);
+        const height = Math.max(1, previous.height >> 1);
+
+        const level = Sampler2D.float32(base.itemSize, width, height);
+
+        const prev_roughness = equirectangular_reflection_lod_to_roughness(i - 1, levels, max_roughness);
+        const curr_roughness = equirectangular_reflection_lod_to_roughness(i, levels, max_roughness);
+
+        const step_roughness = Math.max(
+            BSDF_ROUGHNESS_MINIMUM,
+            roughness_from_relative_mip(prev_roughness, curr_roughness)
+        );
+
+        convolve_equirectangular_reflection_level(previous, level, step_roughness, sample_count);
+
+        mips.push(level);
+    }
+
+    return mips;
+}

package/src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Roughness schedule for a prefiltered reflection mip chain, ported from the
+ * EEVEE "sphere probe" convolution (generalised to an arbitrary mip count).
+ */
+/**
+ * Map a mip level to the perceptual roughness it represents.
+ *
+ * @param {number} lod mip level, 0 = sharpest
+ * @param {number} mip_levels total number of mip levels
+ * @param {number} [max_roughness=0.7] roughness reached at the last mip
+ * @returns {number}
+ */
+export function equirectangular_reflection_lod_to_roughness(lod: number, mip_levels: number, max_roughness?: number): number;
+/**
+ * Given that the previous mip is already convolved to `prev_mip_roughness`,
+ * derive the additional roughness to apply when convolving it into the current
+ * mip, so the result matches `curr_mip_roughness`. Uses the gaussian
+ * convolution composition rule G(a) x G(b) = G(a+b).
+ *
+ * @param {number} prev_mip_roughness
+ * @param {number} curr_mip_roughness
+ * @returns {number}
+ */
+export function roughness_from_relative_mip(prev_mip_roughness: number, curr_mip_roughness: number): number;
+//# sourceMappingURL=equirectangular_reflection_roughness.d.ts.map

package/src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equirectangular_reflection_roughness.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,iEALW,MAAM,cACN,MAAM,kBACN,MAAM,GACJ,MAAM,CAiBlB;AAED;;;;;;;;;GASG;AACH,gEAJW,MAAM,sBACN,MAAM,GACJ,MAAM,CAYlB"}

package/src/engine/graphics/texture/reflection/equirectangular_reflection_roughness.js

@@ -0,0 +1,51 @@
+/**
+ * Roughness schedule for a prefiltered reflection mip chain, ported from the
+ * EEVEE "sphere probe" convolution (generalised to an arbitrary mip count).
+ */
+
+/**
+ * Map a mip level to the perceptual roughness it represents.
+ *
+ * @param {number} lod mip level, 0 = sharpest
+ * @param {number} mip_levels total number of mip levels
+ * @param {number} [max_roughness=0.7] roughness reached at the last mip
+ * @returns {number}
+ */
+export function equirectangular_reflection_lod_to_roughness(lod, mip_levels, max_roughness = 0.7) {
+    const mip_ratio = mip_levels > 1 ? lod / (mip_levels - 1) : 0;
+
+    const a = mip_ratio;
+    const b = 0.6; // factor of ratio
+    const c = 0.4; // factor of ratio_sqrt
+
+    const b2 = b * b;
+    const c2 = c * c;
+    const c4 = c2 * c2;
+
+    // inverse of the roughness->lod mapping (a quadratic)
+    const ratio = (-Math.sqrt(4.0 * a * b * c2 + c4) + 2.0 * a * b + c2) / (2.0 * b2);
+
+    return ratio * max_roughness;
+}
+
+/**
+ * Given that the previous mip is already convolved to `prev_mip_roughness`,
+ * derive the additional roughness to apply when convolving it into the current
+ * mip, so the result matches `curr_mip_roughness`. Uses the gaussian
+ * convolution composition rule G(a) x G(b) = G(a+b).
+ *
+ * @param {number} prev_mip_roughness
+ * @param {number} curr_mip_roughness
+ * @returns {number}
+ */
+export function roughness_from_relative_mip(prev_mip_roughness, curr_mip_roughness) {
+    // the exponent should be 2 but 3 is a bit less blurry than expected in practice
+    const exponent = 3.0;
+
+    const m_prev = Math.pow(prev_mip_roughness, exponent);
+    const m_curr = Math.pow(curr_mip_roughness, exponent);
+
+    const m_target = Math.max(0.0, m_curr - m_prev);
+
+    return Math.pow(m_target, 1.0 / exponent);
+}

package/src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bilinearly sample a Sampler2D that holds an equirectangular image, by world
+ * direction (+Y up). The longitude axis (U) wraps and the latitude axis (V) is
+ * clamped, so there is no seam at longitude +/-pi (unlike Sampler2D's own
+ * bilinear sampling, which clamps both axes).
+ *
+ * @param {Sampler2D} sampler equirectangular source
+ * @param {number} dir_x
+ * @param {number} dir_y
+ * @param {number} dir_z
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function sampler2d_sample_equirectangular_direction(sampler: Sampler2D, dir_x: number, dir_y: number, dir_z: number, result: number[] | Float32Array, result_offset?: number): void;
+//# sourceMappingURL=sampler2d_sample_equirectangular_direction.d.ts.map

package/src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler2d_sample_equirectangular_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,sFANW,MAAM,SACN,MAAM,SACN,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,kBACrB,MAAM,QA+ChB"}

package/src/engine/graphics/texture/sampler/sampler2d_sample_equirectangular_direction.js

@@ -0,0 +1,63 @@
+import { equirectangular_direction_to_uv } from "../../../../core/geom/3d/equirectangular/equirectangular_direction_to_uv.js";
+
+const _uv = [0, 0];
+
+/**
+ * Bilinearly sample a Sampler2D that holds an equirectangular image, by world
+ * direction (+Y up). The longitude axis (U) wraps and the latitude axis (V) is
+ * clamped, so there is no seam at longitude +/-pi (unlike Sampler2D's own
+ * bilinear sampling, which clamps both axes).
+ *
+ * @param {Sampler2D} sampler equirectangular source
+ * @param {number} dir_x
+ * @param {number} dir_y
+ * @param {number} dir_z
+ * @param {number[]|Float32Array} result
+ * @param {number} [result_offset=0]
+ */
+export function sampler2d_sample_equirectangular_direction(sampler, dir_x, dir_y, dir_z, result, result_offset = 0) {
+    equirectangular_direction_to_uv(dir_x, dir_y, dir_z, _uv, 0);
+
+    const width = sampler.width;
+    const height = sampler.height;
+    const itemSize = sampler.itemSize;
+    const data = sampler.data;
+
+    // texel-space coordinates with texel centers at integer + 0.5
+    const fx = _uv[0] * width - 0.5;
+    const fy = _uv[1] * height - 0.5;
+
+    const x0i = Math.floor(fx);
+    const y0i = Math.floor(fy);
+
+    const tx = fx - x0i;
+    const ty = fy - y0i;
+
+    // longitude wraps, latitude clamps
+    const x0 = ((x0i % width) + width) % width;
+    const x1 = ((x0i + 1) % width + width) % width;
+    const y0 = y0i < 0 ? 0 : (y0i >= height ? height - 1 : y0i);
+    const y1i = y0i + 1;
+    const y1 = y1i < 0 ? 0 : (y1i >= height ? height - 1 : y1i);
+
+    const w00 = (1 - tx) * (1 - ty);
+    const w10 = tx * (1 - ty);
+    const w01 = (1 - tx) * ty;
+    const w11 = tx * ty;
+
+    const row0 = y0 * width;
+    const row1 = y1 * width;
+
+    const o00 = (row0 + x0) * itemSize;
+    const o10 = (row0 + x1) * itemSize;
+    const o01 = (row1 + x0) * itemSize;
+    const o11 = (row1 + x1) * itemSize;
+
+    for (let c = 0; c < itemSize; c++) {
+        result[result_offset + c] =
+            data[o00 + c] * w00 +
+            data[o10 + c] * w10 +
+            data[o01 + c] * w01 +
+            data[o11 + c] * w11;
+    }
+}

package/src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Carve holes into a (welded, connected) walkable topology wherever an agent of the given height
+ * would not fit under overhead geometry.
+ *
+ * Operates on the topology rather than a triangle soup so that all subdivision is conformal:
+ * {@link bt_edge_split} re-triangulates every face around a split edge, so neighbouring faces can
+ * never disagree on a shared edge (no cracks / T-junctions). Refinement is adaptive - only faces whose
+ * column actually contains an overhang are subdivided, and only down to `resolution` - so clear areas
+ * stay coarse and the subdivision hugs the obstacle contour instead of tessellating whole triangles.
+ *
+ * @param {object} params
+ * @param {BinaryTopology} params.mesh walkable topology to carve (modified in place)
+ * @param {BinaryTopology} params.source original source mesh (walkable + overhead geometry)
+ * @param {BVH} params.source_bvh BVH over `source` (leaves carry source face IDs)
+ * @param {number} params.agent_height
+ * @param {number} params.agent_radius
+ * @param {Vector3} params.up world up direction
+ */
+export function bt_mesh_carve_height_clearance({ mesh, source, source_bvh, agent_height, agent_radius, up, }: {
+    mesh: BinaryTopology;
+    source: BinaryTopology;
+    source_bvh: BVH;
+    agent_height: number;
+    agent_radius: number;
+    up: Vector3;
+}): void;
+//# sourceMappingURL=bt_mesh_carve_height_clearance.d.ts.map

package/src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_carve_height_clearance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/bt_mesh_carve_height_clearance.js"],"names":[],"mappings":"AA2LA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAPkC,IAAI;IACJ,MAAM;IACjB,UAAU;IACP,YAAY,EAA3B,MAAM;IACS,YAAY,EAA3B,MAAM;IACU,EAAE;SAuH5B"}