@woosh/meep-engine 3.56.0 → 3.58.0

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,186 @@
+import { assert } from "../../../core/assert.js";
+import { convex_hull_monotone_2d } from "../../../core/geom/2d/convex-hull/convex_hull_monotone_2d.js";
+import { polygon2_signed_area } from "../../../core/geom/2d/polygon/polygon2_signed_area.js";
+import { tri2_rasterize_coverage } from "../../../core/geom/2d/triangle/tri2_rasterize_coverage.js";
+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 { tree_mesh_build_foliage } from "../mesh/tree_mesh_build_foliage.js";
+
+
+const SCRATCH_TRIANGLE = new Float64Array(6);
+
+/**
+ * @typedef {Object} FoliageLeafArea
+ * @property {number} total one-sided leaf area of every card, m^2
+ * @property {Float64Array} by_card one-sided leaf area of each attachment, m^2
+ * @property {Float64Array} by_generator one-sided leaf area of the cards each `config.branches` generator's branches
+ *           carry, m^2
+ * @property {number} crown_projected_area area of the crown seen from straight above, m^2: the convex hull of every
+ *           vertex of a card triangle that shows any leaf, projected onto the horizontal (x, z) plane
+ * @property {number} crown_leaf_area_index `total / crown_projected_area`, the tree's own leaf area index
+ */
+
+/**
+ * Measures the one-sided leaf area a tree's foliage cards draw.
+ *
+ * Builds the cards as `tree_mesh_build_foliage` draws them and integrates the atlas's alpha over each triangle. A
+ * triangle maps its atlas UVs onto itself affinely, so every texel's leaf lands on it at the triangle's own ratio of
+ * area to UV area: its leaf area is its area times the alpha-weighted fraction of its UV footprint. Everything the
+ * cards do to their tiles is therefore measured, not modelled: each card's own tile (`attachments.variant_indices`)
+ * and scale (`attachments.scales`), every plane a cross or tri-star stands up, the strip below the tile's anchor
+ * (`foliage_tile_layout`) that a folded card does not draw, folds, arches and droops, a frond's segments and tapering envelope, and a hull card's fan, which
+ * shows only the texels inside its tile's hull.
+ *
+ * Where it approximates:
+ * - each texel's alpha stands over its whole square (the reconstruction `FoliageAtlasCutout.coverage` sums), at the
+ *   atlas's full resolution; a semi-transparent texel counts as that fraction of leaf, which is the expected area the
+ *   path tracer's stochastic alpha test leaves opaque
+ * - the atlas's alpha is stored in 8 bits, so it differs from the unrounded alpha `FoliageAtlasCutout.coverage` sums
+ *   by up to half a step per texel
+ * - every card counts: the full set, before any LOD decimates it or enlarges what it keeps to compensate
+ * - cards in their rest pose: wind bends cards without stretching them, but this measures none of it
+ * - leaf is whatever the atlas draws opaque, the petioles and rachis it draws included
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} config
+ * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null} cutout the atlas's fitted shape, which
+ *        hull cards outline; `null` draws them over whole tiles, as `tree_mesh_build_foliage` does
+ * @param {import("../../../engine/graphics/texture/sampler/Sampler2D.js").Sampler2D} albedo the atlas the cards show,
+ *        8-bit RGBA with straight alpha: `make_foliage_material(...).texture_albedo.image.source`
+ * @returns {FoliageLeafArea}
+ */
+export function foliage_measure_leaf_area(skeleton, attachments, config, cutout, albedo) {
+	assert.equal(albedo.itemSize, 4, 'albedo.itemSize');
+	assert.ok(albedo.data instanceof Uint8Array || albedo.data instanceof Uint8ClampedArray, 'albedo must be 8-bit');
+
+	const card_count = attachments.count;
+	const by_card = new Float64Array(card_count);
+	const by_generator = new Float64Array(config.branches.length);
+	const result = {
+		total: 0.0,
+		by_card,
+		by_generator,
+		crown_projected_area: 0.0,
+		crown_leaf_area_index: 0.0
+	};
+
+	const geometry = tree_mesh_build_foliage(skeleton, attachments, config, cutout);
+	if (geometry === null) {
+		return result;
+	}
+
+	const positions = geometry.getAttribute(StandardAttributes.Position).data;
+	const uvs = geometry.getAttribute(StandardAttributes.TextureCoordinates0).data;
+	const index = geometry.index.data;
+	const triangle_count = geometry.getIndexCount() / 3;
+	const triangles_per_card = triangle_count / card_count;
+	assert.ok(Number.isInteger(triangles_per_card), 'every card is built from as many triangles as the next');
+
+	const width = albedo.width;
+	const height = albedo.height;
+	const data = albedo.data;
+	// each texel's alpha stands over its whole square, as an atlas tile's `FoliageAtlasCutout.coverage` counts it
+	const alpha_over_triangle = {
+		width,
+		height,
+		sum: 0.0,
+		add(x, y, area) {
+			this.sum += data[(y * width + x) * 4 + 3] * area;
+		}
+	};
+
+	// A card triangle's UVs are fixed by its tile and its place in the card, so their leaf fraction is computed once
+	// per (tile, place): the triangle in texels, then its leaf fraction. Checked on every reuse.
+	const fractions = new Map();
+	const leafy_vertices = new Uint8Array(positions.length / 3);
+
+	for (let c = 0; c < card_count; c++) {
+		const tile = attachments.variant_indices[c];
+		let card_area = 0.0;
+
+		for (let k = 0; k < triangles_per_card; k++) {
+			const t = c * triangles_per_card + k;
+			const a = index[t * 3];
+			const b = index[t * 3 + 1];
+			const d = index[t * 3 + 2];
+
+			SCRATCH_TRIANGLE[0] = uvs[a * 2] * width;
+			SCRATCH_TRIANGLE[1] = uvs[a * 2 + 1] * height;
+			SCRATCH_TRIANGLE[2] = uvs[b * 2] * width;
+			SCRATCH_TRIANGLE[3] = uvs[b * 2 + 1] * height;
+			SCRATCH_TRIANGLE[4] = uvs[d * 2] * width;
+			SCRATCH_TRIANGLE[5] = uvs[d * 2 + 1] * height;
+
+			const key = tile * triangles_per_card + k;
+			let entry = fractions.get(key);
+			let same = entry !== undefined;
+			for (let i = 0; same && i < 6; i++) {
+				same = entry[i] === SCRATCH_TRIANGLE[i];
+			}
+			if (!same) {
+				const uv_area = Math.abs(tri2_signed_area(
+					SCRATCH_TRIANGLE[0], SCRATCH_TRIANGLE[1],
+					SCRATCH_TRIANGLE[2], SCRATCH_TRIANGLE[3],
+					SCRATCH_TRIANGLE[4], SCRATCH_TRIANGLE[5]
+				));
+				entry = new Float64Array(7);
+				entry.set(SCRATCH_TRIANGLE);
+				if (uv_area > 1e-12) {
+					alpha_over_triangle.sum = 0.0;
+					tri2_rasterize_coverage(
+						alpha_over_triangle,
+						SCRATCH_TRIANGLE[0], SCRATCH_TRIANGLE[1],
+						SCRATCH_TRIANGLE[2], SCRATCH_TRIANGLE[3],
+						SCRATCH_TRIANGLE[4], SCRATCH_TRIANGLE[5]
+					);
+					entry[6] = alpha_over_triangle.sum / (255 * uv_area);
+				}
+				if (!fractions.has(key)) {
+					fractions.set(key, entry);
+				}
+			}
+			const leaf_fraction = entry[6];
+			if (leaf_fraction <= 0.0) continue;
+
+			card_area += leaf_fraction * tri3_area(
+				positions[a * 3], positions[a * 3 + 1], positions[a * 3 + 2],
+				positions[b * 3], positions[b * 3 + 1], positions[b * 3 + 2],
+				positions[d * 3], positions[d * 3 + 1], positions[d * 3 + 2]
+			);
+
+			leafy_vertices[a] = 1;
+			leafy_vertices[b] = 1;
+			leafy_vertices[d] = 1;
+		}
+
+		by_card[c] = card_area;
+		by_generator[skeleton.branch_generator[attachments.carriers[c]]] += card_area;
+		result.total += card_area;
+	}
+
+	let leafy_count = 0;
+	for (let v = 0; v < leafy_vertices.length; v++) {
+		leafy_count += leafy_vertices[v];
+	}
+	const ground = new Float64Array(leafy_count * 2);
+	for (let v = 0, n = 0; v < leafy_vertices.length; v++) {
+		if (leafy_vertices[v] === 0) continue;
+		ground[n * 2] = positions[v * 3];
+		ground[n * 2 + 1] = positions[v * 3 + 2];
+		n++;
+	}
+	if (leafy_count >= 3) {
+		const hull = convex_hull_monotone_2d(ground, leafy_count);
+		const outline = new Float64Array(hull.length * 2);
+		for (let i = 0; i < hull.length; i++) {
+			outline[i * 2] = ground[hull[i] * 2];
+			outline[i * 2 + 1] = ground[hull[i] * 2 + 1];
+		}
+		result.crown_projected_area = Math.abs(polygon2_signed_area(outline, hull.length));
+	}
+	result.crown_leaf_area_index = result.crown_projected_area > 0.0 ? result.total / result.crown_projected_area : 0.0;
+
+	return result;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Crown density, foliage transparency and light intercepted from below of a generated tree, as drawn at its finest
+ * LOD: `crown_opacity_measure` over the LOD's bark and foliage geometry and the foliage material's albedo alpha.
+ *
+ * The micro/macro hole split defaults to the median card length: the closing fills every gap narrower than two
+ * leaves, a gap the leaves on either side of it would close by reaching into it. Wider gaps are where foliage does
+ * not occur, which FIA leaves out of the transparency rating.
+ *
+ * @param {import("../asset/TreeAsset.js").TreeAsset} asset from `generate_tree`, with the synthesized foliage material
+ * @param {Object} [options] as `crown_opacity_measure`'s, plus:
+ * @param {number} [options.lod=0] which LOD's geometry to measure
+ * @param {number} [options.microhole_radius] m, the median card length by default; required for a leafless tree
+ * @param {number} [options.pixel_size] m, what a rater resolves from one tree length by default
+ * @param {number} [options.frame_count] frames along each side of the hemi-octahedral view grid, odd; 9 by default
+ * @param {number} [options.leaf_transmittance]
+ * @param {CrownOpacity} [out]
+ * @returns {CrownOpacity}
+ */
+export function tree_crown_opacity(asset: import("../asset/TreeAsset.js").TreeAsset, { lod, microhole_radius, pixel_size, frame_count, leaf_transmittance }?: {
+    lod?: number;
+    microhole_radius?: number;
+    pixel_size?: number;
+    frame_count?: number;
+    leaf_transmittance?: number;
+}, out?: CrownOpacity): CrownOpacity;
+import { CrownOpacity } from "./CrownOpacity.js";
+//# sourceMappingURL=tree_crown_opacity.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,58 @@
+import { assert } from "../../../core/assert.js";
+import { CrownOpacity } from "./CrownOpacity.js";
+import { crown_opacity_measure } from "./crown_opacity_measure.js";
+import { foliage_tile_layout } from "../material/foliage_tile.js";
+import { foliage_card_reach } from "../skeleton/foliage_card_density.js";
+
+/**
+ * Length of the median foliage card from where it hangs, m: the size of one leaf (or, on a needle-shoot card, a
+ * needle's reach) as drawn.
+ *
+ * @param {import("../asset/TreeAsset.js").TreeAsset} asset
+ * @returns {number}
+ */
+function median_card_length(asset) {
+    const 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]);
+}
+
+/**
+ * Crown density, foliage transparency and light intercepted from below of a generated tree, as drawn at its finest
+ * LOD: `crown_opacity_measure` over the LOD's bark and foliage geometry and the foliage material's albedo alpha.
+ *
+ * The micro/macro hole split defaults to the median card length: the closing fills every gap narrower than two
+ * leaves, a gap the leaves on either side of it would close by reaching into it. Wider gaps are where foliage does
+ * not occur, which FIA leaves out of the transparency rating.
+ *
+ * @param {import("../asset/TreeAsset.js").TreeAsset} asset from `generate_tree`, with the synthesized foliage material
+ * @param {Object} [options] as `crown_opacity_measure`'s, plus:
+ * @param {number} [options.lod=0] which LOD's geometry to measure
+ * @param {number} [options.microhole_radius] m, the median card length by default; required for a leafless tree
+ * @param {number} [options.pixel_size] m, what a rater resolves from one tree length by default
+ * @param {number} [options.frame_count] frames along each side of the hemi-octahedral view grid, odd; 9 by default
+ * @param {number} [options.leaf_transmittance]
+ * @param {CrownOpacity} [out]
+ * @returns {CrownOpacity}
+ */
+export function tree_crown_opacity(asset, {
+    lod = 0,
+    microhole_radius = median_card_length(asset),
+    pixel_size,
+    frame_count,
+    leaf_transmittance
+} = {}, out = new CrownOpacity()) {
+    assert.equal(asset.isTreeAsset, true, 'asset.isTreeAsset !== true');
+
+    const level = asset.lods[lod];
+    const foliage = level.foliage_geometry;
+    const atlas = foliage !== null ? level.foliage_material.texture_albedo.image.source : null;
+
+    return crown_opacity_measure(level.bark_geometry, foliage, atlas, {
+        microhole_radius,
+        pixel_size,
+        frame_count,
+        leaf_transmittance
+    }, out);
+}

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,88 @@
+/**
+ * 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
+ * @returns {number}
+ */
+export function tree_grown_side_area(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null): number;
+/**
+ * @typedef {Object} TreeRenderCost
+ * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side
+ * @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
+     */
+    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":"AAKA;;;;;;;;;GASG;AACH,yDAJW,MAAM,UAAU,MAAM,CAAC,CAAC,WACxB,MAAM,GACJ,MAAM,CA8ClB;AAiBD;;;;;;;;GAQG;AACH,+CALW,OAAO,6BAA6B,EAAE,YAAY,UAClD,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,GAElE,MAAM,CAYlB;AAaD;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,cAAc,CAgC1B;AA/FD;;;;;;;;;;;;GAYG;AACH,uCAFU;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAC,CAE4C;;;;;eAoCpH,MAAM;;;;eACN,MAAM,EAAE;;;;sBACR,MAAM,EAAE;;;;YACR,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;mBACR,MAAM;;;;qBACN,MAAM"}