@woosh/meep-engine 3.56.0 → 3.57.0

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

@@ -0,0 +1,588 @@
+import { GOLDEN_RATIO } from "../../../core/math/GOLDEN_RATIO.js";
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { phyllotaxis_sample_angle } from "../config/PhyllotaxisMode.js";
+import { shoot_order_value } from "../config/ShootBudZone.js";
+import { foliage_atlas_cutout } from "../material/foliage_atlas_cutout.js";
+import { foliage_tile_layout } from "../material/foliage_tile.js";
+import { foliage_card_leaf_area } from "./foliage_card_density.js";
+import { foliage_unit_leaf_count } from "./foliage_unit_cards.js";
+import { ShootFrameworkHash } from "./ShootFrameworkHash.js";
+import { ShootGirth } from "./ShootGirth.js";
+import { ShootLightField } from "./ShootLightField.js";
+import { shoot_expected_yield, shoot_sample_unit_length } from "./shoot_demography.js";
+import { shoot_locate_on_chain, shoot_normalize3, shoot_outward3, shoot_perpendicular3, shoot_radius } from "./shoot_geometry.js";
+
+const GOLDEN_ANGLE = PI2 / (GOLDEN_RATIO * GOLDEN_RATIO);
+
+/**
+ * Room (m) the light field leaves around the framework for the twig systems to grow into; leaf past it shades nothing
+ * and sees open sky. Chosen.
+ * @type {number}
+ */
+const LIGHT_FIELD_MARGIN = 2.0;
+
+const SCRATCH_P = new Float32Array(3);
+const SCRATCH_T = new Float32Array(3);
+const SCRATCH_R = new Float64Array(3);
+const SCRATCH_O = new Float64Array(3);
+const SCRATCH_H = new Float64Array(3);
+const SCRATCH_A = new Float64Array(3);
+const SCRATCH_B = new Float64Array(3);
+
+/**
+ * @typedef {Object} ShootCarrier
+ * @property {import("../config/ShootSystemRule.js").ShootSystemRule} rule
+ * @property {number} carrier framework branch
+ * @property {number} length metres
+ * @property {number[]} nodes the carrier's chain
+ * @property {number[]} edges
+ * @property {number[]} units lengths (m) of its last annual units, oldest first, ending at its tip
+ * @property {Float64Array} starts arc length (m) from its base where each unit starts
+ * @property {Float64Array} points world position of each unit boundary, `(units + 1) * 3`, the last its tip
+ * @property {number} first_season season its oldest unit grew in
+ * @property {Float64Array} [carrier_area] pipe area of what grows on each unit, after the simulation
+ * @property {Float64Array} [carrier_demand] radius each unit needs where its laterals join, after the simulation
+ */
+
+/**
+ * @typedef {Object} ShootAxis
+ * @property {number} system index of its carrier
+ * @property {number} parent mother axis, `-1` for the carrier
+ * @property {number} parent_unit unit of the mother it grew from, oldest first
+ * @property {number} u where along that unit, 0 base to 1 tip
+ * @property {number} node bud index on that unit, for the leaf spiral
+ * @property {number} order branching order, the carrier being `rule.carrier_order`
+ * @property {boolean} short a short shoot
+ * @property {number} generator its branch generator
+ * @property {number} phase random phase in [0, 1)
+ * @property {number[]} units lengths (m), oldest first
+ * @property {number[]} unit_seasons season each unit grew in
+ * @property {number[]} points world position of each unit boundary, `(units + 1) * 3`
+ * @property {number[]} radii radius (m) of the wood at each unit boundary, `units + 1`
+ * @property {number} anchor_edge carrier segment a first-order axis grows from, else -1
+ */
+
+/**
+ * Grows the twig systems of every carrier together, season by season, in the light their leaves make for each other,
+ * for `seasons` seasons: the tree's age, so every unit of every carrier has had the time since it grew to grow its
+ * twigs.
+ *
+ * Each season:
+ * 1. **Light.** The leaves alive last season are put in a {@link ShootLightField}, and each shoot reads the relative
+ *    irradiance where it grows.
+ * 2. **Extension.** Every living long axis grows a terminal unit, bent from its last by the generator's phototropism,
+ *    gravitropism and zigzag, `terminal_length + terminal_length_slope *` its last unit long on average.
+ * 3. **Short shoots** live on at `short_shoot_survival`, less in light too dim for a shoot to replace itself.
+ * 4. **Buds.** Last season's units burst their buds: by zone and mother order, a `long` share grow long shoots and a
+ *    `short` share short shoots. A `sylleptic` share of this season's units' buds grow at once.
+ * 5. **Shedding.** A new shoot in relative light `Q` survives at `p = net_yield(Q) / yield`. That is the species'
+ *    net shoots per shoot at that light, over the gross new shoots its mother makes. Of a season's new shoots the
+ *    sum of their `p` survive, with a carried-over remainder so the count is exact on average. They are ranked by
+ *    `log p` plus the rank of oak's shedding: the highest orders, the youngest axes and the shortest shoots go first
+ *    (Buck-Sorlin & Bell 1998, Bot. J. Linn. Soc. 127: 371-391, p. 388). So the shaded go before the lit, and among
+ *    equally lit shoots an established axis outlasts a new lateral. A shed terminal sheds its whole axis with
+ *    everything on it, as oak sheds only at an axis's base (p. 388). So a branch in deep shade, whose terminals are
+ *    shed, dies.
+ *
+ * The wood thickens season by season with what it carries (`ShootGirth`): twigs, carriers, and the framework above
+ * them. A shoot whose path would run into framework wood as thick as it is that season is a blocked bud and does not
+ * grow; its mother's junction is the one exception. A blocked terminal leaves its axis without a unit that season. A
+ * shoot whose wood the framework, or its own girth, has grown into by the end of a season is engulfed and dies with
+ * everything on it.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {ShootCarrier[]} carriers
+ * @param {number} seasons
+ * @param {function():number} rng
+ * @returns {ShootAxis[]} the living axes, a mother before its laterals
+ */
+export function shoot_systems_simulate(skeleton, species, carriers, seasons, rng) {
+    const growth = species.shoot_growth;
+    // everything in the skeleton now is framework
+    const framework_segments = skeleton.segment_count;
+    const girth = new ShootGirth(skeleton, carriers, skeleton.branch_count, species.crown.pipe_model_exponent);
+    let framework = new ShootFrameworkHash(skeleton, framework_segments);
+    const leaf_survival = species.foliage.leaf_survival;
+    const yields = carriers.map(c => shoot_expected_yield(c.rule));
+
+    // Leaf area of one leaf, as the cards draw it
+    const leafy = new Map();
+    for (const rule of species.foliage_rules) {
+        leafy.set(rule.source, rule.short_shoot);
+    }
+    let leaf_area_each = 0;
+    if (leafy.size > 0) {
+        const layout = foliage_tile_layout(species);
+        const coverage = foliage_atlas_cutout(species).mean_coverage();
+        leaf_area_each = foliage_card_leaf_area(layout, species.foliage.card_type, coverage, 1.0) / layout.leaves_per_card;
+    }
+
+    const field = make_light_field(skeleton, growth.light_cell);
+
+    /** @type {Array<ShootAxis & {alive: boolean, birth: number, heading: number[], taken: Array<number[]|null>, exempt_branch: number, key: number}>} */
+    const axes = [];
+    /** buds spent on sylleptic shoots per carrier unit, by zone */
+    const carrier_taken = carriers.map(c => new Array(c.units.length).fill(null));
+    let remainder = 0.5;
+
+    const survival_at = (light, system) => clamp(growth.net_yield(light) / yields[system], 0, 1);
+
+    /**
+     * Where a bud on unit `k` of a mother sits, and the mother's tangent there, into SCRATCH_P / SCRATCH_T.
+     * @returns {{edge: number, u: number}|null} the carrier segment, for a carrier's bud
+     */
+    const bud_site = (system, mother, k, u) => {
+        if (mother < 0) {
+            const c = carriers[system];
+            const located = shoot_locate_on_chain(skeleton, c.nodes, c.edges, (c.starts[k] + u * c.units[k]) / c.length);
+            skeleton.evaluate_segment_position(SCRATCH_P, 0, located.edge, located.u);
+            skeleton.evaluate_segment_tangent(SCRATCH_T, 0, located.edge, located.u);
+            shoot_normalize3(SCRATCH_T, SCRATCH_T[0], SCRATCH_T[1], SCRATCH_T[2]);
+            return located;
+        }
+        const p = axes[mother].points;
+        const a = k * 3, b = (k + 1) * 3;
+        SCRATCH_P[0] = p[a] + (p[b] - p[a]) * u;
+        SCRATCH_P[1] = p[a + 1] + (p[b + 1] - p[a + 1]) * u;
+        SCRATCH_P[2] = p[a + 2] + (p[b + 2] - p[a + 2]) * u;
+        shoot_normalize3(SCRATCH_T, p[b] - p[a], p[b + 1] - p[a + 1], p[b + 2] - p[a + 2]);
+        return null;
+    };
+
+    /**
+     * A lateral from bud `node` at `u` on unit `k` of `mother` (`-1` for the carrier), or -1 when the bud cannot grow:
+     * knocked out on a plagiotropic mother, or blocked by framework wood.
+     */
+    const spawn = (system, mother, k, u, node, order, mean_length, short, season, candidates) => {
+        const c = carriers[system];
+        const rule = c.rule;
+        const located = bud_site(system, mother, k, u);
+        const px = SCRATCH_P[0], py = SCRATCH_P[1], pz = SCRATCH_P[2];
+        const mtx = SCRATCH_T[0], mty = SCRATCH_T[1], mtz = SCRATCH_T[2];
+        const mother_phase = mother < 0 ? skeleton.branch_phase_hash[c.carrier] : axes[mother].phase;
+        const mother_generator = mother < 0 ? rule.source : axes[mother].generator;
+
+        // radial direction at the bud: a frame around the mother's tangent turned by the leaf spiral
+        shoot_perpendicular3(SCRATCH_R, mtx, mty, mtz);
+        const rx0 = SCRATCH_R[0], ry0 = SCRATCH_R[1], rz0 = SCRATCH_R[2];
+        const sx0 = mty * rz0 - mtz * ry0;
+        const sy0 = mtz * rx0 - mtx * rz0;
+        const sz0 = mtx * ry0 - mty * rx0;
+        const ins = shoot_order_value(rule.insertion_angle, order - 1) * (0.85 + 0.3 * rng());
+        const cos_i = Math.cos(ins), sin_i = Math.sin(ins);
+        // a plagiotropic mother breaks no bud into the downward cone (its ventral knockout): the bud turns by the golden
+        // angle until it clears it, or does not break
+        const plagio = species.branches[mother_generator].plagiotropism;
+        const ventral_cos = plagio > 0 ? Math.cos(plagio * Math.PI * 0.5) : Infinity;
+        let phi = phyllotaxis_sample_angle(rule.phyllotaxis_mode, node, 1, mother_phase * PI2) + (rng() - 0.5) * 0.4;
+        let tx = 0, ty = 0, tz = 0;
+        let cleared = false;
+        for (let attempt = 0; attempt < 5 && !cleared; attempt++, phi += GOLDEN_ANGLE) {
+            const drx = Math.cos(phi) * rx0 + Math.sin(phi) * sx0;
+            const dry = Math.cos(phi) * ry0 + Math.sin(phi) * sy0;
+            const drz = Math.cos(phi) * rz0 + Math.sin(phi) * sz0;
+            tx = cos_i * mtx + sin_i * drx;
+            ty = cos_i * mty + sin_i * dry;
+            tz = cos_i * mtz + sin_i * drz;
+            cleared = -ty / Math.max(1e-9, Math.hypot(tx, ty, tz)) <= ventral_cos;
+        }
+        if (!cleared) return -1;
+        shoot_normalize3(SCRATCH_H, tx, ty, tz);
+
+        const len = short ? rule.short_shoot_growth : shoot_sample_unit_length(rng, mean_length, order, rule);
+        SCRATCH_A[0] = px;
+        SCRATCH_A[1] = py;
+        SCRATCH_A[2] = pz;
+        SCRATCH_B[0] = px + SCRATCH_H[0] * len;
+        SCRATCH_B[1] = py + SCRATCH_H[1] * len;
+        SCRATCH_B[2] = pz + SCRATCH_H[2] * len;
+        const exempt_branch = mother < 0 ? c.carrier : -1;
+        const exempt_edge = located !== null ? located.edge : -1;
+        // a shoot does not grow through wood that was there first, its own junction aside
+        if (framework.hits(SCRATCH_A, SCRATCH_B, shoot_radius(len, 0), exempt_branch, exempt_edge)) return -1;
+
+        const light = field.irradiance_at(px, py, pz);
+        axes.push({
+            system, parent: mother, parent_unit: k, u, node, order, short,
+            generator: short ? rule.short_target : rule.target,
+            phase: rng(),
+            units: [len],
+            unit_seasons: [season],
+            points: [px, py, pz, SCRATCH_B[0], SCRATCH_B[1], SCRATCH_B[2]],
+            radii: [],
+            anchor_edge: located !== null ? located.edge : -1,
+            exempt_branch,
+            heading: [SCRATCH_H[0], SCRATCH_H[1], SCRATCH_H[2]],
+            taken: [null],
+            birth: season,
+            alive: true,
+            key: 0
+        });
+        const m = axes.length - 1;
+        if (!short) {
+            const p = survival_at(light, system);
+            candidates.push({ axis: m, p, key: shed_rank(p, order, len, 0, rule, rng) });
+            axes[m].taken[0] = sylleptic(system, m, 0, len, order, season, candidates);
+        }
+        return m;
+    };
+
+    /** Buds of a unit grown this season that grow out at once; the buds they spent, by zone */
+    const sylleptic = (system, mother, k, unit_length, order, season, candidates) => {
+        const rule = carriers[system].rule;
+        if (order + 1 > rule.max_order) return null;
+        let taken = null;
+        let node = 0;
+        for (let z = 0; z < rule.zones.length; z++) {
+            const zone = rule.zones[z];
+            const n = zone.bud_count(unit_length, order);
+            const p = shoot_order_value(zone.sylleptic, order);
+            if (p > 0) {
+                const count = binomial(rng, n, p);
+                if (taken === null) taken = new Array(rule.zones.length).fill(0);
+                taken[z] = count;
+                const mean = lateral_mean(zone, order, unit_length);
+                for (let j = 0; j < count; j++) {
+                    const u = lerp_u(zone.u_max, zone.u_min, (j + rng()) / Math.max(1, count));
+                    spawn(system, mother, k, u, node + j, order + 1, mean, false, season, candidates);
+                }
+            }
+            node += n;
+        }
+        return taken;
+    };
+
+    /** Unit `k` of a mother, grown last season, bursts its buds */
+    const burst = (system, mother, k, unit_length, order, taken, season, candidates) => {
+        const rule = carriers[system].rule;
+        if (order + 1 > rule.max_order) return;
+        let node = 0;
+        for (let z = 0; z < rule.zones.length; z++) {
+            const zone = rule.zones[z];
+            const all = zone.bud_count(unit_length, order);
+            const n = all - (taken !== null ? taken[z] : 0);
+            const p_long = shoot_order_value(zone.long, order);
+            const p_short = shoot_order_value(zone.short, order);
+            let n_long = 0;
+            let n_short = 0;
+            if (p_short > 0) {
+                for (let i = 0; i < n; i++) {
+                    const r = rng();
+                    if (r < p_long) n_long++;
+                    else if (r < p_long + p_short) n_short++;
+                }
+            } else {
+                n_long = binomial(rng, n, p_long);
+            }
+            const mean = lateral_mean(zone, order, unit_length);
+            for (let j = 0; j < n_long; j++) {
+                spawn(system, mother, k, lerp_u(zone.u_max, zone.u_min, (j + rng()) / Math.max(1, n_long)), node + j, order + 1, mean, false, season, candidates);
+            }
+            for (let j = 0; j < n_short; j++) {
+                spawn(system, mother, k, lerp_u(zone.u_max, zone.u_min, (j + rng()) / Math.max(1, n_short)), node + n_long + j, order + 1, 0, true, season, candidates);
+            }
+            node += all;
+        }
+    };
+
+    for (let season = 0; season < seasons; season++) {
+        // 1. Light from last season's leaves
+        if (season > 0) {
+            field.clear();
+            deposit_leaves(field, species, carriers, axes, season - 1, leafy, leaf_area_each, leaf_survival);
+            field.solve(growth.leaf_clumping);
+        }
+
+        /** @type {Array<{axis: number, p: number, key: number}>} key: the shedding rank, the highest kept */
+        const candidates = [];
+
+        // 2. Every living long axis extends by a terminal unit, a candidate for shedding with its whole axis
+        const extended = [];
+        const count_before = axes.length;
+        for (let m = 0; m < count_before; m++) {
+            const axis = axes[m];
+            if (!axis.alive || axis.short || axis.birth >= season) continue;
+            const rule = carriers[axis.system].rule;
+            const cfg = species.branches[axis.generator];
+            const n = axis.units.length;
+            const pts = axis.points;
+            const tip = n * 3;
+            const light = field.irradiance_at(pts[tip], pts[tip + 1], pts[tip + 2]);
+            shoot_outward3(SCRATCH_O, skeleton, pts[tip], pts[tip + 1], pts[tip + 2]);
+            const zig = cfg.internode_zigzag;
+            const h = axis.heading;
+            shoot_normalize3(
+                SCRATCH_H,
+                h[0] + cfg.phototropism * 0.5 * SCRATCH_O[0] + (rng() * 2 - 1) * zig,
+                h[1] + cfg.phototropism * 0.5 * SCRATCH_O[1] - cfg.gravitropism * 0.5 + (rng() * 2 - 1) * zig,
+                h[2] + cfg.phototropism * 0.5 * SCRATCH_O[2] + (rng() * 2 - 1) * zig
+            );
+            const prev = axis.units[n - 1];
+            const mean = shoot_order_value(rule.terminal_length, axis.order) + shoot_order_value(rule.terminal_length_slope, axis.order) * prev;
+            const len = shoot_sample_unit_length(rng, mean, axis.order, rule);
+            SCRATCH_A[0] = pts[tip];
+            SCRATCH_A[1] = pts[tip + 1];
+            SCRATCH_A[2] = pts[tip + 2];
+            SCRATCH_B[0] = pts[tip] + SCRATCH_H[0] * len;
+            SCRATCH_B[1] = pts[tip + 1] + SCRATCH_H[1] * len;
+            SCRATCH_B[2] = pts[tip + 2] + SCRATCH_H[2] * len;
+            if (framework.hits(SCRATCH_A, SCRATCH_B, shoot_radius(len, 0), axis.exempt_branch, axis.anchor_edge)) continue;
+            axis.units.push(len);
+            axis.unit_seasons.push(season);
+            axis.taken.push(null);
+            pts.push(SCRATCH_B[0], SCRATCH_B[1], SCRATCH_B[2]);
+            h[0] = SCRATCH_H[0];
+            h[1] = SCRATCH_H[1];
+            h[2] = SCRATCH_H[2];
+            const p_ext = survival_at(light, axis.system);
+            candidates.push({ axis: m, p: p_ext, key: shed_rank(p_ext, axis.order, len, season - axis.birth, rule, rng) });
+            extended.push(m);
+        }
+
+        // 3. Short shoots live on, a year's growth each, or die
+        for (let m = 0; m < count_before; m++) {
+            const axis = axes[m];
+            if (!axis.alive || !axis.short || axis.birth >= season) continue;
+            const rule = carriers[axis.system].rule;
+            const pts = axis.points;
+            const tip = axis.units.length * 3;
+            const light = field.irradiance_at(pts[tip], pts[tip + 1], pts[tip + 2]);
+            if (rng() < rule.short_shoot_survival * Math.min(1, growth.net_yield(light))) {
+                const g = rule.short_shoot_growth;
+                axis.units.push(g);
+                axis.unit_seasons.push(season);
+                pts.push(pts[tip] + axis.heading[0] * g, pts[tip + 1] + axis.heading[1] * g, pts[tip + 2] + axis.heading[2] * g);
+            } else {
+                axis.alive = false;
+            }
+        }
+
+        // 4. Units grown last season burst their buds: on the carriers and on every living long axis
+        for (let s = 0; s < carriers.length; s++) {
+            const c = carriers[s];
+            const k = season - 1 - c.first_season;
+            if (k >= 0 && k < c.units.length) {
+                burst(s, -1, k, c.units[k], c.rule.carrier_order, carrier_taken[s][k], season, candidates);
+            }
+        }
+        for (let m = 0; m < count_before; m++) {
+            const axis = axes[m];
+            if (!axis.alive || axis.short || axis.birth >= season) continue;
+            const k = axis.unit_seasons.lastIndexOf(season - 1);
+            if (k >= 0) {
+                burst(axis.system, m, k, axis.units[k], axis.order, axis.taken[k], season, candidates);
+            }
+        }
+
+        // 5. This season's units branch at once where their buds are sylleptic: the carriers' and the extensions'
+        for (let s = 0; s < carriers.length; s++) {
+            const c = carriers[s];
+            const k = season - c.first_season;
+            if (k >= 0 && k < c.units.length) {
+                carrier_taken[s][k] = sylleptic(s, -1, k, c.units[k], c.rule.carrier_order, season, candidates);
+            }
+        }
+        for (let i = 0; i < extended.length; i++) {
+            const m = extended[i];
+            const axis = axes[m];
+            const k = axis.units.length - 1;
+            axis.taken[k] = sylleptic(axis.system, m, k, axis.units[k], axis.order, season, candidates);
+        }
+
+        // 6. Shedding: the best-lit share of this season's new shoots survives
+        let expected = remainder;
+        for (let i = 0; i < candidates.length; i++) expected += candidates[i].p;
+        const keep = Math.floor(expected);
+        remainder = expected - keep;
+        candidates.sort((a, b) => b.key - a.key);
+        for (let i = keep; i < candidates.length; i++) {
+            axes[candidates[i].axis].alive = false;
+        }
+        // a dead mother takes everything on it; mothers come first
+        cascade(axes);
+
+        // 7. The wood thickens with what it now carries, and what it has grown into dies
+        girth.update(axes, season);
+        framework = new ShootFrameworkHash(skeleton, framework_segments);
+        for (let m = 0; m < axes.length; m++) {
+            const axis = axes[m];
+            if (!axis.alive) continue;
+            if (axis.parent >= 0 && !axes[axis.parent].alive) {
+                axis.alive = false;
+                continue;
+            }
+            const pts = axis.points;
+            const r = axis.radii;
+            for (let k = 0; k < axis.units.length; k++) {
+                SCRATCH_A[0] = pts[k * 3];
+                SCRATCH_A[1] = pts[k * 3 + 1];
+                SCRATCH_A[2] = pts[k * 3 + 2];
+                SCRATCH_B[0] = pts[k * 3 + 3];
+                SCRATCH_B[1] = pts[k * 3 + 4];
+                SCRATCH_B[2] = pts[k * 3 + 5];
+                if (framework.hits(SCRATCH_A, SCRATCH_B, Math.max(r[k], r[k + 1]), axis.exempt_branch, axis.anchor_edge)) {
+                    axis.alive = false;
+                    break;
+                }
+            }
+        }
+    }
+
+    // The living axes, a mother before its laterals
+    const index = new Int32Array(axes.length).fill(-1);
+    /** @type {ShootAxis[]} */
+    const living = [];
+    for (let m = 0; m < axes.length; m++) {
+        const axis = axes[m];
+        if (!axis.alive) continue;
+        index[m] = living.length;
+        living.push({
+            system: axis.system,
+            parent: axis.parent < 0 ? -1 : index[axis.parent],
+            parent_unit: axis.parent_unit,
+            u: axis.u,
+            node: axis.node,
+            order: axis.order,
+            short: axis.short,
+            generator: axis.generator,
+            phase: axis.phase,
+            units: axis.units,
+            unit_seasons: axis.unit_seasons,
+            points: axis.points,
+            radii: axis.radii,
+            anchor_edge: axis.anchor_edge
+        });
+    }
+    return living;
+}
+
+/**
+ * Kills every axis whose mother has died; mothers come before their laterals.
+ * @param {Array<{parent: number, alive: boolean}>} axes
+ */
+function cascade(axes) {
+    for (let m = 0; m < axes.length; m++) {
+        const parent = axes[m].parent;
+        if (axes[m].alive && parent >= 0 && !axes[parent].alive) axes[m].alive = false;
+    }
+}
+
+/**
+ * A light field over the framework and {@link LIGHT_FIELD_MARGIN} around it.
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number} cell
+ * @returns {ShootLightField}
+ */
+function make_light_field(skeleton, cell) {
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    const p = new Float32Array(3);
+    for (let v = 0; v < skeleton.node_count; v++) {
+        skeleton.node_read_position(p, 0, v);
+        for (let i = 0; i < 3; i++) {
+            min[i] = Math.min(min[i], p[i]);
+            max[i] = Math.max(max[i], p[i]);
+        }
+    }
+    for (let i = 0; i < 3; i++) {
+        min[i] -= LIGHT_FIELD_MARGIN;
+        max[i] += LIGHT_FIELD_MARGIN;
+    }
+    return new ShootLightField(min, max, cell);
+}
+
+/**
+ * Puts the leaves alive in `season` into `field`: on each leaf-bearing unit young enough to keep them, the unit's leaves
+ * times the share of that age still alive, spread along it; a short shoot's at its tip. `leaf_area_each` is one leaf's
+ * area (m^2).
+ */
+function deposit_leaves(field, species, carriers, axes, season, leafy, leaf_area_each, leaf_survival) {
+    const L = leaf_survival.length;
+    for (let s = 0; s < carriers.length; s++) {
+        const c = carriers[s];
+        if (!leafy.has(c.rule.source)) continue;
+        for (let k = 0; k < c.units.length; k++) {
+            const age = season - (c.first_season + k);
+            if (age < 0 || age >= L) continue;
+            const area = foliage_unit_leaf_count(species, false, c.units[k]) * leaf_area_each * leaf_survival[age];
+            field.deposit_segment(c.points.subarray(k * 3, k * 3 + 3), c.points.subarray(k * 3 + 3, k * 3 + 6), area);
+        }
+    }
+    for (let m = 0; m < axes.length; m++) {
+        const axis = axes[m];
+        if (!axis.alive || !leafy.has(axis.generator)) continue;
+        const pts = axis.points;
+        if (axis.short) {
+            const tip = axis.units.length * 3;
+            field.deposit(pts[tip], pts[tip + 1], pts[tip + 2], foliage_unit_leaf_count(species, true, 0) * leaf_area_each);
+            continue;
+        }
+        for (let k = 0; k < axis.units.length; k++) {
+            const age = season - axis.unit_seasons[k];
+            if (age < 0 || age >= L) continue;
+            const area = foliage_unit_leaf_count(species, false, axis.units[k]) * leaf_area_each * leaf_survival[age];
+            SCRATCH_A[0] = pts[k * 3];
+            SCRATCH_A[1] = pts[k * 3 + 1];
+            SCRATCH_A[2] = pts[k * 3 + 2];
+            SCRATCH_B[0] = pts[k * 3 + 3];
+            SCRATCH_B[1] = pts[k * 3 + 4];
+            SCRATCH_B[2] = pts[k * 3 + 5];
+            field.deposit_segment(SCRATCH_A, SCRATCH_B, area);
+        }
+    }
+}
+
+/**
+ * Rank of a new shoot for surviving, the highest kept: the log of its chance in the light it has, plus oak's shedding
+ * rank, by which older axes, lower orders and longer units hold on, and the highest orders and short shoots are shed
+ * first [Buck-Sorlin & Bell 1998 p. 388]. The rank's weights are chosen.
+ *
+ * @param {number} p chance of surviving in its light
+ * @param {number} order
+ * @param {number} length metres
+ * @param {number} age seasons its axis has lived
+ * @param {import("../config/ShootSystemRule.js").ShootSystemRule} rule
+ * @param {function():number} rng
+ * @returns {number}
+ */
+function shed_rank(p, order, length, age, rule, rng) {
+    return Math.log(Math.max(1e-6, p)) + 1.5 * age - 0.5 * order + Math.log(length / rule.mean_unit_length) + 0.5 * rng();
+}
+
+/**
+ * Mean length (m) of the first unit of a long lateral from `zone`, grown on a mother of `order` from a unit
+ * `unit_length` long.
+ * @param {import("../config/ShootBudZone.js").ShootBudZone} zone
+ * @param {number} order
+ * @param {number} unit_length
+ * @returns {number}
+ */
+function lateral_mean(zone, order, unit_length) {
+    return shoot_order_value(zone.length, order) + shoot_order_value(zone.length_slope, order) * unit_length;
+}
+
+/**
+ * @param {function():number} rng
+ * @param {number} n
+ * @param {number} p
+ * @returns {number}
+ */
+function binomial(rng, n, p) {
+    let k = 0;
+    for (let i = 0; i < n; i++) {
+        if (rng() < p) k++;
+    }
+    return k;
+}
+
+/**
+ * @param {number} a
+ * @param {number} b
+ * @param {number} t
+ * @returns {number}
+ */
+function lerp_u(a, b, t) {
+    return a + (b - a) * clamp(t, 0, 1);
+}

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

