@woosh/meep-engine 3.52.0 → 3.54.0

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

@@ -0,0 +1,40 @@
+/**
+ * Packs `variant_count` square foliage card tiles of size `resolution x resolution` into a 2D atlas
+ * using the engine's `MaxRectanglesPacker` (`pack_max_rectangles`), returning the atlas dimensions,
+ * pixel-space `AABB2` boxes, and normalized `[u0, v0, u1, v1]` UV rectangles.
+ *
+ * @param {number} [resolution=128]
+ * @param {number} [variant_count=4]
+ * @returns {{
+ *   resolution: number,
+ *   variant_count: number,
+ *   atlas_w: number,
+ *   atlas_h: number,
+ *   boxes: AABB2[],
+ *   uv_rects: Float32Array
+ * }}
+ */
+export function compute_foliage_variant_atlas_layout(resolution?: number, variant_count?: number): {
+    resolution: number;
+    variant_count: number;
+    atlas_w: number;
+    atlas_h: number;
+    boxes: AABB2[];
+    uv_rects: Float32Array;
+};
+/**
+ * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
+ * `ShadeDrawSide.Double`) for botanical foliage cards, packing `config.variant_count` ontogenetic and
+ * biochemically senescent leaf cluster variants into the texture atlas via `MaxRectanglesPacker`
+ * (`pack_max_rectangles`), with dilated straight-alpha Albedo (`AlphaMode.Straight`, `ColorSpace.SRGB`),
+ * 2-channel Normal map (`ColorSpace.LinearSRGB`), and ORM (`ColorSpace.LinearSRGB`).
+ *
+ * @param {FoliageMaterialConfig|Object} [config]
+ * @param {number} [seed=1]
+ * @returns {StandardShadeMaterial}
+ */
+export function make_foliage_material(config?: FoliageMaterialConfig | any, seed?: number): StandardShadeMaterial;
+import AABB2 from "../../../core/geom/2d/aabb/AABB2.js";
+import { FoliageMaterialConfig } from "../config/FoliageMaterialConfig.js";
+import { StandardShadeMaterial } from "../../../shade/renderer/material/StandardShadeMaterial.js";
+//# sourceMappingURL=make_foliage_material.d.ts.map

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

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

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

