@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/mesh/branch_collar_project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch_collar_project.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/branch_collar_project.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,+CA5BW,MAAM,EAAE,GAAC,YAAY,kBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,iBACN,MAAM,eACN,MAAM,gBACN,MAAM,2BACN,MAAM,2BACN,MAAM,uBACN,MAAM,UACN,MAAM,UACN,MAAM,QAmKhB"}

package/src/generation/foliage/mesh/branch_collar_project.js

@@ -0,0 +1,205 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+
+/**
+ * Projects a child branch collar vertex `(ring_x, ring_y, ring_z)` into the parent branch's
+ * polygonal frustum in the orthonormal $(\mathbf{T}_p, \hat{\mathbf{u}}, \hat{\mathbf{w}})$ basis,
+ * guaranteeing that:
+ * 1. Every welded base vertex (`weld_factor === 1`) sits strictly inside the parent polygon's
+ *    inscribed apothem radius $R_{\text{apothem}}(z) = R_p(z) (1 - \text{flute\_amp}_p) \cos(\pi / M_p)$
+ *    at the vertex's axial height $z$ (preventing any daylight gap outside polygonal parent facets or tapering segments).
+ * 2. Every welded base vertex lands strictly on the emerging $+\hat{\mathbf{u}}$ hemisphere of the
+ *    parent axis ($q_u > 0$, preventing any backward protrusion through the opposite side of the parent branch).
+ * 3. Axial offset $z$ along $\mathbf{T}_p$ is bounded within $[z_{\min}, z_{\max}]$.
+ * 4. Outward normals blend smoothly ($C^1$) from the parent cylinder normal to the child tube normal.
+ *
+ * @param {number[]|Float32Array} out_pos
+ * @param {number} out_pos_offset
+ * @param {number[]|Float32Array} out_norm
+ * @param {number} out_norm_offset
+ * @param {number} ring_x flared child ring vertex X
+ * @param {number} ring_y flared child ring vertex Y
+ * @param {number} ring_z flared child ring vertex Z
+ * @param {number} tube_nx outward child tube normal X
+ * @param {number} tube_ny outward child tube normal Y
+ * @param {number} tube_nz outward child tube normal Z
+ * @param {number} child_tx unit child spine tangent X
+ * @param {number} child_ty unit child spine tangent Y
+ * @param {number} child_tz unit child spine tangent Z
+ * @param {number} parent_px parent attachment center X
+ * @param {number} parent_py parent attachment center Y
+ * @param {number} parent_pz parent attachment center Z
+ * @param {number} parent_tx unit parent spine tangent X
+ * @param {number} parent_ty unit parent spine tangent Y
+ * @param {number} parent_tz unit parent spine tangent Z
+ * @param {number} parent_radius parent branch radius at attachment
+ * @param {number} weld_factor in [0, 1] (1 at base ring i=0, decaying to 0 across collar rings)
+ * @param {number} normal_blend in [0, 1] blend weight toward parent normal
+ * @param {number} [parent_radial_segments=8] radial polygon vertex count M_p of parent branch
+ * @param {number} [parent_flute_amplitude=0.0] flute amplitude of parent branch
+ * @param {number} [parent_taper_slope=0.0] linear radius change dR_p/dz along parent_T
+ * @param {number} [z_min=-Infinity] minimum axial offset along parent_T
+ * @param {number} [z_max=Infinity] maximum axial offset along parent_T
+ */
+export function branch_collar_project(
+    out_pos,
+    out_pos_offset,
+    out_norm,
+    out_norm_offset,
+    ring_x, ring_y, ring_z,
+    tube_nx, tube_ny, tube_nz,
+    child_tx, child_ty, child_tz,
+    parent_px, parent_py, parent_pz,
+    parent_tx, parent_ty, parent_tz,
+    parent_radius,
+    weld_factor,
+    normal_blend,
+    parent_radial_segments = 8,
+    parent_flute_amplitude = 0.0,
+    parent_taper_slope = 0.0,
+    z_min = -Infinity,
+    z_max = Infinity
+) {
+    const w = clamp(weld_factor, 0.0, 1.0);
+    if (w <= 1e-5 || parent_radius <= 1e-5) {
+        out_pos[out_pos_offset] = ring_x;
+        out_pos[out_pos_offset + 1] = ring_y;
+        out_pos[out_pos_offset + 2] = ring_z;
+        out_norm[out_norm_offset] = tube_nx;
+        out_norm[out_norm_offset + 1] = tube_ny;
+        out_norm[out_norm_offset + 2] = tube_nz;
+        return;
+    }
+
+    // Polygon apothem factor of parent branch cross-section
+    const m_p = Math.max(3, parent_radial_segments | 0);
+    const flute_guard = Math.max(0.5, 1.0 - Math.max(0.0, parent_flute_amplitude));
+    const apothem_factor = Math.cos(Math.PI / m_p) * flute_guard;
+    const seat_ratio = 0.78 * apothem_factor;
+
+    // Vector from parent axis point to ring vertex
+    const dx = ring_x - parent_px;
+    const dy = ring_y - parent_py;
+    const dz = ring_z - parent_pz;
+
+    // Axial coordinate z_0 along parent_T and perpendicular radial offset q_0
+    const z_0 = dx * parent_tx + dy * parent_ty + dz * parent_tz;
+    const qx = dx - z_0 * parent_tx;
+    const qy = dy - z_0 * parent_ty;
+    const qz = dz - z_0 * parent_tz;
+
+    // Component of child_T perpendicular to parent_T
+    const dot_ct_pt = child_tx * parent_tx + child_ty * parent_ty + child_tz * parent_tz;
+    let ux = child_tx - dot_ct_pt * parent_tx;
+    let uy = child_ty - dot_ct_pt * parent_ty;
+    let uz = child_tz - dot_ct_pt * parent_tz;
+    const u_len = Math.sqrt(ux * ux + uy * uy + uz * uz);
+
+    let unx = 0.0, uny = 0.0, unz = 0.0;
+    if (u_len > 1e-5) {
+        unx = ux / u_len;
+        uny = uy / u_len;
+        unz = uz / u_len;
+    } else {
+        // Fallback orthogonal unit vector when child_T is collinear with parent_T
+        const q_len = Math.sqrt(qx * qx + qy * qy + qz * qz);
+        if (q_len > 1e-6) {
+            unx = qx / q_len;
+            uny = qy / q_len;
+            unz = qz / q_len;
+        } else {
+            if (Math.abs(parent_ty) < 0.9) {
+                unx = -parent_tz;
+                uny = 0.0;
+                unz = parent_tx;
+            } else {
+                unx = 1.0;
+                uny = 0.0;
+                unz = 0.0;
+            }
+            const d_p = unx * parent_tx + uny * parent_ty + unz * parent_tz;
+            unx -= d_p * parent_tx;
+            uny -= d_p * parent_ty;
+            unz -= d_p * parent_tz;
+            const nl = Math.sqrt(unx * unx + uny * uny + unz * unz) || 1.0;
+            unx /= nl;
+            uny /= nl;
+            unz /= nl;
+        }
+    }
+
+    // Lateral binormal w_hat = parent_T x u_hat
+    const wnx = parent_ty * unz - parent_tz * uny;
+    const wny = parent_tz * unx - parent_tx * unz;
+    const wnz = parent_tx * uny - parent_ty * unx;
+
+    const q_u = qx * unx + qy * uny + qz * unz;
+    const q_w = qx * wnx + qy * wny + qz * wnz;
+
+    const z_bound_min = Math.max(z_min, -0.95 * parent_radius);
+    const z_bound_max = Math.min(z_max, 0.95 * parent_radius);
+    const z_proj = z_bound_min <= z_bound_max
+        ? clamp(z_0, z_bound_min, z_bound_max)
+        : clamp(z_0, z_min, z_max);
+
+    // Evaluate tapered parent radius and inscribed seat radius at z_proj,
+    // ensuring conservative containment even when z_proj extends past the segment endpoint
+    const taper_delta = Math.min(0.0, z_proj * parent_taper_slope);
+    const r_parent_at_z = Math.max(0.10 * parent_radius, parent_radius + taper_delta);
+    const r_seat = r_parent_at_z * seat_ratio;
+
+    const q_w_proj = clamp(q_w, -0.78 * r_seat, 0.78 * r_seat);
+    const q_u_max = Math.sqrt(Math.max(0.0, r_seat * r_seat - q_w_proj * q_w_proj));
+    const s_u = clamp(q_u / Math.max(1e-5, r_parent_at_z), -1.0, 1.0);
+    const q_u_proj = q_u_max * (0.90 + 0.08 * s_u);
+
+    const proj_x = parent_px + z_proj * parent_tx + q_u_proj * unx + q_w_proj * wnx;
+    const proj_y = parent_py + z_proj * parent_ty + q_u_proj * uny + q_w_proj * wny;
+    const proj_z = parent_pz + z_proj * parent_tz + q_u_proj * unz + q_w_proj * wnz;
+
+    const final_x = lerp(ring_x, proj_x, w);
+    const final_y = lerp(ring_y, proj_y, w);
+    const final_z = lerp(ring_z, proj_z, w);
+
+    out_pos[out_pos_offset] = final_x;
+    out_pos[out_pos_offset + 1] = final_y;
+    out_pos[out_pos_offset + 2] = final_z;
+
+    // Compute parent cylinder outward normal at final position
+    const fdx = final_x - parent_px;
+    const fdy = final_y - parent_py;
+    const fdz = final_z - parent_pz;
+    const f_dot = fdx * parent_tx + fdy * parent_ty + fdz * parent_tz;
+    let pnx = fdx - f_dot * parent_tx;
+    let pny = fdy - f_dot * parent_ty;
+    let pnz = fdz - f_dot * parent_tz;
+    const pn_len = Math.sqrt(pnx * pnx + pny * pny + pnz * pnz);
+    if (pn_len > 1e-6) {
+        pnx /= pn_len;
+        pny /= pn_len;
+        pnz /= pn_len;
+    } else {
+        pnx = tube_nx;
+        pny = tube_ny;
+        pnz = tube_nz;
+    }
+
+    const nb = clamp(w * normal_blend, 0.0, 1.0);
+    let nx = lerp(tube_nx, pnx, nb);
+    let ny = lerp(tube_ny, pny, nb);
+    let nz = lerp(tube_nz, pnz, nb);
+    const n_len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (n_len > 1e-8) {
+        nx /= n_len;
+        ny /= n_len;
+        nz /= n_len;
+    } else {
+        nx = tube_nx;
+        ny = tube_ny;
+        nz = tube_nz;
+    }
+
+    out_norm[out_norm_offset] = nx;
+    out_norm[out_norm_offset + 1] = ny;
+    out_norm[out_norm_offset + 2] = nz;
+}

