@woosh/meep-engine 3.56.0 → 3.58.0

package/src/generation/foliage/material/leaf_geometry.js

@@ -0,0 +1,540 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { LeafApexShape } from "../config/LeafApexShape.js";
+import { LeafBaseShape } from "../config/LeafBaseShape.js";
+import { LeafLobation } from "../config/LeafLobation.js";
+
+/**
+ * Samples along one side of a blade's outline, base to apex.
+ * @type {number}
+ */
+const SIDE_SAMPLES = 160;
+
+/**
+ * How much of the room between two neighbouring secondary veins a pinnate lobe fills at its widest; the rest is the
+ * sinus between them.
+ * @type {number}
+ */
+const LOBE_FILL = 1.0;
+
+/**
+ * Width of the midvein at the base, and of a secondary vein, as shares of the blade's length.
+ * @type {number}
+ */
+const MIDVEIN_WIDTH = 0.014;
+const SECONDARY_WIDTH = 0.006;
+
+/**
+ * Width of a leaf's stem as a share of what it carries: a petiole of its blade's length, a rachis of the compound
+ * leaf's.
+ * @type {number}
+ */
+const PETIOLE_WIDTH = 0.02;
+
+/**
+ * @typedef {Object} LeafGeometry
+ * @property {number[]} points flat `(x, y)` (m) in the leaf's frame: `y` along the midvein or rachis, the top of the
+ *           petiole at the origin, `x` across
+ * @property {number[]} contours `(first point, count)` pairs, each counter-clockwise; together they fill the leaf by
+ *           the nonzero rule, so lobes and leaflets overlap freely
+ * @property {number[]} veins `(x0, y0, x1, y1, half_width)` segments (m): midveins and primaries first, then
+ *           secondaries
+ * @property {number} midvein_count how many of `veins` are midveins, primaries or the rachis, from which the blade
+ *           cambers
+ * @property {number[]} stems `(x0, y0, x1, y1, half_width)` segments (m) drawn as woody stem: the petiole, a rachis,
+ *           a needle shoot
+ * @property {number} attach_y where the organ attaches to its shoot along `y` (m): the foot of the petiole, or the
+ *           start of a needle shoot's stretch
+ * @property {number} tip_y where the organ ends along `y` (m), for the shading that runs base to tip
+ * @property {number} finest smallest feature of the outline (m): a tooth, a sinus, the blade's width
+ * @property {number} outline smallest feature of the outline's shape (m), its margin's teeth aside: a sinus, a lobe,
+ *           the blade's width; what tells the leaf from another seen whole
+ */
+
+/**
+ * Size, width and lobe depth of a leaf at ontogenetic maturity `maturity` (0 juvenile, 1 mature) against the mature
+ * leaf the architecture describes: juvenile blades are smaller, narrower and less deeply cut, by `shape_var`.
+ *
+ * @param {number} maturity
+ * @param {number} shape_var
+ * @returns {{length: number, width: number, depth: number}}
+ */
+export function leaf_ontogeny(maturity, shape_var) {
+    return {
+        length: lerp(1.0 - 0.14 * shape_var, 1.0, maturity),
+        width: lerp(1.0 - 0.26 * shape_var, 1.0, maturity),
+        depth: lerp(1.0 - 0.45 * shape_var, 1.0, maturity)
+    };
+}
+
+/**
+ * Half-width envelope of an unlobed blade of length `L` and greatest width `W`: a monotone cubic Hermite spline
+ * through the base, the base angle's point a quarter of the way up, the widest point, the apex angle's point a
+ * quarter of the way down, and the apex (Ellis et al. 2009 measure the angles there). The shapes set the slopes at
+ * the ends: straight runs at the secant, convex steeper, rounded steepest, acuminate shallow so the tip draws out.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch
+ * @param {number} L
+ * @param {number} W
+ * @returns {function(number): number} half-width at `y` in `[0, L]`
+ */
+function blade_envelope(arch, L, W) {
+    const half = 0.5 * W;
+    const half_angle_width = (angle) => angle >= Math.PI ? half : Math.min(half, 0.25 * L * Math.tan(0.5 * angle));
+    const yw = arch.widest_at * L;
+    const truncated = arch.base_shape === LeafBaseShape.Truncate || arch.base_shape === LeafBaseShape.Cordate;
+    const wb = half_angle_width(arch.base_angle);
+    const wa = half_angle_width(arch.apex_angle);
+
+    const ys = [0];
+    const ws = [truncated ? Math.max(wb, 0.6 * half) : 0];
+    if (yw - 0.25 * L > 0.06 * L) {
+        ys.push(0.25 * L);
+        ws.push(Math.min(wb, half));
+    }
+    ys.push(yw);
+    ws.push(half);
+    if (0.75 * L - yw > 0.06 * L) {
+        ys.push(0.75 * L);
+        ws.push(Math.min(wa, half));
+    }
+    ys.push(L);
+    ws.push(0);
+
+    const n = ys.length;
+    const secant = new Array(n - 1);
+    for (let i = 0; i < n - 1; i++) secant[i] = (ws[i + 1] - ws[i]) / (ys[i + 1] - ys[i]);
+    // slopes: Fritsch-Carlson inside, flat at the widest point, the shapes at the ends
+    const m = new Array(n);
+    for (let i = 1; i < n - 1; i++) {
+        const a = secant[i - 1], b = secant[i];
+        m[i] = ys[i] === yw || a * b <= 0 ? 0 : 2 * a * b / (a + b);
+    }
+    const base_factor = truncated ? 1.0
+        : arch.base_shape === LeafBaseShape.Rounded ? 3.0
+            : arch.base_shape === LeafBaseShape.Straight ? 1.0 : 2.0;
+    m[0] = secant[0] * base_factor;
+    const apex_factor = arch.apex_shape === LeafApexShape.Rounded ? 3.0
+        : arch.apex_shape === LeafApexShape.Convex ? 2.0
+            : arch.apex_shape === LeafApexShape.Acuminate ? 0.25 : 1.0;
+    m[n - 1] = secant[n - 2] * apex_factor;
+
+    const rounded_apex = arch.apex_shape === LeafApexShape.Rounded;
+    const rounded_base = !truncated && arch.base_shape === LeafBaseShape.Rounded;
+    return (y) => {
+        const yy = clamp(y, 0, L);
+        // a rounded end is an arc: a quarter ellipse from the nearest knot
+        if (rounded_apex && yy > ys[n - 2]) {
+            const t = (yy - ys[n - 2]) / (L - ys[n - 2]);
+            return ws[n - 2] * Math.sqrt(Math.max(0, 1 - t * t));
+        }
+        if (rounded_base && yy < ys[1]) {
+            const t = 1 - yy / ys[1];
+            return ws[1] * Math.sqrt(Math.max(0, 1 - t * t));
+        }
+        let i = 0;
+        while (i < n - 2 && yy > ys[i + 1]) i++;
+        const h = ys[i + 1] - ys[i];
+        const t = (yy - ys[i]) / h;
+        const t2 = t * t, t3 = t2 * t;
+        return Math.max(0, (2 * t3 - 3 * t2 + 1) * ws[i] + (t3 - 2 * t2 + t) * h * m[i]
+            + (-2 * t3 + 3 * t2) * ws[i + 1] + (t3 - t2) * h * m[i + 1]);
+    };
+}
+
+/**
+ * Offsets a polyline outward along its normals by a serration: teeth pointing towards the end of the polyline,
+ * `tooth_orders` 2 adding teeth a third the size on each.
+ *
+ * @param {number[]} xs
+ * @param {number[]} ys
+ * @param {number} period m along the outline
+ * @param {number} depth m
+ * @param {number} orders
+ * @param {number} sign +1 for an outline that runs with its outside on its right, -1 on its left
+ * @param {number} s_from arc length where teeth start, so the petiole end stays clean
+ */
+function serrate(xs, ys, period, depth, orders, sign, s_from) {
+    const n = xs.length;
+    let s = 0;
+    const ox = new Array(n), oy = new Array(n);
+    for (let i = 0; i < n; i++) {
+        if (i > 0) s += Math.hypot(xs[i] - xs[i - 1], ys[i] - ys[i - 1]);
+        const a = Math.max(0, i - 1), b = Math.min(n - 1, i + 1);
+        const tx = xs[b] - xs[a], ty = ys[b] - ys[a];
+        const tl = Math.hypot(tx, ty) || 1;
+        // outward normal
+        const nx = sign * ty / tl, ny = -sign * tx / tl;
+        let h = 0;
+        if (s > s_from) {
+            const phase = ((s - s_from) / period) % 1;
+            // a tooth rises slowly and falls sharply: its tip points towards the apex
+            h = depth * (phase < 0.8 ? phase / 0.8 : (1 - phase) / 0.2);
+            if (orders > 1) {
+                const p2 = ((s - s_from) / (period / 3)) % 1;
+                h += depth / 3 * (p2 < 0.8 ? p2 / 0.8 : (1 - p2) / 0.2);
+            }
+            // teeth fade out where the blade closes at the apex
+            h *= clamp(Math.abs(xs[i]) / (2 * depth + 1e-9), 0, 1);
+        }
+        ox[i] = xs[i] + nx * h;
+        oy[i] = ys[i] + ny * h;
+    }
+    for (let i = 0; i < n; i++) {
+        xs[i] = ox[i];
+        ys[i] = oy[i];
+    }
+}
+
+/**
+ * The right half (`x >= 0`) of a simple blade's outline, from where the base meets the midvein (or the petiole) up
+ * to the apex, with its teeth; for a pinnately lobed blade, the blade between the lobes, and the lobes to add.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch
+ * @param {number} L blade length (m)
+ * @param {number} W blade width (m)
+ * @param {number} depth_scale ontogeny of the lobes' and teeth's depth
+ * @returns {{xs: number[], ys: number[], lobes: number[], finest: number, outline: number}} `lobes`: `(vein origin
+ *          y, length, half width)` of each lateral lobe on a side; `outline` is `finest` but for the teeth
+ */
+function blade_half(arch, L, W, depth_scale) {
+    const envelope = blade_envelope(arch, L, W);
+    const xs = [], ys = [];
+    let finest = W;
+    let outline = W;
+
+    // the base: cordate and lobate bases reach below the top of the petiole
+    const lobe_drop = (arch.base_shape === LeafBaseShape.Cordate || arch.base_shape === LeafBaseShape.Lobate)
+        ? arch.base_lobe_depth * L : 0;
+    if (lobe_drop > 0) {
+        // the margin leaves the sinus at the top of the petiole, curves down round the basal lobe and rises to meet
+        // the outline along its own direction: a cubic Bezier from (0, 0) to the outline's point where the base angle
+        // is measured (a cordate base) or a little above the base (the small auricles of a lobate one)
+        const y_join = arch.base_shape === LeafBaseShape.Cordate ? Math.min(0.25 * L, 0.8 * arch.widest_at * L) : 0.12 * L;
+        const x_join = envelope(y_join);
+        const dy = 1e-3 * L;
+        const slope = (envelope(y_join + dy) - envelope(y_join - dy)) / (2 * dy);
+        const reach = y_join + lobe_drop;
+        // the lobe bulges below the petiole and swings out to the outline's width; its first control point sits as
+        // low as makes the curve's lowest point `lobe_drop` below the petiole
+        const p1x = 0.35 * x_join;
+        const p2x = Math.max(0, x_join - slope * 0.6 * reach), p2y = y_join - 0.6 * reach;
+        const steps = 32;
+        const lowest = (p1y) => {
+            let y = 0;
+            for (let k = 0; k <= steps; k++) {
+                const t = k / steps, u = 1 - t;
+                y = Math.min(y, 3 * u * u * t * p1y + 3 * u * t * t * p2y + t * t * t * y_join);
+            }
+            return y;
+        };
+        let lo = -20 * lobe_drop, hi = 0;
+        for (let it = 0; it < 40; it++) {
+            const mid = 0.5 * (lo + hi);
+            if (lowest(mid) < -lobe_drop) lo = mid;
+            else hi = mid;
+        }
+        const p1y = 0.5 * (lo + hi);
+        for (let k = 0; k <= steps; k++) {
+            const t = k / steps, u = 1 - t;
+            const b1 = 3 * u * u * t, b2 = 3 * u * t * t, b3 = t * t * t;
+            xs.push(b1 * p1x + b2 * p2x + b3 * x_join);
+            ys.push(b1 * p1y + b2 * p2y + b3 * y_join);
+        }
+        // and on up the outline
+        const k0 = Math.floor(SIDE_SAMPLES * y_join / L) + 1;
+        for (let k = k0; k <= SIDE_SAMPLES; k++) {
+            const y = L * k / SIDE_SAMPLES;
+            xs.push(envelope(y));
+            ys.push(y);
+        }
+        finest = Math.min(finest, lobe_drop);
+        outline = Math.min(outline, lobe_drop);
+    } else {
+        for (let k = 0; k <= SIDE_SAMPLES; k++) {
+            const y = L * k / SIDE_SAMPLES;
+            xs.push(envelope(y));
+            ys.push(y);
+        }
+    }
+
+    // pinnate lobes: the blade between them reaches only to the sinus floor, `1 - sinus_depth` of the outline's
+    // width, swelling back to the outline over the apex's own lobe; each lateral lobe is a rounded blade of its own
+    // along the secondary vein that feeds it, out to the outline. The secondary veins leave the midvein evenly spaced.
+    const lobes = [];
+    if (arch.lobation === LeafLobation.Pinnate && arch.lobes > 0) {
+        const pairs = arch.lobes;
+        const spacing = L / (pairs + 1);
+        const floor = 1 - arch.sinus_depth * depth_scale;
+        const lean = 1 / Math.tan(arch.secondary_angle);
+        const y_top = (pairs - 0.5) * spacing;
+        for (let i = 0; i < xs.length; i++) {
+            if (ys[i] <= 0) continue;
+            const t = clamp((ys[i] - y_top) / (L - y_top), 0, 1);
+            xs[i] *= floor + (1 - floor) * t * t * (3 - 2 * t);
+        }
+        // a lobe fills the room between its neighbours' veins, measured across them
+        const half_width = 0.5 * LOBE_FILL * spacing * Math.sin(arch.secondary_angle);
+        for (let k = 0; k < pairs; k++) {
+            const y0 = (k + 0.3) * spacing;
+            // where the vein meets the outline
+            let y = y0;
+            for (let it = 0; it < 12; it++) y = y0 + envelope(y) * lean;
+            const x = envelope(y);
+            const length = Math.hypot(x, y - y0);
+            lobes.push(y0, length, Math.min(half_width, 0.5 * length));
+        }
+        const gap = 2 * (1 - LOBE_FILL) * spacing * Math.sin(arch.secondary_angle) + half_width;
+        finest = Math.min(finest, gap);
+        outline = Math.min(outline, gap);
+    }
+
+    if (arch.teeth_per_cm > 0 && arch.tooth_depth > 0) {
+        const period = 0.01 / arch.teeth_per_cm;
+        // the right side runs base to apex with the outside on its right
+        serrate(xs, ys, period, arch.tooth_depth * depth_scale, arch.tooth_orders, 1, 0.08 * L);
+        finest = Math.min(finest, period / (arch.tooth_orders > 1 ? 3 : 1));
+    }
+    return { xs, ys, lobes, finest, outline };
+}
+
+/**
+ * Outline of a pinnate lobe: a blade with the leaf's apex, rounded at its base where it rises out of the blade, and
+ * entire or toothed as the leaf is.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch
+ * @returns {Object} an architecture for `blade_half`
+ */
+function lobe_architecture(arch) {
+    return Object.assign({}, arch, {
+        lobation: LeafLobation.Unlobed,
+        widest_at: 0.6,
+        base_shape: LeafBaseShape.Rounded,
+        base_angle: Math.PI,
+        base_lobe_depth: 0
+    });
+}
+
+/**
+ * Appends a contour made of the right half and its mirror, rotated by `angle` from `+y` towards `+x` and moved to
+ * `(ox, oy)`.
+ */
+function push_symmetric(out, half, angle, ox, oy) {
+    const c = Math.cos(angle), s = Math.sin(angle);
+    const first = out.points.length / 2;
+    const n = half.xs.length;
+    let count = 0;
+    const put = (x, y) => {
+        out.points.push(ox + x * c + y * s, oy - x * s + y * c);
+        count++;
+    };
+    // up the right side and back down the left: counter-clockwise with y up; the rotation keeps the winding
+    for (let i = 0; i < n; i++) put(half.xs[i], half.ys[i]);
+    for (let i = n - 2; i >= 0; i--) put(-half.xs[i], half.ys[i]);
+    out.contours.push(first, count);
+}
+
+/**
+ * Appends a vein from `(x0, y0)` to `(x1, y1)` in a frame rotated by `angle` and moved to `(ox, oy)`.
+ */
+function push_segment(list, x0, y0, x1, y1, half_width, angle, ox, oy) {
+    const c = Math.cos(angle), s = Math.sin(angle);
+    list.push(ox + x0 * c + y0 * s, oy - x0 * s + y0 * c, ox + x1 * c + y1 * s, oy - x1 * s + y1 * c, half_width);
+}
+
+/**
+ * Appends one simple blade, rotated by `angle` and set at `(ox, oy)`, with its veins, and lowers `out.outline` to its
+ * outline's finest feature.
+ *
+ * @returns {number} its finest feature (m)
+ */
+function push_blade(out, arch, L, W, depth_scale, angle, ox, oy) {
+    const half = blade_half(arch, L, W, depth_scale);
+    push_symmetric(out, half, angle, ox, oy);
+    const mid_w = 0.5 * MIDVEIN_WIDTH * L;
+    push_segment(out.midveins, 0, 0, 0, L * 0.97, mid_w, angle, ox, oy);
+    const sec_w = 0.5 * SECONDARY_WIDTH * L;
+    let finest = half.finest;
+    out.outline = Math.min(out.outline, half.outline);
+    if (half.lobes.length > 0) {
+        // each lobe, both sides, along its secondary vein, which runs most of its length
+        const lobe_arch = lobe_architecture(arch);
+        const c = Math.cos(angle), sn = Math.sin(angle);
+        for (let k = 0; k < half.lobes.length; k += 3) {
+            const y0 = half.lobes[k], length = half.lobes[k + 1], hw = half.lobes[k + 2];
+            const lobe = blade_half(lobe_arch, length, 2 * hw, depth_scale);
+            finest = Math.min(finest, lobe.finest);
+            out.outline = Math.min(out.outline, lobe.outline);
+            // the vein's origin in the blade's frame, turned and moved as the blade is
+            const vx = ox + y0 * sn, vy = oy + y0 * c;
+            for (const side of [1, -1]) {
+                const a = angle + side * arch.secondary_angle;
+                push_symmetric(out, lobe, a, vx, vy);
+                push_segment(out.secondaries, 0, 0, 0, 0.9 * length, sec_w, a, vx, vy);
+            }
+        }
+    } else if (arch.secondary_veins > 0) {
+        const envelope = blade_envelope(arch, L, W);
+        const pairs = arch.secondary_veins;
+        for (let k = 1; k <= pairs; k++) {
+            const y0 = L * k / (pairs + 1) * 0.92;
+            // where a vein at the secondary angle meets the margin
+            const lean = 1 / Math.tan(arch.secondary_angle);
+            let y1 = y0;
+            for (let it = 0; it < 8; it++) y1 = Math.min(0.97 * L, y0 + envelope(y1) * 0.9 * lean);
+            const x1 = envelope(y1) * 0.9;
+            push_segment(out.secondaries, 0, y0, x1, y1, sec_w, angle, ox, oy);
+            push_segment(out.secondaries, 0, y0, -x1, y1, sec_w, angle, ox, oy);
+        }
+    }
+    return finest;
+}
+
+/**
+ * Geometry of a leaf at ontogenetic `maturity`: its outline as contours, its veins, its petiole (and rachis).
+ *
+ * - **Simple:** one blade, its petiole below the origin.
+ * - **Palmately lobed:** a primary lobe per `lobes`, each a blade of the architecture's outline radiating from the
+ *   top of the petiole across `lobe_spread`, the outer ones `lateral_lobe_length` as long, over a body that fills the
+ *   sinuses to `1 - sinus_depth` of the way out.
+ * - **Compound:** `leaflets` blades in pairs along a rachis of `rachis_length`, a terminal one at its end when odd;
+ *   leaflets shorten towards the tip.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch
+ * @param {number} maturity `[0, 1]`
+ * @param {number} shape_var how far juvenile leaves differ, `[0, 1]`
+ * @returns {LeafGeometry}
+ */
+export function leaf_geometry(arch, maturity, shape_var) {
+    const og = leaf_ontogeny(maturity, shape_var);
+    const L = arch.blade_length * og.length;
+    const W = L / arch.length_width_ratio * og.width;
+    const out = { points: [], contours: [], midveins: [], secondaries: [], stems: [], outline: W };
+    let finest = W;
+    let tip_y = L;
+    const petiole = arch.petiole_length * og.length;
+    let petiole_w = 0.5 * PETIOLE_WIDTH * L;
+
+    if (arch.leaflets > 1) {
+        const rachis = arch.rachis_length * og.length;
+        // the rachis carries the whole leaf
+        petiole_w = 0.5 * PETIOLE_WIDTH * (rachis + L);
+        const pairs = Math.floor(arch.leaflets / 2);
+        for (let p = 0; p < pairs; p++) {
+            const u = (p + 0.5) / pairs;
+            const y = rachis * u;
+            const length = L * lerp(1.0, 0.75, u);
+            const angle = lerp(0.95, 0.55, u);
+            finest = Math.min(finest, push_blade(out, arch, length, length / arch.length_width_ratio * og.width, og.depth, angle, 0, y));
+            push_blade(out, arch, length, length / arch.length_width_ratio * og.width, og.depth, -angle, 0, y);
+        }
+        tip_y = rachis;
+        if (arch.leaflets % 2 === 1) {
+            const length = L * 0.75;
+            push_blade(out, arch, length, length / arch.length_width_ratio * og.width, og.depth, 0, 0, rachis);
+            tip_y = rachis + length;
+        }
+        out.stems.push(0, -petiole, 0, rachis, petiole_w);
+    } else if (arch.lobation === LeafLobation.Palmate && arch.lobes > 1) {
+        const n = arch.lobes;
+        const spread = arch.lobe_spread;
+        const lengths = new Array(n), angles = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const a = -0.5 * spread + spread * i / (n - 1);
+            angles[i] = a;
+            lengths[i] = L * lerp(1.0, arch.lateral_lobe_length, Math.abs(a) / (0.5 * spread));
+            finest = Math.min(finest, push_blade(out, arch, lengths[i], lengths[i] / arch.length_width_ratio * og.width, og.depth, a, 0, 0));
+        }
+        // the body: out to the sinus floors between lobes, back to the petiole round the base
+        const floor = 1 - arch.sinus_depth * og.depth;
+        const first = out.points.length / 2;
+        let count = 0;
+        const put = (r, a) => {
+            out.points.push(r * Math.sin(a), r * Math.cos(a));
+            count++;
+        };
+        // counter-clockwise in a y-up frame runs from +x through +y to -x: from the rightmost lobe to the leftmost
+        put(0, 0);
+        for (let i = n - 1; i >= 0; i--) {
+            put(lengths[i] * 0.5, angles[i]);
+            if (i > 0) put(floor * Math.min(lengths[i], lengths[i - 1]), 0.5 * (angles[i] + angles[i - 1]));
+        }
+        out.contours.push(first, count);
+        finest = Math.min(finest, (1 - floor) * L);
+        out.outline = Math.min(out.outline, (1 - floor) * L);
+        tip_y = L;
+        out.stems.push(0, -petiole, 0, 0, petiole_w);
+    } else {
+        finest = Math.min(finest, push_blade(out, arch, L, W, og.depth, 0, 0, 0));
+        out.stems.push(0, -petiole, 0, 0, petiole_w);
+    }
+
+    // the petiole is leaf too: a thin strip under the blade
+    if (petiole > 0) {
+        const first = out.points.length / 2;
+        out.points.push(-petiole_w, -petiole, petiole_w, -petiole, petiole_w, 0.02 * L, -petiole_w, 0.02 * L);
+        out.contours.push(first, 4);
+    }
+
+    return {
+        points: out.points,
+        contours: out.contours,
+        veins: out.midveins.concat(out.secondaries),
+        midvein_count: out.midveins.length / 5,
+        stems: out.stems,
+        attach_y: -petiole,
+        tip_y,
+        finest,
+        outline: out.outline
+    };
+}
+
+/**
+ * Geometry of a stretch of needle shoot `shoot_length` long as one of `planes` card planes through it shows it: the
+ * shoot up `y` from the origin and the `needles` needles whose azimuth round the shoot lies within the plane's sector,
+ * `pi / planes` wide either side of the shoot, evenly along it. Each leaves the shoot at `needle_angle`; turned
+ * out of the plane by its azimuth, it shows at a shallower angle and foreshortened.
+ *
+ * @param {import("../config/LeafArchitecture.js").LeafArchitecture} arch the needle
+ * @param {number} needles drawn on this plane
+ * @param {number} shoot_length m
+ * @param {number} needle_angle radians from the shoot
+ * @param {number} planes card planes the shoot's needles are shared among
+ * @param {number} maturity
+ * @param {number} shape_var
+ * @returns {LeafGeometry}
+ */
+export function needle_shoot_geometry(arch, needles, shoot_length, needle_angle, planes, maturity, shape_var) {
+    const og = leaf_ontogeny(maturity, shape_var);
+    const L = arch.blade_length * og.length;
+    const W = L / arch.length_width_ratio * og.width;
+    const out = { points: [], contours: [], midveins: [], secondaries: [], stems: [], outline: W };
+    let finest = W;
+    const sector = Math.PI / (2 * Math.max(1, planes));
+    const sin_a = Math.sin(needle_angle), cos_a = Math.cos(needle_angle);
+    for (let i = 0; i < needles; i++) {
+        const y = shoot_length * (i + 0.5) / needles;
+        const side = i % 2 === 0 ? 1 : -1;
+        // azimuth from the plane, low-discrepancy over the sector
+        const azimuth = sector * (2 * ((i * 0.6180339887498949) % 1) - 1);
+        const across = sin_a * Math.cos(azimuth);
+        const shown = Math.hypot(across, cos_a);
+        finest = Math.min(finest, push_blade(out, arch, L * shown, W, og.depth, side * Math.atan2(across, cos_a), 0, y));
+    }
+    out.stems.push(0, 0, 0, shoot_length, 0.5 * PETIOLE_WIDTH * L);
+    const first = out.points.length / 2;
+    const w = 0.5 * PETIOLE_WIDTH * L;
+    out.points.push(-w, 0, w, 0, w, shoot_length, -w, shoot_length);
+    out.contours.push(first, 4);
+    return {
+        points: out.points,
+        contours: out.contours,
+        veins: out.midveins.concat(out.secondaries),
+        midvein_count: out.midveins.length / 5,
+        stems: out.stems,
+        attach_y: 0,
+        tip_y: shoot_length + L * Math.cos(needle_angle),
+        finest,
+        outline: out.outline
+    };
+}

