@woosh/meep-engine 3.55.0 → 3.57.0

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

@@ -0,0 +1,66 @@
+/**
+ * @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: import("../skeleton/TreeSkeleton.js").TreeSkeleton, attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet, config: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, cutout: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout | null, albedo: import("../../../engine/graphics/texture/sampler/Sampler2D.js").Sampler2D): FoliageLeafArea;
+export type FoliageLeafArea = {
+    /**
+     * one-sided leaf area of every card, m^2
+     */
+    total: number;
+    /**
+     * one-sided leaf area of each attachment, m^2
+     */
+    by_card: Float64Array;
+    /**
+     * one-sided leaf area of the cards each `config.branches` generator's branches
+     * carry, m^2
+     */
+    by_generator: Float64Array;
+    /**
+     * 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
+     */
+    crown_projected_area: number;
+    /**
+     * `total / crown_projected_area`, the tree's own leaf area index
+     */
+    crown_leaf_area_index: number;
+};
+//# sourceMappingURL=foliage_measure_leaf_area.d.ts.map

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":"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"}

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

@@ -0,0 +1,192 @@
+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 { 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);
+
+/**
+ * @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, ALL_CARDS, 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 ? asset.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/animation/build_tree_wind_rig.d.ts

@@ -4,8 +4,9 @@
  *
  * Joint `0` (`SceneNode` index `1`, at the trunk base `(0, 0, 0)`) remains anchored at its bind
  * pose so the base of the trunk never pivots off the ground, while upper trunk and branch joints
- * carry physically derived Euler-Bernoulli cantilever compliance, natural frequency, damping ratio,
- * branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
+ * carry Euler-Bernoulli cantilever compliance and natural frequency (`skin_info.joint_compliance`, from the drag
+ * each joint carries and the bending stiffness of its span, and `joint_natural_frequency`, its branch's first mode),
+ * plus damping ratio, branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
  * dispatches `shader_foliage_wind_apply` to sample Meep's 3D fluid simulation wind field
  * (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack` wakes/vortices)
  * at each bone's world position and step a 2nd-order damped oscillator directly into `pose_accumulator`.

package/src/generation/foliage/animation/build_tree_wind_rig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build_tree_wind_rig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/build_tree_wind_rig.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,6GAAsG,gBACtG,cAAc,MAAO,GACnB,cAAc,GAAC,IAAI,CAuF/B;+BAvG8B,6BAA6B;+BAD7B,6DAA6D"}
+{"version":3,"file":"build_tree_wind_rig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/build_tree_wind_rig.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,6GAAsG,gBACtG,cAAc,MAAO,GACnB,cAAc,GAAC,IAAI,CAmE/B;+BArF8B,6BAA6B;+BAD7B,6DAA6D"}

package/src/generation/foliage/animation/build_tree_wind_rig.js

@@ -3,6 +3,7 @@ import { clamp } from "../../../core/math/clamp.js";
 import { FoliageWindJoint } from "../../../shade/renderer/animation/foliage/FoliageWindJoint.js";
 import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
 import { TreeWindConfig } from "../config/TreeWindConfig.js";
+import { tree_wind_bend_limit } from "./tree_wind_bend_limit.js";
 
 /**
  * Constructs a GPU fluid-driven `FoliageWindRig` (`name = "foliage_wind"`) for the structural
@@ -10,8 +11,9 @@ import { TreeWindConfig } from "../config/TreeWindConfig.js";
  *
  * Joint `0` (`SceneNode` index `1`, at the trunk base `(0, 0, 0)`) remains anchored at its bind
  * pose so the base of the trunk never pivots off the ground, while upper trunk and branch joints
- * carry physically derived Euler-Bernoulli cantilever compliance, natural frequency, damping ratio,
- * branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
+ * carry Euler-Bernoulli cantilever compliance and natural frequency (`skin_info.joint_compliance`, from the drag
+ * each joint carries and the bending stiffness of its span, and `joint_natural_frequency`, its branch's first mode),
+ * plus damping ratio, branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
  * dispatches `shader_foliage_wind_apply` to sample Meep's 3D fluid simulation wind field
  * (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack` wakes/vortices)
  * at each bone's world position and step a 2nd-order damped oscillator directly into `pose_accumulator`.
@@ -22,7 +24,8 @@ import { TreeWindConfig } from "../config/TreeWindConfig.js";
  */
 export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig()) {
     const cfg = wind_config && wind_config.isTreeWindConfig ? wind_config : TreeWindConfig.from(wind_config);
-    if (!cfg.enabled || !skin_info || skin_info.joint_count <= 0) {
+    // Joint 0 is the anchored trunk base: with no other joint there is nothing to drive
+    if (!cfg.enabled || !skin_info || skin_info.joint_count <= 1) {
         return null;
     }
 
@@ -30,15 +33,9 @@ export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig(
     rig.name = "foliage_wind";
     rig.root = 0; // SceneNode 0 is the tree root in SceneBundle
 
-    const r0 = (skin_info.joint_radii && skin_info.joint_radii.length > 0)
-        ? Math.max(0.02, skin_info.joint_radii[0])
-        : 0.25;
-
-    const start_joint = skin_info.joint_count === 1 ? 0 : 1;
-
     // Count how many driven joints share the same structural level along each joint's ancestor chain
-    // so serial chains of joints on the same trunk/bough divide the total branch deflection cleanly.
-    const same_level_chain_count = new Uint8Array(skin_info.joint_count);
+    // so serial chains of joints on the same trunk/bough divide the total bend saturation cleanly.
+    const same_level_chain_count = new Uint16Array(skin_info.joint_count);
     for (let j = 0; j < skin_info.joint_count; j++) {
         const lvl = skin_info.joint_levels[j];
         let count = 0;
@@ -52,13 +49,9 @@ export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig(
         same_level_chain_count[j] = Math.max(1, count);
     }
 
-    for (let j = start_joint; j < skin_info.joint_count; j++) {
+    for (let j = 1; j < skin_info.joint_count; j++) {
         const level = skin_info.joint_levels[j];
-        const t_norm = j === 0 ? 0.5 : skin_info.joint_t_norms[j];
         const phase = skin_info.joint_phases[j] * PI2;
-        const r_j = (skin_info.joint_radii && j < skin_info.joint_radii.length)
-            ? Math.max(0.005, skin_info.joint_radii[j])
-            : r0 * Math.pow(0.5, level);
 
         let tx = skin_info.joint_tangents[j * 3];
         let ty = skin_info.joint_tangents[j * 3 + 1];
@@ -75,21 +68,10 @@ export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig(
         }
 
         const chain_div = Math.max(1, same_level_chain_count[j]);
-        const base_comp = level === 0
-            ? cfg.trunk_compliance * 0.18
-            : cfg.branch_compliance * 0.24 * (1.0 + 0.35 * (level - 1));
-        const radius_factor = level === 0
-            ? clamp(Math.pow(r0 / Math.max(r_j, 0.25 * r0), 0.35), 0.6, 1.6)
-            : clamp(Math.pow(r0 / Math.max(r_j, 0.08 * r0), 0.45), 0.8, 3.2);
-        const compliance = (base_comp * radius_factor * clamp(0.35 + 0.65 * t_norm, 0.3, 1.15)) / chain_div;
-
-        const natural_frequency = cfg.natural_frequency * (1.0 + 0.65 * level + 0.35 * t_norm);
+        const compliance = skin_info.joint_compliance[j];
+        const natural_frequency = skin_info.joint_natural_frequency[j];
         const damping_ratio = clamp(cfg.damping_ratio * (1.0 + 0.12 * level), 0.05, 1.5);
-        const max_angle = clamp(
-            (cfg.max_bend_angle * (level === 0 ? 0.18 : (0.42 + 0.18 * Math.min(level, 2)))) / chain_div,
-            0.02,
-            0.85
-        );
+        const max_angle = clamp(tree_wind_bend_limit(cfg.max_bend_angle, level) / chain_div, 0.02, 0.85);
         const turbulence = clamp(cfg.turbulence * (level === 0 ? 0.35 : (0.65 + 0.35 * Math.min(level, 2))), 0.0, 1.0);
 
         rig.joints.push(FoliageWindJoint.from({

package/src/generation/foliage/animation/tree_wind_bend_limit.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bend (radians) that the wind joints on one branch can show between them: `chunk_foliage_wind_step` soft-saturates
+ * each joint's deflection `theta` to `theta * m / (m + theta)`, and `build_tree_wind_rig` gives every joint of a
+ * serial chain of `n` joints `m = limit / n`, so a branch bent by `theta` in total shows `theta * limit / (limit + theta)`
+ * however many joints share it equally.
+ *
+ * @param {number} max_bend_angle `TreeWindConfig.max_bend_angle`
+ * @param {number} level branching level of the branch, 0 for the trunk
+ * @returns {number}
+ */
+export function tree_wind_bend_limit(max_bend_angle: number, level: number): number;
+//# sourceMappingURL=tree_wind_bend_limit.d.ts.map

package/src/generation/foliage/animation/tree_wind_bend_limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_wind_bend_limit.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/tree_wind_bend_limit.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qDAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB"}

package/src/generation/foliage/animation/tree_wind_bend_limit.js

@@ -0,0 +1,13 @@
+/**
+ * Bend (radians) that the wind joints on one branch can show between them: `chunk_foliage_wind_step` soft-saturates
+ * each joint's deflection `theta` to `theta * m / (m + theta)`, and `build_tree_wind_rig` gives every joint of a
+ * serial chain of `n` joints `m = limit / n`, so a branch bent by `theta` in total shows `theta * limit / (limit + theta)`
+ * however many joints share it equally.
+ *
+ * @param {number} max_bend_angle `TreeWindConfig.max_bend_angle`
+ * @param {number} level branching level of the branch, 0 for the trunk
+ * @returns {number}
+ */
+export function tree_wind_bend_limit(max_bend_angle, level) {
+    return max_bend_angle * (level === 0 ? 0.18 : (0.42 + 0.18 * Math.min(level, 2)));
+}

package/src/generation/foliage/asset/TreeAsset.d.ts

@@ -42,6 +42,11 @@ export class TreeAsset {
      * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
      */
     foliage_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Shape of the synthesized foliage atlas (hull per tile, leaf coverage), or `null` with a caller's own foliage material.
+     * @type {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null}
+     */
+    foliage_cutout: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout | null;
     /**
      * Progressive LOD asset chain (`lods[0]` = highest detail).
      * @type {import("./TreeLODAsset.js").TreeLODAsset[]}

package/src/generation/foliage/asset/TreeAsset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TreeAsset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeAsset.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,OAAO,gCAAgC,EAAE,iBAAiB,CAEtD;IAEd;;;OAGG;IACH,UAFU,OAAO,6BAA6B,EAAE,YAAY,CAE5C;IAEhB;;;OAGG;IACH,aAFU,OAAO,wCAAwC,EAAE,oBAAoB,CAE5D;IAEnB;;;OAGG;IACH,WAFU,6GAAsG,CAE/F;IAEjB;;;OAGG;IACH,UAFU,OAAO,6DAA6D,EAAE,cAAc,GAAC,IAAI,CAEnF;IAEhB;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;OAGG;IACH,kBAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE3E;IAExB;;;OAGG;IACH,MAFU,OAAO,mBAAmB,EAAE,YAAY,EAAE,CAE1C;IAEV;;;OAGG;IACH,qFAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,2GAEC;IAED;;;OAGG;IACH,8GAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,0EAEC;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B"}
+{"version":3,"file":"TreeAsset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeAsset.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,OAAO,gCAAgC,EAAE,iBAAiB,CAEtD;IAEd;;;OAGG;IACH,UAFU,OAAO,6BAA6B,EAAE,YAAY,CAE5C;IAEhB;;;OAGG;IACH,aAFU,OAAO,wCAAwC,EAAE,oBAAoB,CAE5D;IAEnB;;;OAGG;IACH,WAFU,6GAAsG,CAE/F;IAEjB;;;OAGG;IACH,UAFU,OAAO,6DAA6D,EAAE,cAAc,GAAC,IAAI,CAEnF;IAEhB;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;OAGG;IACH,kBAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE3E;IAExB;;;OAGG;IACH,gBAFU,OAAO,mCAAmC,EAAE,kBAAkB,GAAC,IAAI,CAEvD;IAEtB;;;OAGG;IACH,MAFU,OAAO,mBAAmB,EAAE,YAAY,EAAE,CAE1C;IAEV;;;OAGG;IACH,qFAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,2GAEC;IAED;;;OAGG;IACH,8GAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,0EAEC;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B"}

package/src/generation/foliage/asset/TreeAsset.js

@@ -49,6 +49,12 @@ export class TreeAsset {
      */
     foliage_material = null;
 
+    /**
+     * Shape of the synthesized foliage atlas (hull per tile, leaf coverage), or `null` with a caller's own foliage material.
+     * @type {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null}
+     */
+    foliage_cutout = null;
+
     /**
      * Progressive LOD asset chain (`lods[0]` = highest detail).
      * @type {import("./TreeLODAsset.js").TreeLODAsset[]}

package/src/generation/foliage/asset/generate_tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/generate_tree.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH,wCAHW,MAAM,GAAC,OAAO,gCAAgC,EAAE,iBAAiB,MAAO,GACtE,SAAS,CAqErB;0BAlFyB,gBAAgB"}
+{"version":3,"file":"generate_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/generate_tree.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;GAWG;AACH,wCAHW,MAAM,GAAC,OAAO,gCAAgC,EAAE,iBAAiB,MAAO,GACtE,SAAS,CAqFrB;0BAlGyB,gBAAgB"}

package/src/generation/foliage/asset/generate_tree.js

@@ -1,5 +1,6 @@
 import { build_tree_wind_rig } from "../animation/build_tree_wind_rig.js";
 import { TreePreset } from "../config/TreePreset.js";
+import { FoliageAtlasCutout } from "../material/FoliageAtlasCutout.js";
 import { make_bark_material } from "../material/make_bark_material.js";
 import { make_foliage_material } from "../material/make_foliage_material.js";
 import { foliage_collect_attachments } from "../mesh/foliage_collect_attachments.js";
@@ -47,17 +48,32 @@ export function generate_tree(options = {}) {
     }
 
     const skeleton = tree_skeleton_grow(config);
-    const skin_info = tree_skeleton_assign_skin_joints(skeleton, config.wind.max_joints);
+    const skin_info = tree_skeleton_assign_skin_joints(skeleton, config);
     const wind_rig = config.wind.enabled ? build_tree_wind_rig(skin_info, config.wind) : null;
-    const attachments = foliage_collect_attachments(skeleton, config);
 
     const bark_material = custom_bark_material !== null
         ? custom_bark_material
         : make_bark_material(config.bark_material, config.seed);
 
-    const foliage_material = custom_foliage_material !== null
-        ? custom_foliage_material
-        : (config.foliage.enabled ? make_foliage_material(config.foliage_material, config.seed) : null);
+    // The atlas's shape sets how many cards a shoot carries and, for hull cards, their outline. A caller's own
+    // material has no fitted outline, so its cards cover whole tiles, at the density our atlas would need.
+    let foliage_material = null;
+    let foliage_cutout = null;
+    if (custom_foliage_material !== null) {
+        foliage_material = custom_foliage_material;
+    } else if (config.foliage_rules.length > 0) {
+        foliage_cutout = new FoliageAtlasCutout();
+        foliage_material = make_foliage_material(config, foliage_cutout);
+    }
+    const attachments = foliage_collect_attachments(skeleton, config, foliage_cutout ?? undefined);
+    if (foliage_cutout !== null) {
+        // Card tints can brighten as well as darken; the unorm8 vertex colours carry tint / tint_scale and our
+        // material multiplies tint_scale back in
+        foliage_material.diffuse_color.setRGB(attachments.tint_scale, attachments.tint_scale, attachments.tint_scale);
+    } else {
+        // a caller's own material knows nothing of the scale: tints stay clamped to 1, darkening only
+        attachments.tint_scale = 1.0;
+    }
 
     const asset = new TreeAsset();
     asset.config = config;
@@ -67,6 +83,7 @@ export function generate_tree(options = {}) {
     asset.wind_rig = wind_rig;
     asset.bark_material = bark_material;
     asset.foliage_material = foliage_material;
+    asset.foliage_cutout = foliage_cutout;
 
     for (let i = 0; i < config.lods.length; i++) {
         const lod_cfg = config.lods[i];
@@ -75,7 +92,7 @@ export function generate_tree(options = {}) {
         lod_asset.name = config.name || "tree";
         lod_asset.configure_lazy_geometries(
             () => tree_mesh_build_bark(skeleton, config, lod_cfg),
-            () => tree_mesh_build_foliage(skeleton, attachments, config, lod_cfg)
+            () => tree_mesh_build_foliage(skeleton, attachments, config, lod_cfg, foliage_cutout)
         );
         lod_asset.bark_material = bark_material;
         lod_asset.foliage_material = foliage_material;