package/src/generation/foliage/mesh/branch_ring_triangulate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Triangulates the tubular strip between two UV-seam-duplicated cross-sectional rings
+ * (`ring0` with `m0 + 1` vertices and `ring1` with `m1 + 1` vertices, where `m0 >= 3` and `m1 >= 3`)
+ * using an exact integer cross-multiplied zipper (`(j0 + 1) * m1 <= (j1 + 1) * m0`).
+ *
+ * Guarantees:
+ * - Strictly `m0 + m1` triangles emitted.
+ * - Zero index-degenerate triangles (`i0 !== i1 && i1 !== i2 && i2 !== i0`), preventing
+ *   `MeshoptClusterizer` / `meshlet_batch_to_bvh` from stripping triangles.
+ * - Consistent outward CCW winding for right-handed `(T, R, S = T x R)` rings where `theta`
+ *   increases from `0` to `2*PI`.
+ *
+ * @param {Uint32Array|number[]} indices destination index buffer
+ * @param {number} index_cursor starting offset in `indices`
+ * @param {number} ring0_start starting vertex index of ring 0 (size `m0 + 1`)
+ * @param {number} m0 radial segment count of ring 0 (`>= 3`)
+ * @param {number} ring1_start starting vertex index of ring 1 (size `m1 + 1`)
+ * @param {number} m1 radial segment count of ring 1 (`>= 3`)
+ * @returns {number} updated `index_cursor` (`index_cursor + 3 * (m0 + m1)`)
+ */
+export function branch_ring_triangulate(indices: Uint32Array | number[], index_cursor: number, ring0_start: number, m0: number, ring1_start: number, m1: number): number;
+/**
+ * Triangulates a terminal conical apex fan connecting a ring of `m + 1` vertices (`m >= 3`)
+ * to `m` distinct apex vertices (`apex_start .. apex_start + m - 1`), emitting `m` outward-facing
+ * triangles with zero repeated indices.
+ *
+ * @param {Uint32Array|number[]} indices destination index buffer
+ * @param {number} index_cursor starting offset in `indices`
+ * @param {number} ring_start starting vertex index of the last non-zero ring (size `m + 1`)
+ * @param {number} m radial segment count of the ring (`>= 3`)
+ * @param {number} apex_start starting vertex index of the `m` apex vertices
+ * @returns {number} updated `index_cursor` (`index_cursor + 3 * m`)
+ */
+export function branch_apex_triangulate(indices: Uint32Array | number[], index_cursor: number, ring_start: number, m: number, apex_start: number): number;
+//# sourceMappingURL=branch_ring_triangulate.d.ts.map

