@woosh/meep-engine 3.51.0 → 3.53.0

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,80 @@
+/**
+ * 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 {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 * 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":"AAuBA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,sDAJW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,GACf,oBAAoB,CAuchC;;;;;;;;WA1da,MAAM;;;;eACN,YAAY;;;;aACZ,YAAY;;;;QACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;iBACZ,YAAY;;;;kBACZ,YAAY;;;;YACZ,WAAW;;;;aACX,YAAY;;kCA7BQ,gCAAgC"}

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

@@ -0,0 +1,502 @@
+import { GOLDEN_RATIO } from "../../../core/math/GOLDEN_RATIO.js";
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { t64_look_rotation } from "../../../engine/ecs/transform/t64_look_rotation.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+import { PhyllotaxisMode } from "../config/PhyllotaxisMode.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { spine_frame_double_reflection } from "../skeleton/spine_frame_double_reflection.js";
+import { tree_mesh_compute_branch_rings } from "./tree_mesh_build_bark.js";
+
+const GOLDEN_CONJUGATE = 1.0 / GOLDEN_RATIO; // ~0.6180339887498949
+const GOLDEN_ANGLE = PI2 / (GOLDEN_RATIO * GOLDEN_RATIO);
+
+const SCRATCH_POS = new Float32Array(3);
+const SCRATCH_TAN = new Float32Array(3);
+const SCRATCH_P0 = new Float32Array(3);
+const SCRATCH_T0 = new Float32Array(3);
+const SCRATCH_R0 = new Float32Array(3);
+const SCRATCH_RMF = new Float64Array(6);
+
+/**
+ * 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 {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, config = new TreeSpeciesConfig()) {
+    const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+    const fol = species.foliage;
+    if (!fol.enabled || skeleton.branch_count === 0) {
+        return {
+            count: 0,
+            transforms: [],
+            positions: new Float32Array(0),
+            forward: new Float32Array(0),
+            up: new Float32Array(0),
+            right: new Float32Array(0),
+            scales: new Float32Array(0),
+            ranks: new Float32Array(0),
+            phases: new Float32Array(0),
+            branch_sway: new Float32Array(0),
+            color_jitter: new Float32Array(0),
+            joints: new Uint16Array(0),
+            weights: new Float32Array(0),
+            joints4: new Uint16Array(0),
+            weights4: new Float32Array(0),
+            attr_ranks: Attribute.from(new Float32Array(0), 1, "foliage_ranks"),
+            attr_phases: Attribute.from(new Float32Array(0), 1, "foliage_phases"),
+            attr_branch_sway: Attribute.from(new Float32Array(0), 1, "foliage_branch_sway"),
+            attr_color_jitter: Attribute.from(new Float32Array(0), 1, "foliage_color_jitter"),
+            attr_joints: Attribute.from(new Uint16Array(0), 2, "foliage_joints"),
+            attr_weights: Attribute.from(new Float32Array(0), 2, "foliage_weights")
+        };
+    }
+
+    const rng = seededRandom((species.seed ^ 0x5A3C9E17) | 0);
+    const max_existing_level = Math.max(0, species.levels.length - 1);
+    const min_level = Math.min(fol.attach_min_level, max_existing_level);
+    const branch_rings = tree_mesh_compute_branch_rings(skeleton, species, species.lods?.[0]);
+
+    const cx = skeleton.crown_center[0];
+    const cy = skeleton.crown_center[1];
+    const cz = skeleton.crown_center[2];
+    const ry = Math.max(0.5, skeleton.crown_radii[1]);
+
+    // First collect eligible branch edge chains via `skeleton.graph`
+    const eligible_branches = [];
+    for (let b = 0; b < skeleton.branch_count; b++) {
+        const level = skeleton.branch_level[b];
+        if (level < min_level) continue;
+
+        const nodes = [];
+        const edges = [];
+        skeleton.collect_branch_chain(b, nodes, edges);
+        if (edges.length === 0) continue;
+
+        const t_norms = new Array(nodes.length);
+        for (let i = 0; i < nodes.length; i++) {
+            t_norms[i] = skeleton.node_t_norm(nodes[i]);
+        }
+
+        eligible_branches.push({ branch_id: b, level, nodes, edges, t_norms });
+    }
+
+    const lateral_count = Math.max(0, fol.cards_per_branch | 0);
+    const rosette_count = Math.max(0, fol.terminal_rosette_count | 0);
+    const per_branch = lateral_count + rosette_count;
+    const total_count = eligible_branches.length * per_branch;
+
+    /** @type {Transform64[]} */
+    const transforms = new Array(total_count);
+    const positions = new Float32Array(total_count * 3);
+    const forward = new Float32Array(total_count * 3);
+    const up = new Float32Array(total_count * 3);
+    const right = new Float32Array(total_count * 3);
+    const scales = new Float32Array(total_count);
+    const ranks = new Float32Array(total_count);
+    const phases = new Float32Array(total_count);
+    const branch_sway = new Float32Array(total_count);
+    const color_jitter = new Float32Array(total_count);
+    const joints = new Uint16Array(total_count * 2);
+    const weights = new Float32Array(total_count * 2);
+    const joints4 = new Uint16Array(total_count * 4);
+    const weights4 = new Float32Array(total_count * 4);
+
+    let cursor = 0;
+    const bare = clamp(fol.bare_ratio, 0.0, 0.92);
+
+    for (let eb = 0; eb < eligible_branches.length; eb++) {
+        const item = eligible_branches[eb];
+        const level = item.level;
+        const nodes = item.nodes;
+        const edges = item.edges;
+        const t_norms = item.t_norms;
+        const b_rings = branch_rings.get(item.branch_id);
+        const t_min = Math.max(bare, t_norms[0]);
+        const t_max = t_norms[t_norms.length - 1];
+        const base_phi = rng() * PI2;
+        const b_phase = skeleton.branch_phase_hash[item.branch_id];
+
+        for (let k = 0; k < per_branch; k++) {
+            const is_rosette = k >= lateral_count;
+            let t_attach = 1.0;
+
+            if (!is_rosette && lateral_count > 0) {
+                let u_k = (k + 0.5) / lateral_count;
+                if (fol.phyllotaxis_mode === PhyllotaxisMode.Opposite
+                    || fol.phyllotaxis_mode === PhyllotaxisMode.OppositeDecussate) {
+                    const pair_idx = k >> 1;
+                    const pair_total = Math.max(1, Math.ceil(lateral_count / 2));
+                    u_k = (pair_idx + 0.5) / pair_total;
+                } else if (fol.phyllotaxis_mode === PhyllotaxisMode.Whorled) {
+                    const w_size = Math.max(1, fol.whorl_count | 0);
+                    const w_idx = Math.floor(k / w_size);
+                    const w_total = Math.max(1, Math.ceil(lateral_count / w_size));
+                    u_k = (w_idx + 0.5) / w_total;
+                }
+                t_attach = clamp(lerp(t_min, t_max * 0.92, u_k), t_min, t_max * 0.95);
+            } else {
+                const ros_idx = k - lateral_count;
+                const u_ros = (ros_idx + 0.5) / Math.max(1, rosette_count);
+                t_attach = clamp(lerp(Math.max(t_min, t_max * 0.88), t_max * 0.96, u_ros), t_min, t_max * 0.96);
+            }
+
+            // Locate segment containing t_attach
+            let seg_idx = edges.length - 1;
+            for (let s = 0; s < edges.length; s++) {
+                if (t_attach >= t_norms[s] && t_attach <= t_norms[s + 1]) {
+                    seg_idx = s;
+                    break;
+                }
+            }
+
+            const edge_id = edges[seg_idx];
+            const v0 = nodes[seg_idx];
+            const v1 = nodes[seg_idx + 1];
+            const t0 = t_norms[seg_idx];
+            const t1 = t_norms[seg_idx + 1];
+            const local_u = clamp((t_attach - t0) / Math.max(1e-5, t1 - t0), 0.05, 0.95);
+
+            skeleton.evaluate_segment_position(SCRATCH_POS, 0, edge_id, local_u);
+            skeleton.evaluate_segment_tangent(SCRATCH_TAN, 0, edge_id, local_u);
+            skeleton.node_read_position(SCRATCH_P0, 0, v0);
+            skeleton.node_read_tangent(SCRATCH_T0, 0, v0);
+            skeleton.node_read_frame_r(SCRATCH_R0, 0, v0);
+
+            spine_frame_double_reflection(
+                SCRATCH_RMF, 0,
+                SCRATCH_P0[0], SCRATCH_P0[1], SCRATCH_P0[2],
+                SCRATCH_T0[0], SCRATCH_T0[1], SCRATCH_T0[2],
+                SCRATCH_R0[0], SCRATCH_R0[1], SCRATCH_R0[2],
+                SCRATCH_POS[0], SCRATCH_POS[1], SCRATCH_POS[2],
+                SCRATCH_TAN[0], SCRATCH_TAN[1], SCRATCH_TAN[2]
+            );
+            const rx = SCRATCH_RMF[0], ry_f = SCRATCH_RMF[1], rz = SCRATCH_RMF[2];
+            const sx = SCRATCH_RMF[3], sy_f = SCRATCH_RMF[4], sz = SCRATCH_RMF[5];
+
+            // Phyllotactic angle phi
+            let phi = base_phi;
+            if (is_rosette) {
+                const r_idx = k - lateral_count;
+                phi += (r_idx * PI2) / Math.max(1, rosette_count);
+            } else {
+                switch (fol.phyllotaxis_mode) {
+                    case PhyllotaxisMode.AlternateDistichous:
+                        phi += k * Math.PI;
+                        break;
+                    case PhyllotaxisMode.Tristichous:
+                        phi += k * (PI2 / 3.0);
+                        break;
+                    case PhyllotaxisMode.Opposite:
+                        phi += (k & 1) * Math.PI;
+                        break;
+                    case PhyllotaxisMode.OppositeDecussate:
+                        phi += (k & 1) * Math.PI + (k >> 1) * (Math.PI * 0.5);
+                        break;
+                    case PhyllotaxisMode.Whorled: {
+                        const w_size = Math.max(1, fol.whorl_count | 0);
+                        const w_idx = Math.floor(k / w_size);
+                        const sub_idx = k % w_size;
+                        phi += (sub_idx * PI2) / w_size + (w_idx * Math.PI) / w_size;
+                        break;
+                    }
+                    case PhyllotaxisMode.SpiralGolden:
+                    default:
+                        phi += k * GOLDEN_ANGLE;
+                        break;
+                }
+            }
+            phi += (rng() * 2.0 - 1.0) * fol.angular_jitter;
+
+            const cos_p = Math.cos(phi);
+            const sin_p = Math.sin(phi);
+            const drx = cos_p * rx + sin_p * ry_f * 0 + sin_p * sx;
+            const dry = cos_p * ry_f + sin_p * sy_f;
+            const drz = cos_p * rz + sin_p * sz;
+
+            // Anchor card stem origin on the actual meshed bark frustum chord [ra, rb]
+            // and interpolate the carrier frustum's exact 4-slot skinning weights
+            let px = SCRATCH_POS[0];
+            let py = SCRATCH_POS[1];
+            let pz = SCRATCH_POS[2];
+            let seg_tx = SCRATCH_TAN[0];
+            let seg_ty = SCRATCH_TAN[1];
+            let seg_tz = SCRATCH_TAN[2];
+
+            const c4 = cursor * 4;
+            const c2 = cursor * 2;
+
+            if (b_rings && b_rings.length >= 2) {
+                const ring_idx = Math.min(seg_idx, b_rings.length - 2);
+                const ra = b_rings[ring_idx];
+                const rb = b_rings[ring_idx + 1];
+                const xi = clamp((t_attach - ra.t_norm) / Math.max(1e-5, rb.t_norm - ra.t_norm), 0.05, 0.95);
+
+                px = lerp(ra.cx, rb.cx, xi);
+                py = lerp(ra.cy, rb.cy, xi);
+                pz = lerp(ra.cz, rb.cz, xi);
+
+                const dx_seg = rb.cx - ra.cx;
+                const dy_seg = rb.cy - ra.cy;
+                const dz_seg = rb.cz - ra.cz;
+                const seg_len = Math.hypot(dx_seg, dy_seg, dz_seg);
+                if (seg_len > 1e-6) {
+                    seg_tx = dx_seg / seg_len;
+                    seg_ty = dy_seg / seg_len;
+                    seg_tz = dz_seg / seg_len;
+                }
+
+                // Merge 4-slot skinning weights from ra (weight 1 - xi) and rb (weight xi)
+                const merged_j = [-1, -1, -1, -1, -1, -1, -1, -1];
+                const merged_w = [0, 0, 0, 0, 0, 0, 0, 0];
+                let m_count = 0;
+
+                const accumulate_joint = (j_id, w_val) => {
+                    if (w_val <= 1e-7) return;
+                    for (let m = 0; m < m_count; m++) {
+                        if (merged_j[m] === j_id) {
+                            merged_w[m] += w_val;
+                            return;
+                        }
+                    }
+                    merged_j[m_count] = j_id;
+                    merged_w[m_count] = w_val;
+                    m_count++;
+                };
+
+                const w_a = 1.0 - xi;
+                const w_b = xi;
+                accumulate_joint(ra.j0, ra.w0 * w_a);
+                accumulate_joint(ra.j1, ra.w1 * w_a);
+                accumulate_joint(ra.j2, ra.w2 * w_a);
+                accumulate_joint(ra.j3, ra.w3 * w_a);
+                accumulate_joint(rb.j0, rb.w0 * w_b);
+                accumulate_joint(rb.j1, rb.w1 * w_b);
+                accumulate_joint(rb.j2, rb.w2 * w_b);
+                accumulate_joint(rb.j3, rb.w3 * w_b);
+
+                // Sort descending by weight and normalize top 4
+                for (let a = 0; a < m_count - 1; a++) {
+                    for (let b_sort = a + 1; b_sort < m_count; b_sort++) {
+                        if (merged_w[b_sort] > merged_w[a]) {
+                            const tw = merged_w[a];
+                            merged_w[a] = merged_w[b_sort];
+                            merged_w[b_sort] = tw;
+                            const tj = merged_j[a];
+                            merged_j[a] = merged_j[b_sort];
+                            merged_j[b_sort] = tj;
+                        }
+                    }
+                }
+
+                const top_k = Math.min(4, m_count);
+                let w4_sum = 0.0;
+                for (let s = 0; s < top_k; s++) w4_sum += merged_w[s];
+                const inv_w4 = w4_sum > 1e-7 ? 1.0 / w4_sum : 1.0;
+
+                for (let s = 0; s < 4; s++) {
+                    if (s < top_k) {
+                        joints4[c4 + s] = merged_j[s];
+                        weights4[c4 + s] = merged_w[s] * inv_w4;
+                    } else {
+                        joints4[c4 + s] = 0;
+                        weights4[c4 + s] = 0.0;
+                    }
+                }
+
+                // Populate 2-slot legacy joints/weights normalized to sum to 1.0
+                const j_prim = top_k > 0 ? merged_j[0] : 0;
+                const j_par = top_k > 1 ? merged_j[1] : j_prim;
+                const w0_raw = top_k > 0 ? merged_w[0] : 1.0;
+                const w1_raw = top_k > 1 ? merged_w[1] : 0.0;
+                const w2_sum = w0_raw + w1_raw;
+                joints[c2] = j_prim;
+                joints[c2 + 1] = j_par;
+                weights[c2] = w2_sum > 1e-7 ? w0_raw / w2_sum : 1.0;
+                weights[c2 + 1] = w2_sum > 1e-7 ? w1_raw / w2_sum : 0.0;
+            } else {
+                const j_prim = skeleton.node_read_joint(v1, 0);
+                const j_par = skeleton.node_read_joint(v1, 1);
+                const w_prim = j_prim === j_par ? 1.0 : clamp(0.35 + 0.65 * t_attach, 0.0, 1.0);
+                joints[c2] = j_prim;
+                joints[c2 + 1] = j_par;
+                weights[c2] = w_prim;
+                weights[c2 + 1] = 1.0 - w_prim;
+                joints4[c4] = j_prim;
+                joints4[c4 + 1] = j_par;
+                weights4[c4] = w_prim;
+                weights4[c4 + 1] = 1.0 - w_prim;
+            }
+
+            // Outward canopy normal n_canopy from crown center
+            let ncx = px - cx;
+            let ncy = (py - cy) + 0.35 * ry;
+            let ncz = pz - cz;
+            const nc_len = Math.sqrt(ncx * ncx + ncy * ncy + ncz * ncz);
+            if (nc_len > 1e-6) {
+                ncx /= nc_len;
+                ncy /= nc_len;
+                ncz /= nc_len;
+            } else {
+                ncx = 0.0;
+                ncy = 1.0;
+                ncz = 0.0;
+            }
+
+            // Initial card forward axis F along insertion angle from branch frustum tangent toward D_rad
+            const ins_angle = is_rosette ? fol.insertion_angle * 0.55 : fol.insertion_angle;
+            const cos_a = Math.cos(ins_angle);
+            const sin_a = Math.sin(ins_angle);
+            let fx = cos_a * seg_tx + sin_a * drx;
+            let fy = cos_a * seg_ty + sin_a * dry;
+            let fz = cos_a * seg_tz + sin_a * drz;
+
+            // Blend phototropism (outward/sky) and gravitropism (downward droop along -Y)
+            fx += fol.phototropism * 0.45 * ncx + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35;
+            fy += fol.phototropism * 0.25 * Math.max(0.0, ncy) - fol.gravitropism * 0.85;
+            fz += fol.phototropism * 0.45 * ncz + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35;
+
+            const f_len = Math.sqrt(fx * fx + fy * fy + fz * fz);
+            if (f_len > 1e-8) {
+                fx /= f_len;
+                fy /= f_len;
+                fz /= f_len;
+            } else {
+                fx = drx;
+                fy = dry;
+                fz = drz;
+            }
+
+            // Desired card upward normal U: blend of world +Y and outward canopy normal n_canopy
+            let ux = ncx * 0.45;
+            let uy = 0.65 + ncy * 0.35;
+            let uz = ncz * 0.45;
+            // Gram-Schmidt orthogonalize U against F
+            const dot_uf = ux * fx + uy * fy + uz * fz;
+            ux -= dot_uf * fx;
+            uy -= dot_uf * fy;
+            uz -= dot_uf * fz;
+            const u_len = Math.sqrt(ux * ux + uy * uy + uz * uz);
+            if (u_len > 1e-6) {
+                ux /= u_len;
+                uy /= u_len;
+                uz /= u_len;
+            } else {
+                // Fallback perpendicular to F
+                if (Math.abs(fy) < 0.9) {
+                    ux = -fz;
+                    uy = 0.0;
+                    uz = fx;
+                } else {
+                    ux = 1.0;
+                    uy = 0.0;
+                    uz = 0.0;
+                }
+                const d2 = ux * fx + uy * fy + uz * fz;
+                ux -= d2 * fx;
+                uy -= d2 * fy;
+                uz -= d2 * fz;
+                const l2 = Math.sqrt(ux * ux + uy * uy + uz * uz);
+                ux /= l2;
+                uy /= l2;
+                uz /= l2;
+            }
+
+            // Enforce outward/sky hemisphere alignment: dot(U, n_canopy + (0, 0.5, 0)) >= 0
+            if (ux * ncx + uy * (ncy + 0.5) + uz * ncz < 0.0) {
+                ux = -ux;
+                uy = -uy;
+                uz = -uz;
+            }
+
+            // W = F x U so that (W, F) card triangles have face normal W x F = +U!
+            const wx = fy * uz - fz * uy;
+            const wy = fz * ux - fx * uz;
+            const wz = fx * uy - fy * ux;
+
+            const c3 = cursor * 3;
+
+            positions[c3] = px;
+            positions[c3 + 1] = py;
+            positions[c3 + 2] = pz;
+
+            forward[c3] = fx;
+            forward[c3 + 1] = fy;
+            forward[c3 + 2] = fz;
+
+            up[c3] = ux;
+            up[c3 + 1] = uy;
+            up[c3 + 2] = uz;
+
+            right[c3] = wx;
+            right[c3 + 1] = wy;
+            right[c3 + 2] = wz;
+
+            const scale_var = 1.0 + (rng() * 2.0 - 1.0) * fol.size_variance;
+            const card_scale = Math.max(0.25, scale_var * (is_rosette ? 0.92 : 1.0));
+            scales[cursor] = card_scale;
+
+            const t64 = new Transform64();
+            t64.setTranslation(px, py, pz);
+            t64_look_rotation(t64, fx, fy, fz, ux, uy, uz);
+            t64.setScaleScalar(card_scale);
+            t64.updateMatrix();
+            transforms[cursor] = t64;
+
+            // Golden-ratio low-discrepancy rank in [0, 1)
+            ranks[cursor] = ((cursor * GOLDEN_CONJUGATE) + b_phase * 0.13) % 1.0;
+            phases[cursor] = (b_phase + k * 0.17) % 1.0;
+            branch_sway[cursor] = clamp((level + t_attach) * 0.28, 0.1, 1.0);
+            color_jitter[cursor] = rng() * 2.0 - 1.0;
+
+            cursor++;
+        }
+    }
+
+    return {
+        count: cursor,
+        transforms,
+        positions,
+        forward,
+        up,
+        right,
+        scales,
+        ranks,
+        phases,
+        branch_sway,
+        color_jitter,
+        joints,
+        weights,
+        joints4,
+        weights4,
+        attr_ranks: Attribute.from(ranks, 1, "foliage_ranks"),
+        attr_phases: Attribute.from(phases, 1, "foliage_phases"),
+        attr_branch_sway: Attribute.from(branch_sway, 1, "foliage_branch_sway"),
+        attr_color_jitter: Attribute.from(color_jitter, 1, "foliage_color_jitter"),
+        attr_joints: Attribute.from(joints, 2, "foliage_joints"),
+        attr_weights: Attribute.from(weights, 2, "foliage_weights")
+    };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Computes analytic volumetric crown ambient occlusion (combining normalized crown-shell depth
+ * and vertical sky exposure) into `StandardAttributes.Color` (`vec3<f32>`), and optionally
+ * applies hemisphere-safe normal puffing (`dot(n_puffed, n_orig) >= 0.55`) onto `StandardAttributes.Normal`.
+ *
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} geometry
+ * @param {ArrayLike<number>} crown_center `[cx, cy, cz]`
+ * @param {ArrayLike<number>} crown_radii `[rx, ry, rz]`
+ * @param {Object} [options]
+ * @param {number} [options.ao_core_darkening=0.35]
+ * @param {number} [options.normal_puffiness=0.0]
+ * @param {boolean} [options.preserve_existing_color=true]
+ */
+export function tree_mesh_apply_canopy_ao(geometry: import("../../../shade/renderer/geometry/Geometry.js").Geometry, crown_center: ArrayLike<number>, crown_radii: ArrayLike<number>, options?: {
+    ao_core_darkening?: number;
+    normal_puffiness?: number;
+    preserve_existing_color?: boolean;
+}): void;
+//# sourceMappingURL=tree_mesh_apply_canopy_ao.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree_mesh_apply_canopy_ao.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_mesh_apply_canopy_ao.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,oDARW,OAAO,8CAA8C,EAAE,QAAQ,gBAC/D,UAAU,MAAM,CAAC,eACjB,UAAU,MAAM,CAAC;IAEA,iBAAiB,GAAlC,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACY,uBAAuB,GAAzC,OAAO;SAoIjB"}