@woosh/meep-engine 3.55.0 → 3.57.0

package/src/generation/foliage/skeleton/tree_skeleton_assign_skin_joints.js

@@ -1,14 +1,39 @@
+import { tree_wind_bend_limit } from "../animation/tree_wind_bend_limit.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { TREE_WIND_REFERENCE_SPEED } from "../config/TreeWindConfig.js";
+import {
+    tree_skeleton_compute_joint_mechanics,
+    tree_skeleton_compute_segment_compliance,
+    tree_skeleton_compute_segment_mechanics
+} from "./tree_skeleton_compute_joint_mechanics.js";
+
 const SCRATCH_POS = new Float32Array(3);
 const SCRATCH_TAN = new Float32Array(3);
 const SCRATCH_PARAM = new Float32Array(3);
 
 /**
- * Selects up to `max_joints` structural skeleton nodes in strict topological pre-order
- * (`joint_parents[j] < j`) from `skeleton.graph` for GPU skeletal wind animation (`Skin`),
- * and writes `[primary_joint_index, parent_joint_index]` into `skeleton.attr_node_joint` for every node.
+ * Derives the wind joints of a tree for GPU skeletal wind animation (`Skin`) from how its wood bends, in strict
+ * topological pre-order (`joint_parents[j] < j`), and writes `[primary_joint_index, parent_joint_index]` into
+ * `skeleton.attr_node_joint` for every node, and each joint's pivot and turn in the reference wind into the skeleton
+ * (`TreeSkeleton.set_joints`).
+ *
+ * Joints go where the rig would otherwise hide visible sway. Every segment bends by its share of its branch's bend in a
+ * `TREE_WIND_REFERENCE_SPEED` wind (beam elements, `tree_skeleton_compute_segment_mechanics`), saturated as the rig
+ * shows it (`tree_wind_bend_limit`). Walking each branch from its base:
+ *
+ * - while the branch has no joint, its bending is lost: a bend `theta` moves what the segment carries by up to
+ *   `theta * reach`, so the branch gets a joint at the first node past which that sum is still over the tolerance;
+ * - a joint rotates its whole span about its own pivot, so a bend `theta` at a distance `x` along the span lands
+ *   `theta * x` off, and a new joint starts where that error would pass the tolerance.
+ *
+ * The tolerance is `species.wind.deflection_tolerance`, a distance in metres. So stiff or bare wood takes few joints,
+ * slender leafy wood many, and a tall tree, whose bends move more, more than a small one. Node 0, the trunk
+ * base, is always joint 0 and stays anchored. Branches of a `root` generator never get a joint, so surface roots stay
+ * bound to their parent's stationary base joint and do not lift out of the soil in wind. `species.wind.max_joints` is
+ * only a safety net: past it, the joints that would hide the least sway are dropped.
  *
  * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
- * @param {number} [max_joints=32]
+ * @param {TreeSpeciesConfig} species
  * @returns {{
  *   joint_count: number,
  *   joint_vertex_ids: Int32Array,
@@ -17,14 +42,14 @@ const SCRATCH_PARAM = new Float32Array(3);
  *   joint_tangents: Float32Array,
  *   joint_levels: Uint8Array,
  *   joint_phases: Float32Array,
- *   joint_t_norms: Float32Array,
- *   joint_radii: Float32Array,
- *   joint_lengths: Float32Array
- * }}
+ *   joint_compliance: Float32Array,
+ *   joint_natural_frequency: Float32Array
+ * }} `joint_compliance` (rad / (m/s)^2) and `joint_natural_frequency` (rad/s) are each joint's cantilever
+ * wind mechanics, see `tree_skeleton_compute_joint_mechanics`
  */
