@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -0,0 +1,408 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { foliage_atlas_cutout } from "../material/foliage_atlas_cutout.js";
+import { foliage_tile_layout } from "../material/foliage_tile.js";
+import { foliage_unit_card_spans } from "./foliage_unit_cards.js";
+import {
+    foliage_card_leaf_area,
+    foliage_card_reach,
+    foliage_leaf_area_per_metre,
+    foliage_leafy_span_start,
+    foliage_shoot_card_scale
+} from "./foliage_card_density.js";
+import {
+    foliage_abscission_threshold,
+    foliage_crown_height_norm,
+    foliage_crown_rho,
+    foliage_leaf_maturity,
+    foliage_leaf_variant,
+    foliage_sun_exposure,
+    foliage_variant_abscission_onset,
+    foliage_variant_maturity
+} from "./foliage_senescence.js";
+
+/**
+ * Density of air at sea level, 15 C, kg/m^3.
+ * @type {number}
+ */
+const AIR_DENSITY = 1.225;
+
+/**
+ * Drag coefficient of a circular cylinder (bark) in subcritical cross-flow.
+ * @type {number}
+ */
+const DRAG_COEFFICIENT_WOOD = 1.2;
+
+/**
+ * Effective drag coefficient of leafy foliage, which reconfigures (folds and streamlines) in wind;
+ * measured crowns sit around 0.3-0.5 at moderate speeds (Vogel 1989; Vollsinger et al. 2005).
+ * @type {number}
+ */
+const DRAG_COEFFICIENT_FOLIAGE = 0.4;
+
+/**
+ * Density of green (fresh) wood, kg/m^3.
+ * @type {number}
+ */
+const WOOD_DENSITY = 900.0;
+
+/**
+ * Fresh leaf mass per unit leaf area, kg/m^2 (dry 50-100 g/m^2 at 60-70% water).
+ * @type {number}
+ */
+const LEAF_AREAL_MASS = 0.2;
+
+const SCRATCH_P = new Float32Array(3);
+/** @type {import("./foliage_unit_cards.js").FoliageUnitCardSpan[]} */
+const SCRATCH_SPANS = [];
+
+/**
+ * Bending flexibility `integral dx / r(x)^4` of a segment whose radius tapers linearly from `r0` to `r1`
+ * over `len`; divided by `E pi / 4` it is `integral dx / (E I)`.
+ *
+ * @param {number} len
+ * @param {number} r0
+ * @param {number} r1
+ * @returns {number}
+ */
+function segment_flexibility(len, r0, r1) {
+    return len * (r0 * r0 + r0 * r1 + r1 * r1) / (3.0 * r0 * r0 * r0 * r1 * r1 * r1);
+}
+
+/**
+ * @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, species) {
+    const segment_count = skeleton.segment_count;
+
+    const p0 = new Float64Array(segment_count * 3);
+    const p1 = new Float64Array(segment_count * 3);
+    const mid = new Float64Array(segment_count * 3);
+    const drag_area = new Float64Array(segment_count);
+    const mass = new Float64Array(segment_count);
+    const flex = new Float64Array(segment_count);
+    const moment = new Float64Array(segment_count);
+    const mass_moment = new Float64Array(segment_count);
+    const reach = new Float64Array(segment_count);
+    // how far past its middle each segment's own wood and leaf cards reach
+    const card_reach = new Float64Array(segment_count);
+
+    const foliage_rules = species.foliage_rules;
+    const fol_mat = species.foliage_material;
+    const senescence = clamp(Math.max(fol_mat?.senescence ?? 0.0, fol_mat?.autumn_tint ?? 0.0), 0.0, 1.0);
+    // the species' card: its size, and how many leaves it draws
+    const layout = foliage_rules.length > 0 ? foliage_tile_layout(species) : null;
+    const variant_count = layout !== null ? layout.variant_count : 4;
+    // the atlas's leaf coverage, for branches grown by annual units; built on first need
+    let atlas = null;
+
+    for (let s = 0; s < segment_count; s++) {
+        const v0 = skeleton.segment_v0(s);
+        const v1 = skeleton.segment_v1(s);
+        const b = skeleton.node_branch_id(v1);
+        const generator = skeleton.branch_generator[b];
+
+        skeleton.node_read_position(SCRATCH_P, 0, v0);
+        p0[s * 3] = SCRATCH_P[0];
+        p0[s * 3 + 1] = SCRATCH_P[1];
+        p0[s * 3 + 2] = SCRATCH_P[2];
+        skeleton.node_read_position(SCRATCH_P, 0, v1);
+        p1[s * 3] = SCRATCH_P[0];
+        p1[s * 3 + 1] = SCRATCH_P[1];
+        p1[s * 3 + 2] = SCRATCH_P[2];
+        mid[s * 3] = 0.5 * (p0[s * 3] + p1[s * 3]);
+        mid[s * 3 + 1] = 0.5 * (p0[s * 3 + 1] + p1[s * 3 + 1]);
+        mid[s * 3 + 2] = 0.5 * (p0[s * 3 + 2] + p1[s * 3 + 2]);
+
+        if (species.branches[generator].root) {
+            continue;
+        }
+
+        const len = Math.max(1e-6, skeleton.segment_length(s));
+        const r0 = Math.max(1e-4, skeleton.node_read_radius(v0));
+        const r1 = Math.max(1e-4, skeleton.node_read_radius(v1));
+        const r_mean = 0.5 * (r0 + r1);
+
+        // Leaf of every foliage rule carried by this branch, spread evenly over its leafy span [attach_min, 1]; a branch
+        // grown by annual units carries the cards foliage_collect_attachments hangs on its units, each unit's spread over
+        // that unit
+        const t0 = skeleton.node_t_norm(v0);
+        const t1 = skeleton.node_t_norm(v1);
+        const by_units = skeleton.branch_unit_count[b] > 0;
+        let leaf_area = 0.0;
+        for (let r = 0; r < foliage_rules.length; r++) {
+            const rule = foliage_rules[r];
+            if (rule.source !== generator || skeleton.branch_dead[b]) continue;
+            if (by_units) {
+                if (atlas === null) atlas = foliage_atlas_cutout(species);
+                const coverage = atlas.mean_coverage();
+                foliage_unit_card_spans(skeleton, species, b, rule, layout.leaves_per_card, SCRATCH_SPANS);
+                for (let i = 0; i < SCRATCH_SPANS.length; i++) {
+                    const span = SCRATCH_SPANS[i];
+                    const overlap = Math.max(0.0, Math.min(t1, span.unit_t_max) - Math.max(t0, span.unit_t_min));
+                    if (overlap <= 0.0) continue;
+                    // the cards' own place along the leafy growth, at the middle of the span, as foliage_collect_attachments
+                    // judges it for shedding
+                    if (senescence > 0.0 && leaf_shed(skeleton, species, s, mid, 0.5 * (span.u_min + span.u_max), senescence, variant_count)) continue;
+                    card_reach[s] = Math.max(card_reach[s], foliage_card_reach(layout, span.scale));
+                    leaf_area += span.count * foliage_card_leaf_area(layout, species.foliage.card_type, coverage, span.scale)
+                        * overlap / Math.max(1e-6, span.unit_t_max - span.unit_t_min);
+                }
+                break;
+            }
+            const t_min = foliage_leafy_span_start(rule.attach_min);
+            const overlap = Math.max(0.0, t1 - Math.max(t0, t_min));
+            if (overlap <= 0.0) continue;
+            if (senescence > 0.0) {
+                // the leaves here are shed once senescence passes their threshold, as foliage_collect_attachments sheds them
+                // judged for the expected leaf at the segment's middle (no per-leaf jitter)
+                const t_mid = 0.5 * (Math.max(t0, t_min) + t1);
+                const u_shoot = (t_mid - t_min) / Math.max(1e-4, 1.0 - t_min);
+                if (leaf_shed(skeleton, species, s, mid, u_shoot, senescence, variant_count)) continue;
+            }
+            const card_scale = foliage_shoot_card_scale(layout.card_size, Math.max(0.12, skeleton.branch_length[b]));
+            const reach = foliage_card_reach(layout, card_scale);
+            card_reach[s] = Math.max(card_reach[s], reach);
+            leaf_area += foliage_leaf_area_per_metre(reach, rule.insertion_angle) * len * overlap / Math.max(1e-6, t1 - t0);
+        }
+
+        drag_area[s] = DRAG_COEFFICIENT_WOOD * 2.0 * r_mean * len + DRAG_COEFFICIENT_FOLIAGE * leaf_area;
+        mass[s] = WOOD_DENSITY * Math.PI * r_mean * r_mean * len + LEAF_AREAL_MASS * leaf_area;
+        flex[s] = segment_flexibility(len, r0, r1);
+        // a segment bends under its own load too: a uniform load q over length L turns a cantilever's end by
+        // q L^3 / (6 E I), the moment q L^2 / 6, its own drag and mass at arm L / 6
+        moment[s] += drag_area[s] * len / 6.0;
+        mass_moment[s] += mass[s] * len / 6.0;
+        // a segment's own wood and cards move with it: from its middle, its far end and the cards that hang past it
+        card_reach[s] += 0.5 * len;
+        reach[s] = card_reach[s];
+    }
+
+    // Walk every element's load up through the segments that carry it
+    for (let e = 0; e < segment_count; e++) {
+        const a_e = drag_area[e];
+        const m_e = mass[e];
+        if (a_e <= 0.0 && m_e <= 0.0) continue;
+        const ex = mid[e * 3], ey = mid[e * 3 + 1], ez = mid[e * 3 + 2];
+
+        let v = skeleton.segment_v0(e);
+        for (; ;) {
+            let s = skeleton.node_in_segment(v);
+            let loaded = 1.0;
+            if (s < 0) {
+                // a branch's root node: the load enters the parent segment it hangs from, below the attachment
+                const b = skeleton.node_branch_id(v);
+                s = skeleton.branch_parent_edge[b];
+                if (s < 0) break;
+                const pt0 = skeleton.node_t_norm(skeleton.segment_v0(s));
+                const pt1 = skeleton.node_t_norm(skeleton.segment_v1(s));
+                loaded = clamp((skeleton.branch_parent_attach_t[b] - pt0) / Math.max(1e-6, pt1 - pt0), 0.0, 1.0);
+            }
+            // moment arm to the middle of the segment's loaded part
+            const h = 0.5 * loaded;
+            const d = Math.hypot(
+                ex - (p0[s * 3] + (p1[s * 3] - p0[s * 3]) * h),
+                ey - (p0[s * 3 + 1] + (p1[s * 3 + 1] - p0[s * 3 + 1]) * h),
+                ez - (p0[s * 3 + 2] + (p1[s * 3 + 2] - p0[s * 3 + 2]) * h)
+            );
+            moment[s] += loaded * a_e * d;
+            mass_moment[s] += loaded * m_e * d;
+            // to the far end of what it carries, wood and cards
+            if (d + card_reach[e] > reach[s]) reach[s] = d + card_reach[e];
+            v = skeleton.segment_v0(s);
+        }
+    }
+
+    return { mid, mass, flex, moment, mass_moment, reach };
+}
+
+/**
+ * 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, segments, out) {
+    const { flex, moment } = segments;
+    const k = AIR_DENSITY / (species.wind.elastic_modulus * Math.PI * 0.25);
+    for (let s = 0; s < flex.length; s++) {
+        out[s] = k * moment[s] * flex[s];
+    }
+}
+
+/**
+ * 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,
+    species,
+    segments,
+    joint_vertex_ids,
+    node_joint,
+    out_compliance,
+    out_natural_frequency
+) {
+    const segment_count = skeleton.segment_count;
+    const joint_count = joint_vertex_ids.length;
+    const { flex, moment } = segments;
+
+    const deflection = new Float64Array(joint_count);
+    for (let s = 0; s < segment_count; s++) {
+        if (flex[s] <= 0.0) continue;
+        const j = node_joint[skeleton.segment_v0(s)];
+        if (skeleton.node_branch_id(joint_vertex_ids[j]) === skeleton.node_branch_id(skeleton.segment_v1(s))) {
+            deflection[j] += moment[s] * flex[s];
+        }
+    }
+
+    const branch_frequency = new Float64Array(skeleton.branch_count);
+    tree_skeleton_compute_branch_frequency(skeleton, species, segments, branch_frequency);
+
+    const bending_stiffness = species.wind.elastic_modulus * Math.PI * 0.25;
+    for (let j = 0; j < joint_count; j++) {
+        out_compliance[j] = AIR_DENSITY * deflection[j] / bending_stiffness;
+        out_natural_frequency[j] = branch_frequency[skeleton.node_branch_id(joint_vertex_ids[j])];
+    }
+}
+
+/**
+ * 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, species, segments, out) {
+    const segment_count = skeleton.segment_count;
+    const branch_count = skeleton.branch_count;
+    const { mid, mass, flex, mass_moment } = segments;
+
+    const weight_deflection = new Float64Array(branch_count);
+    for (let s = 0; s < segment_count; s++) {
+        weight_deflection[skeleton.node_branch_id(skeleton.segment_v1(s))] += mass_moment[s] * flex[s];
+    }
+
+    // Moment of inertia and static moment of everything each branch carries, about its root
+    const pivot = new Float64Array(branch_count * 3);
+    for (let b = 0; b < branch_count; b++) {
+        skeleton.node_read_position(SCRATCH_P, 0, skeleton.branch_root_vertex[b]);
+        pivot[b * 3] = SCRATCH_P[0];
+        pivot[b * 3 + 1] = SCRATCH_P[1];
+        pivot[b * 3 + 2] = SCRATCH_P[2];
+    }
+    const inertia = new Float64Array(branch_count);
+    const static_moment = new Float64Array(branch_count);
+    for (let e = 0; e < segment_count; e++) {
+        const m_e = mass[e];
+        if (m_e <= 0.0) continue;
+        const ex = mid[e * 3], ey = mid[e * 3 + 1], ez = mid[e * 3 + 2];
+        for (let b = skeleton.node_branch_id(skeleton.segment_v1(e)); b >= 0; b = skeleton.branch_parent[b]) {
+            const dx = ex - pivot[b * 3];
+            const dy = ey - pivot[b * 3 + 1];
+            const dz = ez - pivot[b * 3 + 2];
+            const d2 = dx * dx + dy * dy + dz * dz;
+            inertia[b] += m_e * d2;
+            static_moment[b] += m_e * Math.sqrt(d2);
+        }
+    }
+
+    const bending_stiffness = species.wind.elastic_modulus * Math.PI * 0.25;
+    for (let b = 0; b < branch_count; b++) {
+        out[b] = weight_deflection[b] > 0.0 && inertia[b] > 0.0
+            ? Math.sqrt(bending_stiffness * static_moment[b] / (weight_deflection[b] * inertia[b]))
+            : 0.0;
+    }
+}
+
+/**
+ * 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, species, segments, out) {
+    out.fill(0.0);
+    const { flex, moment } = segments;
+    for (let s = 0; s < skeleton.segment_count; s++) {
+        out[skeleton.node_branch_id(skeleton.segment_v1(s))] += moment[s] * flex[s];
+    }
+    const k = AIR_DENSITY / (species.wind.elastic_modulus * Math.PI * 0.25);
+    for (let b = 0; b < skeleton.branch_count; b++) {
+        out[b] *= k;
+    }
+}
+
+/**
+ * Whether the expected leaf at the middle of segment `s`, `u_shoot` along its leafy growth, has been shed at
+ * `senescence`, as foliage_collect_attachments sheds its cards (no per-leaf jitter).
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {number} s
+ * @param {Float64Array} mid segment midpoints
+ * @param {number} u_shoot
+ * @param {number} senescence
+ * @param {number} variant_count
+ * @returns {boolean}
+ */
+function leaf_shed(skeleton, species, s, mid, u_shoot, senescence, variant_count) {
+    const rho = foliage_crown_rho(skeleton, mid[s * 3], mid[s * 3 + 1], mid[s * 3 + 2]);
+    const sun = foliage_sun_exposure(rho, foliage_crown_height_norm(species.crown, mid[s * 3 + 1]));
+    const variant = foliage_leaf_variant(foliage_leaf_maturity(u_shoot, rho, 0.0), variant_count);
+    const onset = foliage_variant_abscission_onset(foliage_variant_maturity(variant, variant_count));
+    return senescence >= foliage_abscission_threshold(onset, sun, u_shoot);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"tree_skeleton_compute_pipe_radii.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_compute_pipe_radii.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,2DAJW,OAAO,mBAAmB,EAAE,YAAY,WACxC,iBAAiB,GACf,OAAO,mBAAmB,EAAE,YAAY,CA6LpD;kCA3MiC,gCAAgC"}
+{"version":3,"file":"tree_skeleton_compute_pipe_radii.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_compute_pipe_radii.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,2DAJW,OAAO,mBAAmB,EAAE,YAAY,WACxC,iBAAiB,GACf,OAAO,mBAAmB,EAAE,YAAY,CA+LpD;kCA7MiC,gCAAgC"}