@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -1,206 +1,208 @@
-import { clamp } from "../../../core/math/clamp.js";
-import { lerp } from "../../../core/math/lerp.js";
-import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
-
-/**
- * Enforces Da Vinci's pipe-model cross-sectional area conservation across a `TreeSkeleton`
- * in a bottom-up post-order pass:
- *
- * $$r_{\text{parent}}^\alpha = \sum_{k} r_{\text{child}, k}^\alpha$$
- *
- * Blended with each node's initial parametric taper radius via `pipe_model_weight`, while
- * preserving boundary conditions at both the branch base ($t = 0$) and terminal shoot apex ($t = 1$)
- * so neither trunk nor branch tips inflate into blunt stubs.
- *
- * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
- * @param {TreeSpeciesConfig} [config]
- * @returns {import("./TreeSkeleton.js").TreeSkeleton}
- */
-export function tree_skeleton_compute_pipe_radii(
-    skeleton,
-    config = new TreeSpeciesConfig()
-) {
-    const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
-    const n = skeleton.node_count;
-    const seg_count = skeleton.segment_count;
-    const branch_count = skeleton.branch_count;
-    if (n === 0) return skeleton;
-
-    const exp = clamp(species.crown.pipe_model_exponent ?? 2.05, 1.3, 3.0);
-    const inv_exp = 1.0 / exp;
-    const w_blend = clamp(species.crown.pipe_model_weight ?? 0.65, 0.0, 1.0);
-
-    // Save initial parametric radii and their alpha-power cross-sectional areas
-    const param_radii = new Float32Array(n);
-    const param_area = new Float64Array(n);
-    for (let v = 0; v < n; v++) {
-        const r = Math.max(0.0005, skeleton.node_read_radius(v));
-        param_radii[v] = r;
-        param_area[v] = Math.pow(r, exp);
-    }
-
-    // Map each lateral child branch to the parent segment it attaches to
-    /** @type {Map<number, number[]>} */
-    const edge_lateral_branches = new Map();
-    for (let b = 1; b < branch_count; b++) {
-        const p_edge = skeleton.branch_parent_edge[b];
-        if (p_edge >= 0 && p_edge < seg_count) {
-            let list = edge_lateral_branches.get(p_edge);
-            if (list === undefined) {
-                list = [];
-                edge_lateral_branches.set(p_edge, list);
-            }
-            list.push(b);
-        }
-    }
-
-    // Track accumulated alpha-area at each vertex
-    const pipe_area = new Float64Array(n);
-    // Track how many outgoing segments originate at each vertex (for shared-vertex bifurcations)
-    const outgoing_seg_count = new Int32Array(n);
-    const outgoing_seg_area = new Float64Array(n);
-    for (let s = 0; s < seg_count; s++) {
-        const v0 = skeleton.segment_v0(s);
-        if (v0 >= 0 && v0 < n) {
-            outgoing_seg_count[v0]++;
-        }
-    }
-
-    const branch_nodes = [];
-    const branch_edges = [];
-
-    // Process branches in reverse order (twigs -> boughs -> trunk) because parent_id < child_id
-    for (let b = branch_count - 1; b >= 0; b--) {
-        skeleton.collect_branch_chain(b, branch_nodes, branch_edges);
-        const m = branch_nodes.length;
-        if (m === 0) continue;
-
-        const root_v = branch_nodes[0];
-        const tip_v = branch_nodes[m - 1];
-
-        // 1. Anchor terminal tip vertex to its parametric bud/shoot area (plus any shared-vertex fork children)
-        let tip_area = param_area[tip_v];
-        if (outgoing_seg_count[tip_v] > 0 && outgoing_seg_area[tip_v] > tip_area) {
-            tip_area = outgoing_seg_area[tip_v];
-        }
-        pipe_area[tip_v] = tip_area;
-
-        // 2. Accumulate backward from tip to base along branch b's spine segments
-        for (let i = branch_edges.length - 1; i >= 0; i--) {
-            const e_id = branch_edges[i];
-            const v0 = branch_nodes[i];
-            const v1 = branch_nodes[i + 1];
-
-            // Telescoping parametric area differential along this internode segment
-            // (reproduces exact basal flare and continuous bole/shoot taper between junctions)
-            const min_step = Math.pow(param_radii[v1] * 0.08, exp);
-            const param_diff = Math.max(min_step, param_area[v0] - param_area[v1]);
-
-            // Sum cross-sectional area demand of lateral child branches attached to segment e_id
-            let lateral_demand = 0.0;
-            const child_branches = edge_lateral_branches.get(e_id);
-            if (child_branches !== undefined) {
-                for (let k = 0; k < child_branches.length; k++) {
-                    const cb = child_branches[k];
-                    const c_root = skeleton.branch_root_vertex[cb];
-                    if (c_root >= 0 && c_root < n && c_root !== v0) {
-                        const c_level = skeleton.branch_level[cb];
-                        const lateral_weight = c_level === skeleton.branch_level[b] ? 0.75 : 0.08;
-                        lateral_demand += lateral_weight * pipe_area[c_root];
-                    }
-                }
-            }
-
-            const seg_upstream_area = pipe_area[v1] + param_diff + lateral_demand;
-            outgoing_seg_area[v0] += seg_upstream_area;
-
-            // If v0 is a shared bifurcation node with multiple outgoing segments, sum all outgoing segment areas
-            pipe_area[v0] = Math.max(seg_upstream_area, outgoing_seg_area[v0]);
-        }
-
-        // 3. Normalize branch b's pipe_area profile so both tip (t=1) and base (t=0) boundary conditions
-        //    are respected while preserving all intermediate Da Vinci junction step-downs
-        const a_raw_tip = pipe_area[tip_v];
-        const a_raw_root = pipe_area[root_v];
-        const a_target_tip = param_area[tip_v];
-        // Allow shared-vertex multi-segment forks to exceed single-stem param_area[root_v] when needed
-        const a_target_root = outgoing_seg_count[root_v] > 1
-            ? Math.max(param_area[root_v], outgoing_seg_area[root_v])
-            : Math.max(a_target_tip * 1.05, param_area[root_v]);
-
-        const raw_span = a_raw_root - a_raw_tip;
-        const target_span = Math.max(0.0, a_target_root - a_target_tip);
-
-        for (let i = 0; i < m; i++) {
-            const v = branch_nodes[i];
-            let a_norm;
-            if (raw_span > 1e-12) {
-                const u_area = clamp((pipe_area[v] - a_raw_tip) / raw_span, 0.0, 1.0);
-                a_norm = a_target_tip + u_area * target_span;
-            } else {
-                a_norm = param_area[v];
-            }
-
-            // Preserve strict fork area dominance at shared multi-segment vertices
-            if (outgoing_seg_count[v] > 1 && outgoing_seg_area[v] > a_norm) {
-                a_norm = outgoing_seg_area[v];
-            }
-
-            pipe_area[v] = a_norm;
-        }
-    }
-
-    // Convert normalized pipe areas back to radii and blend with parametric radii
-    for (let v = 0; v < n; v++) {
-        const pipe_r = Math.pow(Math.max(1e-12, pipe_area[v]), inv_exp);
-        const blended = lerp(param_radii[v], pipe_r, w_blend);
-        skeleton.node_write_radius(v, blended);
-    }
-
-    // Enforce strict child-to-parent radius bound at every lateral branch attachment
-    // and monotonically non-increasing radii along each branch chain
-    for (let b = 0; b < branch_count; b++) {
-        skeleton.collect_branch_chain(b, branch_nodes, branch_edges);
-        const m = branch_nodes.length;
-        if (m === 0) continue;
-
-        const root_v = branch_nodes[0];
-        let max_allowed = skeleton.node_read_radius(root_v);
-
-        if (b > 0) {
-            const p_edge = skeleton.branch_parent_edge[b];
-            const attach_t = skeleton.branch_parent_attach_t[b];
-            if (p_edge >= 0 && p_edge < seg_count) {
-                const pv0 = skeleton.segment_v0(p_edge);
-                const pv1 = skeleton.segment_v1(p_edge);
-                const pt0 = skeleton.node_t_norm(pv0);
-                const pt1 = skeleton.node_t_norm(pv1);
-                const local_u = clamp((attach_t - pt0) / Math.max(1e-5, pt1 - pt0), 0.0, 1.0);
-                const pr0 = skeleton.node_read_radius(pv0);
-                const pr1 = skeleton.node_read_radius(pv1);
-                const parent_r = lerp(pr0, pr1, local_u);
-                const cap_r = parent_r * 0.82;
-                if (max_allowed > cap_r) {
-                    const scale = cap_r / Math.max(1e-6, max_allowed);
-                    for (let i = 0; i < m; i++) {
-                        const v = branch_nodes[i];
-                        skeleton.node_write_radius(v, skeleton.node_read_radius(v) * scale);
-                    }
-                    max_allowed = cap_r;
-                }
-            }
-        }
-
-        // Ensure monotonic non-increasing radius from branch root to branch tip
-        let prev_r = skeleton.node_read_radius(root_v);
-        skeleton.branch_base_radius[b] = prev_r;
-        for (let i = 1; i < m; i++) {
-            const v = branch_nodes[i];
-            const cur_r = Math.min(prev_r, skeleton.node_read_radius(v));
-            skeleton.node_write_radius(v, cur_r);
-            prev_r = cur_r;
-        }
-    }
-
-    return skeleton;
-}
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+
+/**
+ * Enforces Da Vinci's pipe-model cross-sectional area conservation across a `TreeSkeleton`
+ * in a bottom-up post-order pass:
+ *
+ * $$r_{\text{parent}}^\alpha = \sum_{k} r_{\text{child}, k}^\alpha$$
+ *
+ * Blended with each node's initial parametric taper radius via `pipe_model_weight`, while
+ * preserving boundary conditions at both the branch base ($t = 0$) and terminal shoot apex ($t = 1$)
+ * so neither trunk nor branch tips inflate into blunt stubs.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {TreeSpeciesConfig} [config]
+ * @returns {import("./TreeSkeleton.js").TreeSkeleton}
+ */
+export function tree_skeleton_compute_pipe_radii(
+    skeleton,
+    config = new TreeSpeciesConfig()
+) {
+    const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+    const n = skeleton.node_count;
+    const seg_count = skeleton.segment_count;
+    const branch_count = skeleton.branch_count;
+    if (n === 0) return skeleton;
+
+    const exp = clamp(species.crown.pipe_model_exponent ?? 2.05, 1.3, 3.0);
+    const inv_exp = 1.0 / exp;
+    const w_blend = clamp(species.crown.pipe_model_weight ?? 0.65, 0.0, 1.0);
+
+    // Save initial parametric radii and their alpha-power cross-sectional areas
+    const param_radii = new Float32Array(n);
+    const param_area = new Float64Array(n);
+    for (let v = 0; v < n; v++) {
+        const r = Math.max(0.0005, skeleton.node_read_radius(v));
+        param_radii[v] = r;
+        param_area[v] = Math.pow(r, exp);
+    }
+
+    // Map each lateral child branch to the parent segment it attaches to
+    /** @type {Map<number, number[]>} */
+    const edge_lateral_branches = new Map();
+    for (let b = 1; b < branch_count; b++) {
+        const p_edge = skeleton.branch_parent_edge[b];
+        if (p_edge >= 0 && p_edge < seg_count) {
+            let list = edge_lateral_branches.get(p_edge);
+            if (list === undefined) {
+                list = [];
+                edge_lateral_branches.set(p_edge, list);
+            }
+            list.push(b);
+        }
+    }
+
+    // Track accumulated alpha-area at each vertex
+    const pipe_area = new Float64Array(n);
+    // Track how many outgoing segments originate at each vertex (for shared-vertex bifurcations)
+    const outgoing_seg_count = new Int32Array(n);
+    const outgoing_seg_area = new Float64Array(n);
+    for (let s = 0; s < seg_count; s++) {
+        const v0 = skeleton.segment_v0(s);
+        if (v0 >= 0 && v0 < n) {
+            outgoing_seg_count[v0]++;
+        }
+    }
+
+    const branch_nodes = [];
+    const branch_edges = [];
+
+    // Process branches in reverse order (twigs -> boughs -> trunk) because parent_id < child_id
+    for (let b = branch_count - 1; b >= 0; b--) {
+        skeleton.collect_branch_chain(b, branch_nodes, branch_edges);
+        const m = branch_nodes.length;
+        if (m === 0) continue;
+
+        const root_v = branch_nodes[0];
+        const tip_v = branch_nodes[m - 1];
+
+        // 1. Anchor terminal tip vertex to its parametric bud/shoot area (plus any shared-vertex fork children)
+        let tip_area = param_area[tip_v];
+        if (outgoing_seg_count[tip_v] > 0 && outgoing_seg_area[tip_v] > tip_area) {
+            tip_area = outgoing_seg_area[tip_v];
+        }
+        pipe_area[tip_v] = tip_area;
+
+        // 2. Accumulate backward from tip to base along branch b's spine segments
+        for (let i = branch_edges.length - 1; i >= 0; i--) {
+            const e_id = branch_edges[i];
+            const v0 = branch_nodes[i];
+            const v1 = branch_nodes[i + 1];
+
+            // Telescoping parametric area differential along this internode segment
+            // (reproduces exact basal flare and continuous bole/shoot taper between junctions)
+            const min_step = Math.pow(param_radii[v1] * 0.08, exp);
+            const param_diff = Math.max(min_step, param_area[v0] - param_area[v1]);
+
+            // Sum cross-sectional area demand of lateral child branches attached to segment e_id
+            let lateral_demand = 0.0;
+            const child_branches = edge_lateral_branches.get(e_id);
+            if (child_branches !== undefined) {
+                for (let k = 0; k < child_branches.length; k++) {
+                    const cb = child_branches[k];
+                    const c_root = skeleton.branch_root_vertex[cb];
+                    const c_gen = skeleton.branch_generator[cb];
+                    // Surface roots draw their sap below the stem, not through it; dead branches draw none
+                    if (c_root >= 0 && c_root < n && c_root !== v0 && !species.branches[c_gen].root && !skeleton.branch_dead[cb]) {
+                        // A split fork continues its parent's generator; a lateral is a different one
+                        const lateral_weight = c_gen === skeleton.branch_generator[b] ? 0.75 : 0.08;
+                        lateral_demand += lateral_weight * pipe_area[c_root];
+                    }
+                }
+            }
+
+            const seg_upstream_area = pipe_area[v1] + param_diff + lateral_demand;
+            outgoing_seg_area[v0] += seg_upstream_area;
+
+            // If v0 is a shared bifurcation node with multiple outgoing segments, sum all outgoing segment areas
+            pipe_area[v0] = Math.max(seg_upstream_area, outgoing_seg_area[v0]);
+        }
+
+        // 3. Normalize branch b's pipe_area profile so both tip (t=1) and base (t=0) boundary conditions
+        //    are respected while preserving all intermediate Da Vinci junction step-downs
+        const a_raw_tip = pipe_area[tip_v];
+        const a_raw_root = pipe_area[root_v];
+        const a_target_tip = param_area[tip_v];
+        // Allow shared-vertex multi-segment forks to exceed single-stem param_area[root_v] when needed
+        const a_target_root = outgoing_seg_count[root_v] > 1
+            ? Math.max(param_area[root_v], outgoing_seg_area[root_v])
+            : Math.max(a_target_tip * 1.05, param_area[root_v]);
+
+        const raw_span = a_raw_root - a_raw_tip;
+        const target_span = Math.max(0.0, a_target_root - a_target_tip);
+
+        for (let i = 0; i < m; i++) {
+            const v = branch_nodes[i];
+            let a_norm;
+            if (raw_span > 1e-12) {
+                const u_area = clamp((pipe_area[v] - a_raw_tip) / raw_span, 0.0, 1.0);
+                a_norm = a_target_tip + u_area * target_span;
+            } else {
+                a_norm = param_area[v];
+            }
+
+            // Preserve strict fork area dominance at shared multi-segment vertices
+            if (outgoing_seg_count[v] > 1 && outgoing_seg_area[v] > a_norm) {
+                a_norm = outgoing_seg_area[v];
+            }
+
+            pipe_area[v] = a_norm;
+        }
+    }
+
+    // Convert normalized pipe areas back to radii and blend with parametric radii
+    for (let v = 0; v < n; v++) {
+        const pipe_r = Math.pow(Math.max(1e-12, pipe_area[v]), inv_exp);
+        const blended = lerp(param_radii[v], pipe_r, w_blend);
+        skeleton.node_write_radius(v, blended);
+    }
+
+    // Enforce strict child-to-parent radius bound at every lateral branch attachment
+    // and monotonically non-increasing radii along each branch chain
+    for (let b = 0; b < branch_count; b++) {
+        skeleton.collect_branch_chain(b, branch_nodes, branch_edges);
+        const m = branch_nodes.length;
+        if (m === 0) continue;
+
+        const root_v = branch_nodes[0];
+        let max_allowed = skeleton.node_read_radius(root_v);
+
+        if (b > 0) {
+            const p_edge = skeleton.branch_parent_edge[b];
+            const attach_t = skeleton.branch_parent_attach_t[b];
+            if (p_edge >= 0 && p_edge < seg_count) {
+                const pv0 = skeleton.segment_v0(p_edge);
+                const pv1 = skeleton.segment_v1(p_edge);
+                const pt0 = skeleton.node_t_norm(pv0);
+                const pt1 = skeleton.node_t_norm(pv1);
+                const local_u = clamp((attach_t - pt0) / Math.max(1e-5, pt1 - pt0), 0.0, 1.0);
+                const pr0 = skeleton.node_read_radius(pv0);
+                const pr1 = skeleton.node_read_radius(pv1);
+                const parent_r = lerp(pr0, pr1, local_u);
+                const cap_r = parent_r * 0.82;
+                if (max_allowed > cap_r) {
+                    const scale = cap_r / Math.max(1e-6, max_allowed);
+                    for (let i = 0; i < m; i++) {
+                        const v = branch_nodes[i];
+                        skeleton.node_write_radius(v, skeleton.node_read_radius(v) * scale);
+                    }
+                    max_allowed = cap_r;
+                }
+            }
+        }
+
+        // Ensure monotonic non-increasing radius from branch root to branch tip
+        let prev_r = skeleton.node_read_radius(root_v);
+        skeleton.branch_base_radius[b] = prev_r;
+        for (let i = 1; i < m; i++) {
+            const v = branch_nodes[i];
+            const cur_r = Math.min(prev_r, skeleton.node_read_radius(v));
+            skeleton.node_write_radius(v, cur_r);
+            prev_r = cur_r;
+        }
+    }
+
+    return skeleton;
+}

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