package/src/generation/foliage/material/make_foliage_material.d.ts

@@ -1,40 +1,19 @@
-/**
- * Packs `variant_count` square foliage card tiles of size `resolution x resolution` into a 2D atlas
- * using the engine's `MaxRectanglesPacker` (`pack_max_rectangles`), returning the atlas dimensions,
- * pixel-space `AABB2` boxes, and normalized `[u0, v0, u1, v1]` UV rectangles.
- *
- * @param {number} [resolution=128]
- * @param {number} [variant_count=4]
- * @returns {{
- *   resolution: number,
- *   variant_count: number,
- *   atlas_w: number,
- *   atlas_h: number,
- *   boxes: AABB2[],
- *   uv_rects: Float32Array
- * }}
- */
-export function compute_foliage_variant_atlas_layout(resolution?: number, variant_count?: number): {
-    resolution: number;
-    variant_count: number;
-    atlas_w: number;
-    atlas_h: number;
-    boxes: AABB2[];
-    uv_rects: Float32Array;
-};
 /**
  * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
- * `ShadeDrawSide.Double`) for botanical foliage cards, packing `config.variant_count` ontogenetic and
- * biochemically senescent leaf cluster variants into the texture atlas via `MaxRectanglesPacker`
- * (`pack_max_rectangles`), with dilated straight-alpha Albedo (`AlphaMode.Straight`, `ColorSpace.SRGB`),
- * 2-channel Normal map (`ColorSpace.LinearSRGB`), and ORM (`ColorSpace.LinearSRGB`).
+ * `ShadeDrawSide.Double`) for a species' foliage cards, packing its `foliage_material.variant_count` ontogenetic and
+ * biochemically senescent variants into the texture atlas via `MaxRectanglesPacker` (`pack_max_rectangles`), with
+ * dilated straight-alpha Albedo (`AlphaMode.Straight`, `ColorSpace.SRGB`), 2-channel Normal map
+ * (`ColorSpace.LinearSRGB`), and ORM (`ColorSpace.LinearSRGB`).
+ *
+ * Every tile draws the species' leaf (or a stretch of its needle shoot) at its true size, from its architecture
+ * (`foliage_tile_layout`, `foliage_tile_raster`): the outline's exact coverage, its veins, its petiole.
+ *
+ * The atlas's shape comes out alongside it in `out_cutout`: per tile, the hull of everything drawn and the leaf
+ * coverage, which the card geometry and the card density are built on.
  *
- * @param {FoliageMaterialConfig|Object} [config]
- * @param {number} [seed=1]
- * @returns {StandardShadeMaterial}
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("./FoliageAtlasCutout.js").FoliageAtlasCutout|null} [out_cutout]
+ * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
  */
