@woosh/meep-engine 3.52.0 → 3.54.0

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

@@ -0,0 +1,1049 @@
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { Attribute } from "../../../shade/renderer/geometry/Attribute.js";
+import { Geometry } from "../../../shade/renderer/geometry/Geometry.js";
+import {
+    geometry_obtain_attribute,
+    geometry_obtain_index
+} from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+import { BranchLevelConfig } from "../config/BranchLevelConfig.js";
+import { TreeLODConfig } from "../config/TreeLODConfig.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { evaluate_bark_relief } from "../material/make_bark_material.js";
+import { spine_frame_double_reflection } from "../skeleton/spine_frame_double_reflection.js";
+import { branch_collar_project } from "./branch_collar_project.js";
+import { branch_apex_triangulate, branch_ring_triangulate } from "./branch_ring_triangulate.js";
+import { tree_mesh_apply_canopy_ao } from "./tree_mesh_apply_canopy_ao.js";
+
+const DEFAULT_LEVEL_CONFIG = new BranchLevelConfig();
+
+const SCRATCH_P0 = new Float32Array(3);
+const SCRATCH_P1 = new Float32Array(3);
+const SCRATCH_T0 = new Float32Array(3);
+const SCRATCH_V_TAN = new Float32Array(3);
+const SCRATCH_R0 = new Float32Array(3);
+const SCRATCH_SPINE0 = new Float32Array(3);
+const SCRATCH_SPINE1 = new Float32Array(3);
+const SCRATCH_RMF = new Float64Array(6);
+const SCRATCH_PARENT_P = new Float32Array(3);
+const SCRATCH_PARENT_T = new Float32Array(3);
+const SCRATCH_COLLAR_POS = new Float32Array(3);
+const SCRATCH_COLLAR_NORM = new Float32Array(3);
+const SCRATCH_RELIEF = new Float32Array(4);
+
+/**
+ * Deterministic [0, 1) hash for procedural knot/burl placement on branch `b`.
+ * @param {number} seed
+ * @param {number} b
+ * @param {number} k
+ * @param {number} salt
+ * @returns {number}
+ */
+function knot_rand01(seed, b, k, salt) {
+    let h = (seed ^ Math.imul(b + 1, 0x9E3779B1) ^ Math.imul(k + 1, 0x85EBCA6B) ^ Math.imul(salt, 0xC2B2AE35)) | 0;
+    h = Math.imul(h ^ (h >>> 16), 0x7FEB352D);
+    h = Math.imul(h ^ (h >>> 15), 0x846CA68B);
+    h = (h ^ (h >>> 16)) >>> 0;
+    return h / 4294967296.0;
+}
+
+/**
+ * Helper to obtain a `Uint16Array` attribute on `Geometry` for `StandardAttributes.SkinningJoints`.
+ * @param {Geometry} geometry
+ * @param {number} count vertex count
+ * @returns {Uint16Array}
+ */
+export function geometry_obtain_joints_attribute(geometry, count) {
+    const existing = geometry.getAttribute(StandardAttributes.SkinningJoints);
+    if (existing === undefined) {
+        const attr = Attribute.from(new Uint16Array(count * 4), 4, StandardAttributes.SkinningJoints);
+        geometry.addAttribute(attr);
+        return /** @type {Uint16Array} */ (attr.data);
+    }
+    if (existing.count !== count || !(existing.data instanceof Uint16Array)) {
+        existing.data = new Uint16Array(count * 4);
+        existing.count = count;
+    }
+    existing.needsUpdate = true;
+    return /** @type {Uint16Array} */ (existing.data);
+}
+
+/**
+ * Sweeps the Cubic Hermite branch spines of a `TreeSkeleton` into a single manifold, seamless-UV
+ * bark `Geometry` with root buttress lobes, longitudinal bark flutes, welded lateral branch collars,
+ * canopy ambient occlusion, and 4-joint skeletal wind skinning attributes.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {TreeSpeciesConfig} [config]
+ * @param {TreeLODConfig} [lod_config]
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} [out]
+ * @returns {Geometry}
+ */
+export function tree_mesh_build_bark(
+    skeleton,
+    config = new TreeSpeciesConfig(),
+    lod_config = new TreeLODConfig(),
+    out = new Geometry(),
+    only_rings = false
+) {
+    const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+    const lod_cfg = lod_config && lod_config.isTreeLODConfig ? lod_config : TreeLODConfig.from(lod_config);
+
+    const branch_count = skeleton.branch_count;
+
+    const radial_scale = clamp(lod_cfg.radial_scale ?? 1.0, 0.2, 2.0);
+    const long_scale = clamp(lod_cfg.longitudinal_scale ?? 1.0, 0.2, 4.0);
+    const max_level = lod_cfg.max_branch_level ?? 3;
+    const min_radius = lod_cfg.min_branch_radius ?? 0.0;
+    const texel_density = Math.max(0.1, species.bark_material.texel_density ?? 1.2);
+    const twist_uv = species.bark_material.twist_uv ?? 0.0;
+
+    // Collect retained branches and their resampled longitudinal cross-sectional rings
+    const branch_plans = [];
+    let total_vertices = 0;
+    let total_indices = 0;
+
+    for (let b = 0; b < branch_count; b++) {
+        const level = skeleton.branch_level[b];
+        const base_r = skeleton.branch_base_radius[b];
+        if (level > max_level) continue;
+        if (level > 0 && base_r < min_radius) continue;
+
+        const lvl_cfg = (species.levels && species.levels.length > 0)
+            ? (species.levels[Math.min(level, species.levels.length - 1)] || DEFAULT_LEVEL_CONFIG)
+            : DEFAULT_LEVEL_CONFIG;
+        const m_max = Math.max(3, Math.round(lvl_cfg.radial_segments_max * radial_scale));
+        const m_min = Math.max(3, Math.min(m_max, Math.round(lvl_cfg.radial_segments_min * radial_scale)));
+
+        // Walk the node/segment spine of branch b via `skeleton.graph`
+        const nodes = [];
+        const edges = [];
+        skeleton.collect_branch_chain(b, nodes, edges);
+
+        const E = edges.length;
+        if (E < 1) continue;
+
+        const sample_steps = Math.max(1, Math.round(E * long_scale));
+        const ring_count = sample_steps + 1;
+        const ring_m = new Int32Array(ring_count);
+        let branch_verts = 0;
+        let branch_tris = 0;
+
+        for (let i = 0; i <= sample_steps; i++) {
+            const u_branch = (i / sample_steps) * E;
+            const edge_idx = Math.min(E - 1, Math.floor(u_branch));
+            const local_u = i === sample_steps ? 1.0 : (u_branch - edge_idx);
+
+            const r0 = skeleton.node_read_radius(nodes[edge_idx]);
+            const r1 = skeleton.node_read_radius(nodes[edge_idx + 1]);
+            const r_i = lerp(r0, r1, local_u);
+
+            const ratio = base_r > 1e-5 ? clamp(r_i / base_r, 0.0, 1.0) : 1.0;
+            const m_i = Math.max(3, Math.round(lerp(m_min, m_max, Math.pow(ratio, 0.7))));
+            ring_m[i] = m_i;
+            branch_verts += (m_i + 1);
+            if (i > 0) {
+                branch_tris += (ring_m[i - 1] + m_i);
+            }
+        }
+
+        // Terminal apex cone cap (m_tip vertices, m_tip triangles)
+        const m_tip = ring_m[sample_steps];
+        branch_verts += m_tip;
+        branch_tris += m_tip;
+
+        branch_plans.push({
+            branch_id: b,
+            level,
+            base_r,
+            lvl_cfg,
+            nodes,
+            edges,
+            sample_steps,
+            ring_m
+        });
+
+        total_vertices += branch_verts;
+        total_indices += branch_tris * 3;
+    }
+
+    const is_empty_fallback = branch_plans.length === 0 || total_vertices === 0 || total_indices === 0;
+    if (is_empty_fallback) {
+        if (only_rings) {
+            return /** @type {any} */ (new Map());
+        }
+        total_vertices = 4;
+        total_indices = 6;
+    }
+
+    const positions = geometry_obtain_attribute(out, StandardAttributes.Position, 3, total_vertices);
+    const normals = geometry_obtain_attribute(out, StandardAttributes.Normal, 3, total_vertices);
+    const uv0 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates0, 2, total_vertices);
+    const uv1 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates1, 2, total_vertices);
+    const colors = geometry_obtain_attribute(out, StandardAttributes.Color, 3, total_vertices);
+    const joints = geometry_obtain_joints_attribute(out, total_vertices);
+    const weights = geometry_obtain_attribute(out, StandardAttributes.SkinningWeights, 4, total_vertices);
+    const indices = geometry_obtain_index(out, total_indices);
+
+    if (is_empty_fallback) {
+        // Populate valid non-degenerate fallback quad so ensureTangents() and MeshoptClusterizer always succeed
+        const quad_pos = [
+            -0.02, 0.0, -0.02,
+            0.02, 0.0, -0.02,
+            0.02, 0.04, 0.02,
+            -0.02, 0.04, 0.02
+        ];
+        const quad_uv = [0.0, 0.0, 1.0, 0.0, 1.0, 1.0, 0.0, 1.0];
+        for (let k = 0; k < 4; k++) {
+            positions[k * 3] = quad_pos[k * 3];
+            positions[k * 3 + 1] = quad_pos[k * 3 + 1];
+            positions[k * 3 + 2] = quad_pos[k * 3 + 2];
+            normals[k * 3] = 0.0;
+            normals[k * 3 + 1] = 1.0;
+            normals[k * 3 + 2] = 0.0;
+            uv0[k * 2] = quad_uv[k * 2];
+            uv0[k * 2 + 1] = quad_uv[k * 2 + 1];
+            uv1[k * 2] = 0.0;
+            uv1[k * 2 + 1] = 0.0;
+            colors[k * 3] = 1.0;
+            colors[k * 3 + 1] = 1.0;
+            colors[k * 3 + 2] = 1.0;
+            joints[k * 4] = 0;
+            joints[k * 4 + 1] = 0;
+            joints[k * 4 + 2] = 0;
+            joints[k * 4 + 3] = 0;
+            weights[k * 4] = 1.0;
+            weights[k * 4 + 1] = 0.0;
+            weights[k * 4 + 2] = 0.0;
+            weights[k * 4 + 3] = 0.0;
+        }
+        indices[0] = 0;
+        indices[1] = 1;
+        indices[2] = 2;
+        indices[3] = 0;
+        indices[4] = 2;
+        indices[5] = 3;
+
+        out.name = `${species.name || "tree"}_bark_lod${lod_cfg.level}`;
+        out.ensureBounds();
+        out.ensureTangents();
+        return out;
+    }
+
+    let v_cursor = 0;
+    let i_cursor = 0;
+    const meshed_branch_rings = new Map();
+
+    for (let p_idx = 0; p_idx < branch_plans.length; p_idx++) {
+        const plan = branch_plans[p_idx];
+        const b = plan.branch_id;
+        const level = plan.level;
+        const base_r = plan.base_r;
+        const lvl_cfg = plan.lvl_cfg;
+        const nodes = plan.nodes;
+        const edges = plan.edges;
+        const E = edges.length;
+        const sample_steps = plan.sample_steps;
+        const ring_m = plan.ring_m;
+
+        // Quantized integer circumference wrap count (1 or 2) for seamless bark tiling proportional to stem radius
+        const k_wrap = Math.max(1, Math.min(2, Math.round(PI2 * base_r * texel_density)));
+
+        // Pre-collect child branch attachment collars on this branch `b` (for parent-stem collar bosses & UV grain flow)
+        const child_collars = [];
+        const b_len = Math.max(0.2, skeleton.branch_length[b]);
+        for (let cb = b + 1; cb < branch_count; cb++) {
+            if (skeleton.branch_parent[cb] === b) {
+                const c_root = skeleton.branch_root_vertex[cb];
+                skeleton.node_read_tangent(SCRATCH_V_TAN, 0, c_root);
+                const c_r = skeleton.branch_base_radius[cb];
+                const r_ratio = clamp(c_r / Math.max(1e-4, base_r), 0.15, 0.82);
+                child_collars.push({
+                    t_c: skeleton.branch_parent_attach_t[cb],
+                    tx_c: SCRATCH_V_TAN[0],
+                    ty_c: SCRATCH_V_TAN[1],
+                    tz_c: SCRATCH_V_TAN[2],
+                    r_ratio,
+                    sigma_t: clamp(1.55 * c_r / b_len, 0.035, 0.13),
+                    sigma_theta: clamp(0.60 * r_ratio + 0.22, 0.28, 0.72)
+                });
+            }
+        }
+
+        // Pre-collect deterministic 3D knots / callus eyes / burls along this branch `b`
+        const branch_knots = [];
+        const knot_count = lvl_cfg.knot_count | 0;
+        const knot_str = lvl_cfg.knot_strength ?? 0.0;
+        if (knot_count > 0 && knot_str > 0.0) {
+            const seed_i = species.seed | 0;
+            for (let k = 0; k < knot_count; k++) {
+                const t_k = clamp(0.09 + (k + 0.2 + 0.6 * knot_rand01(seed_i, b, k, 1)) * (0.78 / knot_count), 0.08, 0.88);
+                const theta_k = (k * 2.399963229728653 + knot_rand01(seed_i, b, k, 2) * 1.4) % PI2;
+                const sigma_t = clamp(0.045 + 0.035 * knot_rand01(seed_i, b, k, 3), 0.04, 0.085);
+                const sigma_theta = clamp(0.32 + 0.24 * knot_rand01(seed_i, b, k, 4), 0.30, 0.56);
+                const amp_k = knot_str * (0.80 + 0.55 * knot_rand01(seed_i, b, k, 5));
+                const is_burl = knot_rand01(seed_i, b, k, 6) > 0.45;
+                branch_knots.push({ t_k, theta_k, sigma_t, sigma_theta, amp_k, is_burl });
+            }
+        }
+
+        // Parent branch attachment context from actual meshed parent frustum
+        const parent_b = skeleton.branch_parent[b];
+        const parent_attach_t = skeleton.branch_parent_attach_t[b];
+        const p_rings = parent_b >= 0 ? meshed_branch_rings.get(parent_b) : undefined;
+        const has_meshed_parent = b > 0 && p_rings !== undefined && p_rings.length >= 2;
+
+        let parent_px = 0.0, parent_py = 0.0, parent_pz = 0.0;
+        let parent_tx = 0.0, parent_ty = 1.0, parent_tz = 0.0;
+        let parent_r = base_r * 1.4;
+        let parent_v_attach = 0.02;
+        let parent_taper_slope = 0.0;
+        let parent_m = 8;
+        let parent_flute_amp = 0.0;
+        let parent_z_min = -Infinity;
+        let parent_z_max = Infinity;
+        let shift_x = 0.0, shift_y = 0.0, shift_z = 0.0;
+        let base_j0 = 0, base_j1 = 0, base_j2 = 0, base_j3 = 0;
+        let base_w0 = 1.0, base_w1 = 0.0, base_w2 = 0.0, base_w3 = 0.0;
+        let emerge_tx = 0.0, emerge_ty = 1.0, emerge_tz = 0.0;
+
+        if (has_meshed_parent) {
+            let k_attach = p_rings.length - 2;
+            for (let k = 0; k < p_rings.length - 1; k++) {
+                if (parent_attach_t >= p_rings[k].t_norm - 1e-5 && parent_attach_t <= p_rings[k + 1].t_norm + 1e-5) {
+                    k_attach = k;
+                    break;
+                }
+            }
+            const pr_a = p_rings[k_attach];
+            const pr_b = p_rings[k_attach + 1];
+            const xi = clamp((parent_attach_t - pr_a.t_norm) / Math.max(1e-5, pr_b.t_norm - pr_a.t_norm), 0.0, 1.0);
+
+            parent_px = lerp(pr_a.cx, pr_b.cx, xi);
+            parent_py = lerp(pr_a.cy, pr_b.cy, xi);
+            parent_pz = lerp(pr_a.cz, pr_b.cz, xi);
+
+            const ax = pr_b.cx - pr_a.cx;
+            const ay = pr_b.cy - pr_a.cy;
+            const az = pr_b.cz - pr_a.cz;
+            const parent_seg_len = Math.sqrt(ax * ax + ay * ay + az * az) || 1e-5;
+            parent_tx = ax / parent_seg_len;
+            parent_ty = ay / parent_seg_len;
+            parent_tz = az / parent_seg_len;
+
+            parent_r = lerp(pr_a.r, pr_b.r, xi);
+            parent_v_attach = lerp(pr_a.v_uv ?? 0.25, pr_b.v_uv ?? 0.25, xi);
+            parent_taper_slope = (pr_b.r - pr_a.r) / parent_seg_len;
+            parent_m = Math.min(pr_a.m, pr_b.m);
+            parent_flute_amp = pr_a.flute_amp;
+            parent_z_min = -(xi + 0.25) * parent_seg_len;
+            parent_z_max = (1.0 - xi + 0.25) * parent_seg_len;
+
+            // Translate child spine so its root lies on the exact parent mesh frustum chord
+            skeleton.node_read_position(SCRATCH_P0, 0, nodes[0]);
+            shift_x = parent_px - SCRATCH_P0[0];
+            shift_y = parent_py - SCRATCH_P0[1];
+            shift_z = parent_pz - SCRATCH_P0[2];
+
+            // Compute emergence chord direction from parent_P to child Ring i = 1 spine center
+            const u_step1 = (1 / sample_steps) * E;
+            const edge_idx1 = Math.min(E - 1, Math.floor(u_step1));
+            const local_u1 = 1 === sample_steps ? 1.0 : (u_step1 - edge_idx1);
+            skeleton.evaluate_segment_position(SCRATCH_P1, 0, edges[edge_idx1], local_u1);
+            const p1x = SCRATCH_P1[0] + shift_x;
+            const p1y = SCRATCH_P1[1] + shift_y;
+            const p1z = SCRATCH_P1[2] + shift_z;
+            const emx = p1x - parent_px;
+            const emy = p1y - parent_py;
+            const emz = p1z - parent_pz;
+            const em_len = Math.sqrt(emx * emx + emy * emy + emz * emz);
+            if (em_len > 1e-6) {
+                emerge_tx = emx / em_len;
+                emerge_ty = emy / em_len;
+                emerge_tz = emz / em_len;
+            } else {
+                skeleton.node_read_tangent(SCRATCH_V_TAN, 0, nodes[0]);
+                emerge_tx = SCRATCH_V_TAN[0];
+                emerge_ty = SCRATCH_V_TAN[1];
+                emerge_tz = SCRATCH_V_TAN[2];
+            }
+
+            // Merge parent frustum skinning weights at xi so child Ring i = 0 deforms identically to parent
+            const merged_j = [];
+            const merged_w = [];
+            const accumulate_joint = (j_id, w_val) => {
+                if (w_val <= 1e-7) return;
+                for (let s = 0; s < merged_j.length; s++) {
+                    if (merged_j[s] === j_id) {
+                        merged_w[s] += w_val;
+                        return;
+                    }
+                }
+                merged_j.push(j_id);
+                merged_w.push(w_val);
+            };
+            const w_a = 1.0 - xi;
+            accumulate_joint(pr_a.j0, pr_a.w0 * w_a);
+            accumulate_joint(pr_a.j1, pr_a.w1 * w_a);
+            accumulate_joint(pr_a.j2, pr_a.w2 * w_a);
+            accumulate_joint(pr_a.j3, pr_a.w3 * w_a);
+            accumulate_joint(pr_b.j0, pr_b.w0 * xi);
+            accumulate_joint(pr_b.j1, pr_b.w1 * xi);
+            accumulate_joint(pr_b.j2, pr_b.w2 * xi);
+            accumulate_joint(pr_b.j3, pr_b.w3 * xi);
+
+            // Sort descending by weight and normalize top 4
+            for (let a = 0; a < merged_j.length; a++) {
+                for (let c = a + 1; c < merged_j.length; c++) {
+                    if (merged_w[c] > merged_w[a]) {
+                        const tj = merged_j[a]; merged_j[a] = merged_j[c]; merged_j[c] = tj;
+                        const tw = merged_w[a]; merged_w[a] = merged_w[c]; merged_w[c] = tw;
+                    }
+                }
+            }
+            base_j0 = merged_j[0] ?? 0;
+            base_j1 = merged_j[1] ?? 0;
+            base_j2 = merged_j[2] ?? 0;
+            base_j3 = merged_j[3] ?? 0;
+            base_w0 = merged_w[0] ?? 1.0;
+            base_w1 = merged_w[1] ?? 0.0;
+            base_w2 = merged_w[2] ?? 0.0;
+            base_w3 = merged_w[3] ?? 0.0;
+            const w_sum = base_w0 + base_w1 + base_w2 + base_w3;
+            if (w_sum > 1e-6) {
+                base_w0 /= w_sum;
+                base_w1 /= w_sum;
+                base_w2 /= w_sum;
+                base_w3 /= w_sum;
+            } else {
+                base_w0 = 1.0;
+            }
+        }
+
+        let prev_ring_start = -1;
+        let prev_m = 0;
+        const current_branch_rings = [];
+
+        // Track continuous RMF along the resampled spine rings
+        let prev_px = 0.0, prev_py = 0.0, prev_pz = 0.0;
+        let prev_tx = 0.0, prev_ty = 1.0, prev_tz = 0.0;
+        let cur_rx = 1.0, cur_ry = 0.0, cur_rz = 0.0;
+        let cur_sx = 0.0, cur_sy = 0.0, cur_sz = 1.0;
+
+        // Keep terminal ring state for apex cap
+        let tip_px = 0.0, tip_py = 0.0, tip_pz = 0.0;
+        let tip_tx = 0.0, tip_ty = 1.0, tip_tz = 0.0;
+        let tip_rx = 1.0, tip_ry = 0.0, tip_rz = 0.0;
+        let tip_sx = 0.0, tip_sy = 0.0, tip_sz = 1.0;
+        let tip_r = 0.002;
+        let tip_arc_s = 0.0;
+        let tip_v_uv = 0.90;
+        let tip_wind_sway = 0.0;
+        let tip_wind_phase = 0.0;
+        let tip_j0 = 0, tip_j1 = 0, tip_j2 = 0, tip_j3 = 0;
+        let tip_w0 = 1.0, tip_w1 = 0.0, tip_w2 = 0.0, tip_w3 = 0.0;
+
+        // Continuous ontogenetic V range [v_start, v_end] in [0, 1] from trunk base (old bark) to twig tips (young shoot bark)
+        const num_levels = (species.levels && species.levels.length > 0) ? species.levels.length : 1;
+        let v_start = 0.02;
+        let v_end = num_levels > 2 ? 0.62 : (num_levels === 2 ? 0.80 : 0.90);
+        if (has_meshed_parent) {
+            v_start = parent_v_attach;
+            if (level === 1 && num_levels > 2) {
+                v_end = clamp(lerp(v_start, 0.80, 0.65), v_start + 0.10, 0.84);
+            } else {
+                v_end = clamp(lerp(v_start, 0.95, 0.82), Math.max(0.82, v_start + 0.08), 0.97);
+            }
+        }
+
+        const max_weld_rings = Math.min(lvl_cfg.collar_weld_rings, Math.max(0, sample_steps - 1));
+
+        for (let i = 0; i <= sample_steps; i++) {
+            const m_i = ring_m[i];
+            const ring_start = v_cursor;
+
+            const u_branch = (i / sample_steps) * E;
+            const edge_idx = Math.min(E - 1, Math.floor(u_branch));
+            const local_u = i === sample_steps ? 1.0 : (u_branch - edge_idx);
+            const edge_id = edges[edge_idx];
+            const v0 = nodes[edge_idx];
+            const v1 = nodes[edge_idx + 1];
+
+            skeleton.evaluate_segment_position(SCRATCH_P0, 0, edge_id, local_u);
+            skeleton.evaluate_segment_tangent(SCRATCH_T0, 0, edge_id, local_u);
+
+            const px = SCRATCH_P0[0] + shift_x;
+            const py = SCRATCH_P0[1] + shift_y;
+            const pz = SCRATCH_P0[2] + shift_z;
+            const tx = SCRATCH_T0[0], ty = SCRATCH_T0[1], tz = SCRATCH_T0[2];
+
+            if (i === 0) {
+                skeleton.node_read_tangent(SCRATCH_V_TAN, 0, v0);
+                skeleton.node_read_frame_r(SCRATCH_R0, 0, v0);
+                spine_frame_double_reflection(
+                    SCRATCH_RMF, 0,
+                    px, py, pz,
+                    SCRATCH_V_TAN[0], SCRATCH_V_TAN[1], SCRATCH_V_TAN[2],
+                    SCRATCH_R0[0], SCRATCH_R0[1], SCRATCH_R0[2],
+                    px, py, pz,
+                    tx, ty, tz
+                );
+            } else {
+                spine_frame_double_reflection(
+                    SCRATCH_RMF, 0,
+                    prev_px, prev_py, prev_pz,
+                    prev_tx, prev_ty, prev_tz,
+                    cur_rx, cur_ry, cur_rz,
+                    px, py, pz,
+                    tx, ty, tz
+                );
+            }
+            cur_rx = SCRATCH_RMF[0];
+            cur_ry = SCRATCH_RMF[1];
+            cur_rz = SCRATCH_RMF[2];
+            cur_sx = SCRATCH_RMF[3];
+            cur_sy = SCRATCH_RMF[4];
+            cur_sz = SCRATCH_RMF[5];
+
+            prev_px = px;
+            prev_py = py;
+            prev_pz = pz;
+            prev_tx = tx;
+            prev_ty = ty;
+            prev_tz = tz;
+
+            const rx = cur_rx, ry = cur_ry, rz = cur_rz;
+            const sx = cur_sx, sy = cur_sy, sz = cur_sz;
+
+            const r0 = skeleton.node_read_radius(v0);
+            const r1 = skeleton.node_read_radius(v1);
+            const r_node = lerp(r0, r1, local_u);
+
+            skeleton.node_read_spine_param(SCRATCH_SPINE0, 0, v0);
+            skeleton.node_read_spine_param(SCRATCH_SPINE1, 0, v1);
+            const t_norm = lerp(SCRATCH_SPINE0[0], SCRATCH_SPINE1[0], local_u);
+            const arc_s = lerp(SCRATCH_SPINE0[1], SCRATCH_SPINE1[1], local_u);
+            const phase_hash = skeleton.branch_phase_hash[b];
+
+            // Skinning joint indices & weights at this ring (causal upstream-only + <= 4 joints per frustum slice)
+            let ring_j0 = 0, ring_j1 = 0, ring_j2 = 0, ring_j3 = 0;
+            let ring_w0 = 1.0, ring_w1 = 0.0, ring_w2 = 0.0, ring_w3 = 0.0;
+            if (has_meshed_parent) {
+                const parent_attach_v = skeleton.node_parent_vertex(nodes[0]);
+                const ancestor_j = parent_attach_v >= 0 ? skeleton.node_read_joint(parent_attach_v, 0) : 0;
+                const j_branch_root = skeleton.node_read_joint(nodes[0], 0);
+                const j_v0 = skeleton.node_read_joint(v0, 0);
+                if (i === 0 || j_v0 === ancestor_j) {
+                    ring_j0 = base_j0;
+                    ring_j1 = base_j1;
+                    ring_j2 = base_j2;
+                    ring_j3 = base_j3;
+                    ring_w0 = base_w0;
+                    ring_w1 = base_w1;
+                    ring_w2 = base_w2;
+                    ring_w3 = base_w3;
+                } else if (j_v0 === j_branch_root) {
+                    const w_own = clamp(0.85 * t_norm, 0.0, 0.90);
+                    const w_base = 1.0 - w_own;
+                    ring_j0 = j_v0;
+                    ring_j1 = base_j0;
+                    ring_j2 = base_j1;
+                    ring_j3 = 0;
+                    ring_w0 = w_own;
+                    ring_w1 = w_base * base_w0;
+                    ring_w2 = w_base * base_w1;
+                    ring_w3 = 0.0;
+                    const rw_sum = ring_w0 + ring_w1 + ring_w2;
+                    if (rw_sum > 1e-6) {
+                        ring_w0 /= rw_sum;
+                        ring_w1 /= rw_sum;
+                        ring_w2 /= rw_sum;
+                    }
+                } else {
+                    const w_own = clamp(0.50 + 0.45 * t_norm, 0.0, 0.95);
+                    ring_j0 = j_v0;
+                    ring_j1 = j_branch_root;
+                    ring_j2 = 0;
+                    ring_j3 = 0;
+                    ring_w0 = w_own;
+                    ring_w1 = 1.0 - w_own;
+                    ring_w2 = 0.0;
+                    ring_w3 = 0.0;
+                }
+            } else {
+                const j_primary = skeleton.node_read_joint(v0, 0);
+                const j_parent = skeleton.node_read_joint(v0, 1);
+                const w_primary = (v0 === 0 || j_primary === j_parent) ? 1.0 : clamp(0.25 + 0.75 * t_norm, 0.0, 1.0);
+                ring_j0 = j_primary;
+                ring_j1 = j_parent;
+                ring_w0 = w_primary;
+                ring_w1 = 1.0 - w_primary;
+            }
+
+            // Collar weld factor: i === 0 of every child branch is always seated into its meshed parent frustum
+            let weld_factor = 0.0;
+            if (has_meshed_parent) {
+                if (i === 0) {
+                    weld_factor = 1.0;
+                } else if (i <= max_weld_rings && i < sample_steps && t_norm < 0.65) {
+                    const u_collar = 1.0 - i / (max_weld_rings + 1);
+                    weld_factor = u_collar * u_collar;
+                }
+            }
+
+            // Root flare factor on trunk/basal branches
+            const has_flare = lvl_cfg.flare_amplitude > 0.0 && t_norm < lvl_cfg.flare_height_ratio;
+            let flare_env = 0.0;
+            if (has_flare) {
+                const u_f = 1.0 - t_norm / Math.max(1e-4, lvl_cfg.flare_height_ratio);
+                flare_env = lvl_cfg.flare_amplitude * u_f * u_f;
+            }
+
+            const unwelded = 1.0 - weld_factor;
+            const v_base = clamp(lerp(v_start, v_end, Math.pow(t_norm, 0.88)), 0.01, 0.98);
+            // Smooth terminal shoot rounding over t_norm in (0.88, 1.0] so young apical tips terminate as circular shoots without pleated flutes
+            const tip_roundness = i === sample_steps ? 0.0 : clamp((1.0 - t_norm) / 0.12, 0.0, 1.0);
+            const ontogenetic_maturity = (level >= 2 ? clamp(1.0 - 0.72 * ((v_base - 0.55) / 0.45), 0.22, 1.0) : 1.0) * tip_roundness;
+            const flute_env = lvl_cfg.flute_amplitude * unwelded * ontogenetic_maturity;
+            const has_flute = flute_env > 1e-5;
+            const horiz_sin = Math.sqrt(Math.max(0.0, 1.0 - ty * ty));
+            const oval_ecc = (lvl_cfg.oval_eccentricity ?? 0.0) * unwelded * horiz_sin * tip_roundness;
+            const bark_disp = (lvl_cfg.bark_displacement ?? 0.0) * unwelded * ontogenetic_maturity;
+            const parent_collar_amp = (lvl_cfg.parent_collar_bulge ?? 0.0) * unwelded * tip_roundness;
+
+            const wind_sway = clamp((level + t_norm) * 0.25, 0.0, 1.0);
+            const wind_phase = clamp(phase_hash, 0.0, 1.0);
+            const collar_ao = 1.0 - 0.16 * weld_factor;
+
+            for (let j = 0; j <= m_i; j++) {
+                // Ensure exact periodic closure between j=0 and j=m_i
+                const j_wrapped = j === m_i ? 0 : j;
+                const theta = (j_wrapped / m_i) * PI2;
+                const cos_t = Math.cos(theta);
+                const sin_t = Math.sin(theta);
+
+                // Outward radial unit vector in cross-section plane
+                const n_rad_x = cos_t * rx + sin_t * sx;
+                const n_rad_y = cos_t * ry + cos_t * 0.0 + sin_t * sy;
+                const n_rad_z = cos_t * rz + sin_t * sz;
+
+                // Circumferential tangent unit vector (-sin_t R + cos_t S)
+                const tan_theta_x = -sin_t * rx + cos_t * sx;
+                const tan_theta_y = -sin_t * ry + cos_t * sy;
+                const tan_theta_z = -sin_t * rz + cos_t * sz;
+
+                // Evaluate lobe/flute/oval/collar/knot/bark radius multiplier & UV grain streamline warp
+                let r_mult = 1.0;
+                let d_rmult_dtheta = 0.0;
+                let u_warp = 0.0;
+                let vert_ao = collar_ao;
+                let d_tan = 0.0;
+
+                // 1. Phase-locked root buttress lobes flowing continuously into twisting trunk flutes
+                const theta_flute = theta + 0.32 * arc_s + phase_hash * PI2;
+                if (has_flare) {
+                    const lobe_phase = lvl_cfg.flare_lobes * theta_flute;
+                    const cos_lobe = Math.cos(lobe_phase);
+                    if (cos_lobe > 0.0) {
+                        const p = lvl_cfg.flare_sharpness;
+                        r_mult += flare_env * Math.pow(cos_lobe, p);
+                        d_rmult_dtheta -= flare_env * p * lvl_cfg.flare_lobes * Math.pow(cos_lobe, Math.max(0.0, p - 1.0)) * Math.sin(lobe_phase);
+                    }
+                }
+
+                if (has_flute) {
+                    const f_freq = Math.min(4, Math.max(2, lvl_cfg.flute_frequency | 0));
+                    const flute_phase = f_freq * theta_flute;
+                    const f_val = Math.sin(flute_phase);
+                    const f_der = f_freq * Math.cos(flute_phase);
+                    r_mult += flute_env * f_val;
+                    d_rmult_dtheta += flute_env * f_der * 0.45;
+                }
+
+                // 2. Biomechanical reaction-wood ovalization on inclined/horizontal boughs
+                if (oval_ecc > 1e-4) {
+                    const oval_term = oval_ecc * (1.35 * (2.0 * n_rad_y * n_rad_y - 1.0) - 0.22 * n_rad_y);
+                    r_mult += oval_term;
+                    d_rmult_dtheta += oval_ecc * (5.4 * n_rad_y - 0.22) * tan_theta_y;
+                }
+
+                // 3. Parent-stem branch collar swelling bosses & UV grain streamline deflection around child branches
+                if (parent_collar_amp > 1e-4 && child_collars.length > 0) {
+                    for (let c_idx = 0; c_idx < child_collars.length; c_idx++) {
+                        const cc = child_collars[c_idx];
+                        const dt = t_norm - cc.t_c;
+                        if (Math.abs(dt) < 3.2 * cc.sigma_t) {
+                            const theta_c = Math.atan2(
+                                cc.tx_c * sx + cc.ty_c * sy + cc.tz_c * sz,
+                                cc.tx_c * rx + cc.ty_c * ry + cc.tz_c * rz
+                            );
+                            const dtheta = Math.atan2(Math.sin(theta - theta_c), Math.cos(theta - theta_c));
+                            const sig_t = dt < 0.0 ? cc.sigma_t * 1.25 : cc.sigma_t * 0.90;
+                            const u_t = dt / sig_t;
+                            const u_th = dtheta / cc.sigma_theta;
+                            const dist2 = u_t * u_t + u_th * u_th;
+                            if (dist2 < 9.0) {
+                                const gauss = Math.exp(-0.5 * dist2);
+                                const b_amp = parent_collar_amp * (0.55 + 0.75 * cc.r_ratio);
+                                r_mult += b_amp * gauss;
+                                d_rmult_dtheta += -b_amp * gauss * (u_th / cc.sigma_theta);
+                                const r_uv2 = dist2 + 0.85;
+                                u_warp += 0.008 * unwelded * (u_th / r_uv2) * Math.exp(-0.35 * dist2);
+                            }
+                        }
+                    }
+                }
+
+                // 4. Localized 3D knots, volcanic callus rims, and burls + UV grain streamline deflection
+                if (unwelded * tip_roundness > 0.05 && branch_knots.length > 0) {
+                    for (let k_idx = 0; k_idx < branch_knots.length; k_idx++) {
+                        const kn = branch_knots[k_idx];
+                        const dt = t_norm - kn.t_k;
+                        if (Math.abs(dt) < 3.2 * kn.sigma_t) {
+                            const dtheta = Math.atan2(Math.sin(theta - kn.theta_k), Math.cos(theta - kn.theta_k));
+                            const u_t = dt / kn.sigma_t;
+                            const u_th = dtheta / kn.sigma_theta;
+                            const rho2 = u_t * u_t + u_th * u_th;
+                            if (rho2 < 9.0) {
+                                const k_amp = kn.amp_k * unwelded * tip_roundness;
+                                if (kn.is_burl) {
+                                    const w_k = Math.exp(-0.55 * rho2);
+                                    r_mult += k_amp * w_k;
+                                    d_rmult_dtheta += -k_amp * w_k * 1.1 * (u_th / kn.sigma_theta);
+                                } else {
+                                    const exp_r = Math.exp(-0.85 * rho2);
+                                    const w_rim = (0.30 + 1.90 * rho2) * exp_r;
+                                    const dw_drho2 = (1.90 - 0.85 * (0.30 + 1.90 * rho2)) * exp_r;
+                                    r_mult += k_amp * w_rim;
+                                    d_rmult_dtheta += k_amp * dw_drho2 * (2.0 * u_th / kn.sigma_theta);
+                                    if (rho2 < 0.65) {
+                                        vert_ao *= (0.72 + 0.28 * (rho2 / 0.65));
+                                    }
+                                }
+                                const r_uv2 = rho2 + 0.85;
+                                u_warp += 0.009 * unwelded * (u_th / r_uv2) * Math.exp(-0.35 * rho2);
+                            }
+                        }
+                    }
+                }
+
+                // 5. 3D Geometric Bark Relief & Coupled Tangential Ridge-Pinch
+                const u_periodic = k_wrap * (j_wrapped / m_i) + twist_uv * arc_s;
+                if (bark_disp > 1e-4) {
+                    evaluate_bark_relief(
+                        SCRATCH_RELIEF,
+                        u_periodic + u_warp,
+                        v_base,
+                        species.bark_material,
+                        (species.seed | 0) + b * 19
+                    );
+                    const h_bark = SCRATCH_RELIEF[0];
+                    const dh_du = SCRATCH_RELIEF[1];
+                    u_warp += SCRATCH_RELIEF[2] * unwelded * 0.65;
+
+                    r_mult += bark_disp * (h_bark - 0.50) * 1.35;
+                    d_rmult_dtheta += bark_disp * dh_du * 0.15;
+                }
+                u_warp = clamp(u_warp, -0.015, 0.015);
+
+                if (weld_factor > 0.0) {
+                    if (i === 0) {
+                        // Asymmetric adaxial (upper crotch) / abaxial (lower support) collar spread at base ring
+                        const align_parent = n_rad_x * parent_tx + n_rad_y * parent_ty + n_rad_z * parent_tz;
+                        const spread = align_parent >= 0.0
+                            ? lvl_cfg.collar_spread_upper * align_parent
+                            : lvl_cfg.collar_spread_lower * (-align_parent);
+                        r_mult += weld_factor * (0.15 + spread);
+                    } else {
+                        // Symmetric collar flare on subsequent rings so Ring i >= 1 stays centered on spine
+                        r_mult += weld_factor * 0.18;
+                    }
+                }
+
+                const r_local = r_node * Math.max(0.25, r_mult);
+                let vx = px + r_local * n_rad_x + d_tan * tan_theta_x;
+                let vy = py + r_local * n_rad_y + d_tan * tan_theta_y;
+                let vz = pz + r_local * n_rad_z + d_tan * tan_theta_z;
+
+                // Perturb outward normal gently by low-frequency lobe/knot derivative (fine detail comes from normal map)
+                const slope = clamp(d_rmult_dtheta / Math.max(0.25, r_mult), -0.24, 0.24);
+
+                let vnx = n_rad_x - slope * tan_theta_x;
+                let vny = n_rad_y - slope * tan_theta_y;
+                let vnz = n_rad_z - slope * tan_theta_z;
+                const vn_len = Math.sqrt(vnx * vnx + vny * vny + vnz * vnz);
+                if (vn_len > 1e-8) {
+                    vnx /= vn_len;
+                    vny /= vn_len;
+                    vnz /= vn_len;
+                }
+
+                if (weld_factor > 0.0) {
+                    branch_collar_project(
+                        SCRATCH_COLLAR_POS, 0,
+                        SCRATCH_COLLAR_NORM, 0,
+                        vx, vy, vz,
+                        vnx, vny, vnz,
+                        emerge_tx, emerge_ty, emerge_tz,
+                        parent_px, parent_py, parent_pz,
+                        parent_tx, parent_ty, parent_tz,
+                        parent_r,
+                        weld_factor,
+                        lvl_cfg.collar_normal_blend,
+                        parent_m,
+                        parent_flute_amp,
+                        parent_taper_slope,
+                        parent_z_min,
+                        parent_z_max
+                    );
+                    if (i === 0) {
+                        vx = SCRATCH_COLLAR_POS[0];
+                        vy = SCRATCH_COLLAR_POS[1];
+                        vz = SCRATCH_COLLAR_POS[2];
+                    }
+                    vnx = SCRATCH_COLLAR_NORM[0];
+                    vny = SCRATCH_COLLAR_NORM[1];
+                    vnz = SCRATCH_COLLAR_NORM[2];
+                }
+
+                const v3 = v_cursor * 3;
+                const v2 = v_cursor * 2;
+                const v4 = v_cursor * 4;
+
+                positions[v3] = vx;
+                positions[v3 + 1] = vy;
+                positions[v3 + 2] = vz;
+
+                normals[v3] = vnx;
+                normals[v3 + 1] = vny;
+                normals[v3 + 2] = vnz;
+
+                uv0[v2] = k_wrap * (j / m_i) + twist_uv * arc_s + u_warp;
+                uv0[v2 + 1] = v_base;
+
+                uv1[v2] = wind_sway;
+                uv1[v2 + 1] = wind_phase;
+
+                colors[v3] = vert_ao;
+                colors[v3 + 1] = vert_ao;
+                colors[v3 + 2] = vert_ao;
+
+                joints[v4] = ring_j0;
+                joints[v4 + 1] = ring_j1;
+                joints[v4 + 2] = ring_j2;
+                joints[v4 + 3] = ring_j3;
+
+                weights[v4] = ring_w0;
+                weights[v4 + 1] = ring_w1;
+                weights[v4 + 2] = ring_w2;
+                weights[v4 + 3] = ring_w3;
+
+                v_cursor++;
+            }
+
+            // Recenter non-collar-root rings so their vertex centroid lies on the exact spine point (px, py, pz)
+            // while preserving all asymmetric 3D relief (knots, burls, collar bosses, ovalization, bark plates)
+            if (i > 0 || !has_meshed_parent) {
+                let mean_x = 0.0, mean_y = 0.0, mean_z = 0.0;
+                for (let j = 0; j < m_i; j++) {
+                    const vi3 = (ring_start + j) * 3;
+                    mean_x += positions[vi3];
+                    mean_y += positions[vi3 + 1];
+                    mean_z += positions[vi3 + 2];
+                }
+                mean_x /= m_i;
+                mean_y /= m_i;
+                mean_z /= m_i;
+                const corr_x = px - mean_x;
+                const corr_y = py - mean_y;
+                const corr_z = pz - mean_z;
+                for (let j = 0; j <= m_i; j++) {
+                    const vi3 = (ring_start + j) * 3;
+                    positions[vi3] += corr_x;
+                    positions[vi3 + 1] += corr_y;
+                    positions[vi3 + 2] += corr_z;
+                }
+            }
+
+            // Record emitted ring centroid and skinning state for child branch attachment
+            let r_cx = 0.0, r_cy = 0.0, r_cz = 0.0;
+            for (let j = 0; j < m_i; j++) {
+                const vi3 = (ring_start + j) * 3;
+                r_cx += positions[vi3];
+                r_cy += positions[vi3 + 1];
+                r_cz += positions[vi3 + 2];
+            }
+            r_cx /= m_i;
+            r_cy /= m_i;
+            r_cz /= m_i;
+
+            current_branch_rings.push({
+                cx: r_cx,
+                cy: r_cy,
+                cz: r_cz,
+                r: r_node,
+                m: m_i,
+                t_norm,
+                v_uv: v_base,
+                flute_amp: lvl_cfg.flute_amplitude ?? 0.0,
+                j0: ring_j0,
+                j1: ring_j1,
+                j2: ring_j2,
+                j3: ring_j3,
+                w0: ring_w0,
+                w1: ring_w1,
+                w2: ring_w2,
+                w3: ring_w3
+            });
+
+            if (prev_ring_start >= 0) {
+                i_cursor = branch_ring_triangulate(
+                    indices,
+                    i_cursor,
+                    prev_ring_start,
+                    prev_m,
+                    ring_start,
+                    m_i
+                );
+            }
+
+            prev_ring_start = ring_start;
+            prev_m = m_i;
+
+            if (i === sample_steps) {
+                tip_px = px;
+                tip_py = py;
+                tip_pz = pz;
+                tip_tx = tx;
+                tip_ty = ty;
+                tip_tz = tz;
+                tip_rx = rx;
+                tip_ry = ry;
+                tip_rz = rz;
+                tip_sx = sx;
+                tip_sy = sy;
+                tip_sz = sz;
+                tip_r = r_node;
+                tip_arc_s = arc_s;
+                tip_v_uv = v_base;
+                tip_wind_sway = wind_sway;
+                tip_wind_phase = wind_phase;
+                tip_j0 = ring_j0;
+                tip_j1 = ring_j1;
+                tip_j2 = ring_j2;
+                tip_j3 = ring_j3;
+                tip_w0 = ring_w0;
+                tip_w1 = ring_w1;
+                tip_w2 = ring_w2;
+                tip_w3 = ring_w3;
+            }
+        }
+
+        meshed_branch_rings.set(b, current_branch_rings);
+
+        // Close terminal branch tip with a watertight conical shoot-bud apex cap via branch_apex_triangulate
+        const apex_start = v_cursor;
+        const m_tip = prev_m;
+        const cap_ext = tip_r * 1.15;
+        const cap_arc_s = tip_arc_s + cap_ext;
+
+        for (let j = 0; j < m_tip; j++) {
+            const theta_mid = ((j + 0.5) / m_tip) * PI2;
+            const cos_m = Math.cos(theta_mid);
+            const sin_m = Math.sin(theta_mid);
+
+            const n_rad_x = cos_m * tip_rx + sin_m * tip_sx;
+            const n_rad_y = cos_m * tip_ry + sin_m * tip_sy;
+            const n_rad_z = cos_m * tip_rz + sin_m * tip_sz;
+
+            // Outward-tilted shoot-bud cone normal for smooth shading at the branch tip
+            let anx = 0.62 * tip_tx + 0.78 * n_rad_x;
+            let any = 0.62 * tip_ty + 0.78 * n_rad_y;
+            let anz = 0.62 * tip_tz + 0.78 * n_rad_z;
+            const an_len = Math.sqrt(anx * anx + any * any + anz * anz);
+            if (an_len > 1e-8) {
+                anx /= an_len;
+                any /= an_len;
+                anz /= an_len;
+            }
+
+            const v3 = v_cursor * 3;
+            const v2 = v_cursor * 2;
+            const v4 = v_cursor * 4;
+
+            positions[v3] = tip_px + cap_ext * tip_tx;
+            positions[v3 + 1] = tip_py + cap_ext * tip_ty;
+            positions[v3 + 2] = tip_pz + cap_ext * tip_tz;
+
+            normals[v3] = anx;
+            normals[v3 + 1] = any;
+            normals[v3 + 2] = anz;
+
+            uv0[v2] = k_wrap * ((j + 0.5) / m_tip) + twist_uv * cap_arc_s;
+            uv0[v2 + 1] = clamp(tip_v_uv + 0.01, 0.02, 0.99);
+
+            uv1[v2] = tip_wind_sway;
+            uv1[v2 + 1] = tip_wind_phase;
+
+            colors[v3] = 1.0;
+            colors[v3 + 1] = 1.0;
+            colors[v3 + 2] = 1.0;
+
+            joints[v4] = tip_j0;
+            joints[v4 + 1] = tip_j1;
+            joints[v4 + 2] = tip_j2;
+            joints[v4 + 3] = tip_j3;
+
+            weights[v4] = tip_w0;
+            weights[v4 + 1] = tip_w1;
+            weights[v4 + 2] = tip_w2;
+            weights[v4 + 3] = tip_w3;
+
+            v_cursor++;
+        }
+
+        i_cursor = branch_apex_triangulate(indices, i_cursor, prev_ring_start, m_tip, apex_start);
+    }
+
+    if (only_rings) {
+        return /** @type {any} */ (meshed_branch_rings);
+    }
+
+    // Apply analytic crown ambient occlusion onto bark vertex colors
+    tree_mesh_apply_canopy_ao(out, skeleton.crown_center, skeleton.crown_radii, {
+        ao_core_darkening: (species.foliage.ao_core_darkening ?? 0.35) * 0.65,
+        normal_puffiness: 0.0,
+        preserve_existing_color: true
+    });
+
+    out.name = `${species.name || "tree"}_bark_lod${lod_cfg.level}`;
+    out.ensureBounds();
+    out.ensureTangents();
+
+    return out;
+}
+
+/**
+ * Computes the meshed cross-sectional ring centroids, radii, polygon vertex counts, and 4-slot
+ * skinning weights for every retained branch in `skeleton` using the exact same ring synthesis as
+ * `tree_mesh_build_bark`.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {TreeSpeciesConfig} [config]
+ * @param {TreeLODConfig} [lod_config]
+ * @returns {Map<number, Array<{
+ *   cx: number, cy: number, cz: number,
+ *   r: number, m: number, t_norm: number, flute_amp: number,
+ *   j0: number, j1: number, j2: number, j3: number,
+ *   w0: number, w1: number, w2: number, w3: number
+ * }>>}
+ */
+export function tree_mesh_compute_branch_rings(
+    skeleton,
+    config = new TreeSpeciesConfig(),
+    lod_config = new TreeLODConfig()
+) {
+    return /** @type {any} */ (tree_mesh_build_bark(skeleton, config, lod_config, new Geometry(), true));
+}