@@ -1,10 +1,26 @@
 /**
- * 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,
@@ -13,12 +29,12 @@
  *   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: import("./TreeSkeleton.js").TreeSkeleton, max_joints?: number): {
+export function tree_skeleton_assign_skin_joints(skeleton: import("./TreeSkeleton.js").TreeSkeleton, species: TreeSpeciesConfig): {
     joint_count: number;
     joint_vertex_ids: Int32Array;
     joint_parents: Int32Array;
@@ -26,8 +42,8 @@ export function tree_skeleton_assign_skin_joints(skeleton: import("./TreeSkeleto
     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;
 };
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
 //# sourceMappingURL=tree_skeleton_assign_skin_joints.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tree_skeleton_assign_skin_joints.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_assign_skin_joints.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2DAfW,OAAO,mBAAmB,EAAE,YAAY,eACxC,MAAM,GACJ;IACZ,WAAe,EAAE,MAAM,CAAC;IACxB,gBAAoB,EAAE,UAAU,CAAC;IACjC,aAAiB,EAAE,UAAU,CAAC;IAC9B,eAAmB,EAAE,YAAY,CAAC;IAClC,cAAkB,EAAE,YAAY,CAAC;IACjC,YAAgB,EAAE,UAAU,CAAC;IAC7B,YAAgB,EAAE,YAAY,CAAC;IAC/B,aAAiB,EAAE,YAAY,CAAC;IAChC,WAAe,EAAE,YAAY,CAAC;IAC9B,aAAiB,EAAE,YAAY,CAAA;CAC5B,CAsLH"}
+{"version":3,"file":"tree_skeleton_assign_skin_joints.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/tree_skeleton_assign_skin_joints.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,2DAfW,OAAO,mBAAmB,EAAE,YAAY,WACxC,iBAAiB,GACf;IACZ,WAAe,EAAE,MAAM,CAAC;IACxB,gBAAoB,EAAE,UAAU,CAAC;IACjC,aAAiB,EAAE,UAAU,CAAC;IAC9B,eAAmB,EAAE,YAAY,CAAC;IAClC,cAAkB,EAAE,YAAY,CAAC;IACjC,YAAgB,EAAE,UAAU,CAAC;IAC7B,YAAgB,EAAE,YAAY,CAAC;IAC/B,gBAAoB,EAAE,YAAY,CAAC;IACnC,uBAA2B,EAAE,YAAY,CAAA;CACtC,CAiMH;kCA9OiC,gCAAgC"}