@@ -0,0 +1,605 @@
+import AABB2 from "../../../core/geom/2d/aabb/AABB2.js";
+import { pack_max_rectangles } from "../../../core/geom/packing/max-rect/pack_max_rectangles.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { sdnoise3_array } from "../../../core/math/noise/sdnoise.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { smoothStep } from "../../../core/math/smoothStep.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { ShadeDrawSide } from "../../../shade/renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../../shade/renderer/material/StandardShadeMaterial.js";
+import { TransparencyMode } from "../../../shade/renderer/material/TransparencyMode.js";
+import { ColorSpace } from "../../../shade/renderer/texture/ColorSpace.js";
+import { ShadeTexture } from "../../../shade/renderer/texture/ShadeTexture.js";
+import { TextureFilterType } from "../../../shade/renderer/texture/TextureFilterType.js";
+import { TextureWrapType } from "../../../shade/renderer/texture/TextureWrapType.js";
+import { AlphaMode } from "../../../shade/renderer/texture/source/AlphaMode.js";
+import { ShadeImage } from "../../../shade/renderer/texture/source/ShadeImage.js";
+import { FoliageMaterialConfig } from "../config/FoliageMaterialConfig.js";
+
+const SCRATCH_NOISE = new Float32Array(4);
+
+/**
+ * Packs `variant_count` square foliage card tiles of size `resolution x resolution` into a 2D atlas
+ * using the engine's `MaxRectanglesPacker` (`pack_max_rectangles`), returning the atlas dimensions,
+ * pixel-space `AABB2` boxes, and normalized `[u0, v0, u1, v1]` UV rectangles.
+ *
+ * @param {number} [resolution=128]
+ * @param {number} [variant_count=4]
+ * @returns {{
+ *   resolution: number,
+ *   variant_count: number,
+ *   atlas_w: number,
+ *   atlas_h: number,
+ *   boxes: AABB2[],
+ *   uv_rects: Float32Array
+ * }}
+ */
+export function compute_foliage_variant_atlas_layout(resolution = 128, variant_count = 4) {
+	const res = Math.max(16, resolution | 0);
+	const count = clamp(variant_count | 0, 1, 16);
+	const cols = Math.max(1, Math.ceil(Math.sqrt(count)));
+	const rows = Math.max(1, Math.ceil(count / cols));
+	const atlas_w = cols * res;
+	const atlas_h = rows * res;
+
+	/** @type {AABB2[]} */
+	const boxes = new Array(count);
+	for (let k = 0; k < count; k++) {
+		boxes[k] = new AABB2(0, 0, res, res);
+	}
+
+	const packed = pack_max_rectangles(atlas_w, atlas_h, boxes);
+	if (!packed) {
+		// Deterministic grid fallback if custom non-uniform boxes are ever used
+		for (let k = 0; k < count; k++) {
+			const c = k % cols;
+			const r = Math.floor(k / cols);
+			boxes[k].set(c * res, r * res, (c + 1) * res, (r + 1) * res);
+		}
+	}
+
+	const uv_rects = new Float32Array(count * 4);
+	for (let k = 0; k < count; k++) {
+		const b = boxes[k];
+		const k4 = k * 4;
+		uv_rects[k4] = b.x0 / atlas_w;
+		uv_rects[k4 + 1] = b.y0 / atlas_h;
+		uv_rects[k4 + 2] = b.x1 / atlas_w;
+		uv_rects[k4 + 3] = b.y1 / atlas_h;
+	}
+
+	return {
+		resolution: res,
+		variant_count: count,
+		atlas_w,
+		atlas_h,
+		boxes,
+		uv_rects
+	};
+}
+
+/**
+ * Evaluates a single leaflet SDF, ontogenetic morphology, and venation relief in local leaflet
+ * coordinates `(lx, ly)` where `ly` in `[0, 1]` runs from petiole base to leaflet tip and `lx`
+ * in `[-0.5, 0.5]` runs across width.
+ *
+ * @param {number} lx
+ * @param {number} ly
+ * @param {string} shape `"ovate" | "lobed" | "serrated" | "palmate" | "needle" | "frond"`
+ * @param {number} mu_k ontogenetic maturity in `[0, 1]` (`0` = juvenile, `1` = mature)
+ * @param {number} shape_var ontogenetic morphology variation strength `[0, 1]`
+ * @param {number} vein_contrast ontogenetic venation & bullation contrast `[0, 1]`
+ * @returns {{ mask: number, vein: number, height: number, edge_norm: number }}
+ */
+function evaluate_leaflet(lx, ly, shape, mu_k, shape_var, vein_contrast) {
+	if (ly < -0.05 || ly > 1.05) {
+		return { mask: 0.0, vein: 0.0, height: 0.0, edge_norm: 0.0 };
+	}
+
+	const t = clamp(ly, 0.0, 1.0);
+	const ax = Math.abs(lx);
+
+	// Juvenile leaves expand longitudinally before full lateral blade expansion (narrower, more acuminate)
+	const width_scale = lerp(1.0 - 0.26 * shape_var, 1.0 + 0.08 * shape_var, mu_k);
+	const lobe_scale = lerp(1.0 - 0.45 * shape_var, 1.0 + 0.15 * shape_var, mu_k);
+	const profile_exp = lerp(0.84, 0.68, mu_k);
+
+	let half_w = 0.34 * width_scale * Math.sin(Math.PI * Math.pow(t, profile_exp));
+
+	switch (shape) {
+		case "lobed": {
+			// Oak-like rounded lobes along margin deepen as lamina matures
+			const lobe = 1.0 + 0.28 * lobe_scale * Math.sin(t * Math.PI * 7.0 - 0.6) * Math.sin(Math.PI * t);
+			half_w *= lobe;
+			break;
+		}
+		case "serrated": {
+			// Birch/elm sawtooth serration
+			const tooth = (t * 14.0) % 1.0;
+			half_w *= (1.0 - 0.12 * lobe_scale + 0.16 * lobe_scale * (1.0 - tooth));
+			break;
+		}
+		case "palmate": {
+			// Maple-like broader lobed palmate blade
+			const lobe = 1.0 + 0.32 * lobe_scale * Math.cos(t * Math.PI * 5.0);
+			half_w = 0.40 * width_scale * Math.sin(Math.PI * Math.pow(t, lerp(0.76, 0.62, mu_k))) * lobe;
+			break;
+		}
+		case "needle": {
+			// Slender conifer needle
+			half_w = 0.065 * lerp(0.85, 1.05, mu_k) * (1.0 - 0.65 * t * t);
+			break;
+		}
+		case "frond": {
+			// Long tapering willow/palm/fern pinna
+			half_w = 0.19 * width_scale * Math.sin(Math.PI * Math.pow(t, lerp(0.70, 0.56, mu_k)));
+			break;
+		}
+		case "ovate":
+		default:
+			break;
+	}
+
+	if (ax > half_w + 0.04) {
+		return { mask: 0.0, vein: 0.0, height: 0.0, edge_norm: 0.0 };
+	}
+
+	const edge_dist = half_w - ax;
+	const mask = smoothStep(-0.015, 0.018, edge_dist);
+	if (mask <= 0.0) {
+		return { mask: 0.0, vein: 0.0, height: 0.0, edge_norm: 0.0 };
+	}
+
+	const inv_hw = 1.0 / Math.max(1e-3, half_w);
+	const edge_norm = clamp(edge_dist * inv_hw, 0.0, 1.0);
+
+	// Midrib + herringbone secondary veins (sharper and more lignified on mature leaves)
+	const midrib_sharp = lerp(700.0, 1050.0, mu_k);
+	const midrib = Math.exp(-ax * ax * midrib_sharp) * (1.0 - 0.58 * t);
+	const sec_coord = (t * 9.0 - ax * 6.5);
+	const sec_frac = sec_coord - Math.floor(sec_coord);
+	const sec_sharp = lerp(36.0, 80.0, mu_k * vein_contrast + 0.25);
+	const sec_amp = lerp(0.28, 0.54, mu_k);
+	const sec_vein = Math.exp(-Math.pow(sec_frac - 0.5, 2.0) * sec_sharp)
+		* smoothStep(0.0, half_w, half_w - ax * 0.85)
+		* sec_amp;
+
+	const vein_relief = lerp(1.0 - 0.62 * vein_contrast, 1.0 + 0.34 * vein_contrast, mu_k);
+	const vein = clamp((midrib + sec_vein) * vein_relief, 0.0, 1.0);
+
+	// Lamina pillow camber across width + mature interveinal mesophyll bullation + vein ridge
+	const camber = Math.sqrt(Math.max(0.0, 1.0 - Math.pow(ax * inv_hw, 2.0))) * lerp(0.45, 0.68, mu_k);
+	const bullation = Math.sin(sec_frac * Math.PI)
+		* smoothStep(0.0, 0.65, edge_norm)
+		* (1.0 - midrib)
+		* lerp(0.02, 0.26, mu_k)
+		* vein_contrast;
+	const height = (camber + bullation + vein * 0.40) * mask;
+
+	return { mask, vein, height, edge_norm };
+}
+
+/**
+ * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
+ * `ShadeDrawSide.Double`) for botanical foliage cards, packing `config.variant_count` ontogenetic and
+ * biochemically senescent leaf cluster variants into the texture atlas via `MaxRectanglesPacker`
+ * (`pack_max_rectangles`), with dilated straight-alpha Albedo (`AlphaMode.Straight`, `ColorSpace.SRGB`),
+ * 2-channel Normal map (`ColorSpace.LinearSRGB`), and ORM (`ColorSpace.LinearSRGB`).
+ *
+ * @param {FoliageMaterialConfig|Object} [config]
+ * @param {number} [seed=1]
+ * @returns {StandardShadeMaterial}
+ */
+export function make_foliage_material(config = new FoliageMaterialConfig(), seed = 1) {
+	const cfg = config && config.isFoliageMaterialConfig ? config : FoliageMaterialConfig.from(config);
+	const layout = compute_foliage_variant_atlas_layout(cfg.resolution, cfg.variant_count);
+	const res = layout.resolution;
+	const variant_count = layout.variant_count;
+	const atlas_w = layout.atlas_w;
+	const atlas_h = layout.atlas_h;
+	const boxes = layout.boxes;
+
+	const rng = seededRandom((seed ^ 0x7F4A7C15) | 0);
+
+	const albedo_sampler = Sampler2D.uint8(4, atlas_w, atlas_h);
+	const normal_sampler = Sampler2D.uint8(2, atlas_w, atlas_h);
+	const orm_sampler = Sampler2D.uint8(4, atlas_w, atlas_h);
+
+	const albedo_data = albedo_sampler.data;
+	const normal_data = normal_sampler.data;
+	const orm_data = orm_sampler.data;
+
+	const height_field = new Float32Array(atlas_w * atlas_h);
+	const shape = cfg.leaf_shape || "lobed";
+	const leaflet_count = Math.max(1, cfg.leaflets_per_cluster | 0);
+	const base_rough = clamp(cfg.roughness, 0.1, 1.0);
+	const vein_str = clamp(cfg.vein_strength, 0.0, 1.0);
+
+	// Ontogeny & first-principles biochemical senescence parameters
+	const juv_shift = clamp(cfg.juvenile_color_shift ?? 0.38, 0.0, 1.0);
+	const juv_antho = clamp(cfg.juvenile_anthocyanin ?? 0.08, 0.0, 1.0);
+	const shape_var = clamp(cfg.ontogeny_shape_variation ?? 0.35, 0.0, 1.0);
+	const vein_contrast = clamp(cfg.ontogeny_vein_contrast ?? 0.55, 0.0, 1.0);
+
+	// Honour both first-principles `senescence` and legacy `autumn_tint`
+	const senescence = clamp(Math.max(cfg.senescence ?? 0.0, cfg.autumn_tint ?? 0.0), 0.0, 1.0);
+	const car_density = clamp(cfg.carotenoid_density ?? 0.75, 0.0, 1.0);
+	const antho_pot = clamp(cfg.anthocyanin_potential ?? 0.35, 0.0, 1.0);
+	const tannin_ox = clamp(cfg.tannin_oxidation ?? 0.25, 0.0, 1.0);
+
+	const p_r = cfg.primary_color.r;
+	const p_g = cfg.primary_color.g;
+	const p_b = cfg.primary_color.b;
+	const s_r = cfg.secondary_color.r;
+	const s_g = cfg.secondary_color.g;
+	const s_b = cfg.secondary_color.b;
+
+	// Pre-fill entire atlas with dilated base RGB (alpha = 0) and neutral normal/ORM so any
+	// unused rectangle cells (e.g., when variant_count = 3 or 5) still carry valid dilated RGB.
+	const fill_r = clamp(Math.round(Math.max(0.04, p_r) * 255), 1, 255);
+	const fill_g = clamp(Math.round(Math.max(0.04, p_g) * 255), 1, 255);
+	const fill_b = clamp(Math.round(Math.max(0.02, p_b) * 255), 1, 255);
+	const fill_rough = clamp(Math.round(base_rough * 255), 0, 255);
+	const total_texels = atlas_w * atlas_h;
+	for (let p = 0; p < total_texels; p++) {
+		const i4 = p * 4;
+		albedo_data[i4] = fill_r;
+		albedo_data[i4 + 1] = fill_g;
+		albedo_data[i4 + 2] = fill_b;
+		albedo_data[i4 + 3] = 0;
+
+		const i2 = p * 2;
+		normal_data[i2] = 128;
+		normal_data[i2 + 1] = 128;
+
+		orm_data[i4] = 255;
+		orm_data[i4 + 1] = fill_rough;
+		orm_data[i4 + 2] = 0;
+		orm_data[i4 + 3] = 255;
+	}
+
+	const anchor_u = clamp(cfg.stem_anchor_u ?? 0.5, 0.1, 0.9);
+	const anchor_v = clamp(cfg.stem_anchor_v ?? 0.0, 0.0, 0.25);
+	const min_stem_half_w = Math.max(0.022, 1.5 / res);
+
+	for (let v_idx = 0; v_idx < variant_count; v_idx++) {
+		const box = boxes[v_idx];
+		const tile_x0 = box.x0;
+		const tile_y0 = box.y0;
+
+		// Ontogenetic coordinate mu_k in [0, 1]: 0 = juvenile apical flush, 1 = mature basal foliage
+		const mu_k = variant_count > 1 ? v_idx / (variant_count - 1) : 0.65;
+		const ox = (rng() - 0.5) * 150.0 + v_idx * 37.3;
+		const oy = (rng() - 0.5) * 150.0 + v_idx * 53.7;
+
+		// Ontogenetic cluster geometry scaling: juvenile shoots are slightly more forward-cupped and compact
+		const angle_scale = lerp(1.0 - 0.22 * shape_var, 1.0 + 0.06 * shape_var, mu_k);
+		const len_scale = lerp(1.0 - 0.14 * shape_var, 1.0 + 0.04 * shape_var, mu_k);
+
+		const leaflets = [];
+		if (shape === "palmate") {
+			const count = Math.max(3, leaflet_count | 1);
+			for (let i = 0; i < count; i++) {
+				const frac = (i / (count - 1)) * 2.0 - 1.0; // [-1, 1]
+				const angle = frac * 1.05 * angle_scale;
+				const scale = (1.0 - 0.32 * Math.abs(frac)) * 0.76 * len_scale;
+				leaflets.push({
+					ox: anchor_u,
+					oy: anchor_v + 0.08,
+					dir_x: Math.sin(angle),
+					dir_y: Math.cos(angle),
+					length: scale,
+					width: scale * 0.9
+				});
+			}
+		} else if (shape === "needle") {
+			const pairs = Math.max(4, leaflet_count);
+			for (let i = 0; i < pairs; i++) {
+				const v_stem = anchor_v + 0.04 + (i / pairs) * 0.74;
+				for (const side of [-1, 1]) {
+					const angle = side * (0.45 + 0.25 * (1.0 - i / pairs)) * angle_scale;
+					const len = 0.36 * (1.0 - 0.35 * (i / pairs)) * len_scale;
+					leaflets.push({
+						ox: anchor_u,
+						oy: v_stem,
+						dir_x: Math.sin(angle),
+						dir_y: Math.cos(angle),
+						length: len,
+						width: len
+					});
+				}
+			}
+			leaflets.push({
+				ox: anchor_u,
+				oy: anchor_v + 0.72,
+				dir_x: 0.0,
+				dir_y: 1.0,
+				length: 0.26 * len_scale,
+				width: 0.26 * len_scale
+			});
+		} else {
+			const pairs = Math.max(1, Math.floor(leaflet_count / 2));
+			for (let p = 0; p < pairs; p++) {
+				const u_p = (p + 0.35) / (pairs + 0.35);
+				const v_stem = anchor_v + 0.04 + u_p * 0.56;
+				const angle_mag = lerp(0.95, 0.55, u_p) * angle_scale;
+				const len = lerp(0.40, 0.30, u_p) * len_scale;
+				for (const side of [-1, 1]) {
+					const angle = side * angle_mag;
+					leaflets.push({
+						ox: anchor_u,
+						oy: v_stem,
+						dir_x: Math.sin(angle),
+						dir_y: Math.cos(angle),
+						length: len,
+						width: len * 0.95
+					});
+				}
+			}
+			leaflets.push({
+				ox: anchor_u,
+				oy: anchor_v + 0.56,
+				dir_x: 0.0,
+				dir_y: 1.0,
+				length: 0.42 * len_scale,
+				width: 0.40 * len_scale
+			});
+		}
+
+		// Ontogenetic chlorophyll accumulation (juvenile protochlorophyllide lag -> lighter yellow-green)
+		const juv_factor = (1.0 - mu_k) * juv_shift;
+		// Staggered variant senescence progression across the atlas so autumn crowns exhibit natural leaf-to-leaf diversity
+		const sigma_k = senescence > 0.0
+			? clamp(senescence * (0.80 + 0.36 * Math.abs(mu_k - 0.35)) + senescence * senescence * 0.12, 0.0, 1.0)
+			: 0.0;
+		const sun_variant_factor = lerp(1.18, 0.74, mu_k);
+		const rough_ontogeny_offset = lerp(-0.10 * vein_contrast, 0.07 * vein_contrast, mu_k);
+
+		for (let ly_px = 0; ly_px < res; ly_px++) {
+			const v = (ly_px + 0.5) / res;
+			const atlas_y = tile_y0 + ly_px;
+			const row_offset = atlas_y * atlas_w;
+			// Prevent top-edge vertical bleeding into adjacent stacked tiles while keeping v=0 stem anchor solid
+			const top_border_fade = smoothStep(1.0, 0.975, v);
+
+			for (let lx_px = 0; lx_px < res; lx_px++) {
+				const u = (lx_px + 0.5) / res;
+				const atlas_x = tile_x0 + lx_px;
+				const p_idx = row_offset + atlas_x;
+
+				// Central woody twig / rachis along u = anchor_u, v in [anchor_v, anchor_v + 0.72]
+				let stem_mask = 0.0;
+				if (v >= anchor_v && v <= anchor_v + 0.72) {
+					const u_stem = clamp((v - anchor_v) / 0.72, 0.0, 1.0);
+					const stem_half_w = lerp(min_stem_half_w, 0.007, u_stem);
+					const d_stem = stem_half_w - Math.abs(u - anchor_u);
+					stem_mask = smoothStep(-0.008, 0.008, d_stem);
+				}
+
+				let best_mask = 0.0;
+				let best_vein = 0.0;
+				let best_h = 0.0;
+				let best_tip = 0.0;
+				let best_edge_norm = 0.5;
+
+				for (let l = 0; l < leaflets.length; l++) {
+					const lf = leaflets[l];
+					const dx = u - lf.ox;
+					const dy = v - lf.oy;
+					const ly = (dx * lf.dir_x + dy * lf.dir_y) / lf.length;
+					const lx = (dx * lf.dir_y - dy * lf.dir_x) / lf.width;
+
+					const eval_res = evaluate_leaflet(lx, ly, shape, mu_k, shape_var, vein_contrast);
+					if (eval_res.mask > best_mask) {
+						best_mask = eval_res.mask;
+						best_vein = eval_res.vein;
+						best_h = eval_res.height;
+						best_tip = clamp(ly, 0.0, 1.0);
+						best_edge_norm = eval_res.edge_norm;
+					}
+				}
+
+				best_mask *= top_border_fade;
+				const alpha = clamp(Math.max(best_mask, stem_mask), 0.0, 1.0);
+				height_field[p_idx] = Math.max(best_h * top_border_fade, stem_mask * 0.4);
+
+				sdnoise3_array(SCRATCH_NOISE, u * 6.0 + ox, v * 6.0 + oy, 0.0);
+				const n_var = SCRATCH_NOISE[0] * 0.5 + 0.5;
+
+				// 1. Base photosynthetic chlorophyll + carotenoid lamina reflectance (with juvenile chartreuse shift)
+				const vein_mix_w = lerp(0.38, 0.72, mu_k) * vein_str;
+				const mix_t = clamp(best_vein * vein_mix_w + best_tip * 0.24 + n_var * 0.18, 0.0, 1.0);
+				let cr = lerp(p_r, s_r, mix_t);
+				let cg = lerp(p_g, s_g, mix_t);
+				let cb = lerp(p_b, s_b, mix_t);
+
+				// Juvenile protochlorophyllide lag: higher mesophyll reflectance + yellow-green chartreuse shift
+				if (juv_factor > 1e-4) {
+					const tip_boost = 0.75 + 0.25 * best_tip;
+					const j_w = juv_factor * tip_boost;
+					cr = clamp(cr + j_w * 0.22, 0.0, 1.0);
+					cg = clamp(cg + j_w * 0.28, 0.0, 1.0);
+					cb = clamp(cb + j_w * 0.04, 0.0, 1.0);
+				}
+
+				// Transient juvenile epidermal anthocyanin flush along expanding young leaf margins/tips
+				const w_ant_juv = juv_antho * Math.pow(1.0 - mu_k, 1.8)
+					* (0.30 + 0.70 * (1.0 - best_edge_norm * 0.65) * (0.35 + 0.65 * best_tip))
+					* (1.0 - sigma_k);
+				if (w_ant_juv > 1e-4) {
+					cr = lerp(cr, 0.58, w_ant_juv * 0.75);
+					cg = lerp(cg, 0.24, w_ant_juv * 0.65);
+					cb = lerp(cb, 0.14, w_ant_juv * 0.65);
+				}
+
+				// 2. First-principles autumn senescence (Chlorophyll catabolism -> Carotenoid unmasking -> Anthocyanin -> Tannin)
+				if (sigma_k > 1e-4) {
+					// Vascular bundles (midrib & secondary veins) and basal petiole retain chlorophyll longest
+					const vascular_shield = clamp(
+						0.48 * best_vein + 0.34 * best_edge_norm * (1.0 - 0.55 * best_tip) + 0.18 * n_var,
+						0.0,
+						1.0
+					);
+					const r_chl_lin = clamp(1.0 - sigma_k * (1.36 - 0.68 * vascular_shield), 0.0, 1.0);
+					const r_chl = r_chl_lin * r_chl_lin;
+					const chl_loss = 1.0 - r_chl;
+
+					// (a) Unmask plastid carotenoids (xanthophyll / beta-carotene -> golden-yellow)
+					const car_r = lerp(0.76, 0.94, car_density);
+					const car_g = lerp(0.54, 0.74, car_density);
+					const car_b = lerp(0.14, 0.08, car_density);
+					const w_car = clamp(chl_loss * (0.38 + 0.62 * car_density), 0.0, 1.0);
+					cr = lerp(cr, car_r, w_car);
+					cg = lerp(cg, car_g, w_car);
+					cb = lerp(cb, car_b, w_car);
+
+					// (b) De novo vacuolar anthocyanin synthesis (high light + margin/tip sugar accumulation -> scarlet/crimson)
+					if (antho_pot > 1e-4) {
+						const margin_sugar = clamp(
+							0.52 * (1.0 - best_edge_norm) + 0.34 * best_tip + 0.22 * (1.0 - best_vein) + 0.15 * (1.0 - n_var),
+							0.0,
+							1.0
+						);
+						const w_ant = clamp(
+							antho_pot * chl_loss * Math.pow(sigma_k, 0.72) * sun_variant_factor * (0.42 + 0.78 * margin_sugar),
+							0.0,
+							1.0
+						);
+						// Vacuolar anthocyanin strongly absorbs green (~530nm) and blue while transmitting red (~650nm)
+						cr = lerp(cr, 0.82, w_ant * 0.85);
+						cg *= lerp(1.0, 0.18, w_ant);
+						cb *= lerp(1.0, 0.24, w_ant);
+					}
+
+					// (c) Late-senescence condensed tannin / polyphenol oxidation into russet/copper-brown
+					if (tannin_ox > 1e-4 && sigma_k > 0.22) {
+						const w_tan = clamp(
+							tannin_ox
+							* chl_loss * chl_loss
+							* smoothStep(0.22, 0.95, sigma_k)
+							* lerp(0.68, 1.22, mu_k)
+							* (0.42 + 0.72 * (1.0 - best_edge_norm * 0.7)),
+							0.0,
+							1.0
+						);
+						cr = lerp(cr, 0.44, w_tan);
+						cg = lerp(cg, 0.24, w_tan);
+						cb = lerp(cb, 0.10, w_tan);
+					}
+				}
+
+				// 3. Petiole / rachis coloration: herbaceous green on juvenile shoots -> suberized woody brown on mature shoots
+				if (stem_mask > best_mask) {
+					const stem_r = lerp(lerp(p_r, 0.32, 0.55), 0.32, mu_k);
+					const stem_g = lerp(lerp(p_g, 0.38, 0.55), 0.26, mu_k);
+					const stem_b = lerp(lerp(p_b, 0.16, 0.55), 0.16, mu_k);
+					cr = lerp(cr, stem_r, stem_mask * 0.75);
+					cg = lerp(cg, stem_g, stem_mask * 0.75);
+					cb = lerp(cb, stem_b, stem_mask * 0.75);
+				}
+
+				// Subtle basal petiole ambient darkening
+				const base_shade = 0.82 + 0.18 * v;
+				cr = Math.max(0.01, cr * base_shade);
+				cg = Math.max(0.01, cg * base_shade);
+				cb = Math.max(0.005, cb * base_shade);
+
+				const i4 = p_idx * 4;
+				albedo_data[i4] = clamp(Math.round(cr * 255), 1, 255);
+				albedo_data[i4 + 1] = clamp(Math.round(cg * 255), 1, 255);
+				albedo_data[i4 + 2] = clamp(Math.round(cb * 255), 1, 255);
+				albedo_data[i4 + 3] = clamp(Math.round(alpha * 255), 0, 255);
+
+				const ao = clamp(0.75 + 0.25 * best_h, 0.25, 1.0);
+				const rough = clamp(
+					base_rough + rough_ontogeny_offset + sigma_k * 0.08 - best_vein * 0.08 + (1.0 - n_var) * 0.06,
+					0.15,
+					0.95
+				);
+				orm_data[i4] = clamp(Math.round(ao * 255), 0, 255);
+				orm_data[i4 + 1] = clamp(Math.round(rough * 255), 0, 255);
+				orm_data[i4 + 2] = 0;
+				orm_data[i4 + 3] = 255;
+			}
+		}
+
+		// Pass 2 (per-tile): Central-difference tangent-space normal map clamped to tile bounds
+		const tile_vein_scale = lerp(1.0 - 0.58 * vein_contrast, 1.0 + 0.35 * vein_contrast, mu_k);
+		const norm_str = (1.6 * vein_str + 0.35) * tile_vein_scale;
+		for (let ly_px = 0; ly_px < res; ly_px++) {
+			const y0 = tile_y0 + Math.max(0, ly_px - 1);
+			const y1 = tile_y0 + Math.min(res - 1, ly_px + 1);
+			const yc = tile_y0 + ly_px;
+
+			for (let lx_px = 0; lx_px < res; lx_px++) {
+				const x0 = tile_x0 + Math.max(0, lx_px - 1);
+				const x1 = tile_x0 + Math.min(res - 1, lx_px + 1);
+				const xc = tile_x0 + lx_px;
+
+				const dh_du = (height_field[yc * atlas_w + x1] - height_field[yc * atlas_w + x0]) * 0.5 * norm_str;
+				const dh_dv = (height_field[y1 * atlas_w + xc] - height_field[y0 * atlas_w + xc]) * 0.5 * norm_str;
+
+				let nx = -dh_du;
+				let ny = -dh_dv;
+				const nz = 1.0;
+				const nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+				nx /= nl;
+				ny /= nl;
+
+				const i2 = (yc * atlas_w + xc) * 2;
+				normal_data[i2] = clamp(Math.round((nx * 0.5 + 0.5) * 255), 0, 255);
+				normal_data[i2 + 1] = clamp(Math.round((ny * 0.5 + 0.5) * 255), 0, 255);
+			}
+		}
+	}
+
+	const albedo_image = ShadeImage.fromSampler2D(albedo_sampler);
+	albedo_image.color_space = ColorSpace.SRGB;
+	// CRITICAL: Keep AlphaMode.Straight so texture_write_to_gpu premultiplies once on upload
+	// and G-buffer albedo_unpremultiply recovers clean dilated leaf color at cutout boundaries.
+	albedo_image.alpha_mode = AlphaMode.Straight;
+	const texture_albedo = ShadeTexture.from(albedo_image);
+	texture_albedo.label = "foliage_leaf_albedo";
+	texture_albedo.color_space = ColorSpace.SRGB;
+	texture_albedo.mipmapGenerationFilter = TextureFilterType.MagicKernelSharp;
+	texture_albedo.wrapS = TextureWrapType.ClampToEdge;
+	texture_albedo.wrapT = TextureWrapType.ClampToEdge;
+
+	const normal_image = ShadeImage.fromSampler2D(normal_sampler);
+	normal_image.color_space = ColorSpace.None;
+	normal_image.alpha_mode = AlphaMode.Opaque;
+	const texture_normal = ShadeTexture.from(normal_image);
+	texture_normal.label = "foliage_leaf_normal";
+	texture_normal.color_space = ColorSpace.LinearSRGB;
+	texture_normal.mipmapGenerationFilter = TextureFilterType.LinearNormal;
+	texture_normal.wrapS = TextureWrapType.ClampToEdge;
+	texture_normal.wrapT = TextureWrapType.ClampToEdge;
+
+	const orm_image = ShadeImage.fromSampler2D(orm_sampler);
+	orm_image.color_space = ColorSpace.None;
+	orm_image.alpha_mode = AlphaMode.Opaque;
+	const texture_orm = ShadeTexture.from(orm_image);
+	texture_orm.label = "foliage_leaf_orm";
+	texture_orm.color_space = ColorSpace.LinearSRGB;
+	texture_orm.wrapS = TextureWrapType.ClampToEdge;
+	texture_orm.wrapT = TextureWrapType.ClampToEdge;
+
+	const material = new StandardShadeMaterial();
+	material.name = "foliage_leaf_material";
+	material.texture_albedo = texture_albedo;
+	material.texture_normal = texture_normal;
+	material.texture_orm = texture_orm;
+	material.roughness_factor = 1.0;
+	material.metallic_factor = 0.0;
+	// CRITICAL: Keep transmission_factor = 0 on AlphaTested cards so transparent card corners
+	// do not act as refractive glass in the path tracer!
+	material.transmission_factor = 0.0;
+	material.ambient_factors.a = 1.0;
+	material.ambient_factors.b = 0.0;
+	material.transparency_mode = TransparencyMode.AlphaTested;
+	material.transparency = TransparencyMode.AlphaTested;
+	material.draw_side = ShadeDrawSide.Double;
+
+	return material;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Projects a child branch collar vertex `(ring_x, ring_y, ring_z)` into the parent branch's
+ * polygonal frustum in the orthonormal $(\mathbf{T}_p, \hat{\mathbf{u}}, \hat{\mathbf{w}})$ basis,
+ * guaranteeing that:
+ * 1. Every welded base vertex (`weld_factor === 1`) sits strictly inside the parent polygon's
+ *    inscribed apothem radius $R_{\text{apothem}}(z) = R_p(z) (1 - \text{flute\_amp}_p) \cos(\pi / M_p)$
+ *    at the vertex's axial height $z$ (preventing any daylight gap outside polygonal parent facets or tapering segments).
+ * 2. Every welded base vertex lands strictly on the emerging $+\hat{\mathbf{u}}$ hemisphere of the
+ *    parent axis ($q_u > 0$, preventing any backward protrusion through the opposite side of the parent branch).
+ * 3. Axial offset $z$ along $\mathbf{T}_p$ is bounded within $[z_{\min}, z_{\max}]$.
+ * 4. Outward normals blend smoothly ($C^1$) from the parent cylinder normal to the child tube normal.
+ *
+ * @param {number[]|Float32Array} out_pos
+ * @param {number} out_pos_offset
+ * @param {number[]|Float32Array} out_norm
+ * @param {number} out_norm_offset
+ * @param {number} ring_x flared child ring vertex X
+ * @param {number} ring_y flared child ring vertex Y
+ * @param {number} ring_z flared child ring vertex Z
+ * @param {number} tube_nx outward child tube normal X
+ * @param {number} tube_ny outward child tube normal Y
+ * @param {number} tube_nz outward child tube normal Z
+ * @param {number} child_tx unit child spine tangent X
+ * @param {number} child_ty unit child spine tangent Y
+ * @param {number} child_tz unit child spine tangent Z
+ * @param {number} parent_px parent attachment center X
+ * @param {number} parent_py parent attachment center Y
+ * @param {number} parent_pz parent attachment center Z
+ * @param {number} parent_tx unit parent spine tangent X
+ * @param {number} parent_ty unit parent spine tangent Y
+ * @param {number} parent_tz unit parent spine tangent Z
+ * @param {number} parent_radius parent branch radius at attachment
+ * @param {number} weld_factor in [0, 1] (1 at base ring i=0, decaying to 0 across collar rings)
+ * @param {number} normal_blend in [0, 1] blend weight toward parent normal
+ * @param {number} [parent_radial_segments=8] radial polygon vertex count M_p of parent branch
+ * @param {number} [parent_flute_amplitude=0.0] flute amplitude of parent branch
+ * @param {number} [parent_taper_slope=0.0] linear radius change dR_p/dz along parent_T
+ * @param {number} [z_min=-Infinity] minimum axial offset along parent_T
+ * @param {number} [z_max=Infinity] maximum axial offset along parent_T
+ */
+export function branch_collar_project(out_pos: number[] | Float32Array, out_pos_offset: number, out_norm: number[] | Float32Array, out_norm_offset: number, ring_x: number, ring_y: number, ring_z: number, tube_nx: number, tube_ny: number, tube_nz: number, child_tx: number, child_ty: number, child_tz: number, parent_px: number, parent_py: number, parent_pz: number, parent_tx: number, parent_ty: number, parent_tz: number, parent_radius: number, weld_factor: number, normal_blend: number, parent_radial_segments?: number, parent_flute_amplitude?: number, parent_taper_slope?: number, z_min?: number, z_max?: number): void;
+//# sourceMappingURL=branch_collar_project.d.ts.map