@woosh/meep-engine 3.57.0 → 3.59.0

package/src/generation/foliage/analysis/crown_opacity_measure.js

@@ -1,3 +1,4 @@
+import { tri2_rasterize_barycentric } from "../../../core/geom/2d/triangle/tri2_rasterize_barycentric.js";
 import { assert } from "../../../core/assert.js";
 import { typed_array_value_denormalize } from "../../../core/collection/array/typed/typed_array_value_denormalize.js";
 import { convex_hull_monotone_2d } from "../../../core/geom/2d/convex-hull/convex_hull_monotone_2d.js";
@@ -203,15 +204,16 @@ function raster_geometry(
     raster, projected, positions, uvs, index, triangle_count,
     atlas, alpha_channel, alpha_scale, leaf_transmittance, crown_base
 ) {
-    const width = raster.width;
-    const height = raster.height;
-    const T = raster.transmittance;
-    const T_foliage = raster.foliage_transmittance;
-    const flags = raster.flags;
-    const is_foliage = uvs !== null;
-    const atlas_w = is_foliage ? atlas.width : 0;
-    const atlas_h = is_foliage ? atlas.height : 0;
-    const blocked = 1.0 - leaf_transmittance;
+    const v = RASTER_VISITOR;
+    v.raster = raster;
+    v.uvs = uvs;
+    v.atlas = atlas;
+    v.atlas_w = uvs !== null ? atlas.width : 0;
+    v.atlas_h = uvs !== null ? atlas.height : 0;
+    v.alpha_channel = alpha_channel;
+    v.alpha_scale = alpha_scale;
+    v.blocked = 1.0 - leaf_transmittance;
+    v.crown_base = crown_base;
 
     for (let t = 0; t < triangle_count; t++) {
         let i0, i1, i2;
@@ -225,110 +227,86 @@ function raster_geometry(
             i2 = t * 3 + 2;
         }
 
-        let x0 = projected[i0 * 2], y0 = projected[i0 * 2 + 1];
-        let x1 = projected[i1 * 2], y1 = projected[i1 * 2 + 1];
-        let x2 = projected[i2 * 2], y2 = projected[i2 * 2 + 1];
-
-        let area = (x1 - x0) * (y2 - y0) - (y1 - y0) * (x2 - x0);
-        if (!(Math.abs(area) > 0)) {
-            // edge-on: a card has no thickness
-            continue;
-        }
-        if (area < 0) {
-            // counter-clockwise, so the interior is where all three edge functions are positive
-            let s = i1; i1 = i2; i2 = s;
-            s = x1; x1 = x2; x2 = s;
-            s = y1; y1 = y2; y2 = s;
-            area = -area;
-        }
-        const inv_area = 1.0 / area;
-
-        // a point on an edge belongs to the triangle that edge runs up through (or left along) in
-        const own_0 = (y2 - y1) > 0 || ((y2 - y1) === 0 && (x2 - x1) < 0);
-        const own_1 = (y0 - y2) > 0 || ((y0 - y2) === 0 && (x0 - x2) < 0);
-        const own_2 = (y1 - y0) > 0 || ((y1 - y0) === 0 && (x1 - x0) < 0);
-
         const h0 = positions[i0 * 3 + 1];
         const h1 = positions[i1 * 3 + 1];
         const h2 = positions[i2 * 3 + 1];
         if (Math.max(h0, h1, h2) < crown_base) {
             continue;
         }
+        v.i0 = i0;
+        v.i1 = i1;
+        v.i2 = i2;
+        v.h0 = h0;
+        v.h1 = h1;
+        v.h2 = h2;
         // only a triangle across the crown base is cut per fragment: one wholly above keeps every fragment, where an
         // interpolated height could round below a base it sits on
-        const cut_at_base = Math.min(h0, h1, h2) < crown_base;
-
-        const col_lo = Math.max(0, Math.ceil(Math.min(x0, x1, x2) - 0.5));
-        const col_hi = Math.min(width - 1, Math.floor(Math.max(x0, x1, x2) - 0.5));
-        const row_lo = Math.max(0, Math.ceil(Math.min(y0, y1, y2) - 0.5));
-        const row_hi = Math.min(height - 1, Math.floor(Math.max(y0, y1, y2) - 0.5));
-
-        for (let row = row_lo; row <= row_hi; row++) {
-            const cy = row + 0.5;
-
-            // Each edge function is linear along the row, `e(cx) = a - dy * cx`, and bounds cx on one side: the row's
-            // span, widened by a pixel each way so the exact tests below keep their say on the edges
-            let x_lower = -Infinity;
-            let x_upper = Infinity;
-            let dy = y2 - y1;
-            let a = (x2 - x1) * (cy - y1) + dy * x1;
-            if (dy > 0) x_upper = Math.min(x_upper, a / dy); else if (dy < 0) x_lower = Math.max(x_lower, a / dy); else if (a < 0) continue;
-            dy = y0 - y2;
-            a = (x0 - x2) * (cy - y2) + dy * x2;
-            if (dy > 0) x_upper = Math.min(x_upper, a / dy); else if (dy < 0) x_lower = Math.max(x_lower, a / dy); else if (a < 0) continue;
-            dy = y1 - y0;
-            a = (x1 - x0) * (cy - y0) + dy * x0;
-            if (dy > 0) x_upper = Math.min(x_upper, a / dy); else if (dy < 0) x_lower = Math.max(x_lower, a / dy); else if (a < 0) continue;
-
-            const span_lo = Math.max(col_lo, Math.ceil(x_lower - 0.5) - 1);
-            const span_hi = Math.min(col_hi, Math.floor(x_upper - 0.5) + 1);
-
-            for (let col = span_lo; col <= span_hi; col++) {
-                const cx = col + 0.5;
-
-                const e0 = (x2 - x1) * (cy - y1) - (y2 - y1) * (cx - x1);
-                if (e0 < 0 || (e0 === 0 && !own_0)) continue;
-                const e1 = (x0 - x2) * (cy - y2) - (y0 - y2) * (cx - x2);
-                if (e1 < 0 || (e1 === 0 && !own_1)) continue;
-                const e2 = (x1 - x0) * (cy - y0) - (y1 - y0) * (cx - x0);
-                if (e2 < 0 || (e2 === 0 && !own_2)) continue;
-
-                const l0 = e0 * inv_area;
-                const l1 = e1 * inv_area;
-                const l2 = e2 * inv_area;
-
-                if (cut_at_base && l0 * h0 + l1 * h1 + l2 * h2 < crown_base) continue;
-
-                const k = row * width + col;
-
-                if (!is_foliage) {
-                    T[k] = 0.0;
-                    flags[k] |= FLAG_DRAWN;
-                    continue;
-                }
-
-                if (T_foliage[k] === 0.0) {
-                    // an opaque leaf is already here: nothing behind or in front of it changes the pixel
-                    continue;
-                }
-
-                const u = l0 * uvs[i0 * 2] + l1 * uvs[i1 * 2] + l2 * uvs[i2 * 2];
-                const v = l0 * uvs[i0 * 2 + 1] + l1 * uvs[i1 * 2 + 1] + l2 * uvs[i2 * 2 + 1];
-                scratch_position[0] = u * atlas_w - 0.5;
-                scratch_position[1] = v * atlas_h - 0.5;
-                atlas.sampleChannelBilinearArray(scratch_sample, 0, scratch_position, 0, alpha_channel);
-                const alpha = clamp(scratch_sample[0] * alpha_scale, 0.0, 1.0);
-                if (alpha <= 0.0) continue;
-
-                const pass = 1.0 - alpha * blocked;
-                T[k] *= pass;
-                T_foliage[k] *= pass;
-                flags[k] |= FLAG_DRAWN | FLAG_FOLIAGE;
-            }
-        }
+        v.cut_at_base = Math.min(h0, h1, h2) < crown_base;
+
+        tri2_rasterize_barycentric(
+            raster.width, raster.height,
+            projected[i0 * 2], projected[i0 * 2 + 1],
+            projected[i1 * 2], projected[i1 * 2 + 1],
+            projected[i2 * 2], projected[i2 * 2 + 1],
+            v
+        );
     }
 }
 