-export function make_foliage_material(config?: FoliageMaterialConfig | any, seed?: number): StandardShadeMaterial;
-import AABB2 from "../../../core/geom/2d/aabb/AABB2.js";
-import { FoliageMaterialConfig } from "../config/FoliageMaterialConfig.js";
-import { StandardShadeMaterial } from "../../../shade/renderer/material/StandardShadeMaterial.js";
+export function make_foliage_material(species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, out_cutout?: import("./FoliageAtlasCutout.js").FoliageAtlasCutout | null): import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
 //# sourceMappingURL=make_foliage_material.d.ts.map

package/src/generation/foliage/material/make_foliage_material.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_foliage_material.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/material/make_foliage_material.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AACH,kEAXW,MAAM,kBACN,MAAM,GACJ;IACZ,UAAc,EAAE,MAAM,CAAC;IACvB,aAAiB,EAAE,MAAM,CAAC;IAC1B,OAAW,EAAE,MAAM,CAAC;IACpB,OAAW,EAAE,MAAM,CAAC;IACpB,KAAS,EAAE,KAAK,EAAE,CAAC;IACnB,QAAY,EAAE,YAAY,CAAA;CACvB,CA4CH;AAuGD;;;;;;;;;;GAUG;AACH,+CAJW,qBAAqB,MAAO,SAC5B,MAAM,GACJ,qBAAqB,CA6ZjC;kBA5lBiB,qCAAqC;sCAiBjB,oCAAoC;sCARpC,2DAA2D"}
+{"version":3,"file":"make_foliage_material.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/material/make_foliage_material.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,yBAAyB,EAAE,kBAAkB,GAAC,IAAI,GACvD,OAAO,2DAA2D,EAAE,qBAAqB,CA6QrG"}