@woosh/meep-engine 3.52.0 → 3.54.0

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

@@ -0,0 +1,206 @@
+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;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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`)
+ * - 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`
+ * - Rotation-Minimizing Frames (`spine_frame_double_reflection`)
+ * - Pipe Model cross-section radius accumulation (`tree_skeleton_compute_pipe_radii`)
+ *
+ * @param {TreeSpeciesConfig|Object} [config]
+ * @param {TreeSkeleton} [out]
+ * @returns {TreeSkeleton}
+ */
+export function tree_skeleton_grow(config?: TreeSpeciesConfig | any, out?: TreeSkeleton): TreeSkeleton;
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { TreeSkeleton } from "./TreeSkeleton.js";
+//# sourceMappingURL=tree_skeleton_grow.d.ts.map

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

@@ -0,0 +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"}