@woosh/meep-engine 3.52.0 → 3.53.0

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

@@ -0,0 +1,14 @@
+/**
+ * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
+ * `ShadeDrawSide.Double`) for botanical foliage cards, 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 { 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":"AAgGA;;;;;;;;;GASG;AACH,+CAJW,qBAAqB,MAAO,SAC5B,MAAM,GACJ,qBAAqB,CA8PjC;sCAvVqC,oCAAoC;sCARpC,2DAA2D"}

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

@@ -0,0 +1,359 @@
+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);
+
+/**
+ * Evaluates a single leaflet SDF + 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"`
+ * @returns {{ mask: number, vein: number, height: number }}
+ */
+function evaluate_leaflet(lx, ly, shape) {
+    if (ly < -0.05 || ly > 1.05) {
+        return { mask: 0.0, vein: 0.0, height: 0.0 };
+    }
+
+    const t = clamp(ly, 0.0, 1.0);
+    const ax = Math.abs(lx);
+
+    let half_w = 0.34 * Math.sin(Math.PI * Math.pow(t, 0.72));
+
+    switch (shape) {
+        case "lobed": {
+            // Oak-like rounded lobes along margin
+            const lobe = 1.0 + 0.28 * 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 *= (0.88 + 0.16 * (1.0 - tooth));
+            break;
+        }
+        case "palmate": {
+            // Maple-like broader lobed palmate blade
+            const lobe = 1.0 + 0.32 * Math.cos(t * Math.PI * 5.0);
+            half_w = 0.40 * Math.sin(Math.PI * Math.pow(t, 0.65)) * lobe;
+            break;
+        }
+        case "needle": {
+            // Slender conifer needle
+            half_w = 0.065 * (1.0 - 0.65 * t * t);
+            break;
+        }
+        case "frond": {
+            // Long tapering willow/palm/fern pinna
+            half_w = 0.19 * Math.sin(Math.PI * Math.pow(t, 0.6));
+            break;
+        }
+        case "ovate":
+        default:
+            break;
+    }
+
+    if (ax > half_w + 0.04) {
+        return { mask: 0.0, vein: 0.0, height: 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 };
+    }
+
+    // Midrib + herringbone secondary veins
+    const midrib = Math.exp(-ax * ax * 900.0) * (1.0 - 0.6 * t);
+    const sec_coord = (t * 9.0 - ax * 6.5);
+    const sec_frac = sec_coord - Math.floor(sec_coord);
+    const sec_vein = Math.exp(-Math.pow(sec_frac - 0.5, 2.0) * 65.0) * smoothStep(0.0, half_w, half_w - ax * 0.85) * 0.45;
+
+    const vein = clamp(midrib + sec_vein, 0.0, 1.0);
+    // Lamina pillow camber across width + vein ridge
+    const camber = Math.sqrt(Math.max(0.0, 1.0 - Math.pow(ax / Math.max(1e-3, half_w), 2.0))) * 0.65;
+    const height = (camber + vein * 0.35) * mask;
+
+    return { mask, vein, height };
+}
+
+/**
+ * Synthesizes a turn-key procedural PBR cutout `StandardShadeMaterial` (`TransparencyMode.AlphaTested`,
+ * `ShadeDrawSide.Double`) for botanical foliage cards, 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 res = Math.max(16, cfg.resolution | 0);
+    const rng = seededRandom((seed ^ 0x7F4A7C15) | 0);
+    const ox = (rng() - 0.5) * 150.0;
+    const oy = (rng() - 0.5) * 150.0;
+
+    const albedo_sampler = Sampler2D.uint8(4, res, res);
+    const normal_sampler = Sampler2D.uint8(2, res, res);
+    const orm_sampler = Sampler2D.uint8(4, res, res);
+
+    const albedo_data = albedo_sampler.data;
+    const normal_data = normal_sampler.data;
+    const orm_data = orm_sampler.data;
+
+    const height_field = new Float32Array(res * res);
+    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);
+    const autumn = clamp(cfg.autumn_tint, 0.0, 1.0);
+
+    // Base leaf color (mixed with optional autumn golden-orange tint)
+    const r1 = lerp(cfg.primary_color.r, 0.78, autumn * 0.7);
+    const g1 = lerp(cfg.primary_color.g, 0.36, autumn * 0.5);
+    const b1 = lerp(cfg.primary_color.b, 0.08, autumn * 0.7);
+
+    const r2 = lerp(cfg.secondary_color.r, 0.88, autumn * 0.75);
+    const g2 = lerp(cfg.secondary_color.g, 0.55, autumn * 0.5);
+    const b2 = lerp(cfg.secondary_color.b, 0.12, autumn * 0.75);
+
+    // Precompute leaflet placement descriptors on the `[0, 1]^2` card anchored at `(anchor_u, anchor_v)`
+    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 leaflets = [];
+    if (shape === "palmate") {
+        // Radiating palmate leaflets from basal hub above (anchor_u, anchor_v)
+        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;
+            const scale = (1.0 - 0.32 * Math.abs(frac)) * 0.76;
+            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") {
+        // Fascicle of radiating conifer needles along central twig from anchor_v
+        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));
+                const len = 0.36 * (1.0 - 0.35 * (i / pairs));
+                leaflets.push({
+                    ox: anchor_u,
+                    oy: v_stem,
+                    dir_x: Math.sin(angle),
+                    dir_y: Math.cos(angle),
+                    length: len,
+                    width: len
+                });
+            }
+        }
+        // Terminal needle tuft
+        leaflets.push({ ox: anchor_u, oy: anchor_v + 0.72, dir_x: 0.0, dir_y: 1.0, length: 0.26, width: 0.26 });
+    } else {
+        // Pinnate twig cluster: pairs of lateral leaflets + 1 terminal apical leaflet starting near anchor_v
+        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);
+            const len = lerp(0.40, 0.30, u_p);
+            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
+                });
+            }
+        }
+        // Terminal apical leaflet
+        leaflets.push({
+            ox: anchor_u,
+            oy: anchor_v + 0.56,
+            dir_x: 0.0,
+            dir_y: 1.0,
+            length: 0.42,
+            width: 0.40
+        });
+    }
+
+    const min_stem_half_w = Math.max(0.022, 1.5 / res);
+    for (let y = 0; y < res; y++) {
+        const v = (y + 0.5) / res;
+        for (let x = 0; x < res; x++) {
+            const u = (x + 0.5) / res;
+            const p_idx = y * res + 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;
+
+            for (let l = 0; l < leaflets.length; l++) {
+                const lf = leaflets[l];
+                const dx = u - lf.ox;
+                const dy = v - lf.oy;
+                // Project onto leaflet forward (dir_x, dir_y) and right (dir_y, -dir_x)
+                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);
+                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);
+                }
+            }
+
+            const alpha = clamp(Math.max(best_mask, stem_mask), 0.0, 1.0);
+            height_field[p_idx] = Math.max(best_h, 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;
+
+            // Compute straight RGB even when alpha === 0 (automatic infinite dilation for mipmap bleeding safety!)
+            const mix_t = clamp(best_vein * vein_str * 0.65 + best_tip * 0.25 + n_var * 0.2, 0.0, 1.0);
+            let cr = lerp(r1, r2, mix_t);
+            let cg = lerp(g1, g2, mix_t);
+            let cb = lerp(b1, b2, mix_t);
+
+            if (stem_mask > best_mask) {
+                cr = lerp(cr, 0.32, stem_mask * 0.75);
+                cg = lerp(cg, 0.26, stem_mask * 0.75);
+                cb = lerp(cb, 0.16, stem_mask * 0.75);
+            }
+
+            // Subtle basal petiole ambient darkening
+            const base_shade = 0.82 + 0.18 * v;
+            cr *= base_shade;
+            cg *= base_shade;
+            cb *= base_shade;
+
+            const i4 = p_idx * 4;
+            albedo_data[i4] = clamp(Math.round(cr * 255), 0, 255);
+            albedo_data[i4 + 1] = clamp(Math.round(cg * 255), 0, 255);
+            albedo_data[i4 + 2] = clamp(Math.round(cb * 255), 0, 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 - 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: Central-difference tangent-space normal map from leaf venation heightfield
+    const norm_str = 1.6 * vein_str + 0.35;
+    for (let y = 0; y < res; y++) {
+        const y0 = Math.max(0, y - 1);
+        const y1 = Math.min(res - 1, y + 1);
+        for (let x = 0; x < res; x++) {
+            const x0 = Math.max(0, x - 1);
+            const x1 = Math.min(res - 1, x + 1);
+
+            const dh_du = (height_field[y * res + x1] - height_field[y * res + x0]) * 0.5 * norm_str;
+            const dh_dv = (height_field[y1 * res + x] - height_field[y0 * res + x]) * 0.5 * norm_str;
+
+            let nx = -dh_du;
+            let ny = -dh_dv;
+            let nz = 1.0;
+            const nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+            nx /= nl;
+            ny /= nl;
+
+            const i2 = (y * res + x) * 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch_collar_project.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/branch_collar_project.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,+CA5BW,MAAM,EAAE,GAAC,YAAY,kBACrB,MAAM,YACN,MAAM,EAAE,GAAC,YAAY,mBACrB,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,iBACN,MAAM,eACN,MAAM,gBACN,MAAM,2BACN,MAAM,2BACN,MAAM,uBACN,MAAM,UACN,MAAM,UACN,MAAM,QAiKhB"}

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

@@ -0,0 +1,203 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+
+/**
+ * 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,
+    out_pos_offset,
+    out_norm,
+    out_norm_offset,
+    ring_x, ring_y, ring_z,
+    tube_nx, tube_ny, tube_nz,
+    child_tx, child_ty, child_tz,
+    parent_px, parent_py, parent_pz,
+    parent_tx, parent_ty, parent_tz,
+    parent_radius,
+    weld_factor,
+    normal_blend,
+    parent_radial_segments = 8,
+    parent_flute_amplitude = 0.0,
+    parent_taper_slope = 0.0,
+    z_min = -Infinity,
+    z_max = Infinity
+) {
+    const w = clamp(weld_factor, 0.0, 1.0);
+    if (w <= 1e-5 || parent_radius <= 1e-5) {
+        out_pos[out_pos_offset] = ring_x;
+        out_pos[out_pos_offset + 1] = ring_y;
+        out_pos[out_pos_offset + 2] = ring_z;
+        out_norm[out_norm_offset] = tube_nx;
+        out_norm[out_norm_offset + 1] = tube_ny;
+        out_norm[out_norm_offset + 2] = tube_nz;
+        return;
+    }
+
+    // Polygon apothem factor of parent branch cross-section
+    const m_p = Math.max(3, parent_radial_segments | 0);
+    const flute_guard = Math.max(0.5, 1.0 - Math.max(0.0, parent_flute_amplitude));
+    const apothem_factor = Math.cos(Math.PI / m_p) * flute_guard;
+    const seat_ratio = 0.78 * apothem_factor;
+
+    // Vector from parent axis point to ring vertex
+    const dx = ring_x - parent_px;
+    const dy = ring_y - parent_py;
+    const dz = ring_z - parent_pz;
+
+    // Axial coordinate z_0 along parent_T and perpendicular radial offset q_0
+    const z_0 = dx * parent_tx + dy * parent_ty + dz * parent_tz;
+    const qx = dx - z_0 * parent_tx;
+    const qy = dy - z_0 * parent_ty;
+    const qz = dz - z_0 * parent_tz;
+
+    // Component of child_T perpendicular to parent_T
+    const dot_ct_pt = child_tx * parent_tx + child_ty * parent_ty + child_tz * parent_tz;
+    let ux = child_tx - dot_ct_pt * parent_tx;
+    let uy = child_ty - dot_ct_pt * parent_ty;
+    let uz = child_tz - dot_ct_pt * parent_tz;
+    const u_len = Math.sqrt(ux * ux + uy * uy + uz * uz);
+
+    let unx = 0.0, uny = 0.0, unz = 0.0;
+    if (u_len > 1e-5) {
+        unx = ux / u_len;
+        uny = uy / u_len;
+        unz = uz / u_len;
+    } else {
+        // Fallback orthogonal unit vector when child_T is collinear with parent_T
+        const q_len = Math.sqrt(qx * qx + qy * qy + qz * qz);
+        if (q_len > 1e-6) {
+            unx = qx / q_len;
+            uny = qy / q_len;
+            unz = qz / q_len;
+        } else {
+            if (Math.abs(parent_ty) < 0.9) {
+                unx = -parent_tz;
+                uny = 0.0;
+                unz = parent_tx;
+            } else {
+                unx = 1.0;
+                uny = 0.0;
+                unz = 0.0;
+            }
+            const d_p = unx * parent_tx + uny * parent_ty + unz * parent_tz;
+            unx -= d_p * parent_tx;
+            uny -= d_p * parent_ty;
+            unz -= d_p * parent_tz;
+            const nl = Math.sqrt(unx * unx + uny * uny + unz * unz) || 1.0;
+            unx /= nl;
+            uny /= nl;
+            unz /= nl;
+        }
+    }
+
+    // Lateral binormal w_hat = parent_T x u_hat
+    const wnx = parent_ty * unz - parent_tz * uny;
+    const wny = parent_tz * unx - parent_tx * unz;
+    const wnz = parent_tx * uny - parent_ty * unx;
+
+    const q_u = qx * unx + qy * uny + qz * unz;
+    const q_w = qx * wnx + qy * wny + qz * wnz;
+
+    const z_bound_min = Math.max(z_min, -0.95 * parent_radius);
+    const z_bound_max = Math.min(z_max, 0.95 * parent_radius);
+    const z_proj = z_bound_min <= z_bound_max
+        ? clamp(z_0, z_bound_min, z_bound_max)
+        : clamp(z_0, z_min, z_max);
+
+    // Evaluate tapered parent radius and inscribed seat radius at z_proj
+    const r_parent_at_z = Math.max(0.25 * parent_radius, parent_radius + z_proj * parent_taper_slope);
+    const r_seat = r_parent_at_z * seat_ratio;
+
+    const q_w_proj = clamp(q_w, -0.78 * r_seat, 0.78 * r_seat);
+    const q_u_max = Math.sqrt(Math.max(0.0, r_seat * r_seat - q_w_proj * q_w_proj));
+    const s_u = clamp(q_u / Math.max(1e-5, r_parent_at_z), -1.0, 1.0);
+    const q_u_proj = q_u_max * (0.90 + 0.08 * s_u);
+
+    const proj_x = parent_px + z_proj * parent_tx + q_u_proj * unx + q_w_proj * wnx;
+    const proj_y = parent_py + z_proj * parent_ty + q_u_proj * uny + q_w_proj * wny;
+    const proj_z = parent_pz + z_proj * parent_tz + q_u_proj * unz + q_w_proj * wnz;
+
+    const final_x = lerp(ring_x, proj_x, w);
+    const final_y = lerp(ring_y, proj_y, w);
+    const final_z = lerp(ring_z, proj_z, w);
+
+    out_pos[out_pos_offset] = final_x;
+    out_pos[out_pos_offset + 1] = final_y;
+    out_pos[out_pos_offset + 2] = final_z;
+
+    // Compute parent cylinder outward normal at final position
+    const fdx = final_x - parent_px;
+    const fdy = final_y - parent_py;
+    const fdz = final_z - parent_pz;
+    const f_dot = fdx * parent_tx + fdy * parent_ty + fdz * parent_tz;
+    let pnx = fdx - f_dot * parent_tx;
+    let pny = fdy - f_dot * parent_ty;
+    let pnz = fdz - f_dot * parent_tz;
+    const pn_len = Math.sqrt(pnx * pnx + pny * pny + pnz * pnz);
+    if (pn_len > 1e-6) {
+        pnx /= pn_len;
+        pny /= pn_len;
+        pnz /= pn_len;
+    } else {
+        pnx = tube_nx;
+        pny = tube_ny;
+        pnz = tube_nz;
+    }
+
+    const nb = clamp(w * normal_blend, 0.0, 1.0);
+    let nx = lerp(tube_nx, pnx, nb);
+    let ny = lerp(tube_ny, pny, nb);
+    let nz = lerp(tube_nz, pnz, nb);
+    const n_len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (n_len > 1e-8) {
+        nx /= n_len;
+        ny /= n_len;
+        nz /= n_len;
+    } else {
+        nx = tube_nx;
+        ny = tube_ny;
+        nz = tube_nz;
+    }
+
+    out_norm[out_norm_offset] = nx;
+    out_norm[out_norm_offset + 1] = ny;
+    out_norm[out_norm_offset + 2] = nz;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Triangulates the tubular strip between two UV-seam-duplicated cross-sectional rings
+ * (`ring0` with `m0 + 1` vertices and `ring1` with `m1 + 1` vertices, where `m0 >= 3` and `m1 >= 3`)
+ * using an exact integer cross-multiplied zipper (`(j0 + 1) * m1 <= (j1 + 1) * m0`).
+ *
+ * Guarantees:
+ * - Strictly `m0 + m1` triangles emitted.
+ * - Zero index-degenerate triangles (`i0 !== i1 && i1 !== i2 && i2 !== i0`), preventing
+ *   `MeshoptClusterizer` / `meshlet_batch_to_bvh` from stripping triangles.
+ * - Consistent outward CCW winding for right-handed `(T, R, S = T x R)` rings where `theta`
+ *   increases from `0` to `2*PI`.
+ *
+ * @param {Uint32Array|number[]} indices destination index buffer
+ * @param {number} index_cursor starting offset in `indices`
+ * @param {number} ring0_start starting vertex index of ring 0 (size `m0 + 1`)
+ * @param {number} m0 radial segment count of ring 0 (`>= 3`)
+ * @param {number} ring1_start starting vertex index of ring 1 (size `m1 + 1`)
+ * @param {number} m1 radial segment count of ring 1 (`>= 3`)
+ * @returns {number} updated `index_cursor` (`index_cursor + 3 * (m0 + m1)`)
+ */
+export function branch_ring_triangulate(indices: Uint32Array | number[], index_cursor: number, ring0_start: number, m0: number, ring1_start: number, m1: number): number;
+/**
+ * Triangulates a terminal conical apex fan connecting a ring of `m + 1` vertices (`m >= 3`)
+ * to `m` distinct apex vertices (`apex_start .. apex_start + m - 1`), emitting `m` outward-facing
+ * triangles with zero repeated indices.
+ *
+ * @param {Uint32Array|number[]} indices destination index buffer
+ * @param {number} index_cursor starting offset in `indices`
+ * @param {number} ring_start starting vertex index of the last non-zero ring (size `m + 1`)
+ * @param {number} m radial segment count of the ring (`>= 3`)
+ * @param {number} apex_start starting vertex index of the `m` apex vertices
+ * @returns {number} updated `index_cursor` (`index_cursor + 3 * m`)
+ */
+export function branch_apex_triangulate(indices: Uint32Array | number[], index_cursor: number, ring_start: number, m: number, apex_start: number): number;
+//# sourceMappingURL=branch_ring_triangulate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch_ring_triangulate.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/branch_ring_triangulate.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iDARW,WAAW,GAAC,MAAM,EAAE,gBACpB,MAAM,eACN,MAAM,MACN,MAAM,eACN,MAAM,MACN,MAAM,GACJ,MAAM,CA2BlB;AAED;;;;;;;;;;;GAWG;AACH,iDAPW,WAAW,GAAC,MAAM,EAAE,gBACpB,MAAM,cACN,MAAM,KACN,MAAM,cACN,MAAM,GACJ,MAAM,CAYlB"}