@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -0,0 +1,101 @@
+/**
+ * Ontogenetic maturity of atlas variant `variant`: 0 for the juvenile apical flush, 1 for mature basal foliage.
+ *
+ * @param {number} variant
+ * @param {number} variant_count
+ * @returns {number}
+ */
+export function foliage_variant_maturity(variant: number, variant_count: number): number;
+/**
+ * How far a tile of maturity `mu` has senesced at the tree's `senescence`. Tiles are staggered, so an autumn crown
+ * shows leaf-to-leaf diversity: juvenile and mature tiles run ahead of the ones in between.
+ *
+ * @param {number} senescence `[0, 1]`
+ * @param {number} mu tile maturity, see {@link foliage_variant_maturity}
+ * @returns {number} the tile's senescence stage `sigma_k`, `[0, 1]`
+ */
+export function foliage_variant_senescence(senescence: number, mu: number): number;
+/**
+ * The tree senescence at which a tile of maturity `mu` has lost the chlorophyll of its exposed lamina: its nutrients
+ * are resorbed and the abscission layer can close, so the first of its leaves may fall. Solves
+ * {@link foliage_variant_senescence} `= 1 / FOLIAGE_CHLOROPHYLL_LOSS_RATE` for the tree's senescence.
+ *
+ * @param {number} mu
+ * @returns {number} `(0, 1]`
+ */
+export function foliage_variant_abscission_onset(mu: number): number;
+/**
+ * Ontogenetic maturity of a leaf, `[0, 1]`: acropetal along its shoot (the distal tip is juvenile, basal nodes
+ * mature), and younger on the crown's shell than in its shaded core. It picks the atlas variant the leaf shows.
+ *
+ * @param {number} u_shoot position along the carrying shoot's leafy span, 0 at its base, 1 at its tip
+ * @param {number} rho_shell see {@link foliage_crown_rho}
+ * @param {number} jitter per-leaf jitter in `[-1, 1]`; 0 for the expected leaf
+ * @returns {number}
+ */
+export function foliage_leaf_maturity(u_shoot: number, rho_shell: number, jitter: number): number;
+/**
+ * Atlas variant shown by a leaf of maturity `maturity`.
+ *
+ * @param {number} maturity
+ * @param {number} variant_count
+ * @returns {number}
+ */
+export function foliage_leaf_variant(maturity: number, variant_count: number): number;
+/**
+ * Ellipsoidal radius of a point in the grown crown: 0 at its centre, 1 on its shell and beyond.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
+export function foliage_crown_rho(skeleton: import("./TreeSkeleton.js").TreeSkeleton, x: number, y: number, z: number): number;
+/**
+ * Height of `y` across the configured crown: 0 at its base, 1 at its top.
+ *
+ * @param {import("../config/CrownConfig.js").CrownConfig} crown
+ * @param {number} y
+ * @returns {number}
+ */
+export function foliage_crown_height_norm(crown: import("../config/CrownConfig.js").CrownConfig, y: number): number;
+/**
+ * How exposed a leaf is to sun, cold and wind, from 0 (shaded interior) to 1 (crown surface, high up). The crown
+ * shell term is the leaf's ellipsoidal radius in the crown, `rho`, the height term its height across the crown.
+ *
+ * @param {number} rho_shell normalized distance from the crown centre, `[0, 1]`
+ * @param {number} h_norm normalized height in the crown, `[0, 1]`
+ * @returns {number}
+ */
+export function foliage_sun_exposure(rho_shell: number, h_norm: number): number;
+/**
+ * The senescence at which a leaf is shed. No leaf falls before its tile has lost the chlorophyll of its exposed
+ * lamina (`onset`, {@link foliage_variant_abscission_onset}); after that, outer and apical leaves go first: a leaf at
+ * the crown's surface and at its shoot's tip (`sun_exposure = u_shoot = 1`) falls at `onset`, a shaded basal one last,
+ * at 1.
+ *
+ * @param {number} onset its tile's abscission onset
+ * @param {number} sun_exposure see {@link foliage_sun_exposure}
+ * @param {number} u_shoot position along the carrying shoot's leafy span, 0 at its base, 1 at its tip
+ * @returns {number} in `[onset, 1]`
+ */
+export function foliage_abscission_threshold(onset: number, sun_exposure: number, u_shoot: number): number;
+/**
+ * How far a still-attached leaf has dried, `[0, 1)`: 0 while its tile still has chlorophyll (it is turgid), rising
+ * from its tile's onset to 1 at its own abscission threshold.
+ *
+ * @param {number} senescence
+ * @param {number} onset its tile's abscission onset
+ * @param {number} threshold see {@link foliage_abscission_threshold}
+ * @returns {number}
+ */
+export function foliage_leaf_dryness(senescence: number, onset: number, threshold: number): number;
+/**
+ * Rate at which senescence strips chlorophyll from the exposed lamina in the leaf pigment model
+ * (`make_foliage_material`): a tile at senescence stage `sigma_k` retains `1 - sigma_k * (rate - shielding)` of its
+ * chlorophyll, so its most exposed lamina is bare of it once `sigma_k` reaches `1 / rate`.
+ * @type {number}
+ */
+export const FOLIAGE_CHLOROPHYLL_LOSS_RATE: number;
+//# sourceMappingURL=foliage_senescence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"foliage_senescence.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/foliage_senescence.js"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,kDAJW,MAAM,iBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,uDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;GAOG;AACH,qDAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;;GAQG;AACH,+CALW,MAAM,aACN,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,+CAJW,MAAM,iBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,4CANW,OAAO,mBAAmB,EAAE,YAAY,KACxC,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;GAMG;AACH,iDAJW,OAAO,0BAA0B,EAAE,WAAW,KAC9C,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,gDAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,oDALW,MAAM,gBACN,MAAM,WACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;GAQG;AACH,iDALW,MAAM,SACN,MAAM,aACN,MAAM,GACJ,MAAM,CASlB;AAlJD;;;;;GAKG;AACH,4CAFU,MAAM,CAEkC"}

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

