@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/mesh/foliage_collect_attachments.js

@@ -0,0 +1,569 @@
+import { GOLDEN_RATIO } from "../../../core/math/GOLDEN_RATIO.js";
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { t64_look_rotation } from "../../../engine/ecs/transform/t64_look_rotation.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+import { CrownEnvelopeType } from "../config/CrownEnvelopeType.js";
+import { PhyllotaxisMode } from "../config/PhyllotaxisMode.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { spine_frame_double_reflection } from "../skeleton/spine_frame_double_reflection.js";
+import { tree_mesh_compute_branch_rings } from "./tree_mesh_build_bark.js";
+
+const GOLDEN_CONJUGATE = 1.0 / GOLDEN_RATIO; // ~0.6180339887498949
+const GOLDEN_ANGLE = PI2 / (GOLDEN_RATIO * GOLDEN_RATIO);
+
+const SCRATCH_POS = new Float32Array(3);
+const SCRATCH_TAN = new Float32Array(3);
+const SCRATCH_P0 = new Float32Array(3);
+const SCRATCH_T0 = new Float32Array(3);
+const SCRATCH_R0 = new Float32Array(3);
+const SCRATCH_RMF = new Float64Array(6);
+
+/**
+ * Flat typed-array structure holding all phyllotactic foliage attachment points and oriented card frames.
+ *
+ * @typedef {Object} FoliageAttachmentSet
+ * @property {number} count number of foliage attachments
+ * @property {Float32Array} positions `count * 3` attachment world/local positions
+ * @property {Float32Array} forward `count * 3` unit card length axis F
+ * @property {Float32Array} up `count * 3` unit card outward normal U
+ * @property {Float32Array} right `count * 3` unit card width axis W = F x U (so W x F = +U)
+ * @property {Float32Array} scales `count` per-card size multiplier
+ * @property {Float32Array} ranks `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+ * @property {Float32Array} phases `count` per-card wind phase in [0, 1)
+ * @property {Float32Array} branch_sway `count` parent branch sway weight in [0, 1]
+ * @property {Float32Array} color_jitter `count` per-card luminance/tint jitter in [-1, 1]
+ * @property {Float32Array} maturities `count` per-card ontogenetic leaf maturity in [0, 1] (0 = juvenile tip, 1 = mature base)
+ * @property {Float32Array} sun_exposure `count` per-card canopy solar irradiance exposure in [0, 1]
+ * @property {Uint8Array} variant_indices `count` assigned foliage atlas variant index in `[0, variant_count - 1]`
+ * @property {Uint16Array} joints `count * 2` `[j_primary, j_parent]`
+ * @property {Float32Array} weights `count * 2` `[w_primary, w_parent]`
+ */
+
+/**
+ * Generates phyllotactic foliage card attachment transforms along all eligible branches of a `TreeSkeleton`.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {TreeSpeciesConfig} [config]
+ * @returns {FoliageAttachmentSet}
+ */
+export function foliage_collect_attachments(skeleton, config = new TreeSpeciesConfig()) {
+	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+	const fol = species.foliage;
+	if (!fol.enabled || skeleton.branch_count === 0) {
+		return {
+			count: 0,
+			transforms: [],
+			positions: new Float32Array(0),
+			forward: new Float32Array(0),
+			up: new Float32Array(0),
+			right: new Float32Array(0),
+			scales: new Float32Array(0),
+			ranks: new Float32Array(0),
+			phases: new Float32Array(0),
+			branch_sway: new Float32Array(0),
+			color_jitter: new Float32Array(0),
+			maturities: new Float32Array(0),
+			sun_exposure: new Float32Array(0),
+			variant_indices: new Uint8Array(0),
+			joints: new Uint16Array(0),
+			weights: new Float32Array(0),
+			joints4: new Uint16Array(0),
+			weights4: new Float32Array(0),
+			attr_ranks: Attribute.from(new Float32Array(0), 1, "foliage_ranks"),
+			attr_phases: Attribute.from(new Float32Array(0), 1, "foliage_phases"),
+			attr_branch_sway: Attribute.from(new Float32Array(0), 1, "foliage_branch_sway"),
+			attr_color_jitter: Attribute.from(new Float32Array(0), 1, "foliage_color_jitter"),
+			attr_maturities: Attribute.from(new Float32Array(0), 1, "foliage_maturities"),
+			attr_variant_indices: Attribute.from(new Uint8Array(0), 1, "foliage_variant_indices"),
+			attr_joints: Attribute.from(new Uint16Array(0), 2, "foliage_joints"),
+			attr_weights: Attribute.from(new Float32Array(0), 2, "foliage_weights")
+		};
+	}
+
+	const rng = seededRandom((species.seed ^ 0x5A3C9E17) | 0);
+	const max_existing_level = Math.max(0, species.levels.length - 1);
+	const min_level = Math.min(fol.attach_min_level, max_existing_level);
+	const branch_rings = tree_mesh_compute_branch_rings(skeleton, species, species.lods?.[0]);
+	const variant_count = clamp((species.foliage_material?.variant_count ?? 4) | 0, 1, 16);
+
+	const crown = species.crown;
+	const is_conical_crown = crown.envelope_type === CrownEnvelopeType.Conical;
+	const cx = skeleton.crown_center[0];
+	const cy = skeleton.crown_center[1];
+	const cz = skeleton.crown_center[2];
+	const rx_crown = Math.max(0.5, skeleton.crown_radii[0]);
+	const ry = Math.max(0.5, skeleton.crown_radii[1]);
+	const rz_crown = Math.max(0.5, skeleton.crown_radii[2]);
+	const ref_card_len = Math.max(0.25, fol.card_length);
+
+	// First collect eligible branch edge chains via `skeleton.graph`
+	const eligible_branches = [];
+	for (let b = 0; b < skeleton.branch_count; b++) {
+		const level = skeleton.branch_level[b];
+		if (level < min_level) continue;
+
+		const nodes = [];
+		const edges = [];
+		skeleton.collect_branch_chain(b, nodes, edges);
+		if (edges.length === 0) continue;
+
+		const t_norms = new Array(nodes.length);
+		for (let i = 0; i < nodes.length; i++) {
+			t_norms[i] = skeleton.node_t_norm(nodes[i]);
+		}
+
+		eligible_branches.push({ branch_id: b, level, nodes, edges, t_norms });
+	}
+
+	const lateral_count = Math.max(0, fol.cards_per_branch | 0);
+	const rosette_count = Math.max(0, fol.terminal_rosette_count | 0);
+	const per_branch = lateral_count + rosette_count;
+	const total_count = eligible_branches.length * per_branch;
+
+	/** @type {Transform64[]} */
+	const transforms = new Array(total_count);
+	const positions = new Float32Array(total_count * 3);
+	const forward = new Float32Array(total_count * 3);
+	const up = new Float32Array(total_count * 3);
+	const right = new Float32Array(total_count * 3);
+	const scales = new Float32Array(total_count);
+	const ranks = new Float32Array(total_count);
+	const phases = new Float32Array(total_count);
+	const branch_sway = new Float32Array(total_count);
+	const color_jitter = new Float32Array(total_count);
+	const maturities = new Float32Array(total_count);
+	const sun_exposure = new Float32Array(total_count);
+	const variant_indices = new Uint8Array(total_count);
+	const joints = new Uint16Array(total_count * 2);
+	const weights = new Float32Array(total_count * 2);
+	const joints4 = new Uint16Array(total_count * 4);
+	const weights4 = new Float32Array(total_count * 4);
+
+	let cursor = 0;
+	const bare = clamp(fol.bare_ratio, 0.0, 0.92);
+
+	for (let eb = 0; eb < eligible_branches.length; eb++) {
+		const item = eligible_branches[eb];
+		const level = item.level;
+		const nodes = item.nodes;
+		const edges = item.edges;
+		const t_norms = item.t_norms;
+		const b_rings = branch_rings.get(item.branch_id);
+		const b_len = Math.max(0.12, skeleton.branch_length[item.branch_id]);
+		const shoot_scale = clamp(b_len / (ref_card_len * 0.95), 0.22, 1.0);
+		const t_min = Math.max(bare, t_norms[0]);
+		const t_max = t_norms[t_norms.length - 1];
+		const base_phi = rng() * PI2;
+		const b_phase = skeleton.branch_phase_hash[item.branch_id];
+
+		for (let k = 0; k < per_branch; k++) {
+			const is_rosette = k >= lateral_count;
+			let t_attach = 1.0;
+
+			if (!is_rosette && lateral_count > 0) {
+				let u_k = (k + 0.5) / lateral_count;
+				if (fol.phyllotaxis_mode === PhyllotaxisMode.Opposite
+					|| fol.phyllotaxis_mode === PhyllotaxisMode.OppositeDecussate) {
+					const pair_idx = k >> 1;
+					const pair_total = Math.max(1, Math.ceil(lateral_count / 2));
+					u_k = (pair_idx + 0.5) / pair_total;
+				} else if (fol.phyllotaxis_mode === PhyllotaxisMode.Whorled) {
+					const w_size = Math.max(1, fol.whorl_count | 0);
+					const w_idx = Math.floor(k / w_size);
+					const w_total = Math.max(1, Math.ceil(lateral_count / w_size));
+					u_k = (w_idx + 0.5) / w_total;
+				}
+				t_attach = clamp(lerp(t_min, t_max * 0.92, u_k), t_min, t_max * 0.95);
+			} else {
+				const ros_idx = k - lateral_count;
+				const u_ros = (ros_idx + 0.5) / Math.max(1, rosette_count);
+				t_attach = clamp(lerp(Math.max(t_min, t_max * 0.88), t_max * 0.96, u_ros), t_min, t_max * 0.96);
+			}
+
+			// Locate segment containing t_attach
+			let seg_idx = edges.length - 1;
+			for (let s = 0; s < edges.length; s++) {
+				if (t_attach >= t_norms[s] && t_attach <= t_norms[s + 1]) {
+					seg_idx = s;
+					break;
+				}
+			}
+
+			const edge_id = edges[seg_idx];
+			const v0 = nodes[seg_idx];
+			const v1 = nodes[seg_idx + 1];
+			const t0 = t_norms[seg_idx];
+			const t1 = t_norms[seg_idx + 1];
+			const local_u = clamp((t_attach - t0) / Math.max(1e-5, t1 - t0), 0.05, 0.95);
+
+			skeleton.evaluate_segment_position(SCRATCH_POS, 0, edge_id, local_u);
+			skeleton.evaluate_segment_tangent(SCRATCH_TAN, 0, edge_id, local_u);
+			skeleton.node_read_position(SCRATCH_P0, 0, v0);
+			skeleton.node_read_tangent(SCRATCH_T0, 0, v0);
+			skeleton.node_read_frame_r(SCRATCH_R0, 0, v0);
+
+			spine_frame_double_reflection(
+				SCRATCH_RMF, 0,
+				SCRATCH_P0[0], SCRATCH_P0[1], SCRATCH_P0[2],
+				SCRATCH_T0[0], SCRATCH_T0[1], SCRATCH_T0[2],
+				SCRATCH_R0[0], SCRATCH_R0[1], SCRATCH_R0[2],
+				SCRATCH_POS[0], SCRATCH_POS[1], SCRATCH_POS[2],
+				SCRATCH_TAN[0], SCRATCH_TAN[1], SCRATCH_TAN[2]
+			);
+			const rx = SCRATCH_RMF[0], ry_f = SCRATCH_RMF[1], rz = SCRATCH_RMF[2];
+			const sx = SCRATCH_RMF[3], sy_f = SCRATCH_RMF[4], sz = SCRATCH_RMF[5];
+
+			// Phyllotactic angle phi
+			let phi = base_phi;
+			if (is_rosette) {
+				const r_idx = k - lateral_count;
+				phi += (r_idx * PI2) / Math.max(1, rosette_count);
+			} else {
+				switch (fol.phyllotaxis_mode) {
+					case PhyllotaxisMode.AlternateDistichous:
+						phi += k * Math.PI;
+						break;
+					case PhyllotaxisMode.Tristichous:
+						phi += k * (PI2 / 3.0);
+						break;
+					case PhyllotaxisMode.Opposite:
+						phi += (k & 1) * Math.PI;
+						break;
+					case PhyllotaxisMode.OppositeDecussate:
+						phi += (k & 1) * Math.PI + (k >> 1) * (Math.PI * 0.5);
+						break;
+					case PhyllotaxisMode.Whorled: {
+						const w_size = Math.max(1, fol.whorl_count | 0);
+						const w_idx = Math.floor(k / w_size);
+						const sub_idx = k % w_size;
+						phi += (sub_idx * PI2) / w_size + (w_idx * Math.PI) / w_size;
+						break;
+					}
+					case PhyllotaxisMode.SpiralGolden:
+					default:
+						phi += k * GOLDEN_ANGLE;
+						break;
+				}
+			}
+			phi += (rng() * 2.0 - 1.0) * fol.angular_jitter;
+
+			const cos_p = Math.cos(phi);
+			const sin_p = Math.sin(phi);
+			const drx = cos_p * rx + sin_p * sx;
+			const dry = cos_p * ry_f + sin_p * sy_f;
+			const drz = cos_p * rz + sin_p * sz;
+
+			// Anchor card stem origin on the actual meshed bark frustum chord [ra, rb]
+			// and interpolate the carrier frustum's exact 4-slot skinning weights
+			let px = SCRATCH_POS[0];
+			let py = SCRATCH_POS[1];
+			let pz = SCRATCH_POS[2];
+			let seg_tx = SCRATCH_TAN[0];
+			let seg_ty = SCRATCH_TAN[1];
+			let seg_tz = SCRATCH_TAN[2];
+
+			const c4 = cursor * 4;
+			const c2 = cursor * 2;
+
+			if (b_rings && b_rings.length >= 2) {
+				const ring_idx = Math.min(seg_idx, b_rings.length - 2);
+				const ra = b_rings[ring_idx];
+				const rb = b_rings[ring_idx + 1];
+				const xi = clamp((t_attach - ra.t_norm) / Math.max(1e-5, rb.t_norm - ra.t_norm), 0.05, 0.95);
+
+				px = lerp(ra.cx, rb.cx, xi);
+				py = lerp(ra.cy, rb.cy, xi);
+				pz = lerp(ra.cz, rb.cz, xi);
+
+				const dx_seg = rb.cx - ra.cx;
+				const dy_seg = rb.cy - ra.cy;
+				const dz_seg = rb.cz - ra.cz;
+				const seg_len = Math.hypot(dx_seg, dy_seg, dz_seg);
+				if (seg_len > 1e-6) {
+					seg_tx = dx_seg / seg_len;
+					seg_ty = dy_seg / seg_len;
+					seg_tz = dz_seg / seg_len;
+				}
+
+				// Merge 4-slot skinning weights from ra (weight 1 - xi) and rb (weight xi)
+				const merged_j = [-1, -1, -1, -1, -1, -1, -1, -1];
+				const merged_w = [0, 0, 0, 0, 0, 0, 0, 0];
+				let m_count = 0;
+
+				const accumulate_joint = (j_id, w_val) => {
+					if (w_val <= 1e-7) return;
+					for (let m = 0; m < m_count; m++) {
+						if (merged_j[m] === j_id) {
+							merged_w[m] += w_val;
+							return;
+						}
+					}
+					merged_j[m_count] = j_id;
+					merged_w[m_count] = w_val;
+					m_count++;
+				};
+
+				const w_a = 1.0 - xi;
+				const w_b = xi;
+				accumulate_joint(ra.j0, ra.w0 * w_a);
+				accumulate_joint(ra.j1, ra.w1 * w_a);
+				accumulate_joint(ra.j2, ra.w2 * w_a);
+				accumulate_joint(ra.j3, ra.w3 * w_a);
+				accumulate_joint(rb.j0, rb.w0 * w_b);
+				accumulate_joint(rb.j1, rb.w1 * w_b);
+				accumulate_joint(rb.j2, rb.w2 * w_b);
+				accumulate_joint(rb.j3, rb.w3 * w_b);
+
+				// Sort descending by weight and normalize top 4
+				for (let a = 0; a < m_count - 1; a++) {
+					for (let b_sort = a + 1; b_sort < m_count; b_sort++) {
+						if (merged_w[b_sort] > merged_w[a]) {
+							const tw = merged_w[a];
+							merged_w[a] = merged_w[b_sort];
+							merged_w[b_sort] = tw;
+							const tj = merged_j[a];
+							merged_j[a] = merged_j[b_sort];
+							merged_j[b_sort] = tj;
+						}
+					}
+				}
+
+				const top_k = Math.min(4, m_count);
+				let w4_sum = 0.0;
+				for (let s = 0; s < top_k; s++) w4_sum += merged_w[s];
+				const inv_w4 = w4_sum > 1e-7 ? 1.0 / w4_sum : 1.0;
+
+				for (let s = 0; s < 4; s++) {
+					if (s < top_k) {
+						joints4[c4 + s] = merged_j[s];
+						weights4[c4 + s] = merged_w[s] * inv_w4;
+					} else {
+						joints4[c4 + s] = 0;
+						weights4[c4 + s] = 0.0;
+					}
+				}
+
+				// Populate 2-slot legacy joints/weights normalized to sum to 1.0
+				const j_prim = top_k > 0 ? merged_j[0] : 0;
+				const j_par = top_k > 1 ? merged_j[1] : j_prim;
+				const w0_raw = top_k > 0 ? merged_w[0] : 1.0;
+				const w1_raw = top_k > 1 ? merged_w[1] : 0.0;
+				const w2_sum = w0_raw + w1_raw;
+				joints[c2] = j_prim;
+				joints[c2 + 1] = j_par;
+				weights[c2] = w2_sum > 1e-7 ? w0_raw / w2_sum : 1.0;
+				weights[c2 + 1] = w2_sum > 1e-7 ? w1_raw / w2_sum : 0.0;
+			} else {
+				const j_prim = skeleton.node_read_joint(v1, 0);
+				const j_par = skeleton.node_read_joint(v1, 1);
+				const w_prim = j_prim === j_par ? 1.0 : clamp(0.35 + 0.65 * t_attach, 0.0, 1.0);
+				joints[c2] = j_prim;
+				joints[c2 + 1] = j_par;
+				weights[c2] = w_prim;
+				weights[c2 + 1] = 1.0 - w_prim;
+				joints4[c4] = j_prim;
+				joints4[c4 + 1] = j_par;
+				weights4[c4] = w_prim;
+				weights4[c4 + 1] = 1.0 - w_prim;
+			}
+
+			// Outward canopy normal n_canopy from crown center
+			let ncx = px - cx;
+			let ncy = (py - cy) + 0.35 * ry;
+			let ncz = pz - cz;
+			const nc_len = Math.sqrt(ncx * ncx + ncy * ncy + ncz * ncz);
+			if (nc_len > 1e-6) {
+				ncx /= nc_len;
+				ncy /= nc_len;
+				ncz /= nc_len;
+			} else {
+				ncx = 0.0;
+				ncy = 1.0;
+				ncz = 0.0;
+			}
+
+			const h_norm_card = clamp((py - crown.base_height) / Math.max(0.1, crown.height), 0.0, 1.0);
+			const w_apex_spire = is_conical_crown && h_norm_card > 0.72
+				? Math.pow(clamp((h_norm_card - 0.72) / 0.25, 0.0, 1.0), 1.35)
+				: 0.0;
+
+			// Initial card forward axis F along insertion angle from branch frustum tangent toward D_rad
+			const base_ins = is_rosette ? fol.insertion_angle * 0.55 : fol.insertion_angle;
+			const ins_angle = base_ins * (1.0 - 0.65 * w_apex_spire);
+			const cos_a = Math.cos(ins_angle);
+			const sin_a = Math.sin(ins_angle);
+			let fx = cos_a * seg_tx + sin_a * drx;
+			let fy = cos_a * seg_ty + sin_a * dry;
+			let fz = cos_a * seg_tz + sin_a * drz;
+
+			// Blend phototropism (outward/sky), gravitropism (downward droop along -Y), and orthotropic apical candle spire
+			const grav_atten = 1.0 - 0.90 * w_apex_spire;
+			const out_atten = 1.0 - 0.75 * w_apex_spire;
+			fx += fol.phototropism * 0.45 * out_atten * ncx + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35 * out_atten;
+			fy += fol.phototropism * 0.25 * Math.max(0.0, ncy) - fol.gravitropism * 0.85 * grav_atten;
+			fz += fol.phototropism * 0.45 * out_atten * ncz + (rng() * 2.0 - 1.0) * fol.angular_jitter * 0.35 * out_atten;
+
+			if (w_apex_spire > 1e-4) {
+				const w_spire = clamp(w_apex_spire * (is_rosette ? 0.92 : 0.78), 0.0, 0.94);
+				fx = lerp(fx, -0.15 * ncx, w_spire);
+				fy = lerp(fy, 1.0, w_spire);
+				fz = lerp(fz, -0.15 * ncz, w_spire);
+			}
+
+			const f_len = Math.sqrt(fx * fx + fy * fy + fz * fz);
+			if (f_len > 1e-8) {
+				fx /= f_len;
+				fy /= f_len;
+				fz /= f_len;
+			} else {
+				fx = drx;
+				fy = dry;
+				fz = drz;
+			}
+
+			// Desired card upward normal U: blend of world +Y and outward canopy normal n_canopy
+			let ux = ncx * 0.45;
+			let uy = 0.65 + ncy * 0.35;
+			let uz = ncz * 0.45;
+			// Gram-Schmidt orthogonalize U against F
+			const dot_uf = ux * fx + uy * fy + uz * fz;
+			ux -= dot_uf * fx;
+			uy -= dot_uf * fy;
+			uz -= dot_uf * fz;
+			const u_len = Math.sqrt(ux * ux + uy * uy + uz * uz);
+			if (u_len > 1e-6) {
+				ux /= u_len;
+				uy /= u_len;
+				uz /= u_len;
+			} else {
+				// Fallback perpendicular to F
+				if (Math.abs(fy) < 0.9) {
+					ux = -fz;
+					uy = 0.0;
+					uz = fx;
+				} else {
+					ux = 1.0;
+					uy = 0.0;
+					uz = 0.0;
+				}
+				const d2 = ux * fx + uy * fy + uz * fz;
+				ux -= d2 * fx;
+				uy -= d2 * fy;
+				uz -= d2 * fz;
+				const l2 = Math.sqrt(ux * ux + uy * uy + uz * uz);
+				ux /= l2;
+				uy /= l2;
+				uz /= l2;
+			}
+
+			// Enforce outward/sky hemisphere alignment: dot(U, n_canopy + (0, 0.5, 0)) >= 0
+			if (ux * ncx + uy * (ncy + 0.5) + uz * ncz < 0.0) {
+				ux = -ux;
+				uy = -uy;
+				uz = -uz;
+			}
+
+			// W = F x U so that (W, F) card triangles have face normal W x F = +U!
+			const wx = fy * uz - fz * uy;
+			const wy = fz * ux - fx * uz;
+			const wz = fx * uy - fy * ux;
+
+			const c3 = cursor * 3;
+
+			positions[c3] = px;
+			positions[c3 + 1] = py;
+			positions[c3 + 2] = pz;
+
+			forward[c3] = fx;
+			forward[c3 + 1] = fy;
+			forward[c3 + 2] = fz;
+
+			up[c3] = ux;
+			up[c3 + 1] = uy;
+			up[c3 + 2] = uz;
+
+			right[c3] = wx;
+			right[c3 + 1] = wy;
+			right[c3 + 2] = wz;
+
+			const apex_env_scale = is_conical_crown && h_norm_card > 0.70
+				? lerp(1.0, 0.24, Math.pow(clamp((h_norm_card - 0.70) / 0.28, 0.0, 1.0), 1.15))
+				: 1.0;
+			const scale_var = 1.0 + (rng() * 2.0 - 1.0) * fol.size_variance;
+			const card_scale = Math.max(
+				0.18,
+				scale_var * (is_rosette ? 0.92 : 1.0) * Math.min(shoot_scale, apex_env_scale)
+			);
+			scales[cursor] = card_scale;
+
+			const t64 = new Transform64();
+			t64.setTranslation(px, py, pz);
+			t64_look_rotation(t64, fx, fy, fz, ux, uy, uz);
+			t64.setScaleScalar(card_scale);
+			t64.updateMatrix();
+			transforms[cursor] = t64;
+
+			// Golden-ratio low-discrepancy rank in [0, 1)
+			ranks[cursor] = ((cursor * GOLDEN_CONJUGATE) + b_phase * 0.13) % 1.0;
+			phases[cursor] = (b_phase + k * 0.17) % 1.0;
+			branch_sway[cursor] = clamp((level + t_attach) * 0.28, 0.1, 1.0);
+			const c_jit = rng() * 2.0 - 1.0;
+			color_jitter[cursor] = c_jit;
+
+			// Ontogenetic leaf maturity mu_i in [0, 1]:
+			// Acropetal shoot progression (terminal rosette / distal tip -> 0 juvenile, basal nodes -> 1 mature)
+			// combined with crown shell periphery (outer shell -> younger shoots, inner core -> older shade leaves)
+			const u_shoot = is_rosette
+				? clamp(0.88 + 0.12 * ((k - lateral_count + 0.5) / Math.max(1, rosette_count)), 0.88, 1.0)
+				: clamp((t_attach - t_min) / Math.max(1e-4, t_max * 0.92 - t_min), 0.0, 1.0);
+			const ndx_c = (px - cx) / rx_crown;
+			const ndy_c = (py - cy) / ry;
+			const ndz_c = (pz - cz) / rz_crown;
+			const rho_shell = clamp(Math.sqrt(ndx_c * ndx_c + ndy_c * ndy_c + ndz_c * ndz_c), 0.0, 1.0);
+			const maturity = clamp(
+				0.66 * (1.0 - u_shoot) + 0.24 * (1.0 - rho_shell) + 0.05 + 0.07 * c_jit,
+				0.0,
+				1.0
+			);
+			const sun_exp = clamp(0.62 * rho_shell + 0.38 * h_norm_card, 0.0, 1.0);
+			maturities[cursor] = maturity;
+			sun_exposure[cursor] = sun_exp;
+			variant_indices[cursor] = clamp(Math.floor(maturity * variant_count), 0, variant_count - 1);
+
+			cursor++;
+		}
+	}
+
+	return {
+		count: cursor,
+		transforms,
+		positions,
+		forward,
+		up,
+		right,
+		scales,
+		ranks,
+		phases,
+		branch_sway,
+		color_jitter,
+		maturities,
+		sun_exposure,
+		variant_indices,
+		joints,
+		weights,
+		joints4,
+		weights4,
+		attr_ranks: Attribute.from(ranks, 1, "foliage_ranks"),
+		attr_phases: Attribute.from(phases, 1, "foliage_phases"),
+		attr_branch_sway: Attribute.from(branch_sway, 1, "foliage_branch_sway"),
+		attr_color_jitter: Attribute.from(color_jitter, 1, "foliage_color_jitter"),
+		attr_maturities: Attribute.from(maturities, 1, "foliage_maturities"),
+		attr_variant_indices: Attribute.from(variant_indices, 1, "foliage_variant_indices"),
+		attr_joints: Attribute.from(joints, 2, "foliage_joints"),
+		attr_weights: Attribute.from(weights, 2, "foliage_weights")
+	};
+}