-export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32) {
+export function tree_skeleton_assign_skin_joints(skeleton, species) {
     const vertex_count = skeleton.node_count;
-    const budget = Math.max(1, max_joints | 0);
+    const budget = Math.max(1, species.wind.max_joints | 0);
 
     if (vertex_count === 0) {
         return {
@@ -35,95 +60,104 @@ export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32) {
             joint_tangents: new Float32Array([0, 1, 0]),
             joint_levels: new Uint8Array([0]),
             joint_phases: new Float32Array([0]),
-            joint_t_norms: new Float32Array([0]),
-            joint_radii: new Float32Array([0.1]),
-            joint_lengths: new Float32Array([1.0])
+            joint_compliance: new Float32Array([0]),
+            joint_natural_frequency: new Float32Array([0])
         };
     }
 
-    // Mark candidate nodes by branch-aware round-robin so the joint budget is distributed
-    // across the trunk (2-4 joints) AND all primary boughs around 360° of the crown,
-    // then iterate node IDs in ascending order to guarantee topological pre-order (parent < child).
-    const is_selected = new Uint8Array(vertex_count);
-    let selected_count = 0;
+    const tolerance = species.wind.deflection_tolerance;
+
+    const segments = tree_skeleton_compute_segment_mechanics(skeleton, species);
+    const segment_compliance = new Float64Array(skeleton.segment_count);
+    tree_skeleton_compute_segment_compliance(species, segments, segment_compliance);
+    const half_v2 = 0.5 * TREE_WIND_REFERENCE_SPEED * TREE_WIND_REFERENCE_SPEED;
 
-    // Always include node 0 (trunk root) as joint 0
+    // Sway each selected node's joint keeps from being hidden; node 0 is always joint 0
+    const is_selected = new Uint8Array(vertex_count);
+    const kept_sway = new Float64Array(vertex_count);
+    // bend of the span each selected node's joint turns
+    const span_bend = new Float64Array(vertex_count);
     is_selected[0] = 1;
-    selected_count = 1;
-
-    const branch_count = skeleton.branch_count;
-
-    // 1. Trunk / level-0 branches: pick up to 3 evenly spaced milestones (t ~ 0.35, 0.68, 1.0)
-    const max_trunk_joints = Math.min(budget, Math.max(2, Math.min(5, Math.floor(budget * 0.2))));
-    const trunk_targets = [0.38, 0.72, 1.0];
-    for (let m = 0; m < trunk_targets.length && selected_count < max_trunk_joints; m++) {
-        const target_t = trunk_targets[m];
-        for (let b = 0; b < branch_count && selected_count < max_trunk_joints; b++) {
-            if (skeleton.branch_level[b] !== 0) continue;
-            const nodes = [];
-            const edges = [];
-            skeleton.collect_branch_chain(b, nodes, edges);
-            let best_v = -1;
-            let best_dist = Infinity;
-            for (let i = 1; i < nodes.length; i++) {
-                const v = nodes[i];
-                if (is_selected[v]) continue;
-                const d = Math.abs(skeleton.node_t_norm(v) - target_t);
-                if (d < best_dist) {
-                    best_dist = d;
-                    best_v = v;
-                }
-            }
-            if (best_v >= 0 && best_dist <= 0.28) {
-                is_selected[best_v] = 1;
-                selected_count++;
-            }
+    kept_sway[0] = Infinity;
+    let selected_count = 1;
+
+    const nodes = [];
+    const edges = [];
+    let bend = new Float64Array(16);
+    let lost_beyond = new Float64Array(17);
+    for (let b = 0; b < skeleton.branch_count; b++) {
+        if (species.branches[skeleton.branch_generator[b]].root) continue;
+        skeleton.collect_branch_chain(b, nodes, edges);
+        const n = edges.length;
+        if (n === 0) continue;
+        if (bend.length < n) {
+            bend = new Float64Array(n * 2);
+            lost_beyond = new Float64Array(n * 2 + 1);
         }
-    }
 
-    // 2. Primary boughs (level === 1): first select root hinge nodes[0] so every bough pivots at its trunk collar,
-    // then select a mid-bough node (~0.55) on a second pass for multi-segment bough bending.
-    for (let pass = 0; pass < 2 && selected_count < budget; pass++) {
-        for (let b = 0; b < branch_count && selected_count < budget; b++) {
-            if (skeleton.branch_level[b] !== 1) continue;
-            const nodes = [];
-            const edges = [];
-            skeleton.collect_branch_chain(b, nodes, edges);
-            if (nodes.length === 0) continue;
-
-            if (pass === 0) {
-                const root_v = nodes[0];
-                if (!is_selected[root_v]) {
-                    is_selected[root_v] = 1;
+        // Each segment's bend as the rig shows it: the branch's total, saturated, shared out in proportion
+        let total = 0.0;
+        for (let i = 0; i < n; i++) {
+            bend[i] = half_v2 * segment_compliance[edges[i]];
+            total += bend[i];
+        }
+        const limit = tree_wind_bend_limit(species.wind.max_bend_angle, skeleton.branch_level[b]);
+        const shown = limit / (limit + total);
+        lost_beyond[n] = 0.0;
+        for (let i = n - 1; i >= 0; i--) {
+            bend[i] *= shown;
+            lost_beyond[i] = lost_beyond[i + 1] + bend[i] * segments.reach[edges[i]];
+        }
+
+        let jointed = false;
+        let pivot = 0.0;
+        let pivot_vertex = 0;
+        let error = 0.0;
+        let arc = 0.0;
+        for (let i = 0; i < n; i++) {
+            const v = nodes[i];
+            // a split fork starts on its parent's node, which is not this branch's to rotate
+            const placeable = v !== 0 && skeleton.node_branch_id(v) === b;
+            const len = skeleton.segment_length(edges[i]);
+            if (!jointed) {
+                if (placeable && lost_beyond[i] > tolerance) {
+                    is_selected[v] = 1;
+                    kept_sway[v] = lost_beyond[i];
                     selected_count++;
+                    jointed = true;
+                    pivot = arc;
+                    pivot_vertex = v;
                 }
-            } else if (nodes.length >= 3) {
-                const mid_idx = Math.max(1, Math.min(nodes.length - 1, Math.round((nodes.length - 1) * 0.55)));
-                const mid_v = nodes[mid_idx];
-                if (!is_selected[mid_v]) {
-                    is_selected[mid_v] = 1;
+            } else {
+                const lumped = bend[i] * (arc + 0.5 * len - pivot);
+                if (placeable && error + lumped > tolerance) {
+                    is_selected[v] = 1;
+                    kept_sway[v] = error + lumped;
                     selected_count++;
+                    pivot = arc;
+                    pivot_vertex = v;
+                    error = 0.0;
                 }
             }
+            if (jointed) {
+                error += bend[i] * (arc + 0.5 * len - pivot);
+                span_bend[pivot_vertex] += bend[i];
+            }
+            arc += len;
         }
     }
 
-    // 3. Secondary branches (level >= 2): select root hinge nodes[0] across remaining budget
-    for (let b = 0; b < branch_count && selected_count < budget; b++) {
-        if (skeleton.branch_level[b] < 2) continue;
-        const root_v = skeleton.branch_root_vertex[b];
-        if (root_v >= 0 && !is_selected[root_v]) {
-            is_selected[root_v] = 1;
-            selected_count++;
+    // Safety net: keep the joints that keep the most sway
+    if (selected_count > budget) {
+        const ranked = [];
+        for (let v = 0; v < vertex_count; v++) {
+            if (is_selected[v]) ranked.push(v);
         }
-    }
-
-    // 4. If budget still has room, fill any remaining nodes in topological order
-    for (let v = 1; v < vertex_count && selected_count < budget; v++) {
-        if (!is_selected[v]) {
-            is_selected[v] = 1;
-            selected_count++;
+        ranked.sort((a, b) => kept_sway[b] - kept_sway[a] || a - b);
+        for (let i = budget; i < ranked.length; i++) {
+            is_selected[ranked[i]] = 0;
         }
+        selected_count = budget;
     }
 
     const joint_count = selected_count;
@@ -133,9 +167,8 @@ export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32) {
     const joint_tangents = new Float32Array(joint_count * 3);
     const joint_levels = new Uint8Array(joint_count);
     const joint_phases = new Float32Array(joint_count);
-    const joint_t_norms = new Float32Array(joint_count);
-    const joint_radii = new Float32Array(joint_count);
-    const joint_lengths = new Float32Array(joint_count);
+    const joint_compliance = new Float32Array(joint_count);
+    const joint_natural_frequency = new Float32Array(joint_count);
 
     // Map each node to its active joint index (or closest selected ancestor joint index in `skeleton.graph`)
     const vertex_active_joint = new Int32Array(vertex_count);
@@ -163,22 +196,8 @@ export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32) {
             joint_tangents[j * 3 + 1] = SCRATCH_TAN[1];
             joint_tangents[j * 3 + 2] = SCRATCH_TAN[2];
 
-            const b_v = skeleton.node_branch_id(v);
             joint_levels[j] = skeleton.node_level(v);
-            joint_t_norms[j] = b_v > 0 ? Math.max(0.55, SCRATCH_PARAM[0]) : SCRATCH_PARAM[0];
             joint_phases[j] = SCRATCH_PARAM[2];
-            joint_radii[j] = Math.max(0.005, skeleton.node_read_radius(v));
-
-            if (b_v > 0 && b_v < skeleton.branch_count) {
-                joint_lengths[j] = Math.max(0.2, skeleton.branch_length[b_v]);
-            } else if (pj >= 0) {
-                const dx = SCRATCH_POS[0] - joint_positions[pj * 3];
-                const dy = SCRATCH_POS[1] - joint_positions[pj * 3 + 1];
-                const dz = SCRATCH_POS[2] - joint_positions[pj * 3 + 2];
-                joint_lengths[j] = Math.max(0.2, Math.hypot(dx, dy, dz));
-            } else {
-                joint_lengths[j] = 1.0;
-            }
 
             vertex_active_joint[v] = j;
             const p_joint = pj >= 0 ? pj : 0;
@@ -190,6 +209,23 @@ export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32) {
         }
     }
 
+    // a joint turns its span; a span whose joint the safety net dropped turns with the joint above it
+    const joint_rotation = new Float64Array(joint_count);
+    for (let v = 0; v < vertex_count; v++) {
+        joint_rotation[vertex_active_joint[v]] += span_bend[v];
+    }
+    skeleton.set_joints(joint_vertex_ids, joint_rotation);
+
+    tree_skeleton_compute_joint_mechanics(
+        skeleton,
+        species,
+        segments,
+        joint_vertex_ids,
+        vertex_active_joint,
+        joint_compliance,
+        joint_natural_frequency
+    );
+
     return {
         joint_count,
         joint_vertex_ids,
@@ -198,8 +234,7 @@ export function tree_skeleton_assign_skin_joints(skeleton, max_joints = 32) {
         joint_tangents,
         joint_levels,
         joint_phases,
-        joint_t_norms,
-        joint_radii,
-        joint_lengths
+        joint_compliance,
+        joint_natural_frequency
     };
 }

package/src/generation/foliage/skeleton/tree_skeleton_compute_joint_mechanics.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @typedef {Object} TreeSegmentMechanics
+ * @property {Float64Array} mid segment midpoints, `3` per segment
+ * @property {Float64Array} mass kg per segment (green wood + fresh leaves)
+ * @property {Float64Array} flex `integral dx / r^4` per segment (`0` in the soil)
+ * @property {Float64Array} moment drag moment carried by each segment per unit `0.5 rho v^2` (m^3)
+ * @property {Float64Array} mass_moment moment of the mass carried by each segment (kg m)
+ * @property {Float64Array} reach distance from each segment to the farthest point it carries, leaf cards included (m),
+ * so a bend of the segment by `theta` moves what it carries by up to `theta * reach`
+ */
+/**
+ * Euler-Bernoulli beam elements of a tree's skeleton: every segment is a tapered beam carrying its bark's
+ * frontal area and, on foliage carriers, its share of leaf cards, with the mass of green wood and fresh leaves.
+ *
+ * Each element's drag and mass load every segment upstream of it, the moment arm being the distance to that
+ * segment's loaded part, and the element itself, as a uniform load at arm `L / 6`. A lateral loads the parent segment it hangs from only below its attachment point.
+ * Structural surface roots (`BranchGeneratorConfig.root`) lie in the soil: they carry no wind load and do not bend.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @returns {TreeSegmentMechanics}
+ */
+export function tree_skeleton_compute_segment_mechanics(skeleton: import("./TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig): TreeSegmentMechanics;
+/**
+ * Wind compliance (rad / (m/s)^2) of every segment's own bending, `rho M_s flex_s / (E pi / 4)`: a joint's compliance
+ * is the sum over the segments of its span, and a segment bends by `0.5 * compliance * v^2` in a wind of speed `v`.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {TreeSegmentMechanics} segments
+ * @param {Float64Array} out per segment
+ */
+export function tree_skeleton_compute_segment_compliance(species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, segments: TreeSegmentMechanics, out: Float64Array): void;
+/**
+ * Wind mechanics of a tree's joints from its beam elements (`tree_skeleton_compute_segment_mechanics`).
+ *
+ * A joint rotates its span, the segments of its own branch that start at nodes bound to it (as the bark mesher
+ * skins them), from its pivot out to the next joints. Its quasi-static deflection is the curvature `M / (E I)`
+ * integrated over that span:
+ *
+ * - `out_compliance[j]` = `rho sum(M_s * flex_s) / (E pi / 4)`, rad / (m/s)^2, so that `chunk_foliage_wind_step`'s
+ *   deflection `0.5 * compliance * v^2` is the beam's under drag `0.5 rho C_d A v^2`. A branch's joints share out its
+ *   bend between them, however many there are.
+ * - `out_natural_frequency[j]` (rad/s) is the first-mode frequency of the joint's branch
+ *   (`tree_skeleton_compute_branch_frequency`). The joints are samples of that mode, not separate oscillators, so a
+ *   branch sways at its own frequency however many joints the rig cuts it into.
+ *
+ * So a joint deflects with the sail it carries and how slender its span is: a bare, short, thick stub carries
+ * almost nothing on a stiff span and barely moves, while a thin leafy twig whips. `E` is
+ * `species.wind.elastic_modulus`. A joint whose span holds no segment is rigid (compliance 0).
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {TreeSegmentMechanics} segments
+ * @param {Int32Array} joint_vertex_ids skeleton node of each joint
+ * @param {Int32Array} node_joint joint each skeleton node is bound to
+ * @param {Float32Array} out_compliance per joint, rad / (m/s)^2
+ * @param {Float32Array} out_natural_frequency per joint, rad/s
+ */
+export function tree_skeleton_compute_joint_mechanics(skeleton: import("./TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, segments: TreeSegmentMechanics, joint_vertex_ids: Int32Array, node_joint: Int32Array, out_compliance: Float32Array, out_natural_frequency: Float32Array): void;
+/**
+ * First-mode natural frequency (rad/s) of every branch, bent as one cantilever about its root: the
+ * single-degree-of-freedom estimate `sqrt(K / J)`, rotational stiffness `K = (E pi / 4) Q / D_m` of the branch under
+ * its own weight distribution (`Q = sum(m d)`, the moment about its root of everything it carries, its laterals
+ * included; `D_m = sum(M_m,s * flex_s)` over its own segments, its rotation per unit of that moment) over the moment of
+ * inertia `J = sum(m d^2)` of everything it carries. Weighting each segment's flexibility by the moment it carries
+ * keeps an unloaded hair-thin tip from passing for the stiffness of the whole branch. A branch with no mass or no
+ * flexibility gets 0.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {TreeSegmentMechanics} segments
+ * @param {Float64Array} out per branch
+ */
+export function tree_skeleton_compute_branch_frequency(skeleton: import("./TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, segments: TreeSegmentMechanics, out: Float64Array): void;
+/**
+ * Wind compliance (rad / (m/s)^2) of every branch bent as one cantilever about its root: how far it would sway
+ * with a joint at its base.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {TreeSegmentMechanics} segments
+ * @param {Float64Array} out per branch
+ */
+export function tree_skeleton_compute_branch_compliance(skeleton: import("./TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, segments: TreeSegmentMechanics, out: Float64Array): void;
+export type TreeSegmentMechanics = {
+    /**
+     * segment midpoints, `3` per segment
+     */
+    mid: Float64Array;
+    /**
+     * kg per segment (green wood + fresh leaves)
+     */
+    mass: Float64Array;
+    /**
+     * `integral dx / r^4` per segment (`0` in the soil)
+     */
+    flex: Float64Array;
+    /**
+     * drag moment carried by each segment per unit `0.5 rho v^2` (m^3)
+     */
+    moment: Float64Array;
+    /**
+     * moment of the mass carried by each segment (kg m)
+     */
+    mass_moment: Float64Array;
+    /**
+     * distance from each segment to the farthest point it carries, leaf cards included (m),
+     * so a bend of the segment by `theta` moves what it carries by up to `theta * reach`
+     */
+    reach: Float64Array;
+};
+//# sourceMappingURL=tree_skeleton_compute_joint_mechanics.d.ts.map

package/src/generation/foliage/skeleton/tree_skeleton_compute_joint_mechanics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_skeleton_compute_joint_mechanics.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_compute_joint_mechanics.js"],"names":[],"mappings":"AAsEA;;;;;;;;;GASG;AAEH;;;;;;;;;;;GAWG;AACH,kEAJW,OAAO,mBAAmB,EAAE,YAAY,WACxC,OAAO,gCAAgC,EAAE,iBAAiB,GACxD,oBAAoB,CAgJhC;AAED;;;;;;;GAOG;AACH,kEAJW,OAAO,gCAAgC,EAAE,iBAAiB,YAC1D,oBAAoB,OACpB,YAAY,QAQtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,gEARW,OAAO,mBAAmB,EAAE,YAAY,WACxC,OAAO,gCAAgC,EAAE,iBAAiB,YAC1D,oBAAoB,oBACpB,UAAU,cACV,UAAU,kBACV,YAAY,yBACZ,YAAY,QAgCtB;AAED;;;;;;;;;;;;;GAaG;AACH,iEALW,OAAO,mBAAmB,EAAE,YAAY,WACxC,OAAO,gCAAgC,EAAE,iBAAiB,YAC1D,oBAAoB,OACpB,YAAY,QA0CtB;AAED;;;;;;;;GAQG;AACH,kEALW,OAAO,mBAAmB,EAAE,YAAY,WACxC,OAAO,gCAAgC,EAAE,iBAAiB,YAC1D,oBAAoB,OACpB,YAAY,QAYtB;;;;;SA1Ta,YAAY;;;;UACZ,YAAY;;;;UACZ,YAAY;;;;YACZ,YAAY;;;;iBACZ,YAAY;;;;;WACZ,YAAY"}