@@ -0,0 +1,149 @@
+import { clamp } from "../../../core/math/clamp.js";
+
+/**
+ * Rate at which senescence strips chlorophyll from the exposed lamina in the leaf pigment model
+ * (`make_foliage_material`): a tile at senescence stage `sigma_k` retains `1 - sigma_k * (rate - shielding)` of its
+ * chlorophyll, so its most exposed lamina is bare of it once `sigma_k` reaches `1 / rate`.
+ * @type {number}
+ */
+export const FOLIAGE_CHLOROPHYLL_LOSS_RATE = 1.36;
+
+/**
+ * Ontogenetic maturity of atlas variant `variant`: 0 for the juvenile apical flush, 1 for mature basal foliage.
+ *
+ * @param {number} variant
+ * @param {number} variant_count
+ * @returns {number}
+ */
+export function foliage_variant_maturity(variant, variant_count) {
+	return variant_count > 1 ? variant / (variant_count - 1) : 0.65;
+}
+
+/**
+ * How far a tile of maturity `mu` has senesced at the tree's `senescence`. Tiles are staggered, so an autumn crown
+ * shows leaf-to-leaf diversity: juvenile and mature tiles run ahead of the ones in between.
+ *
+ * @param {number} senescence `[0, 1]`
+ * @param {number} mu tile maturity, see {@link foliage_variant_maturity}
+ * @returns {number} the tile's senescence stage `sigma_k`, `[0, 1]`
+ */
+export function foliage_variant_senescence(senescence, mu) {
+	if (senescence <= 0.0) {
+		return 0.0;
+	}
+	return clamp(senescence * (0.80 + 0.36 * Math.abs(mu - 0.35)) + senescence * senescence * 0.12, 0.0, 1.0);
+}
+
+/**
+ * The tree senescence at which a tile of maturity `mu` has lost the chlorophyll of its exposed lamina: its nutrients
+ * are resorbed and the abscission layer can close, so the first of its leaves may fall. Solves
+ * {@link foliage_variant_senescence} `= 1 / FOLIAGE_CHLOROPHYLL_LOSS_RATE` for the tree's senescence.
+ *
+ * @param {number} mu
+ * @returns {number} `(0, 1]`
+ */
+export function foliage_variant_abscission_onset(mu) {
+	const a = 0.80 + 0.36 * Math.abs(mu - 0.35);
+	const c = 1.0 / FOLIAGE_CHLOROPHYLL_LOSS_RATE;
+	// 0.12 s^2 + a s - c = 0
+	return Math.min(1.0, (-a + Math.sqrt(a * a + 4.0 * 0.12 * c)) / (2.0 * 0.12));
+}
+
+/**
+ * Ontogenetic maturity of a leaf, `[0, 1]`: acropetal along its shoot (the distal tip is juvenile, basal nodes
+ * mature), and younger on the crown's shell than in its shaded core. It picks the atlas variant the leaf shows.
+ *
+ * @param {number} u_shoot position along the carrying shoot's leafy span, 0 at its base, 1 at its tip
+ * @param {number} rho_shell see {@link foliage_crown_rho}
+ * @param {number} jitter per-leaf jitter in `[-1, 1]`; 0 for the expected leaf
+ * @returns {number}
+ */
+export function foliage_leaf_maturity(u_shoot, rho_shell, jitter) {
+	return clamp(0.66 * (1.0 - u_shoot) + 0.24 * (1.0 - rho_shell) + 0.05 + 0.07 * jitter, 0.0, 1.0);
+}
+
+/**
+ * Atlas variant shown by a leaf of maturity `maturity`.
+ *
+ * @param {number} maturity
+ * @param {number} variant_count
+ * @returns {number}
+ */
+export function foliage_leaf_variant(maturity, variant_count) {
+	return clamp(Math.floor(maturity * variant_count), 0, variant_count - 1);
+}
+
+/**
+ * Ellipsoidal radius of a point in the grown crown: 0 at its centre, 1 on its shell and beyond.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
+export function foliage_crown_rho(skeleton, x, y, z) {
+	const c = skeleton.crown_center;
+	const r = skeleton.crown_radii;
+	const dx = (x - c[0]) / Math.max(0.5, r[0]);
+	const dy = (y - c[1]) / Math.max(0.5, r[1]);
+	const dz = (z - c[2]) / Math.max(0.5, r[2]);
+	return clamp(Math.sqrt(dx * dx + dy * dy + dz * dz), 0.0, 1.0);
+}
+
+/**
+ * Height of `y` across the configured crown: 0 at its base, 1 at its top.
+ *
+ * @param {import("../config/CrownConfig.js").CrownConfig} crown
+ * @param {number} y
+ * @returns {number}
+ */
+export function foliage_crown_height_norm(crown, y) {
+	return clamp((y - crown.base_height) / Math.max(0.1, crown.height), 0.0, 1.0);
+}
+
+/**
+ * How exposed a leaf is to sun, cold and wind, from 0 (shaded interior) to 1 (crown surface, high up). The crown
+ * shell term is the leaf's ellipsoidal radius in the crown, `rho`, the height term its height across the crown.
+ *
+ * @param {number} rho_shell normalized distance from the crown centre, `[0, 1]`
+ * @param {number} h_norm normalized height in the crown, `[0, 1]`
+ * @returns {number}
+ */
+export function foliage_sun_exposure(rho_shell, h_norm) {
+	return clamp(0.62 * rho_shell + 0.38 * h_norm, 0.0, 1.0);
+}
+
+/**
+ * The senescence at which a leaf is shed. No leaf falls before its tile has lost the chlorophyll of its exposed
+ * lamina (`onset`, {@link foliage_variant_abscission_onset}); after that, outer and apical leaves go first: a leaf at
+ * the crown's surface and at its shoot's tip (`sun_exposure = u_shoot = 1`) falls at `onset`, a shaded basal one last,
+ * at 1.
+ *
+ * @param {number} onset its tile's abscission onset
+ * @param {number} sun_exposure see {@link foliage_sun_exposure}
+ * @param {number} u_shoot position along the carrying shoot's leafy span, 0 at its base, 1 at its tip
+ * @returns {number} in `[onset, 1]`
+ */
+export function foliage_abscission_threshold(onset, sun_exposure, u_shoot) {
+	const exposure_order = 0.5 * (clamp(sun_exposure, 0.0, 1.0) + clamp(u_shoot, 0.0, 1.0));
+	return onset + (1.0 - onset) * (1.0 - exposure_order);
+}
+
+/**
+ * How far a still-attached leaf has dried, `[0, 1)`: 0 while its tile still has chlorophyll (it is turgid), rising
+ * from its tile's onset to 1 at its own abscission threshold.
+ *
+ * @param {number} senescence
+ * @param {number} onset its tile's abscission onset
+ * @param {number} threshold see {@link foliage_abscission_threshold}
+ * @returns {number}
+ */
+export function foliage_leaf_dryness(senescence, onset, threshold) {
+	const span = threshold - onset;
+	if (span <= 1e-9) {
+		// it falls the moment its tile's chlorophyll goes: attached, it has not begun to dry
+		return 0.0;
+	}
+	return clamp((senescence - onset) / span, 0.0, 1.0);
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Leaves an annual unit `length` metres long bears, before any have fallen: `leaves_per_unit + leaves_per_metre *
+ * length`, or a short shoot's `leaves_per_short_shoot`, every year.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {boolean} short_shoot
+ * @param {number} length
+ * @returns {number}
+ */
+export function foliage_unit_leaf_count(species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, short_shoot: boolean, length: number): number;
+/**
+ * @typedef {Object} FoliageUnitCardSpan
+ * @property {number} age years since the unit grew, 0 for this year's
+ * @property {number} t_min where the cards hang, as `t_norm` along the branch: card `k` of `count` hangs at
+ *           `lerp(t_min, t_max, (k + slot) / count)`, the slot by what a card draws; a short shoot's all at its tip
+ * @property {number} t_max
+ * @property {number} count cards
+ * @property {number} scale card size relative to the species' card
+ * @property {number} u_min where along the branch's leafy growth the first card's leaves sit, 0 at its oldest end, 1 at
+ *           its tip; card `k` is at `lerp(u_min, u_max, (k + 0.5) / count)`. Equal ends draw one place for every card.
+ * @property {number} u_max
+ * @property {number} unit_t_min the unit the cards grow on, whose wood carries them
+ * @property {number} unit_t_max
+ */
+/**
+ * Leaf cards of foliage `rule` on branch `b`, grown by annual units (`TreeSkeleton.branch_unit_count[b] > 0`): one
+ * span per unit young enough to carry leaves (`FoliageConfig.leaf_survival`), oldest first.
+ *
+ * A unit carries its leaves, `leaves_per_unit + leaves_per_metre *` its length (a short shoot:
+ * `leaves_per_short_shoot` a year), kept by `leaf_survival[age]`, over the leaves a card draws
+ * (`foliage_tile_layout`): one card a leaf, or a needle shoot's needles a card. The count is rounded with a dither per
+ * branch and age so it is exact on average. Every card is the species' card, so leaves keep their size whatever the
+ * shoot. A short shoot's leaves are crowded at its tip, and each short shoot draws its own leaf maturity; elsewhere
+ * maturity follows the card's place along the branch's leafy growth.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {number} b
+ * @param {import("../config/FoliageSpawnRule.js").FoliageSpawnRule} rule
+ * @param {number} leaves_per_card `FoliageTileLayout.leaves_per_card`
+ * @param {FoliageUnitCardSpan[]} out cleared and filled
+ * @returns {FoliageUnitCardSpan[]} `out`
+ */
+export function foliage_unit_card_spans(skeleton: import("./TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, b: number, rule: import("../config/FoliageSpawnRule.js").FoliageSpawnRule, leaves_per_card: number, out: FoliageUnitCardSpan[]): FoliageUnitCardSpan[];
+export type FoliageUnitCardSpan = {
+    /**
+     * years since the unit grew, 0 for this year's
+     */
+    age: number;
+    /**
+     * where the cards hang, as `t_norm` along the branch: card `k` of `count` hangs at
+     * `lerp(t_min, t_max, (k + slot) / count)`, the slot by what a card draws; a short shoot's all at its tip
+     */
+    t_min: number;
+    t_max: number;
+    /**
+     * cards
+     */
+    count: number;
+    /**
+     * card size relative to the species' card
+     */
+    scale: number;
+    /**
+     * where along the branch's leafy growth the first card's leaves sit, 0 at its oldest end, 1 at
+     * its tip; card `k` is at `lerp(u_min, u_max, (k + 0.5) / count)`. Equal ends draw one place for every card.
+     */
+    u_min: number;
+    u_max: number;
+    /**
+     * the unit the cards grow on, whose wood carries them
+     */
+    unit_t_min: number;
+    unit_t_max: number;
+};
+//# sourceMappingURL=foliage_unit_cards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"foliage_unit_cards.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/foliage_unit_cards.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,iDALW,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,UACP,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDARW,OAAO,mBAAmB,EAAE,YAAY,WACxC,OAAO,gCAAgC,EAAE,iBAAiB,KAC1D,MAAM,QACN,OAAO,+BAA+B,EAAE,gBAAgB,mBACxD,MAAM,OACN,mBAAmB,EAAE,GACnB,mBAAmB,EAAE,CAyCjC;;;;;SAvEa,MAAM;;;;;WACN,MAAM;WAEN,MAAM;;;;WACN,MAAM;;;;WACN,MAAM;;;;;WACN,MAAM;WAEN,MAAM;;;;gBACN,MAAM;gBACN,MAAM"}

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

@@ -0,0 +1,95 @@
+/**
+ * `1 / golden ratio`: the per-age step of the dither that rounds a thinned cohort's card count.
+ * @type {number}
+ */
+const GOLDEN_CONJUGATE = 0.6180339887498949;
+
+/**
+ * Leaves an annual unit `length` metres long bears, before any have fallen: `leaves_per_unit + leaves_per_metre *
+ * length`, or a short shoot's `leaves_per_short_shoot`, every year.
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {boolean} short_shoot
+ * @param {number} length
+ * @returns {number}
+ */
+export function foliage_unit_leaf_count(species, short_shoot, length) {
+    return short_shoot
+        ? species.foliage.leaves_per_short_shoot
+        : species.foliage.leaves_per_unit + species.foliage.leaves_per_metre * length;
+}
+
+/**
+ * @typedef {Object} FoliageUnitCardSpan
+ * @property {number} age years since the unit grew, 0 for this year's
+ * @property {number} t_min where the cards hang, as `t_norm` along the branch: card `k` of `count` hangs at
+ *           `lerp(t_min, t_max, (k + slot) / count)`, the slot by what a card draws; a short shoot's all at its tip
+ * @property {number} t_max
+ * @property {number} count cards
+ * @property {number} scale card size relative to the species' card
+ * @property {number} u_min where along the branch's leafy growth the first card's leaves sit, 0 at its oldest end, 1 at
+ *           its tip; card `k` is at `lerp(u_min, u_max, (k + 0.5) / count)`. Equal ends draw one place for every card.
+ * @property {number} u_max
+ * @property {number} unit_t_min the unit the cards grow on, whose wood carries them
+ * @property {number} unit_t_max
+ */
+
+/**
+ * Leaf cards of foliage `rule` on branch `b`, grown by annual units (`TreeSkeleton.branch_unit_count[b] > 0`): one
+ * span per unit young enough to carry leaves (`FoliageConfig.leaf_survival`), oldest first.
+ *
+ * A unit carries its leaves, `leaves_per_unit + leaves_per_metre *` its length (a short shoot:
+ * `leaves_per_short_shoot` a year), kept by `leaf_survival[age]`, over the leaves a card draws
+ * (`foliage_tile_layout`): one card a leaf, or a needle shoot's needles a card. The count is rounded with a dither per
+ * branch and age so it is exact on average. Every card is the species' card, so leaves keep their size whatever the
+ * shoot. A short shoot's leaves are crowded at its tip, and each short shoot draws its own leaf maturity; elsewhere
+ * maturity follows the card's place along the branch's leafy growth.
+ *
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {number} b
+ * @param {import("../config/FoliageSpawnRule.js").FoliageSpawnRule} rule
+ * @param {number} leaves_per_card `FoliageTileLayout.leaves_per_card`
+ * @param {FoliageUnitCardSpan[]} out cleared and filled
+ * @returns {FoliageUnitCardSpan[]} `out`
+ */
+export function foliage_unit_card_spans(skeleton, species, b, rule, leaves_per_card, out) {
+    out.length = 0;
+    const units = skeleton.branch_unit_count[b];
+    if (units === 0) {
+        return out;
+    }
+    const survival = species.foliage.leaf_survival;
+    const at_tip = rule.short_shoot;
+    const branch_length = skeleton.branch_length[b];
+    const phase = skeleton.branch_phase_hash[b];
+
+    const cohorts = Math.min(units, survival.length);
+    for (let age = cohorts - 1; age >= 0; age--) {
+        const t0 = skeleton.branch_unit_start_t(b, age);
+        const t1 = age > 0 ? skeleton.branch_unit_start_t(b, age - 1) : 1.0;
+        const length = Math.max(0.0, t1 - t0) * branch_length;
+
+        const leaves = foliage_unit_leaf_count(species, rule.short_shoot, length);
+        const dither = (phase + age * GOLDEN_CONJUGATE) % 1.0;
+        const count = Math.floor(leaves * survival[age] / Math.max(1, leaves_per_card) + dither);
+        if (count === 0) continue;
+
+        // the oldest leaf-bearing unit is the base of the branch's leafy growth, this year's its tip
+        const u0 = (cohorts - 1 - age) / cohorts;
+        const u1 = (cohorts - age) / cohorts;
+        out.push({
+            age,
+            t_min: at_tip ? t1 : t0,
+            t_max: t1,
+            count,
+            scale: 1.0,
+            // a short shoot's leaves share its own place
+            u_min: at_tip ? phase : u0,
+            u_max: at_tip ? phase : u1,
+            unit_t_min: t0,
+            unit_t_max: t1
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Length (m) of one extension unit of mean `mean` grown at branching `order`: 1 cm plus a negative binomial (orders
+ * listed in `rule.length_negative_binomial_p`) or Poisson (the rest) count of further centimetres, the models
+ * [BB2000 p. 10-11] fitted to oak, capped at `rule.max_unit_length` of the order.
+ *
+ * @param {function():number} rng
+ * @param {number} mean metres
+ * @param {number} order 1-based
+ * @param {import("../config/ShootSystemRule.js").ShootSystemRule} rule
+ * @returns {number}
+ */
+export function shoot_sample_unit_length(rng: () => number, mean: number, order: number, rule: import("../config/ShootSystemRule.js").ShootSystemRule): number;
+/**
+ * Expected new long shoots a living shoot of the carrier's order yields in a year: its terminal, plus the laterals its
+ * bud zones grow out on a unit of `rule.mean_unit_length`. About 2.65 for oak [BB2000 p. 11]. Short shoots are not
+ * counted: they bear no laterals.
+ *
+ * @param {import("../config/ShootSystemRule.js").ShootSystemRule} rule
+ * @returns {number}
+ */
+export function shoot_expected_yield(rule: import("../config/ShootSystemRule.js").ShootSystemRule): number;
+//# sourceMappingURL=shoot_demography.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shoot_demography.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/shoot_demography.js"],"names":[],"mappings":"AAoDA;;;;;;;;;;GAUG;AACH,oDANsB,MAAM,QACjB,MAAM,SACN,MAAM,QACN,OAAO,8BAA8B,EAAE,eAAe,GACpD,MAAM,CAgBlB;AAED;;;;;;;GAOG;AACH,2CAHW,OAAO,8BAA8B,EAAE,eAAe,GACpD,MAAM,CAUlB"}

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

@@ -0,0 +1,96 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { shoot_order_value } from "../config/ShootBudZone.js";
+
+/**
+ * Lowest length (m) of an extension unit: the 1 cm length class [BB2000 p. 9]. [BB2000]: Buck-Sorlin & Bell (2000),
+ * Forestry 73(1): 1-19.
+ * @type {number}
+ */
+const MIN_UNIT_LENGTH = 0.01;
+
+/**
+ * @param {function():number} rng
+ * @param {number} lambda
+ * @returns {number}
+ */
+function sample_poisson(rng, lambda) {
+    if (lambda <= 0) return 0;
+    const limit = Math.exp(-lambda);
+    let k = 0;
+    let p = rng();
+    while (p > limit) {
+        k++;
+        p *= rng();
+    }
+    return k;
+}
+
+/**
+ * Marsaglia & Tsang gamma variate with scale 1.
+ * @param {function():number} rng
+ * @param {number} shape
+ * @returns {number}
+ */
+function sample_gamma(rng, shape) {
+    if (shape < 1) {
+        return sample_gamma(rng, shape + 1) * Math.pow(Math.max(1e-12, rng()), 1 / shape);
+    }
+    const d = shape - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    for (; ;) {
+        // standard normal by Box-Muller
+        const n = Math.sqrt(-2 * Math.log(Math.max(1e-12, rng()))) * Math.cos(2 * Math.PI * rng());
+        const v0 = 1 + c * n;
+        if (v0 <= 0) continue;
+        const v = v0 * v0 * v0;
+        const u = rng();
+        if (Math.log(Math.max(1e-12, u)) < 0.5 * n * n + d - d * v + d * Math.log(v)) {
+            return d * v;
+        }
+    }
+}
+
+/**
+ * Length (m) of one extension unit of mean `mean` grown at branching `order`: 1 cm plus a negative binomial (orders
+ * listed in `rule.length_negative_binomial_p`) or Poisson (the rest) count of further centimetres, the models
+ * [BB2000 p. 10-11] fitted to oak, capped at `rule.max_unit_length` of the order.
+ *
+ * @param {function():number} rng
+ * @param {number} mean metres
+ * @param {number} order 1-based
+ * @param {import("../config/ShootSystemRule.js").ShootSystemRule} rule
+ * @returns {number}
+ */
+export function shoot_sample_unit_length(rng, mean, order, rule) {
+    const extra_cm = Math.max(0, mean * 100 - 1);
+    const nb_p = rule.length_negative_binomial_p;
+    let count;
+    if (order <= nb_p.length && extra_cm > 0) {
+        // a negative binomial as a gamma-Poisson mixture, with as many failures r as give the fitted p this mean
+        const p = nb_p[order - 1];
+        const r = extra_cm * p / (1 - p);
+        count = sample_poisson(rng, sample_gamma(rng, r) * (1 - p) / p);
+    } else {
+        count = sample_poisson(rng, extra_cm);
+    }
+    const cap = shoot_order_value(rule.max_unit_length, order);
+    return clamp((1 + count + rng()) / 100, MIN_UNIT_LENGTH, Math.max(MIN_UNIT_LENGTH, cap));
+}
+
+/**
+ * Expected new long shoots a living shoot of the carrier's order yields in a year: its terminal, plus the laterals its
+ * bud zones grow out on a unit of `rule.mean_unit_length`. About 2.65 for oak [BB2000 p. 11]. Short shoots are not
+ * counted: they bear no laterals.
+ *
+ * @param {import("../config/ShootSystemRule.js").ShootSystemRule} rule
+ * @returns {number}
+ */
+export function shoot_expected_yield(rule) {
+    const order = rule.carrier_order;
+    let y = 1;
+    for (let z = 0; z < rule.zones.length; z++) {
+        const zone = rule.zones[z];
+        y += zone.bud_count(rule.mean_unit_length, order) * (shoot_order_value(zone.long, order) + shoot_order_value(zone.sylleptic, order));
+    }
+    return y;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Radius (m) at the base of an annual unit `length` (m) long that grew `age` years ago: diameter `d = 0.27 + 0.02 l`
+ * (cm) for a current shoot and `0.40 + 0.02 l` a year on [BB2000 Table 7, all oaks], so a ring of 0.13 cm a year,
+ * carried on to older wood. Kept above the 1.9 mm the bark mesher draws without thin-strand artifacts. [BB2000]:
+ * Buck-Sorlin & Bell (2000), Forestry 73(1): 1-19.
+ * @param {number} length
+ * @param {number} age
+ * @returns {number}
+ */
+export function shoot_radius(length: number, age: number): number;
+/**
+ * The radius of {@link shoot_radius} as the wood has it, before the floor the bark mesher draws at: what a shoot adds to
+ * the pipe model of the wood that carries it.
+ * @param {number} length
+ * @param {number} age
+ * @returns {number}
+ */
+export function shoot_wood_radius(length: number, age: number): number;
+/**
+ * Normalises `(x, y, z)` into `out`; a zero vector becomes up.
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+export function shoot_normalize3(out: Float32Array | Float64Array | number[], x: number, y: number, z: number): void;
+/**
+ * A unit vector perpendicular to unit `(x, y, z)`.
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+export function shoot_perpendicular3(out: Float32Array | Float64Array | number[], x: number, y: number, z: number): void;
+/**
+ * Direction out of the crown and up at a point, as the foliage's phototropism reads it.
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ */
+export function shoot_outward3(out: Float32Array | Float64Array | number[], skeleton: import("./TreeSkeleton.js").TreeSkeleton, x: number, y: number, z: number): void;
+/**
+ * The segment of a branch chain containing `t`, and where on it.
+ * @param {import("./TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number[]} nodes
+ * @param {number[]} edges
+ * @param {number} t
+ * @returns {{edge: number, u: number}}
+ */
+export function shoot_locate_on_chain(skeleton: import("./TreeSkeleton.js").TreeSkeleton, nodes: number[], edges: number[], t: number): {
+    edge: number;
+    u: number;
+};
+/**
+ * Thinnest radius (m) a shoot is drawn at.
+ * @type {number}
+ */
+export const SHOOT_MIN_RADIUS: number;
+/**
+ * Largest radius of a lateral relative to its mother where it grows out, as `tree_skeleton_compute_pipe_radii` holds it.
+ * @type {number}
+ */
+export const SHOOT_LATERAL_RADIUS_RATIO: number;
+//# sourceMappingURL=shoot_geometry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shoot_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/shoot_geometry.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,qCAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,0CAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;AAcD;;;;;;GAMG;AACH,sCALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,KAClC,MAAM,KACN,MAAM,KACN,MAAM,QAahB;AAED;;;;;;GAMG;AACH,0CALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,KAClC,MAAM,KACN,MAAM,KACN,MAAM,QAShB;AAED;;;;;;;GAOG;AACH,oCANW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,YAClC,OAAO,mBAAmB,EAAE,YAAY,KACxC,MAAM,KACN,MAAM,KACN,MAAM,QAShB;AAED;;;;;;;GAOG;AACH,gDANW,OAAO,mBAAmB,EAAE,YAAY,SACxC,MAAM,EAAE,SACR,MAAM,EAAE,KACR,MAAM,GACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,CAWrC;AAlFD;;;GAGG;AACH,+BAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,yCAFU,MAAM,CAE+B"}