+/**
+ * What one pixel of a triangle does to the raster: bark makes it opaque, a leaf passes what its alpha does not cover.
+ */
+const RASTER_VISITOR = {
+    /** @type {CrownRaster|null} */
+    raster: null,
+    /** @type {Float32Array|null} */
+    uvs: null,
+    /** @type {Sampler2D|null} */
+    atlas: null,
+    atlas_w: 0,
+    atlas_h: 0,
+    alpha_channel: 0,
+    alpha_scale: 1,
+    blocked: 1,
+    crown_base: -Infinity,
+    i0: 0, i1: 0, i2: 0,
+    h0: 0, h1: 0, h2: 0,
+    cut_at_base: false,
+    visit(col, row, l0, l1, l2) {
+        if (this.cut_at_base && l0 * this.h0 + l1 * this.h1 + l2 * this.h2 < this.crown_base) return;
+
+        const raster = this.raster;
+        const k = row * raster.width + col;
+
+        const uvs = this.uvs;
+        if (uvs === null) {
+            raster.transmittance[k] = 0.0;
+            raster.flags[k] |= FLAG_DRAWN;
+            return;
+        }
+
+        const T_foliage = raster.foliage_transmittance;
+        if (T_foliage[k] === 0.0) {
+            // an opaque leaf is already here: nothing behind or in front of it changes the pixel
+            return;
+        }
+
+        const i0 = this.i0, i1 = this.i1, i2 = this.i2;
+        const u = l0 * uvs[i0 * 2] + l1 * uvs[i1 * 2] + l2 * uvs[i2 * 2];
+        const v = l0 * uvs[i0 * 2 + 1] + l1 * uvs[i1 * 2 + 1] + l2 * uvs[i2 * 2 + 1];
+        scratch_position[0] = u * this.atlas_w - 0.5;
+        scratch_position[1] = v * this.atlas_h - 0.5;
+        this.atlas.sampleChannelBilinearArray(scratch_sample, 0, scratch_position, 0, this.alpha_channel);
+        const alpha = clamp(scratch_sample[0] * this.alpha_scale, 0.0, 1.0);
+        if (alpha <= 0.0) return;
+
+        const pass = 1.0 - alpha * this.blocked;
+        raster.transmittance[k] *= pass;
+        T_foliage[k] *= pass;
+        raster.flags[k] |= FLAG_DRAWN | FLAG_FOLIAGE;
+    }
+};
+
 /**
  * Marks the foliated part of the view: the morphological closing of the foliage's pixels by a ball of `radius_px`,
  * so a gap narrower than the ball's diameter is a microhole within the foliage and a wider one is a large gap

package/src/generation/foliage/analysis/foliage_measure_leaf_area.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"foliage_measure_leaf_area.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/foliage_measure_leaf_area.js"],"names":[],"mappings":"AAkBA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,oDATW,OAAO,6BAA6B,EAAE,YAAY,eAClD,OAAO,wCAAwC,EAAE,oBAAoB,UACrE,OAAO,gCAAgC,EAAE,iBAAiB,UAC1D,OAAO,mCAAmC,EAAE,kBAAkB,GAAC,IAAI,UAEnE,OAAO,uDAAuD,EAAE,SAAS,GAEvE,eAAe,CAsI3B;;;;;WA3Ka,MAAM;;;;aACN,YAAY;;;;;kBACZ,YAAY;;;;;0BAEZ,MAAM;;;;2BAEN,MAAM"}
+{"version":3,"file":"foliage_measure_leaf_area.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/foliage_measure_leaf_area.js"],"names":[],"mappings":"AAYA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,oDATW,OAAO,6BAA6B,EAAE,YAAY,eAClD,OAAO,wCAAwC,EAAE,oBAAoB,UACrE,OAAO,gCAAgC,EAAE,iBAAiB,UAC1D,OAAO,mCAAmC,EAAE,kBAAkB,GAAC,IAAI,UAEnE,OAAO,uDAAuD,EAAE,SAAS,GAEvE,eAAe,CAsI3B;;;;;WA3Ka,MAAM;;;;aACN,YAAY;;;;;kBACZ,YAAY;;;;;0BAEZ,MAAM;;;;2BAEN,MAAM"}

package/src/generation/foliage/analysis/foliage_measure_leaf_area.js

@@ -5,14 +5,8 @@ import { tri2_rasterize_coverage } from "../../../core/geom/2d/triangle/tri2_ras
 import { tri2_signed_area } from "../../../core/geom/2d/triangle/tri2_signed_area.js";
 import { tri3_area } from "../../../core/geom/3d/triangle/tri3_area.js";
 import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
-import { TreeLODConfig } from "../config/TreeLODConfig.js";
 import { tree_mesh_build_foliage } from "../mesh/tree_mesh_build_foliage.js";
 
-/**
- * Every card the tree has: the full set, before any LOD decimates it or scales it up to compensate.
- * @type {TreeLODConfig}
- */
-const ALL_CARDS = new TreeLODConfig();
 
 const SCRATCH_TRIANGLE = new Float64Array(6);
 