@@ -1,7 +1,10 @@
 /**
  * Generates a directed botanical `TreeSkeleton` from a `TreeSpeciesConfig`, combining:
- * - Multi-level parametric Cubic Hermite spine generation (`BranchLevelConfig`, `AnimationCurve` profiles)
- * - Botanical phyllotaxis (`SpiralGolden`, `AlternateDistichous`, `Tristichous`, `Opposite`, `OppositeDecussate`, `Whorled`)
+ * - A branch generator graph: `species.branches[0]` grows the trunk, and every `species.branch_rules` edge
+ *   spawns branches of its `target` generator along each branch of its `source` generator
+ * - Parametric Cubic Hermite spine generation (`BranchGeneratorConfig`, `AnimationCurve` profiles)
+ * - Botanical phyllotaxis (`SpiralGolden`, `AlternateDistichous`, `Tristichous`, `Opposite`, `OppositeDecussate`, `Whorled`, `FlareLobes`)
+ * - Structural surface roots (`BranchGeneratorConfig.root`) that creep along the ground plane `y = 0`
  * - Gravitropism (toward `-Y`), phototropism (toward `+Y` and outward crown exterior), and 3D `curl_noise_3d` gnarl
  * - Dichotomous / sympodial trunk & bough splitting
  * - Space colonization crown competition via `PointHashGrid3`

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

@@ -1 +1 @@
-{"version":3,"file":"tree_skeleton_grow.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_grow.js"],"names":[],"mappings":"AAsOA;;;;;;;;;;;;;GAaG;AACH,4CAJW,iBAAiB,MAAO,QACxB,YAAY,GACV,YAAY,CA4lDxB;kCAn0DiC,gCAAgC;6BACrC,mBAAmB"}
+{"version":3,"file":"tree_skeleton_grow.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_grow.js"],"names":[],"mappings":"AA8RA;;;;;;;;;;;;;;;;GAgBG;AACH,4CAJW,iBAAiB,MAAO,QACxB,YAAY,GACV,YAAY,CAktDxB;kCAp/DiC,gCAAgC;6BACrC,mBAAmB"}