@woosh/meep-engine 3.53.0 → 3.54.0

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

@@ -1,179 +1,206 @@
-import { clamp } from "../../../core/math/clamp.js";
-import { lerp } from "../../../core/math/lerp.js";
-import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
-
-/**
- * Computes and blends botanical Pipe Model Theory (Shinozaki et al. 1964; Leonardo da Vinci / Murray's law)
- * cross-sectional radii $R_p^\alpha = \sum R_i^\alpha$ bottom-up across `skeleton.graph`,
- * blending with the parametric `radius_profile` curves according to `config.crown.pipe_model_weight`.
- *
- * Also guarantees monotonic non-increasing radii along each branch from base to tip and updates
- * each node's {@link Transform64} scale and `skeleton.branch_base_radius`.
- *
- * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
- * @param {TreeSpeciesConfig|Object} [config]
- */
-export function tree_skeleton_compute_pipe_radii(skeleton, config = new TreeSpeciesConfig()) {
-    const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
-    const graph = skeleton.graph;
-    const vertex_count = skeleton.node_count;
-    if (vertex_count === 0) {
-        return;
-    }
-
-    const alpha = clamp(species.crown.pipe_model_exponent ?? 2.3, 1.5, 3.5);
-    const inv_alpha = 1.0 / alpha;
-    const pipe_weight = clamp(species.crown.pipe_model_weight ?? 0.65, 0.0, 1.0);
-
-    const param_radii = new Float32Array(vertex_count);
-    const pipe_radii = new Float32Array(vertex_count);
-
-    for (let v = 0; v < vertex_count; v++) {
-        param_radii[v] = Math.max(0.001, skeleton.node_read_radius(v));
-    }
-
-    // Nodes are allocated in topological pre-order (parents before children),
-    // so iterating from vertex_count - 1 down to 0 is a valid reverse topological (post-order) pass.
-    for (let v = vertex_count - 1; v >= 0; v--) {
-        const container = graph.getNodeContainer(v);
-        const level = skeleton.node_level(v);
-        const lvl_cfg = species.levels[Math.min(level, Math.max(0, species.levels.length - 1))];
-        const seg_count = Math.max(1, lvl_cfg ? lvl_cfg.segments : 4);
-
-        const r_param = param_radii[v];
-        const r_min_tip = Math.max(0.002, r_param * 0.22);
-
-        if (container === undefined) {
-            pipe_radii[v] = r_param;
-            continue;
-        }
-
-        const edges = container.getEdges();
-        let sum_pow = 0.0;
-        let spine_out_count = 0;
-
-        for (let i = 0; i < edges.length; i++) {
-            const edge = edges[i];
-            if (edge.isDirectedAwayFrom(v)) {
-                const u = edge.other(v);
-                const child_r = pipe_radii[u] > 0 ? pipe_radii[u] : param_radii[u];
-                if (skeleton.node_in_segment(u) >= 0) {
-                    sum_pow += Math.pow(child_r, alpha);
-                    spine_out_count++;
-                } else {
-                    // Lateral branch attachment link
-                    sum_pow += 0.2 * Math.pow(child_r, alpha);
-                }
-            }
-        }
-
-        if (spine_out_count === 0) {
-            // Terminal tip node of a branch
-            pipe_radii[v] = r_param;
-        } else {
-            // Add small per-internode vascular leaf-supply increment so unbranched internodes still taper smoothly
-            const internode_supply = Math.pow(r_min_tip, alpha) / seg_count;
-            pipe_radii[v] = Math.pow(sum_pow + internode_supply, inv_alpha);
-        }
-    }
-
-    // Normalize per branch root against its parametric base radius so Leonardo/Murray area-preserving ratios
-    // hold across all forks while preserving species-configured branch/trunk base thickness ratios.
-    for (let v = 0; v < vertex_count; v++) {
-        const b = skeleton.node_branch_id(v);
-        const root_v = skeleton.branch_root_vertex[b];
-        const root_pipe = pipe_radii[root_v];
-        const root_param = param_radii[root_v];
-        const pipe_scale = root_pipe > 1e-6 ? (root_param / root_pipe) : 1.0;
-
-        const scaled_pipe = pipe_radii[v] * pipe_scale;
-        const blended = lerp(param_radii[v], scaled_pipe, pipe_weight);
-        skeleton.node_write_radius(v, Math.max(0.0015, blended));
-    }
-
-    // Forward pass (0 .. V-1): enforce child radius <= parent radius across every directed edge in `skeleton.graph`
-    for (let v = 0; v < vertex_count; v++) {
-        const container = graph.getNodeContainer(v);
-        if (container === undefined) {
-            continue;
-        }
-        const r_parent = skeleton.node_read_radius(v);
-        const parent_branch = skeleton.node_branch_id(v);
-        const edges = container.getEdges();
-
-        for (let i = 0; i < edges.length; i++) {
-            const edge = edges[i];
-            if (edge.isDirectedAwayFrom(v)) {
-                const u = edge.other(v);
-                const child_branch = skeleton.node_branch_id(u);
-                const r_child = skeleton.node_read_radius(u);
-                const max_allowed = child_branch === parent_branch ? r_parent : r_parent * 0.78;
-                if (r_child > max_allowed) {
-                    skeleton.node_write_radius(u, max_allowed);
-                }
-            }
-        }
-    }
-
-    // Branch-level pass: ensure every child branch's base radius is <= 0.78 * interpolated parent radius
-    // at `parent_attach_t` along `parent_edge` (accounting for parent segment taper between pv0 and pv1),
-    // and maintain monotonic non-increasing radii along the child branch spine.
-    const branch_nodes = [];
-    const branch_edges = [];
-    for (let b = 1; b < skeleton.branch_count; b++) {
-        const pe = skeleton.branch_parent_edge[b];
-        if (pe < 0) continue;
-
-        const pv0 = skeleton.segment_v0(pe);
-        const pv1 = skeleton.segment_v1(pe);
-        const pt0 = skeleton.node_t_norm(pv0);
-        const pt1 = skeleton.node_t_norm(pv1);
-        const pt = skeleton.branch_parent_attach_t[b];
-        const local_u = clamp((pt - 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_at_attach = lerp(pr0, pr1, local_u);
-        const max_base_r = parent_r_at_attach * 0.78;
-
-        skeleton.collect_branch_chain(b, branch_nodes, branch_edges);
-        if (branch_nodes.length === 0) continue;
-
-        const root_v = branch_nodes[0];
-        if (skeleton.node_branch_id(root_v) !== b) continue;
-
-        const cur_base_r = skeleton.node_read_radius(root_v);
-        if (cur_base_r > max_base_r && cur_base_r > 1e-6) {
-            const scale = max_base_r / cur_base_r;
-            for (let i = 0; i < branch_nodes.length; i++) {
-                const nv = branch_nodes[i];
-                if (skeleton.node_branch_id(nv) === b) {
-                    skeleton.node_write_radius(
-                        nv,
-                        Math.min(max_base_r, Math.max(0.0005, skeleton.node_read_radius(nv) * scale))
-                    );
-                }
-            }
-        }
-
-        // Guarantee monotonic taper along the branch
-        let prev_r = skeleton.node_read_radius(branch_nodes[0]);
-        for (let i = 1; i < branch_nodes.length; i++) {
-            const nv = branch_nodes[i];
-            const nr = skeleton.node_read_radius(nv);
-            if (nr > prev_r) {
-                skeleton.node_write_radius(nv, prev_r);
-            } else {
-                prev_r = nr;
-            }
-        }
-    }
-
-    // Synchronize branch_base_radius table with updated root node radii
-    for (let b = 0; b < skeleton.branch_count; b++) {
-        const root_v = skeleton.branch_root_vertex[b];
-        if (root_v >= 0 && root_v < vertex_count) {
-            skeleton.branch_base_radius[b] = skeleton.node_read_radius(root_v);
-        }
-    }
-}
+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.map

@@ -1 +1 @@
-{"version":3,"file":"tree_skeleton_grow.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_grow.js"],"names":[],"mappings":"AAuIA;;;;;;;;;;;;;GAaG;AACH,4CAJW,iBAAiB,MAAO,QACxB,YAAY,GACV,YAAY,CA47BxB;kCAtkCiC,gCAAgC;6BACrC,mBAAmB"}
+{"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"}