package/src/generation/foliage/mesh/tree_mesh_apply_canopy_ao.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Computes analytic volumetric crown ambient occlusion (combining normalized crown-shell depth
+ * and vertical sky exposure) into `StandardAttributes.Color` (`vec3<f32>`), and optionally
+ * applies hemisphere-safe normal puffing (`dot(n_puffed, n_orig) >= 0.55`) onto `StandardAttributes.Normal`.
+ *
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} geometry
+ * @param {ArrayLike<number>} crown_center `[cx, cy, cz]`
+ * @param {ArrayLike<number>} crown_radii `[rx, ry, rz]`
+ * @param {Object} [options]
+ * @param {number} [options.ao_core_darkening=0.35]
+ * @param {number} [options.normal_puffiness=0.0]
+ * @param {boolean} [options.preserve_existing_color=true]
+ */
+export function tree_mesh_apply_canopy_ao(geometry: import("../../../shade/renderer/geometry/Geometry.js").Geometry, crown_center: ArrayLike<number>, crown_radii: ArrayLike<number>, options?: {
+    ao_core_darkening?: number;
+    normal_puffiness?: number;
+    preserve_existing_color?: boolean;
+}): void;
+//# sourceMappingURL=tree_mesh_apply_canopy_ao.d.ts.map

package/src/generation/foliage/mesh/tree_mesh_apply_canopy_ao.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_mesh_apply_canopy_ao.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_mesh_apply_canopy_ao.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,oDARW,OAAO,8CAA8C,EAAE,QAAQ,gBAC/D,UAAU,MAAM,CAAC,eACjB,UAAU,MAAM,CAAC;IAEA,iBAAiB,GAAlC,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACY,uBAAuB,GAAzC,OAAO;SAoIjB"}