@woosh/meep-engine 3.56.0 → 3.58.0

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

@@ -0,0 +1,222 @@
+import { assert } from "../../../core/assert.js";
+import { clamp } from "../../../core/math/clamp.js";
+
+/**
+ * Projection of unit leaf area onto a plane normal to the light, for leaves with a spherical angle distribution
+ * (Ross 1981, The Radiation Regime and Architecture of Plant Stands): the `G` of Beer-Lambert extinction in canopies.
+ * @type {number}
+ */
+const SPHERICAL_LEAF_PROJECTION = 0.5;
+
+/**
+ * Sky directions as integer lattice steps, so light from each crosses the grid in one sweep: the zenith, a ring
+ * around 40 degrees of elevation and a ring around 23. Every step rises one cell.
+ * @type {number[][]}
+ */
+const SKY_DIRECTIONS = [
+    [0, 1, 0],
+    [1, 1, 0], [-1, 1, 0], [0, 1, 1], [0, 1, -1],
+    [1, 1, 1], [-1, 1, 1], [1, 1, -1], [-1, 1, -1],
+    [2, 1, 0], [-2, 1, 0], [0, 1, 2], [0, 1, -2],
+    [2, 1, 2], [-2, 1, 2], [2, 1, -2], [-2, 1, -2]
+];
+
+/**
+ * Share of the irradiance on a horizontal surface under a standard overcast sky that comes from each of
+ * {@link SKY_DIRECTIONS}: the sky's radiance `(1 + 2 sin b) / 3` at elevation `b` (Moon & Spencer 1942), times
+ * `sin b cos b db` over the band of elevations closest to each ring, shared equally among the ring's directions.
+ * @type {Float64Array}
+ */
+const SKY_WEIGHTS = (() => {
+    const elevation = SKY_DIRECTIONS.map(([x, y, z]) => Math.atan2(y, Math.hypot(x, z)));
+    // rings by elevation, highest first
+    const rings = [];
+    for (let i = 0; i < elevation.length; i++) {
+        let ring = rings.find(r => Math.abs(r.mean - elevation[i]) < 0.15);
+        if (ring === undefined) {
+            ring = { members: [], mean: elevation[i] };
+            rings.push(ring);
+        }
+        ring.members.push(i);
+        ring.mean = ring.members.reduce((s, m) => s + elevation[m], 0) / ring.members.length;
+    }
+    rings.sort((a, b) => b.mean - a.mean);
+    const band = (lo, hi) => {
+        // integral of (1 + 2 sin b) / 3 * sin b cos b db
+        const f = (b) => (Math.sin(b) ** 2 / 2 + 2 * Math.sin(b) ** 3 / 3) / 3;
+        return f(hi) - f(lo);
+    };
+    const w = new Float64Array(SKY_DIRECTIONS.length);
+    let total = 0;
+    for (let r = 0; r < rings.length; r++) {
+        const hi = r === 0 ? Math.PI / 2 : 0.5 * (rings[r - 1].mean + rings[r].mean);
+        const lo = r === rings.length - 1 ? 0 : 0.5 * (rings[r].mean + rings[r + 1].mean);
+        const share = band(lo, hi) / rings[r].members.length;
+        for (const m of rings[r].members) {
+            w[m] = share;
+            total += share;
+        }
+    }
+    for (let i = 0; i < w.length; i++) w[i] /= total;
+    return w;
+})();
+
+/**
+ * Light inside a crown from its own leaves: leaf area deposited in a voxel grid, and the relative irradiance each
+ * voxel receives from a standard overcast sky through the leaf area between it and the sky, by Beer-Lambert,
+ * `exp(-G Omega LAD path)` per direction. 1 under open sky.
+ *
+ * The cost of {@link solve} is the grid's cells times its 17 sky directions, whatever the leaf count.
+ */
+export class ShootLightField {
+    /**
+     * @param {ArrayLike<number>} min world corner of the grid
+     * @param {ArrayLike<number>} max opposite corner
+     * @param {number} cell edge of a voxel (m)
+     */
+    constructor(min, max, cell) {
+        assert.greaterThan(cell, 0, 'cell');
+        this.cell = cell;
+        this.min = Float64Array.from(min);
+        this.nx = Math.max(1, Math.ceil((max[0] - min[0]) / cell));
+        this.ny = Math.max(1, Math.ceil((max[1] - min[1]) / cell));
+        this.nz = Math.max(1, Math.ceil((max[2] - min[2]) / cell));
+        const n = this.nx * this.ny * this.nz;
+        /**
+         * One-sided leaf area in each voxel (m^2).
+         * @type {Float64Array}
+         */
+        this.leaf_area = new Float64Array(n);
+        /**
+         * Relative irradiance at each voxel's centre, after {@link solve}.
+         * @type {Float64Array}
+         */
+        this.irradiance = new Float64Array(n).fill(1);
+        this.transmittance = new Float64Array(n);
+    }
+
+    /**
+     * Removes all leaf area.
+     */
+    clear() {
+        this.leaf_area.fill(0);
+    }
+
+    /**
+     * Index of the voxel holding a point, or -1 outside the grid.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number}
+     */
+    voxel(x, y, z) {
+        const i = Math.floor((x - this.min[0]) / this.cell);
+        const j = Math.floor((y - this.min[1]) / this.cell);
+        const k = Math.floor((z - this.min[2]) / this.cell);
+        if (i < 0 || j < 0 || k < 0 || i >= this.nx || j >= this.ny || k >= this.nz) return -1;
+        return (j * this.nz + k) * this.nx + i;
+    }
+
+    /**
+     * Adds `area` of leaf (m^2) at a point. Leaf outside the grid shades nothing.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} area
+     */
+    deposit(x, y, z, area) {
+        const v = this.voxel(x, y, z);
+        if (v >= 0) this.leaf_area[v] += area;
+    }
+
+    /**
+     * Adds `area` of leaf spread evenly along the segment from `a` to `b`.
+     * @param {ArrayLike<number>} a
+     * @param {ArrayLike<number>} b
+     * @param {number} area
+     */
+    deposit_segment(a, b, area) {
+        const len = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+        const n = Math.max(1, Math.ceil(len / this.cell));
+        const share = area / n;
+        for (let s = 0; s < n; s++) {
+            const t = (s + 0.5) / n;
+            this.deposit(a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t, share);
+        }
+    }
+
+    /**
+     * Relative irradiance at every voxel from the leaf area deposited, with leaf clumping `clumping` (`Omega`, 1 for
+     * leaves spread at random within a voxel). A voxel's own leaf shades its centre over half a step.
+     * @param {number} clumping
+     */
+    solve(clumping) {
+        const { nx, ny, nz, cell } = this;
+        const k_ext = SPHERICAL_LEAF_PROJECTION * clamp(clumping, 0, 1);
+        const volume = cell * cell * cell;
+        const irradiance = this.irradiance;
+        const transmittance = this.transmittance;
+        const leaf_area = this.leaf_area;
+        irradiance.fill(0);
+        for (let d = 0; d < SKY_DIRECTIONS.length; d++) {
+            const [dx, dy, dz] = SKY_DIRECTIONS[d];
+            const step = Math.hypot(dx, dy, dz) * cell;
+            const w = SKY_WEIGHTS[d];
+            // a voxel sees the sky through the voxel one step towards it, which was swept the row before
+            for (let j = ny - 1; j >= 0; j--) {
+                const j1 = j + dy;
+                for (let k = 0; k < nz; k++) {
+                    const k1 = k + dz;
+                    for (let i = 0; i < nx; i++) {
+                        const i1 = i + dx;
+                        const v = (j * nz + k) * nx + i;
+                        let t = 1.0;
+                        if (j1 < ny && k1 >= 0 && k1 < nz && i1 >= 0 && i1 < nx) {
+                            const u = (j1 * nz + k1) * nx + i1;
+                            t = transmittance[u] * Math.exp(-k_ext * (leaf_area[u] / volume) * step);
+                        }
+                        transmittance[v] = t;
+                        irradiance[v] += w * t * Math.exp(-k_ext * (leaf_area[v] / volume) * step * 0.5);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * The direction light grows brighter in at a point: the irradiance's central difference over a cell along each
+     * axis, normalised; zero where it is even, as under open sky.
+     * @param {Float32Array|Float64Array|number[]} out
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    gradient_at(out, x, y, z) {
+        const c = this.cell;
+        const gx = this.irradiance_at(x + c, y, z) - this.irradiance_at(x - c, y, z);
+        const gy = this.irradiance_at(x, y + c, z) - this.irradiance_at(x, y - c, z);
+        const gz = this.irradiance_at(x, y, z + c) - this.irradiance_at(x, y, z - c);
+        const len = Math.hypot(gx, gy, gz);
+        if (len > 1e-9) {
+            out[0] = gx / len;
+            out[1] = gy / len;
+            out[2] = gz / len;
+        } else {
+            out[0] = 0;
+            out[1] = 0;
+            out[2] = 0;
+        }
+    }
+
+    /**
+     * Relative irradiance at a point, 1 outside the grid.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number}
+     */
+    irradiance_at(x, y, z) {
+        const v = this.voxel(x, y, z);
+        return v < 0 ? 1 : this.irradiance[v];
+    }
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Spatial hash of the annual units the shoot axes have grown, so a shoot can be kept from growing into older shoot
+ * wood, and thinner wood that thicker wood has grown into can be found. A unit is added once, when it has grown, under
+ * the cells its axis line crosses; a query reads every unit's place and radius from its axis as they are then, and
+ * reaches as far round as the thickest wood ({@link max_radius}), so wood that thickens needs no re-adding. The units
+ * of an axis that has died are passed over.
+ */
+export class ShootWoodHash {
+    /**
+     * Radius (m) of unit `k` of `axis` at `t` along it: its radii once its wood has thickened, a new shoot's before.
+     * @param {{radii: number[], units: number[]}} axis
+     * @param {number} k
+     * @param {number} t
+     * @returns {number}
+     */
+    static radius_at(axis: {
+        radii: number[];
+        units: number[];
+    }, k: number, t: number): number;
+    /**
+     * @param {Array<{alive: boolean, points: number[], radii: number[], units: number[]}>} axes
+     */
+    constructor(axes: Array<{
+        alive: boolean;
+        points: number[];
+        radii: number[];
+        units: number[];
+    }>);
+    /** @type {Map<number, number[]>} */
+    cells: Map<number, number[]>;
+    /**
+     * Thickest living unit (m) in each cell as of the last {@link refresh}, a unit added since counting as infinitely
+     * thick, so a query that wants only wood at least so thick can pass a cell by.
+     * @type {Map<number, number>}
+     */
+    cell_max: Map<number, number>;
+    /**
+     * Thickest radius (m) of any unit, so a query reaches every unit whose wood may meet it.
+     * @type {number}
+     */
+    max_radius: number;
+    /**
+     * Axis of each added unit.
+     * @type {number[]}
+     */
+    unit_axis: number[];
+    /**
+     * Index of each added unit along its axis.
+     * @type {number[]}
+     */
+    unit_index: number[];
+    /**
+     * Stamp of the last query that met each unit, so each is tested once a query.
+     * @type {number[]}
+     */
+    seen: number[];
+    query: number;
+    axes: {
+        alive: boolean;
+        points: number[];
+        radii: number[];
+        units: number[];
+    }[];
+    /**
+     * Adds unit `k` of axis `m`, grown.
+     * @param {number} m
+     * @param {number} k
+     */
+    add(m: number, k: number): void;
+    /**
+     * Records each cell's thickest living unit, after the wood has thickened, and the thickest of all
+     * ({@link max_radius}).
+     */
+    refresh(): void;
+    /**
+     * The axis of the first living unit whose wood meets the capsule from `a` to `b` of radius `radius`, other than
+     * units nowhere as thick as `min_radius` and those `skip(axis, unit, wood_radius, s)` passes over, `wood_radius`
+     * being the unit's radius where they meet and `s` how far along the capsule, 0 at `a`; -1 for none.
+     *
+     * @param {ArrayLike<number>} a
+     * @param {ArrayLike<number>} b
+     * @param {number} radius
+     * @param {number} min_radius
+     * @param {function(number, number, number, number): boolean} skip
+     * @returns {number}
+     */
+    hits(a: ArrayLike<number>, b: ArrayLike<number>, radius: number, min_radius: number, skip: (arg0: number, arg1: number, arg2: number, arg3: number) => boolean): number;
+}
+//# sourceMappingURL=ShootWoodHash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ShootWoodHash.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/ShootWoodHash.js"],"names":[],"mappings":"AAwBA;;;;;;GAMG;AACH;IA8FI;;;;;;OAMG;IACH,uBALW;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,KAClC,MAAM,KACN,MAAM,GACJ,MAAM,CAMlB;IApED;;OAEG;IACH,kBAFW,MAAM;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC,EAIrF;IAzCD,oCAAoC;IACpC,OADW,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC,CACd;IAElB;;;;OAIG;IACH,UAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAER;IAErB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,WAFU,MAAM,EAAE,CAEH;IAEf;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEF;IAEhB;;;OAGG;IACH,MAFU,MAAM,EAAE,CAER;IAEV,cAAU;IAMN;eAHqB,OAAO;gBAAU,MAAM,EAAE;eAAS,MAAM,EAAE;eAAS,MAAM,EAAE;QAGhE;IAGpB;;;;OAIG;IACH,OAHW,MAAM,KACN,MAAM,QAsBhB;IAED;;;OAGG;IACH,gBAiBC;IAeD;;;;;;;;;;;OAWG;IACH,QAPW,UAAU,MAAM,CAAC,KACjB,UAAU,MAAM,CAAC,UACjB,MAAM,cACN,MAAM,eACG,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,OAAO,GAC/C,MAAM,CA6ClB;CACJ"}

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

@@ -0,0 +1,195 @@
+import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
+import { shoot_radius } from "./shoot_geometry.js";
+
+/**
+ * Edge (m) of a cell of the hash: about a twig's annual unit (5-11 cm in the presets' higher orders), which most of the
+ * units are, so a cell holds few. Measured against 0.25 and 0.05 m on the pine and the spruce.
+ * @type {number}
+ */
+const WOOD_CELL = 0.1;
+
+/**
+ * Gap (m) a shoot keeps from other wood, as from the framework's (`ShootFrameworkHash`).
+ * @type {number}
+ */
+const CLEARANCE = 0.001;
+
+/**
+ * Cells per axis the integer key spans, centred on the origin: 2048 cells of 0.1 m is 205 m.
+ * @type {number}
+ */
+const KEY_SPAN = 2048;
+
+const SCRATCH_ST = new Float64Array(2);
+
+/**
+ * Spatial hash of the annual units the shoot axes have grown, so a shoot can be kept from growing into older shoot
+ * wood, and thinner wood that thicker wood has grown into can be found. A unit is added once, when it has grown, under
+ * the cells its axis line crosses; a query reads every unit's place and radius from its axis as they are then, and
+ * reaches as far round as the thickest wood ({@link max_radius}), so wood that thickens needs no re-adding. The units
+ * of an axis that has died are passed over.
+ */
+export class ShootWoodHash {
+    /** @type {Map<number, number[]>} */
+    cells = new Map();
+
+    /**
+     * Thickest living unit (m) in each cell as of the last {@link refresh}, a unit added since counting as infinitely
+     * thick, so a query that wants only wood at least so thick can pass a cell by.
+     * @type {Map<number, number>}
+     */
+    cell_max = new Map();
+
+    /**
+     * Thickest radius (m) of any unit, so a query reaches every unit whose wood may meet it.
+     * @type {number}
+     */
+    max_radius = 0;
+
+    /**
+     * Axis of each added unit.
+     * @type {number[]}
+     */
+    unit_axis = [];
+
+    /**
+     * Index of each added unit along its axis.
+     * @type {number[]}
+     */
+    unit_index = [];
+
+    /**
+     * Stamp of the last query that met each unit, so each is tested once a query.
+     * @type {number[]}
+     */
+    seen = [];
+
+    query = 0;
+
+    /**
+     * @param {Array<{alive: boolean, points: number[], radii: number[], units: number[]}>} axes
+     */
+    constructor(axes) {
+        this.axes = axes;
+    }
+
+    /**
+     * Adds unit `k` of axis `m`, grown.
+     * @param {number} m
+     * @param {number} k
+     */
+    add(m, k) {
+        const id = this.unit_axis.length;
+        this.unit_axis.push(m);
+        this.unit_index.push(k);
+        this.seen.push(0);
+        const p = this.axes[m].points;
+        const a = k * 3, b = a + 3;
+        const x0 = Math.floor(Math.min(p[a], p[b]) / WOOD_CELL), x1 = Math.floor(Math.max(p[a], p[b]) / WOOD_CELL);
+        const y0 = Math.floor(Math.min(p[a + 1], p[b + 1]) / WOOD_CELL), y1 = Math.floor(Math.max(p[a + 1], p[b + 1]) / WOOD_CELL);
+        const z0 = Math.floor(Math.min(p[a + 2], p[b + 2]) / WOOD_CELL), z1 = Math.floor(Math.max(p[a + 2], p[b + 2]) / WOOD_CELL);
+        for (let x = x0; x <= x1; x++) for (let y = y0; y <= y1; y++) for (let z = z0; z <= z1; z++) {
+            const key = ((x + KEY_SPAN / 2) * KEY_SPAN + (y + KEY_SPAN / 2)) * KEY_SPAN + (z + KEY_SPAN / 2);
+            let list = this.cells.get(key);
+            if (list === undefined) {
+                list = [];
+                this.cells.set(key, list);
+            }
+            list.push(id);
+            this.cell_max.set(key, Infinity);
+        }
+    }
+
+    /**
+     * Records each cell's thickest living unit, after the wood has thickened, and the thickest of all
+     * ({@link max_radius}).
+     */
+    refresh() {
+        const axes = this.axes;
+        let most = 0;
+        for (const [key, list] of this.cells) {
+            let max = 0;
+            for (let i = 0; i < list.length; i++) {
+                const id = list[i];
+                const axis = axes[this.unit_axis[id]];
+                if (!axis.alive) continue;
+                const k = this.unit_index[id];
+                const thickest = axis.radii.length > k + 1 ? Math.max(axis.radii[k], axis.radii[k + 1]) : shoot_radius(axis.units[k], 0);
+                if (thickest > max) max = thickest;
+            }
+            this.cell_max.set(key, max);
+            if (max > most) most = max;
+        }
+        this.max_radius = most;
+    }
+
+    /**
+     * Radius (m) of unit `k` of `axis` at `t` along it: its radii once its wood has thickened, a new shoot's before.
+     * @param {{radii: number[], units: number[]}} axis
+     * @param {number} k
+     * @param {number} t
+     * @returns {number}
+     */
+    static radius_at(axis, k, t) {
+        const r = axis.radii;
+        if (r.length <= k + 1) return shoot_radius(axis.units[k], 0);
+        return r[k] + (r[k + 1] - r[k]) * t;
+    }
+
+    /**
+     * The axis of the first living unit whose wood meets the capsule from `a` to `b` of radius `radius`, other than
+     * units nowhere as thick as `min_radius` and those `skip(axis, unit, wood_radius, s)` passes over, `wood_radius`
+     * being the unit's radius where they meet and `s` how far along the capsule, 0 at `a`; -1 for none.
+     *
+     * @param {ArrayLike<number>} a
+     * @param {ArrayLike<number>} b
+     * @param {number} radius
+     * @param {number} min_radius
+     * @param {function(number, number, number, number): boolean} skip
+     * @returns {number}
+     */
+    hits(a, b, radius, min_radius, skip) {
+        const pad = radius + this.max_radius + CLEARANCE;
+        const x0 = Math.floor((Math.min(a[0], b[0]) - pad) / WOOD_CELL), x1 = Math.floor((Math.max(a[0], b[0]) + pad) / WOOD_CELL);
+        const y0 = Math.floor((Math.min(a[1], b[1]) - pad) / WOOD_CELL), y1 = Math.floor((Math.max(a[1], b[1]) + pad) / WOOD_CELL);
+        const z0 = Math.floor((Math.min(a[2], b[2]) - pad) / WOOD_CELL), z1 = Math.floor((Math.max(a[2], b[2]) + pad) / WOOD_CELL);
+        const query = ++this.query;
+        const axes = this.axes;
+        const ax0 = Math.min(a[0], b[0]) - radius, ax1 = Math.max(a[0], b[0]) + radius;
+        const ay0 = Math.min(a[1], b[1]) - radius, ay1 = Math.max(a[1], b[1]) + radius;
+        const az0 = Math.min(a[2], b[2]) - radius, az1 = Math.max(a[2], b[2]) + radius;
+        for (let x = x0; x <= x1; x++) for (let y = y0; y <= y1; y++) for (let z = z0; z <= z1; z++) {
+            const key = ((x + KEY_SPAN / 2) * KEY_SPAN + (y + KEY_SPAN / 2)) * KEY_SPAN + (z + KEY_SPAN / 2);
+            const list = this.cells.get(key);
+            if (list === undefined || this.cell_max.get(key) < min_radius) continue;
+            for (let i = 0; i < list.length; i++) {
+                const id = list[i];
+                if (this.seen[id] === query) continue;
+                this.seen[id] = query;
+                const m = this.unit_axis[id];
+                const axis = axes[m];
+                if (!axis.alive) continue;
+                const k = this.unit_index[id];
+                const p = axis.points;
+                const q = k * 3;
+                // the thickest the unit is, and whether its box padded by that meets the capsule's
+                const thickest = axis.radii.length > k + 1 ? Math.max(axis.radii[k], axis.radii[k + 1]) : shoot_radius(axis.units[k], 0);
+                if (thickest < min_radius) continue;
+                const pad_k = thickest + CLEARANCE;
+                if (Math.min(p[q], p[q + 3]) - pad_k > ax1 || Math.max(p[q], p[q + 3]) + pad_k < ax0
+                    || Math.min(p[q + 1], p[q + 4]) - pad_k > ay1 || Math.max(p[q + 1], p[q + 4]) + pad_k < ay0
+                    || Math.min(p[q + 2], p[q + 5]) - pad_k > az1 || Math.max(p[q + 2], p[q + 5]) + pad_k < az0) continue;
+                line3_compute_segment_segment_closest_points(SCRATCH_ST, a[0], a[1], a[2], b[0], b[1], b[2], p[q], p[q + 1], p[q + 2], p[q + 3], p[q + 4], p[q + 5]);
+                const s = SCRATCH_ST[0], t = SCRATCH_ST[1];
+                const r = ShootWoodHash.radius_at(axis, k, t);
+                const dx = a[0] + (b[0] - a[0]) * s - (p[q] + (p[q + 3] - p[q]) * t);
+                const dy = a[1] + (b[1] - a[1]) * s - (p[q + 1] + (p[q + 4] - p[q + 1]) * t);
+                const dz = a[2] + (b[2] - a[2]) * s - (p[q + 2] + (p[q + 5] - p[q + 2]) * t);
+                if (Math.hypot(dx, dy, dz) >= r + radius + CLEARANCE) continue;
+                if (skip(m, k, r, s)) continue;
+                return m;
+            }
+        }
+        return -1;
+    }
+}

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

@@ -87,10 +87,21 @@ export class TreeSkeleton {
      */
     branch_tip_vertex: Int32Array;
     /**
-     * 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: Uint8Array;
+    /**
+     * Index into `TreeSpeciesConfig.branches` of the generator that grew each branch.
+     * @type {Uint16Array}
+     */
+    branch_generator: Uint16Array;
+    /**
+     * `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: Uint8Array;
     /**
      * Parent branch ID (-1 for trunk).
      * @type {Int32Array}
@@ -121,6 +132,45 @@ export class TreeSkeleton {
      * @type {Float32Array}
      */
     branch_phase_hash: Float32Array;
+    /**
+     * 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: Uint32Array;
+    /**
+     * Annual extension units recorded for each branch, see {@link branch_unit_offset}.
+     * @type {Uint16Array}
+     */
+    branch_unit_count: Uint16Array;
+    /**
+     * Where each recorded annual extension unit starts, as `t_norm` along its branch, see {@link branch_unit_offset}.
+     * @type {Float32Array}
+     */
+    unit_start_t: Float32Array;
+    /**
+     * Entries of {@link unit_start_t} in use.
+     * @type {number}
+     */
+    unit_count: number;
+    /**
+     * Wind joints bound to the nodes (`attr_node_joint`), written by `tree_skeleton_assign_skin_joints`; 0 until then.
+     * @type {number}
+     */
+    joint_count: number;
+    /**
+     * Node each wind joint pivots at, see {@link joint_count}.
+     * @type {Int32Array}
+     */
+    joint_vertex: Int32Array;
+    /**
+     * 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: Float32Array;
     /**
      * Crown center `[cx, cy, cz]` in tree local space (Y-up).
      * @type {Float32Array}
@@ -131,15 +181,68 @@ export class TreeSkeleton {
      * @type {Float32Array}
      */
     crown_radii: Float32Array;
+    /**
+     * Number of branch scars: healed-over sites where a shed branch once grew.
+     * @type {number}
+     */
+    scar_count: number;
+    /**
+     * Branch carrying each scar.
+     * @type {Int32Array}
+     */
+    scar_branch: Int32Array;
+    /**
+     * 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: Float32Array;
     /**
      * Resets the skeleton to empty state while retaining allocated attribute buffers and `Transform64` instances.
      */
     clear(): void;
+    /**
+     * 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: ArrayLike<number>, rotations: ArrayLike<number>): void;
+    /**
+     * 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: number, starts: ArrayLike<number>): void;
+    /**
+     * 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: number, age: number): number;
+    /**
+     * 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: number, t: number, dir_x: number, dir_y: number, dir_z: number, radius: number): number;
     /**
      * 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
@@ -148,7 +251,7 @@ export class TreeSkeleton {
      * @param {number} [phase_hash=0]
      * @returns {number} branch_id
      */
-    add_branch(root_vertex: number, level: number, parent_branch_id: number, parent_edge_id: number, parent_attach_t: number, length: number, base_radius: number, phase_hash?: number): number;
+    add_branch(root_vertex: number, level: number, generator: number, parent_branch_id: number, parent_edge_id: number, parent_attach_t: number, length: number, base_radius: number, phase_hash?: number): number;
     /**
      * Allocates and initializes a new skeleton node in `this.graph`, storing its 3D position,
      * orthonormal RMF basis `[R, S, T]`, and radius in a {@link Transform64}, and its metadata in {@link Attribute}s.
@@ -307,6 +410,12 @@ export class TreeSkeleton {
      * @returns {number}
      */
     node_t_norm(v: number): number;
+    /**
+     * Sets node `v`'s normalized position along its branch, as when the branch grows longer.
+     * @param {number} v
+     * @param {number} t_norm
+     */
+    node_write_t_norm(v: number, t_norm: number): void;
     /**
      * @param {number} v
      * @returns {number}