package/src/generation/foliage/mesh/branch_ring_triangulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch_ring_triangulate.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/branch_ring_triangulate.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iDARW,WAAW,GAAC,MAAM,EAAE,gBACpB,MAAM,eACN,MAAM,MACN,MAAM,eACN,MAAM,MACN,MAAM,GACJ,MAAM,CA2BlB;AAED;;;;;;;;;;;GAWG;AACH,iDAPW,WAAW,GAAC,MAAM,EAAE,gBACpB,MAAM,cACN,MAAM,KACN,MAAM,cACN,MAAM,GACJ,MAAM,CAYlB"}

package/src/generation/foliage/mesh/branch_ring_triangulate.js

@@ -0,0 +1,72 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Triangulates the tubular strip between two UV-seam-duplicated cross-sectional rings
+ * (`ring0` with `m0 + 1` vertices and `ring1` with `m1 + 1` vertices, where `m0 >= 3` and `m1 >= 3`)
+ * using an exact integer cross-multiplied zipper (`(j0 + 1) * m1 <= (j1 + 1) * m0`).
+ *
+ * Guarantees:
+ * - Strictly `m0 + m1` triangles emitted.
+ * - Zero index-degenerate triangles (`i0 !== i1 && i1 !== i2 && i2 !== i0`), preventing
+ *   `MeshoptClusterizer` / `meshlet_batch_to_bvh` from stripping triangles.
+ * - Consistent outward CCW winding for right-handed `(T, R, S = T x R)` rings where `theta`
+ *   increases from `0` to `2*PI`.
+ *
+ * @param {Uint32Array|number[]} indices destination index buffer
+ * @param {number} index_cursor starting offset in `indices`
+ * @param {number} ring0_start starting vertex index of ring 0 (size `m0 + 1`)
+ * @param {number} m0 radial segment count of ring 0 (`>= 3`)
+ * @param {number} ring1_start starting vertex index of ring 1 (size `m1 + 1`)
+ * @param {number} m1 radial segment count of ring 1 (`>= 3`)
+ * @returns {number} updated `index_cursor` (`index_cursor + 3 * (m0 + m1)`)
+ */
+export function branch_ring_triangulate(indices, index_cursor, ring0_start, m0, ring1_start, m1) {
+    assert.greaterThanOrEqual(m0, 3, 'm0 must be >= 3');
+    assert.greaterThanOrEqual(m1, 3, 'm1 must be >= 3');
+
+    let j0 = 0;
+    let j1 = 0;
+    let cursor = index_cursor;
+
+    while (j0 < m0 || j1 < m1) {
+        if (j0 < m0 && (j1 === m1 || (j0 + 1) * m1 <= (j1 + 1) * m0)) {
+            // Advance along ring 0: (ring0[j0], ring0[j0 + 1], ring1[j1])
+            indices[cursor++] = ring0_start + j0;
+            indices[cursor++] = ring0_start + j0 + 1;
+            indices[cursor++] = ring1_start + j1;
+            j0++;
+        } else {
+            // Advance along ring 1: (ring0[j0], ring1[j1 + 1], ring1[j1])
+            indices[cursor++] = ring0_start + j0;
+            indices[cursor++] = ring1_start + j1 + 1;
+            indices[cursor++] = ring1_start + j1;
+            j1++;
+        }
+    }
+
+    return cursor;
+}
+
+/**
+ * Triangulates a terminal conical apex fan connecting a ring of `m + 1` vertices (`m >= 3`)
+ * to `m` distinct apex vertices (`apex_start .. apex_start + m - 1`), emitting `m` outward-facing
+ * triangles with zero repeated indices.
+ *
+ * @param {Uint32Array|number[]} indices destination index buffer
+ * @param {number} index_cursor starting offset in `indices`
+ * @param {number} ring_start starting vertex index of the last non-zero ring (size `m + 1`)
+ * @param {number} m radial segment count of the ring (`>= 3`)
+ * @param {number} apex_start starting vertex index of the `m` apex vertices
+ * @returns {number} updated `index_cursor` (`index_cursor + 3 * m`)
+ */
+export function branch_apex_triangulate(indices, index_cursor, ring_start, m, apex_start) {
+    assert.greaterThanOrEqual(m, 3, 'm must be >= 3');
+
+    let cursor = index_cursor;
+    for (let j = 0; j < m; j++) {
+        indices[cursor++] = ring_start + j;
+        indices[cursor++] = ring_start + j + 1;
+        indices[cursor++] = apex_start + j;
+    }
+    return cursor;
+}

