@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -155,11 +155,24 @@ export class TreeSkeleton {
     branch_tip_vertex = new Int32Array(INITIAL_BRANCH_CAPACITY);
 
     /**
-     * Recursion level of each branch (0 = trunk).
+     * Branching depth of each branch (0 = trunk, parent depth + 1 for a lateral, parent depth for a split fork).
      * @type {Uint8Array}
      */
     branch_level = new Uint8Array(INITIAL_BRANCH_CAPACITY);
 
+    /**
+     * Index into `TreeSpeciesConfig.branches` of the generator that grew each branch.
+     * @type {Uint16Array}
+     */
+    branch_generator = new Uint16Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * `1` for a dead branch: a self-pruned stub, shaded out below the crown, that grows nothing, carries no leaves
+     * and conducts no sap.
+     * @type {Uint8Array}
+     */
+    branch_dead = new Uint8Array(INITIAL_BRANCH_CAPACITY);
+
     /**
      * Parent branch ID (-1 for trunk).
      * @type {Int32Array}
@@ -196,6 +209,52 @@ export class TreeSkeleton {
      */
     branch_phase_hash = new Float32Array(INITIAL_BRANCH_CAPACITY);
 
+    /**
+     * Annual extension units recorded for each branch grown by them (`tree_skeleton_grow_shoots`): branch `b`'s
+     * units start at `unit_start_t[branch_unit_offset[b] + k]` for `k < branch_unit_count[b]`, as `t_norm` along
+     * it, oldest first, the last being this year's. A branch with no record has a count of 0. See
+     * {@link branch_unit_start_t}.
+     * @type {Uint32Array}
+     */
+    branch_unit_offset = new Uint32Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Annual extension units recorded for each branch, see {@link branch_unit_offset}.
+     * @type {Uint16Array}
+     */
+    branch_unit_count = new Uint16Array(INITIAL_BRANCH_CAPACITY);
+
+    /**
+     * Where each recorded annual extension unit starts, as `t_norm` along its branch, see {@link branch_unit_offset}.
+     * @type {Float32Array}
+     */
+    unit_start_t = new Float32Array(256);
+
+    /**
+     * Entries of {@link unit_start_t} in use.
+     * @type {number}
+     */
+    unit_count = 0;
+
+    /**
+     * Wind joints bound to the nodes (`attr_node_joint`), written by `tree_skeleton_assign_skin_joints`; 0 until then.
+     * @type {number}
+     */
+    joint_count = 0;
+
+    /**
+     * Node each wind joint pivots at, see {@link joint_count}.
+     * @type {Int32Array}
+     */
+    joint_vertex = new Int32Array(16);
+
+    /**
+     * How far (rad) each wind joint turns the wood it carries in the reference wind, as the joints were placed for it,
+     * see {@link joint_count}.
+     * @type {Float32Array}
+     */
+    joint_rotation = new Float32Array(16);
+
     /**
      * Crown center `[cx, cy, cz]` in tree local space (Y-up).
      * @type {Float32Array}
@@ -208,6 +267,25 @@ export class TreeSkeleton {
      */
     crown_radii = new Float32Array([4.5, 5.0, 4.5]);
 
+    /**
+     * Number of branch scars: healed-over sites where a shed branch once grew.
+     * @type {number}
+     */
+    scar_count = 0;
+
+    /**
+     * Branch carrying each scar.
+     * @type {Int32Array}
+     */
+    scar_branch = new Int32Array(16);
+
+    /**
+     * Float32x5 per scar: `[t, dir_x, dir_y, dir_z, radius]`, the normalized position along its branch, the unit
+     * direction the shed branch grew in, and that branch's radius when it died.
+     * @type {Float32Array}
+     */
+    scar_data = new Float32Array(16 * 5);
+
     constructor() {
         this.attr_node_branch_info.count = 0;
         this.attr_node_spine_param.count = 0;
@@ -233,6 +311,97 @@ export class TreeSkeleton {
         this.attr_segment_hermite_m0.count = 0;
         this.attr_segment_hermite_m1.count = 0;
         this.attr_segment_metrics.count = 0;
+        this.scar_count = 0;
+        this.unit_count = 0;
+        this.joint_count = 0;
+    }
+
+    /**
+     * Records the wind joints bound to the nodes: where each pivots and how far it turns in the reference wind.
+     *
+     * @param {ArrayLike<number>} vertices node of each joint
+     * @param {ArrayLike<number>} rotations rad, per joint
+     */
+    set_joints(vertices, rotations) {
+        const n = vertices.length;
+        assert.equal(rotations.length, n, 'rotations.length');
+        if (n > this.joint_vertex.length) {
+            this.joint_vertex = new Int32Array(n);
+            this.joint_rotation = new Float32Array(n);
+        }
+        this.joint_vertex.set(vertices);
+        this.joint_rotation.set(rotations);
+        this.joint_count = n;
+    }
+
+    /**
+     * Records where each annual extension unit of `branch` starts, as `t_norm` along it, oldest first, the last being
+     * this year's. Replaces any record `branch` had (the old one stays allocated).
+     *
+     * @param {number} branch
+     * @param {ArrayLike<number>} starts
+     */
+    set_branch_units(branch, starts) {
+        const n = starts.length;
+        assert.lessThanOrEqual(n, 0xFFFF, 'starts.length');
+        const offset = this.unit_count;
+        if (offset + n > this.unit_start_t.length) {
+            const grown = new Float32Array(Math.max(this.unit_start_t.length * 2, offset + n));
+            grown.set(this.unit_start_t);
+            this.unit_start_t = grown;
+        }
+        for (let k = 0; k < n; k++) {
+            this.unit_start_t[offset + k] = starts[k];
+        }
+        this.unit_count = offset + n;
+        this.branch_unit_offset[branch] = offset;
+        this.branch_unit_count[branch] = n;
+    }
+
+    /**
+     * Where the recorded annual unit of `branch` that grew `age` years ago starts, as `t_norm` along it: `age` 0 is
+     * this year's. The unit ends where the one a year younger starts, or at the tip.
+     *
+     * @param {number} branch
+     * @param {number} age `[0, branch_unit_count[branch])`
+     * @returns {number}
+     */
+    branch_unit_start_t(branch, age) {
+        const n = this.branch_unit_count[branch];
+        assert.lessThan(age, n, 'age');
+        return this.unit_start_t[this.branch_unit_offset[branch] + n - 1 - age];
+    }
+
+    /**
+     * Records the healed-over site of a shed branch on `branch`.
+     *
+     * @param {number} branch
+     * @param {number} t normalized position along `branch`
+     * @param {number} dir_x unit direction the shed branch grew in
+     * @param {number} dir_y
+     * @param {number} dir_z
+     * @param {number} radius the shed branch's radius when it died
+     * @returns {number} scar index
+     */
+    add_scar(branch, t, dir_x, dir_y, dir_z, radius) {
+        const id = this.scar_count;
+        if (id >= this.scar_branch.length) {
+            const branches = new Int32Array(this.scar_branch.length * 2);
+            branches.set(this.scar_branch);
+            this.scar_branch = branches;
+            const data = new Float32Array(this.scar_data.length * 2);
+            data.set(this.scar_data);
+            this.scar_data = data;
+        }
+        this.scar_branch[id] = branch;
+        const d = id * 5;
+        this.scar_data[d] = t;
+        this.scar_data[d + 1] = dir_x;
+        this.scar_data[d + 2] = dir_y;
+        this.scar_data[d + 3] = dir_z;
+        this.scar_data[d + 4] = radius;
+        this.scar_count = id + 1;
+        return id;
     }
 
     /**
@@ -292,6 +461,11 @@ export class TreeSkeleton {
             arr.set(old);
             return arr;
         };
+        const grow_u16 = (old) => {
+            const arr = new Uint16Array(next_cap);
+            arr.set(old);
+            return arr;
+        };
         const grow_f32 = (old) => {
             const arr = new Float32Array(next_cap);
             arr.set(old);
@@ -301,12 +475,18 @@ export class TreeSkeleton {
         this.branch_root_vertex = grow_i32(this.branch_root_vertex);
         this.branch_tip_vertex = grow_i32(this.branch_tip_vertex);
         this.branch_level = grow_u8(this.branch_level);
+        this.branch_generator = grow_u16(this.branch_generator);
+        this.branch_dead = grow_u8(this.branch_dead);
         this.branch_parent = grow_i32(this.branch_parent);
         this.branch_parent_edge = grow_i32(this.branch_parent_edge);
         this.branch_parent_attach_t = grow_f32(this.branch_parent_attach_t);
         this.branch_length = grow_f32(this.branch_length);
         this.branch_base_radius = grow_f32(this.branch_base_radius);
         this.branch_phase_hash = grow_f32(this.branch_phase_hash);
+        const grown_offset = new Uint32Array(next_cap);
+        grown_offset.set(this.branch_unit_offset);
+        this.branch_unit_offset = grown_offset;
+        this.branch_unit_count = grow_u16(this.branch_unit_count);
         this.#branch_capacity = next_cap;
     }
 
@@ -314,7 +494,8 @@ export class TreeSkeleton {
      * Registers a new branch in the branch table and returns its `branch_id`.
      *
      * @param {number} root_vertex
-     * @param {number} level
+     * @param {number} level branching depth
+     * @param {number} generator index into `TreeSpeciesConfig.branches`
      * @param {number} parent_branch_id
      * @param {number} parent_edge_id
      * @param {number} parent_attach_t
@@ -326,6 +507,7 @@ export class TreeSkeleton {
     add_branch(
         root_vertex,
         level,
+        generator,
         parent_branch_id,
         parent_edge_id,
         parent_attach_t,
@@ -340,12 +522,15 @@ export class TreeSkeleton {
         this.branch_root_vertex[id] = root_vertex;
         this.branch_tip_vertex[id] = root_vertex;
         this.branch_level[id] = level;
+        this.branch_generator[id] = generator;
+        this.branch_dead[id] = 0;
         this.branch_parent[id] = parent_branch_id;
         this.branch_parent_edge[id] = parent_edge_id;
         this.branch_parent_attach_t[id] = parent_attach_t;
         this.branch_length[id] = length;
         this.branch_base_radius[id] = base_radius;
         this.branch_phase_hash[id] = phase_hash;
+        this.branch_unit_count[id] = 0;
 
         return id;
     }
@@ -859,14 +1044,13 @@ export class TreeSkeleton {
     }
 
     /**
-     * Evaluates the 3D position along Cubic Hermite segment `edge_id` at parameter `u` in `[0, 1]`.
-     *
      * @param {number[]|Float32Array} out
      * @param {number} out_offset
      * @param {number} edge_id
      * @param {number} u
+     * @param {(t: number, p0: number, p1: number, m0: number, m1: number) => number} eval_fn
      */
-    evaluate_segment_position(out, out_offset, edge_id, u) {
+    #evaluate_segment_hermite(out, out_offset, edge_id, u, eval_fn) {
         const endpoints = /** @type {Int32Array} */ (this.attr_segment_endpoints.data);
         const v0 = endpoints[edge_id * 2];
         const v1 = endpoints[edge_id * 2 + 1];
@@ -877,21 +1061,21 @@ export class TreeSkeleton {
         const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
         const e3 = edge_id * 3;
 
-        out[out_offset] = spline3_hermite(
+        out[out_offset] = eval_fn(
             u,
             t0[TRANSFORM64_TRANSLATION_OFFSET],
             t1[TRANSFORM64_TRANSLATION_OFFSET],
             m0[e3],
             m1[e3]
         );
-        out[out_offset + 1] = spline3_hermite(
+        out[out_offset + 1] = eval_fn(
             u,
             t0[TRANSFORM64_TRANSLATION_OFFSET + 1],
             t1[TRANSFORM64_TRANSLATION_OFFSET + 1],
             m0[e3 + 1],
             m1[e3 + 1]
         );
-        out[out_offset + 2] = spline3_hermite(
+        out[out_offset + 2] = eval_fn(
             u,
             t0[TRANSFORM64_TRANSLATION_OFFSET + 2],
             t1[TRANSFORM64_TRANSLATION_OFFSET + 2],
@@ -900,6 +1084,18 @@ export class TreeSkeleton {
         );
     }
 
+    /**
+     * Evaluates the 3D position along Cubic Hermite segment `edge_id` at parameter `u` in `[0, 1]`.
+     *
+     * @param {number[]|Float32Array} out
+     * @param {number} out_offset
+     * @param {number} edge_id
+     * @param {number} u
+     */
+    evaluate_segment_position(out, out_offset, edge_id, u) {
+        this.#evaluate_segment_hermite(out, out_offset, edge_id, u, spline3_hermite);
+    }
+
     /**
      * Evaluates the unnormalized 3D derivative along Cubic Hermite segment `edge_id` at parameter `u` in `[0, 1]`.
      *
@@ -909,37 +1105,7 @@ export class TreeSkeleton {
      * @param {number} u
      */
     evaluate_segment_derivative(out, out_offset, edge_id, u) {
-        const endpoints = /** @type {Int32Array} */ (this.attr_segment_endpoints.data);
-        const v0 = endpoints[edge_id * 2];
-        const v1 = endpoints[edge_id * 2 + 1];
-
-        const t0 = this.node_transforms[v0];
-        const t1 = this.node_transforms[v1];
-        const m0 = /** @type {Float32Array} */ (this.attr_segment_hermite_m0.data);
-        const m1 = /** @type {Float32Array} */ (this.attr_segment_hermite_m1.data);
-        const e3 = edge_id * 3;
-
-        out[out_offset] = spline3_hermite_derivative(
-            u,
-            t0[TRANSFORM64_TRANSLATION_OFFSET],
-            t1[TRANSFORM64_TRANSLATION_OFFSET],
-            m0[e3],
-            m1[e3]
-        );
-        out[out_offset + 1] = spline3_hermite_derivative(
-            u,
-            t0[TRANSFORM64_TRANSLATION_OFFSET + 1],
-            t1[TRANSFORM64_TRANSLATION_OFFSET + 1],
-            m0[e3 + 1],
-            m1[e3 + 1]
-        );
-        out[out_offset + 2] = spline3_hermite_derivative(
-            u,
-            t0[TRANSFORM64_TRANSLATION_OFFSET + 2],
-            t1[TRANSFORM64_TRANSLATION_OFFSET + 2],
-            m0[e3 + 2],
-            m1[e3 + 2]
-        );
+        this.#evaluate_segment_hermite(out, out_offset, edge_id, u, spline3_hermite_derivative);
     }
 
     /**
@@ -1069,15 +1235,27 @@ export class TreeSkeleton {
             this.branch_root_vertex[i] = other.branch_root_vertex[i];
             this.branch_tip_vertex[i] = other.branch_tip_vertex[i];
             this.branch_level[i] = other.branch_level[i];
+            this.branch_generator[i] = other.branch_generator[i];
+            this.branch_dead[i] = other.branch_dead[i];
             this.branch_parent[i] = other.branch_parent[i];
             this.branch_parent_edge[i] = other.branch_parent_edge[i];
             this.branch_parent_attach_t[i] = other.branch_parent_attach_t[i];
             this.branch_length[i] = other.branch_length[i];
             this.branch_base_radius[i] = other.branch_base_radius[i];
             this.branch_phase_hash[i] = other.branch_phase_hash[i];
+            this.branch_unit_offset[i] = other.branch_unit_offset[i];
+            this.branch_unit_count[i] = other.branch_unit_count[i];
         }
 
         this.crown_center.set(other.crown_center);
+        this.scar_count = other.scar_count;
+        this.unit_count = other.unit_count;
+        this.unit_start_t = other.unit_start_t.slice();
+        this.joint_count = other.joint_count;
+        this.joint_vertex = other.joint_vertex.slice();
+        this.joint_rotation = other.joint_rotation.slice();
+        this.scar_branch = other.scar_branch.slice();
+        this.scar_data = other.scar_data.slice();
         this.crown_radii.set(other.crown_radii);
 
         return this;

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

@@ -0,0 +1,13 @@
+/**
+ * Angular offset of a branch's basal flare lobes and flutes at arc length `arc_s`: the lobe pattern around
+ * the cross-section is a function of `theta + flare_lobe_phase_offset(arc_s, phase_hash)`, so its crests sit at
+ * `theta = 2 * pi * k / flare_lobes - flare_lobe_phase_offset(arc_s, phase_hash)`.
+ *
+ * Shared by the bark mesher (which shapes the lobes) and the skeleton grower (which plants roots on their crests).
+ *
+ * @param {number} arc_s arc length along the branch (meters)
+ * @param {number} phase_hash per-branch random phase in [0, 1)
+ * @returns {number} radians
+ */
+export function flare_lobe_phase_offset(arc_s: number, phase_hash: number): number;
+//# sourceMappingURL=flare_lobe_phase_offset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flare_lobe_phase_offset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/flare_lobe_phase_offset.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,+CAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAIlB"}

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

@@ -0,0 +1,16 @@
+import { PI2 } from "../../../core/math/PI2.js";
+
+/**
+ * Angular offset of a branch's basal flare lobes and flutes at arc length `arc_s`: the lobe pattern around
+ * the cross-section is a function of `theta + flare_lobe_phase_offset(arc_s, phase_hash)`, so its crests sit at
+ * `theta = 2 * pi * k / flare_lobes - flare_lobe_phase_offset(arc_s, phase_hash)`.
+ *
+ * Shared by the bark mesher (which shapes the lobes) and the skeleton grower (which plants roots on their crests).
+ *
+ * @param {number} arc_s arc length along the branch (meters)
+ * @param {number} phase_hash per-branch random phase in [0, 1)
+ * @returns {number} radians
+ */
+export function flare_lobe_phase_offset(arc_s, phase_hash) {
+    return 0.32 * arc_s + phase_hash * PI2;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Planes one card of `card_type` stands up: a cross card is two tiles, a tri-star three.
+ *
+ * @param {FoliageCardType|number} card_type
+ * @returns {number}
+ */
+export function foliage_card_plane_count(card_type: FoliageCardType | number): number;
+/**
+ * Where a carrier's leafy span starts, normalized along it: the rule's `attach_min`, honoured up to 0.92 so every
+ * carrier keeps a stretch to hang its cards on. The cards and the wind sail both start here.
+ *
+ * @param {number} attach_min
+ * @returns {number}
+ */
+export function foliage_leafy_span_start(attach_min: number): number;
+/**
+ * Size of the cards a shoot of `shoot_length` carries, relative to the species' card: a shoot shorter than a card
+ * carries cards about as long as itself (`shoot_length / 0.95`), never smaller than 0.22 of the species' card.
+ *
+ * @param {number} card_size the species' card (m), `foliage_tile_layout`
+ * @param {number} shoot_length
+ * @returns {number}
+ */
+export function foliage_shoot_card_scale(card_size: number, shoot_length: number): number;
+/**
+ * How far a card reaches from the shoot it hangs on (m): its tile from the anchor up.
+ *
+ * @param {import("../material/foliage_tile.js").FoliageTileLayout} layout
+ * @param {number} card_scale
+ * @returns {number}
+ */
+export function foliage_card_reach(layout: import("../material/foliage_tile.js").FoliageTileLayout, card_scale: number): number;
+/**
+ * One-sided leaf area one card holds: its tile, at the species' scale, times the atlas's leaf coverage, for every
+ * plane it stands up.
+ *
+ * @param {import("../material/foliage_tile.js").FoliageTileLayout} layout
+ * @param {FoliageCardType|number} card_type
+ * @param {number} coverage leaf fraction of an atlas tile, `FoliageAtlasCutout.mean_coverage()`
+ * @param {number} card_scale
+ * @returns {number} m^2
+ */
+export function foliage_card_leaf_area(layout: import("../material/foliage_tile.js").FoliageTileLayout, card_type: FoliageCardType | number, coverage: number, card_scale: number): number;
+/**
+ * One-sided leaf area per metre of a carrier's leafy span.
+ *
+ * Cards leave the shoot at `insertion_angle` and reach `reach` from it, so the shoot wears a sleeve of foliage of
+ * radius `R = reach sin(insertion_angle)`. The carrier holds just enough leaf that every line of sight through that
+ * sleeve meets one leaf on average: by Cauchy's formula the sleeve's mean projected area is a quarter of its surface
+ * `2 pi R` per metre, a flat leaf's is half its area, so the leaf area is `pi R` per metre. Leaf beyond that is
+ * overdraw; less leaves the shoot see-through.
+ *
+ * @param {number} reach m, `foliage_card_reach`
+ * @param {number} insertion_angle radians from the shoot's tangent
+ * @returns {number} m^2 per m
+ */
+export function foliage_leaf_area_per_metre(reach: number, insertion_angle: number): number;
+/**
+ * Cards per metre of a carrier's leafy span that carry {@link foliage_leaf_area_per_metre} of leaf: each card
+ * holds the atlas's leaf coverage of every plane it stands up.
+ *
+ * @param {import("../material/foliage_tile.js").FoliageTileLayout} layout
+ * @param {FoliageCardType|number} card_type
+ * @param {number} coverage leaf fraction of an atlas tile, `FoliageAtlasCutout.mean_coverage()`
+ * @param {number} insertion_angle
+ * @param {number} card_scale
+ * @returns {number}
+ */
+export function foliage_cards_per_metre(layout: import("../material/foliage_tile.js").FoliageTileLayout, card_type: FoliageCardType | number, coverage: number, insertion_angle: number, card_scale: number): number;
+import { FoliageCardType } from "../config/FoliageCardType.js";
+//# sourceMappingURL=foliage_card_density.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"foliage_card_density.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/foliage_card_density.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,oDAHW,eAAe,GAAC,MAAM,GACpB,MAAM,CAWlB;AAED;;;;;;GAMG;AACH,qDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,oDAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,2CAJW,OAAO,6BAA6B,EAAE,iBAAiB,cACvD,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;GASG;AACH,+CANW,OAAO,6BAA6B,EAAE,iBAAiB,aACvD,eAAe,GAAC,MAAM,YACtB,MAAM,cACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;;;;;GAYG;AACH,mDAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,gDAPW,OAAO,6BAA6B,EAAE,iBAAiB,aACvD,eAAe,GAAC,MAAM,YACtB,MAAM,mBACN,MAAM,cACN,MAAM,GACJ,MAAM,CAKlB;gCAnG+B,8BAA8B"}

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

@@ -0,0 +1,101 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { FoliageCardType } from "../config/FoliageCardType.js";
+
+/**
+ * Planes one card of `card_type` stands up: a cross card is two tiles, a tri-star three.
+ *
+ * @param {FoliageCardType|number} card_type
+ * @returns {number}
+ */
+export function foliage_card_plane_count(card_type) {
+	switch (card_type) {
+		case FoliageCardType.CrossCard:
+			return 2;
+		case FoliageCardType.TriStarCluster:
+			return 3;
+		default:
+			return 1;
+	}
+}
+
+/**
+ * Where a carrier's leafy span starts, normalized along it: the rule's `attach_min`, honoured up to 0.92 so every
+ * carrier keeps a stretch to hang its cards on. The cards and the wind sail both start here.
+ *
+ * @param {number} attach_min
+ * @returns {number}
+ */
+export function foliage_leafy_span_start(attach_min) {
+	return clamp(attach_min, 0.0, 0.92);
+}
+
+/**
+ * Size of the cards a shoot of `shoot_length` carries, relative to the species' card: a shoot shorter than a card
+ * carries cards about as long as itself (`shoot_length / 0.95`), never smaller than 0.22 of the species' card.
+ *
+ * @param {number} card_size the species' card (m), `foliage_tile_layout`
+ * @param {number} shoot_length
+ * @returns {number}
+ */
+export function foliage_shoot_card_scale(card_size, shoot_length) {
+	return clamp(shoot_length / (Math.max(0.25, card_size) * 0.95), 0.22, 1.0);
+}
+
+/**
+ * How far a card reaches from the shoot it hangs on (m): its tile from the anchor up.
+ *
+ * @param {import("../material/foliage_tile.js").FoliageTileLayout} layout
+ * @param {number} card_scale
+ * @returns {number}
+ */
+export function foliage_card_reach(layout, card_scale) {
+	return layout.card_size * (1.0 - layout.anchor_v) * card_scale;
+}
+
+/**
+ * One-sided leaf area one card holds: its tile, at the species' scale, times the atlas's leaf coverage, for every
+ * plane it stands up.
+ *
+ * @param {import("../material/foliage_tile.js").FoliageTileLayout} layout
+ * @param {FoliageCardType|number} card_type
+ * @param {number} coverage leaf fraction of an atlas tile, `FoliageAtlasCutout.mean_coverage()`
+ * @param {number} card_scale
+ * @returns {number} m^2
+ */
+export function foliage_card_leaf_area(layout, card_type, coverage, card_scale) {
+	const tile_area = layout.card_size * layout.card_size * card_scale * card_scale;
+	return tile_area * Math.max(1e-3, coverage) * foliage_card_plane_count(card_type);
+}
+
+/**
+ * One-sided leaf area per metre of a carrier's leafy span.
+ *
+ * Cards leave the shoot at `insertion_angle` and reach `reach` from it, so the shoot wears a sleeve of foliage of
+ * radius `R = reach sin(insertion_angle)`. The carrier holds just enough leaf that every line of sight through that
+ * sleeve meets one leaf on average: by Cauchy's formula the sleeve's mean projected area is a quarter of its surface
+ * `2 pi R` per metre, a flat leaf's is half its area, so the leaf area is `pi R` per metre. Leaf beyond that is
+ * overdraw; less leaves the shoot see-through.
+ *
+ * @param {number} reach m, `foliage_card_reach`
+ * @param {number} insertion_angle radians from the shoot's tangent
+ * @returns {number} m^2 per m
+ */
+export function foliage_leaf_area_per_metre(reach, insertion_angle) {
+	return Math.PI * reach * Math.abs(Math.sin(insertion_angle));
+}
+
+/**
+ * Cards per metre of a carrier's leafy span that carry {@link foliage_leaf_area_per_metre} of leaf: each card
+ * holds the atlas's leaf coverage of every plane it stands up.
+ *
+ * @param {import("../material/foliage_tile.js").FoliageTileLayout} layout
+ * @param {FoliageCardType|number} card_type
+ * @param {number} coverage leaf fraction of an atlas tile, `FoliageAtlasCutout.mean_coverage()`
+ * @param {number} insertion_angle
+ * @param {number} card_scale
+ * @returns {number}
+ */
+export function foliage_cards_per_metre(layout, card_type, coverage, insertion_angle, card_scale) {
+	return foliage_leaf_area_per_metre(foliage_card_reach(layout, card_scale), insertion_angle)
+		/ foliage_card_leaf_area(layout, card_type, coverage, card_scale);
+}