@@ -72,7 +66,7 @@ export function foliage_measure_leaf_area(skeleton, attachments, config, cutout,
 		crown_leaf_area_index: 0.0
 	};
 
-	const geometry = tree_mesh_build_foliage(skeleton, attachments, config, ALL_CARDS, cutout);
+	const geometry = tree_mesh_build_foliage(skeleton, attachments, config, cutout);
 	if (geometry === null) {
 		return result;
 	}

package/src/generation/foliage/analysis/tree_crown_opacity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree_crown_opacity.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_crown_opacity.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAVW,OAAO,uBAAuB,EAAE,SAAS;IAExB,GAAG,GAApB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,kBAAkB,GAAnC,MAAM;SACN,YAAY,GACV,YAAY,CAqBxB;6BAxD4B,mBAAmB"}
+{"version":3,"file":"tree_crown_opacity.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_crown_opacity.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAVW,OAAO,uBAAuB,EAAE,SAAS;IAExB,GAAG,GAApB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,kBAAkB,GAAnC,MAAM;SACN,YAAY,GACV,YAAY,CAqBxB;6BAzD4B,mBAAmB"}

package/src/generation/foliage/analysis/tree_crown_opacity.js

@@ -12,7 +12,8 @@ import { foliage_card_reach } from "../skeleton/foliage_card_density.js";
  * @returns {number}
  */
 function median_card_length(asset) {
-    const attachments = asset.attachments;
+    // a tree grown by its generator graph draws its prototypes' leaves
+    const attachments = asset.shoot_prototypes !== null ? asset.shoot_prototypes.attachments : asset.attachments;
     assert.greaterThan(attachments.count, 0, 'a leafless tree has no card length: pass microhole_radius');
     const scales = attachments.scales.slice(0, attachments.count).sort();
     return foliage_card_reach(foliage_tile_layout(asset.config), scales[scales.length >> 1]);
@@ -47,7 +48,7 @@ export function tree_crown_opacity(asset, {
 
     const level = asset.lods[lod];
     const foliage = level.foliage_geometry;
-    const atlas = foliage !== null ? asset.foliage_material.texture_albedo.image.source : null;
+    const atlas = foliage !== null ? level.foliage_material.texture_albedo.image.source : null;
 
     return crown_opacity_measure(level.bark_geometry, foliage, atlas, {
         microhole_radius,

package/src/generation/foliage/analysis/tree_leaf_area_targets.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The leaf area a measured tree of a preset's species carries at breast-height diameter `dbh_cm` and height
+ * `height_m`: the range over the allometries that hold it, and every allometry's value with whether `dbh_cm` is inside
+ * its sample. `null` for a species with none.
+ *
+ * @param {TreePreset|string} preset
+ * @param {number} dbh_cm
+ * @param {number} height_m
+ * @returns {{low: number, high: number, values: Array<{source: string, leaf_area: number, in_sample: boolean}>}|null}
+ */
+export function tree_expected_leaf_area(preset: TreePreset | string, dbh_cm: number, height_m: number): {
+    low: number;
+    high: number;
+    values: Array<{
+        source: string;
+        leaf_area: number;
+        in_sample: boolean;
+    }>;
+} | null;
+/**
+ * Measured whole-tree leaf area against breast-height diameter, per preset species, from forest-grown samples (no
+ * open-grown allometry was found). Broadleaves are one-sided; the conifers' convention differs between sources, which
+ * is part of the spread. See `CROWN_FULLNESS_BRIEF_2026_10_26.md`.
+ *
+ * - [F17]: Forrester et al. (2017), For. Ecol. Manage. 396: 160-175, Appendix A, Table A.5: `ln LA = ln b0 + b ln d`,
+ *   times the correction factor.
+ * - [M98]: Martin et al. (1998), Can. J. For. Res. 28: 1648-1659, Table 4: `log10 LA = a + b log10 d`, times the
+ *   correction factor.
+ * - [GG15]: Gomez-Garcia & Perez-Rodriguez (2015), Bosque 36: 255-264, eq. 9: leaf mass `0.01369 d²` kg, times the SLA
+ *   of mature Q. robur, 12.85-16.2 m²/kg (F17 Table A.1).
+ * - [R09]: Repola (2009), Silva Fennica 43: 184, eqs. 7 and 15: needle mass, times projected SLA (Scots pine 3.86-5.65
+ *   m²/kg, Bilgili et al. 2020, Dendrobiology 84: 1-11; Norway spruce 3.3-5.0 m²/kg, F17 Table A.1).
+ *
+ * @type {Object<string, LeafAreaAllometry[]>}
+ */
+export const TREE_LEAF_AREA_ALLOMETRY: {
+    [x: string]: LeafAreaAllometry[];
+};
+/**
+ * FIA's ratings of a healthy crown seen from the side: crown density, the share of the crown outline that foliage,
+ * branches and reproductive structures block, and foliage transparency, the skylight through the foliated part
+ * [Randolph 2006, as cited in `CROWN_FILLING_BRIEF_2026_10_26.md`].
+ * @type {{density_min: number, density_max: number, transparency: number}}
+ */
+export const TREE_CROWN_RATING_TARGET: {
+    density_min: number;
+    density_max: number;
+    transparency: number;
+};
+export type LeafAreaAllometry = {
+    /**
+     * citation
+     */
+    source: string;
+    /**
+     * the sample's breast-height diameters (cm)
+     */
+    dbh_min: number;
+    dbh_max: number;
+    /**
+     * m² at a DBH (cm) and height (m)
+     */
+    leaf_area: (arg0: number, arg1: number) => number;
+};
+import { TreePreset } from "../config/TreePreset.js";
+//# sourceMappingURL=tree_leaf_area_targets.d.ts.map

package/src/generation/foliage/analysis/tree_leaf_area_targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_leaf_area_targets.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_leaf_area_targets.js"],"names":[],"mappings":"AAoEA;;;;;;;;;GASG;AACH,gDALW,UAAU,GAAC,MAAM,UACjB,MAAM,YACN,MAAM,GACJ;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAC,CAAC,CAAA;CAAC,GAAC,IAAI,CAkBpH;AA1ED;;;;;;;;;;;;;;;GAeG;AACH;QAFiB,MAAM,GAAE,iBAAiB,EAAE;EAwB1C;AAEF;;;;;GAKG;AACH,uCAFU;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAC,CAE2B;;;;;YA9DvF,MAAM;;;;aACN,MAAM;aACN,MAAM;;;;sBACG,MAAM,QAAE,MAAM,KAAG,MAAM;;2BAPnB,yBAAyB"}

package/src/generation/foliage/analysis/tree_leaf_area_targets.js

@@ -0,0 +1,95 @@
+import { TreePreset } from "../config/TreePreset.js";
+
+/**
+ * @typedef {Object} LeafAreaAllometry
+ * @property {string} source citation
+ * @property {number} dbh_min the sample's breast-height diameters (cm)
+ * @property {number} dbh_max
+ * @property {function(number, number): number} leaf_area m² at a DBH (cm) and height (m)
+ */
+
+/**
+ * Repola (2009) needle mass (kg) of a tree of diameter `d` (cm) and height `h` (m): `ln y = a + b dS / (dS + k) +
+ * c h / (h + 1)`, `dS = 2 + 1.25 d`, the log bias corrected by half the summed variances [Repola 2009, Silva Fennica 43:
+ * 184].
+ */
+function repola_needles(a, b, k, c, variances, d, h) {
+    const ds = 2 + 1.25 * d;
+    return Math.exp(a + b * ds / (ds + k) + c * h / (h + 1) + 0.5 * variances);
+}
+
+/**
+ * Measured whole-tree leaf area against breast-height diameter, per preset species, from forest-grown samples (no
+ * open-grown allometry was found). Broadleaves are one-sided; the conifers' convention differs between sources, which
+ * is part of the spread. See `CROWN_FULLNESS_BRIEF_2026_10_26.md`.
+ *
+ * - [F17]: Forrester et al. (2017), For. Ecol. Manage. 396: 160-175, Appendix A, Table A.5: `ln LA = ln b0 + b ln d`,
+ *   times the correction factor.
+ * - [M98]: Martin et al. (1998), Can. J. For. Res. 28: 1648-1659, Table 4: `log10 LA = a + b log10 d`, times the
+ *   correction factor.
+ * - [GG15]: Gomez-Garcia & Perez-Rodriguez (2015), Bosque 36: 255-264, eq. 9: leaf mass `0.01369 d²` kg, times the SLA
+ *   of mature Q. robur, 12.85-16.2 m²/kg (F17 Table A.1).
+ * - [R09]: Repola (2009), Silva Fennica 43: 184, eqs. 7 and 15: needle mass, times projected SLA (Scots pine 3.86-5.65
+ *   m²/kg, Bilgili et al. 2020, Dendrobiology 84: 1-11; Norway spruce 3.3-5.0 m²/kg, F17 Table A.1).
+ *
+ * @type {Object<string, LeafAreaAllometry[]>}
+ */
+export const TREE_LEAF_AREA_ALLOMETRY = {
+    [TreePreset.Oak]: [
+        { source: "F17 Quercus robur", dbh_min: 5.9, dbh_max: 67.5, leaf_area: (d) => Math.exp(-1.7839) * Math.pow(d, 2.1375) * 0.966 },
+        { source: "GG15 leaf mass x SLA 12.85", dbh_min: 5, dbh_max: 40, leaf_area: (d) => 0.01369 * d * d * 12.85 },
+        { source: "GG15 leaf mass x SLA 16.2", dbh_min: 5, dbh_max: 40, leaf_area: (d) => 0.01369 * d * d * 16.2 }
+    ],
+    [TreePreset.Pine]: [
+        { source: "F17 Pinus sylvestris", dbh_min: 1, dbh_max: 61.7, leaf_area: (d) => Math.exp(-2.065) * Math.pow(d, 1.746) * 1.0096 },
+        { source: "R09 needles x SLA 3.86", dbh_min: 1.5, dbh_max: 35.8, leaf_area: (d, h) => repola_needles(-6.303, 14.472, 6, -3.976, 0.109 + 0.118, d, h) * 3.86 },
+        { source: "R09 needles x SLA 5.65", dbh_min: 1.5, dbh_max: 35.8, leaf_area: (d, h) => repola_needles(-6.303, 14.472, 6, -3.976, 0.109 + 0.118, d, h) * 5.65 }
+    ],
+    [TreePreset.Maple]: [
+        { source: "M98 Acer rubrum", dbh_min: 6.3, dbh_max: 52.4, leaf_area: (d) => Math.pow(10, -0.494) * Math.pow(d, 1.762) * 1.046 }
+    ],
+    [TreePreset.Spruce]: [
+        { source: "F17 Picea abies", dbh_min: 1, dbh_max: 76.4, leaf_area: (d) => Math.exp(-1.3434) * Math.pow(d, 1.857) * 1.011 },
+        { source: "R09 needles x SLA 3.3", dbh_min: 1.7, dbh_max: 41.7, leaf_area: (d, h) => repola_needles(-2.994, 12.251, 10, -3.415, 0.107 + 0.089, d, h) * 3.3 },
+        { source: "R09 needles x SLA 5.0", dbh_min: 1.7, dbh_max: 41.7, leaf_area: (d, h) => repola_needles(-2.994, 12.251, 10, -3.415, 0.107 + 0.089, d, h) * 5.0 }
+    ],
+    [TreePreset.Birch]: [
+        { source: "F17 Betula pendula/pubescens", dbh_min: 0.6, dbh_max: 38, leaf_area: (d) => Math.exp(-1.5663) * Math.pow(d, 1.8857) * 1.169 }
+    ]
+};
+
+/**
+ * FIA's ratings of a healthy crown seen from the side: crown density, the share of the crown outline that foliage,
+ * branches and reproductive structures block, and foliage transparency, the skylight through the foliated part
+ * [Randolph 2006, as cited in `CROWN_FILLING_BRIEF_2026_10_26.md`].
+ * @type {{density_min: number, density_max: number, transparency: number}}
+ */
+export const TREE_CROWN_RATING_TARGET = { density_min: 0.45, density_max: 0.51, transparency: 0.15 };
+
+/**
+ * The leaf area a measured tree of a preset's species carries at breast-height diameter `dbh_cm` and height
+ * `height_m`: the range over the allometries that hold it, and every allometry's value with whether `dbh_cm` is inside
+ * its sample. `null` for a species with none.
+ *
+ * @param {TreePreset|string} preset
+ * @param {number} dbh_cm
+ * @param {number} height_m
+ * @returns {{low: number, high: number, values: Array<{source: string, leaf_area: number, in_sample: boolean}>}|null}
+ */
+export function tree_expected_leaf_area(preset, dbh_cm, height_m) {
+    const list = TREE_LEAF_AREA_ALLOMETRY[preset];
+    if (list === undefined) {
+        return null;
+    }
+    const values = list.map(a => ({
+        source: a.source,
+        leaf_area: a.leaf_area(dbh_cm, height_m),
+        in_sample: dbh_cm >= a.dbh_min && dbh_cm <= a.dbh_max
+    }));
+    let low = Infinity, high = -Infinity;
+    for (const v of values) {
+        low = Math.min(low, v.leaf_area);
+        high = Math.max(high, v.leaf_area);
+    }
+    return { low, high, values };
+}

package/src/generation/foliage/analysis/tree_render_cost.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Mean area (m^2) a tree's drawn envelope shows from the side, over every azimuth: the envelope is the convex hull of
+ * the drawn vertices in each of `slices` equal horizontal slices, and a convex slice's mean width over azimuths is its
+ * perimeter over PI (Cauchy), so the area is the sum of `perimeter / PI * thickness`. It is what a viewer at the
+ * tree's height sees of it, the part of the screen the tree's triangles are spent on.
+ *
+ * @param {Array<ArrayLike<number>>} position_arrays vertex positions, 3 per vertex, y up
+ * @param {number} [slices] horizontal slices the height is cut into; the measure's resolution
+ * @returns {number}
+ */
+export function tree_envelope_side_area(position_arrays: Array<ArrayLike<number>>, slices?: number): number;
+/**
+ * What a tree grown as `skeleton` shows from the side, m^2: `tree_envelope_side_area` of its wood's nodes and every
+ * leaf's card, whatever an LOD draws them as.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card
+ *        (`tree_mesh_build_foliage`), `null` for a leafless tree
+ * @param {Float32Array|null} [carried] the cards of the leaves it draws but does not hold, its shoot prototypes'
+ *        (`tree_shoot_instance_leaves`): positions
+ * @returns {number}
+ */
+export function tree_grown_side_area(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null, carried?: Float32Array | null): number;
+/**
+ * @typedef {Object} TreeRenderCost
+ * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side (`TreeAsset.side_area`)
+ * @property {number[]} triangles bark and foliage triangles of each LOD
+ * @property {number[]} triangle_density each LOD's triangles per m^2 of `side_area`
+ * @property {number[]} joints each LOD's wind joints
+ * @property {number[]} joint_density each LOD's joints per m^2 of `side_area`
+ * @property {number} texture_bytes the base levels of every foliage texture its LODs draw with, each counted once
+ * @property {number} texture_density `texture_bytes` per m^2 of `side_area`
+ */
+/**
+ * What a generated tree costs to draw: its triangles and wind joints at every LOD and its foliage textures, each per
+ * square metre of what the tree shows from the side. A bigger tree covers more of the screen and may spend proportionately more.
+ *
+ * @param {import("../asset/TreeAsset.js").TreeAsset} asset from `generate_tree`
+ * @returns {TreeRenderCost}
+ */
+export function tree_render_cost(asset: import("../asset/TreeAsset.js").TreeAsset): TreeRenderCost;
+/**
+ * The most a generated tree may spend per square metre it shows from the side (`tree_render_cost`), at each LOD and in
+ * wind joints: the densest of the presets at 6aff5265e (2026-10-25), the last generator whose trees were drawn in real
+ * time, before twigs were meshed shoot by shoot (seed 1337), over `tree_grown_side_area` (its LOD0 drew every leaf's
+ * card). Triangles: the willow at LOD0 and LOD1, the shrub at LOD2; joints, which every LOD's rig is held to: the
+ * shrub; foliage texture bytes, every map's base level, which all of a tree's LODs share: the shrub, whose leaf atlas
+ * was the 640 KiB every preset's was. The fern was 7,065 triangles per m^2 at LOD0 there, nine times the willow, and
+ * its atlas 1.3 MiB per m^2, and is held to the same ceiling.
+ *
+ * A ceiling, not a target: a tree spends what its look needs, up to this.
+ *
+ * @type {{triangle_density: number[], joint_density: number, texture_density: number}}
+ */
+export const TREE_RENDER_COST_CEILING: {
+    triangle_density: number[];
+    joint_density: number;
+    texture_density: number;
+};
+export type TreeRenderCost = {
+    /**
+     * m^2, `tree_grown_side_area`: what the tree grew shows from the side (`TreeAsset.side_area`)
+     */
+    side_area: number;
+    /**
+     * bark and foliage triangles of each LOD
+     */
+    triangles: number[];
+    /**
+     * each LOD's triangles per m^2 of `side_area`
+     */
+    triangle_density: number[];
+    /**
+     * each LOD's wind joints
+     */
+    joints: number[];
+    /**
+     * each LOD's joints per m^2 of `side_area`
+     */
+    joint_density: number[];
+    /**
+     * the base levels of every foliage texture its LODs draw with, each counted once
+     */
+    texture_bytes: number;
+    /**
+     * `texture_bytes` per m^2 of `side_area`
+     */
+    texture_density: number;
+};
+//# sourceMappingURL=tree_render_cost.d.ts.map

package/src/generation/foliage/analysis/tree_render_cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_render_cost.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/analysis/tree_render_cost.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,yDAJW,MAAM,UAAU,MAAM,CAAC,CAAC,WACxB,MAAM,GACJ,MAAM,CA8ClB;AAiBD;;;;;;;;;;GAUG;AACH,+CAPW,OAAO,6BAA6B,EAAE,YAAY,UAClD,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,YAEpE,YAAY,GAAC,IAAI,GAEf,MAAM,CAelB;AAaD;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,cAAc,CA6B1B;AAjGD;;;;;;;;;;;;GAYG;AACH,uCAFU;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAC,CAE4C;;;;;eAyCpH,MAAM;;;;eACN,MAAM,EAAE;;;;sBACR,MAAM,EAAE;;;;YACR,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;mBACR,MAAM;;;;qBACN,MAAM"}