package/src/generation/foliage/mesh/foliage_collect_attachments.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Flat typed-array structure holding all phyllotactic foliage attachment points and oriented card frames.
+ *
+ * @typedef {Object} FoliageAttachmentSet
+ * @property {number} count number of foliage attachments
+ * @property {Float32Array} positions `count * 3` attachment world/local positions
+ * @property {Float32Array} forward `count * 3` unit card length axis F
+ * @property {Float32Array} up `count * 3` unit card outward normal U
+ * @property {Float32Array} right `count * 3` unit card width axis W = F x U (so W x F = +U)
+ * @property {Float32Array} scales `count` per-card size multiplier
+ * @property {Float32Array} ranks `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+ * @property {Float32Array} phases `count` per-card wind phase in [0, 1)
+ * @property {Float32Array} branch_sway `count` parent branch sway weight in [0, 1]
+ * @property {Float32Array} color_jitter `count` per-card luminance/tint jitter in [-1, 1]
+ * @property {Float32Array} maturities `count` per-card ontogenetic leaf maturity in [0, 1] (0 = juvenile tip, 1 = mature base)
+ * @property {Float32Array} sun_exposure `count` per-card canopy solar irradiance exposure in [0, 1]
+ * @property {Uint8Array} variant_indices `count` assigned foliage atlas variant index in `[0, variant_count - 1]`
+ * @property {Uint16Array} joints `count * 2` `[j_primary, j_parent]`
+ * @property {Float32Array} weights `count * 2` `[w_primary, w_parent]`
+ */
+/**
+ * Generates phyllotactic foliage card attachment transforms along all eligible branches of a `TreeSkeleton`.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {TreeSpeciesConfig} [config]
+ * @returns {FoliageAttachmentSet}
+ */
+export function foliage_collect_attachments(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, config?: TreeSpeciesConfig): FoliageAttachmentSet;
+/**
+ * Flat typed-array structure holding all phyllotactic foliage attachment points and oriented card frames.
+ */
+export type FoliageAttachmentSet = {
+    /**
+     * number of foliage attachments
+     */
+    count: number;
+    /**
+     * `count * 3` attachment world/local positions
+     */
+    positions: Float32Array;
+    /**
+     * `count * 3` unit card length axis F
+     */
+    forward: Float32Array;
+    /**
+     * `count * 3` unit card outward normal U
+     */
+    up: Float32Array;
+    /**
+     * `count * 3` unit card width axis W = F x U (so W x F = +U)
+     */
+    right: Float32Array;
+    /**
+     * `count` per-card size multiplier
+     */
+    scales: Float32Array;
+    /**
+     * `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+     */
+    ranks: Float32Array;
+    /**
+     * `count` per-card wind phase in [0, 1)
+     */
+    phases: Float32Array;
+    /**
+     * `count` parent branch sway weight in [0, 1]
+     */
+    branch_sway: Float32Array;
+    /**
+     * `count` per-card luminance/tint jitter in [-1, 1]
+     */
+    color_jitter: Float32Array;
+    /**
+     * `count` per-card ontogenetic leaf maturity in [0, 1] (0 = juvenile tip, 1 = mature base)
+     */
+    maturities: Float32Array;
+    /**
+     * `count` per-card canopy solar irradiance exposure in [0, 1]
+     */
+    sun_exposure: Float32Array;
+    /**
+     * `count` assigned foliage atlas variant index in `[0, variant_count - 1]`
+     */
+    variant_indices: Uint8Array;
+    /**
+     * `count * 2` `[j_primary, j_parent]`
+     */
+    joints: Uint16Array;
+    /**
+     * `count * 2` `[w_primary, w_parent]`
+     */
+    weights: Float32Array;
+};
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+//# sourceMappingURL=foliage_collect_attachments.d.ts.map

package/src/generation/foliage/mesh/foliage_collect_attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foliage_collect_attachments.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/foliage_collect_attachments.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;GAMG;AACH,sDAJW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,GACf,oBAAoB,CAsgBhC;;;;;;;;WA5hBa,MAAM;;;;eACN,YAAY;;;;aACZ,YAAY;;;;QACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;iBACZ,YAAY;;;;kBACZ,YAAY;;;;gBACZ,YAAY;;;;kBACZ,YAAY;;;;qBACZ,UAAU;;;;YACV,WAAW;;;;aACX,YAAY;;kCAhCQ,gCAAgC"}