@woosh/meep-engine 3.57.0 → 3.58.0

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

@@ -1,3 +1,5 @@
+import { assert } from "../../../core/assert.js";
+import { polyline_simplify_by_error } from "../../../core/geom/polyline/polyline_simplify_by_error.js";
 import { PI2 } from "../../../core/math/PI2.js";
 import { clamp } from "../../../core/math/clamp.js";
 import { lerp } from "../../../core/math/lerp.js";
@@ -41,6 +43,513 @@ const SCRATCH_COLLAR_NORM = new Float32Array(3);
 const SCRATCH_RELIEF = new Float32Array(4);
 const SCRATCH_JOINTS4 = new Int32Array(4);
 const SCRATCH_WEIGHTS4 = new Float64Array(4);
+const SCRATCH_SHAPE = new Float64Array(4);
+const SCRATCH_PLAN_T = new Float64Array(3);
+const SCRATCH_PLAN_MID = new Float64Array(3);
+
+/**
+ * What shapes a bark ring around its spine point, set once per ring and read by {@link bark_ring_shape}.
+ */
+const RING = {
+    // the ring's frame: R and S span its plane
+    rx: 1, ry: 0, rz: 0, sx: 0, sy: 0, sz: 1,
+    t_norm: 0,
+    // phase the buttress lobes and flutes twist by at this arc length
+    theta_offset: 0,
+    flare_env: 0,
+    flute_env: 0,
+    oval_ecc: 0,
+    // collar bosses of the branches it carries, and the callus rims of those it shed, each scaled down by the weld
+    collar_amp: 0,
+    knot_scale: 0,
+    unwelded: 1,
+    /** @type {import("../config/BranchGeneratorConfig.js").BranchGeneratorConfig|null} */
+    lvl_cfg: null,
+    collars: [],
+    knots: []
+};
+
+/**
+ * The collars of the branches `b` carries, where each joins it: a boss on its bark, and the grain flowing round it.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number} b
+ * @param {number} base_r
+ * @returns {Array<{t_c: number, tx_c: number, ty_c: number, tz_c: number, r_ratio: number, sigma_t: number, sigma_theta: number}>}
+ */
+function bark_child_collars(skeleton, b, base_r) {
+    const child_collars = [];
+    const b_len = Math.max(0.2, skeleton.branch_length[b]);
+    for (let cb = b + 1; cb < skeleton.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)
+            });
+        }
+    }
+    return child_collars;
+}
+
+/**
+ * Knots: the healed scars of the branches `b` shed (`TreeSkeleton.add_scar`). Each is the collar the branch had,
+ * outliving it as a callus rim around the eye, sized by the branch when it died.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {number} b
+ * @param {number} base_r
+ * @param {number} collar_bulge
+ * @returns {Array<{t_k: number, tx_k: number, ty_k: number, tz_k: number, sigma_t: number, sigma_theta: number, amp_k: number}>}
+ */
+function bark_branch_knots(skeleton, b, base_r, collar_bulge) {
+    const branch_knots = [];
+    if (!(collar_bulge > 0.0)) {
+        return branch_knots;
+    }
+    const b_len = Math.max(0.2, skeleton.branch_length[b]);
+    for (let k = 0; k < skeleton.scar_count; k++) {
+        if (skeleton.scar_branch[k] !== b) continue;
+        const d = k * 5;
+        const scar_r = skeleton.scar_data[d + 4];
+        if (scar_r <= 0.0) continue;
+        const r_ratio = clamp(scar_r / Math.max(1e-4, base_r), 0.15, 0.82);
+        branch_knots.push({
+            t_k: skeleton.scar_data[d],
+            tx_k: skeleton.scar_data[d + 1],
+            ty_k: skeleton.scar_data[d + 2],
+            tz_k: skeleton.scar_data[d + 3],
+            sigma_t: clamp(1.55 * scar_r / b_len, 0.035, 0.13),
+            sigma_theta: clamp(0.60 * r_ratio + 0.22, 0.28, 0.72),
+            amp_k: collar_bulge * (0.55 + 0.75 * r_ratio)
+        });
+    }
+    return branch_knots;
+}
+
+/**
+ * Fewest sides of a polygon whose chords sag no more than `tolerance` from a circle of radius `r`.
+ * @param {number} r
+ * @param {number} tolerance
+ * @returns {number}
+ */
+function circle_sides(r, tolerance) {
+    if (tolerance >= r) {
+        return 3;
+    }
+    return Math.max(3, Math.ceil(Math.PI / Math.acos(1 - tolerance / r)));
+}
+
+/**
+ * Fewest angles a ring's shape is measured at: the measure is four times finer than the circle needs, and no coarser
+ * than a sixty-fourth of a turn, so that lobes, flutes and bosses between its samples are seen.
+ * @type {number}
+ */
+const BARK_REFERENCE_SIDES = 64;
+
+/**
+ * Fills {@link RING} for the candidate ring `c` of a plan's arrays.
+ */
+function plan_fill_ring(plan, c, lvl_cfg, collars, knots) {
+    const f = plan.frames;
+    RING.rx = f[c * 6];
+    RING.ry = f[c * 6 + 1];
+    RING.rz = f[c * 6 + 2];
+    RING.sx = f[c * 6 + 3];
+    RING.sy = f[c * 6 + 4];
+    RING.sz = f[c * 6 + 5];
+    RING.t_norm = plan.t_norm[c];
+    RING.theta_offset = plan.theta_offset[c];
+    RING.flare_env = plan.flare_env[c];
+    RING.flute_env = plan.flute_env[c];
+    RING.oval_ecc = plan.oval_ecc[c];
+    RING.collar_amp = plan.collar_amp[c];
+    RING.knot_scale = plan.knot_scale[c];
+    RING.unwelded = plan.unwelded[c];
+    RING.lvl_cfg = lvl_cfg;
+    RING.collars = collars;
+    RING.knots = knots;
+}
+
+/**
+ * Point of candidate ring `c` at angle `theta`, into `out` at `o`: its spine point plus its shaped radius along the
+ * ring's radial direction. {@link RING} must hold the ring.
+ */
+function plan_ring_point(out, o, plan, c, theta) {
+    bark_ring_shape(SCRATCH_SHAPE, theta, RING);
+    // the weld's symmetric flare on the rings after the first
+    const r_mult = SCRATCH_SHAPE[0] + (c > 0 ? plan.weld[c] * 0.18 : 0.0);
+    const r = plan.radius[c] * Math.max(0.25, r_mult);
+    const cos_t = Math.cos(theta);
+    const sin_t = Math.sin(theta);
+    out[o] = plan.points[c * 3] + r * (cos_t * RING.rx + sin_t * RING.sx);
+    out[o + 1] = plan.points[c * 3 + 1] + r * (cos_t * RING.ry + sin_t * RING.sy);
+    out[o + 2] = plan.points[c * 3 + 2] + r * (cos_t * RING.rz + sin_t * RING.sz);
+}
+
+/**
+ * Distance from point `p` (at `po`) to the segment `a`-`b` (at `ao`, `bo`), all in flat arrays of xyz.
+ */
+function point_segment_distance(p, po, a, ao, b, bo) {
+    const abx = b[bo] - a[ao], aby = b[bo + 1] - a[ao + 1], abz = b[bo + 2] - a[ao + 2];
+    const apx = p[po] - a[ao], apy = p[po + 1] - a[ao + 1], apz = p[po + 2] - a[ao + 2];
+    const len2 = abx * abx + aby * aby + abz * abz;
+    const t = len2 > 0 ? clamp((apx * abx + apy * aby + apz * abz) / len2, 0, 1) : 0;
+    return Math.hypot(apx - t * abx, apy - t * aby, apz - t * abz);
+}
+
+/**
+ * The rings that draw branch `b`'s kept spine `nodes`/`edges` to within `error` of the surface the mesher draws
+ * (spine, radius, lobes, flutes, ovalization, collar bosses, knots and the collar weld's flare; bark relief is the
+ * normal map's), half of it along the branch and half around each ring:
+ *
+ * - candidate rings stand at every node, every segment's middle, and the centre of every collar and knot on the spine;
+ * - each candidate's shape is measured at {@link BARK_REFERENCE_SIDES} or more angles;
+ * - along the branch, Douglas-Peucker keeps the candidates that the rings either side, blended, would miss by more than
+ *   half the error ({@link polyline_simplify_by_error}); the first `weld_rings` rings of a welded branch stay, as the
+ *   weld fades over them;
+ * - around a kept ring, the fewest sides whose polygon misses none of its measured points by more than half the error.
+ *
+ * @returns {{u: number[], m: number[]}} each ring's place along the spine, in segments from its base, and its sides
+ */
+function bark_plan_rings(skeleton, b, lvl_cfg, nodes, edges, collars, knots, welded, weld_rings, error) {
+    const E = edges.length;
+    const tolerance = 0.5 * error;
+
+    // the wood is drawn as far as it is as thick as the error: to the point of its last segment where it thins to that
+    const r_end0 = skeleton.node_read_radius(nodes[E - 1]);
+    const r_end1 = skeleton.node_read_radius(nodes[E]);
+    const end = 2 * r_end1 >= error ? E : (E - 1) + clamp((r_end0 - 0.5 * error) / Math.max(1e-12, r_end0 - r_end1), 0, 1);
+
+    const t_first = skeleton.node_t_norm(nodes[0]);
+    const t_last = lerp(skeleton.node_t_norm(nodes[E - 1]), skeleton.node_t_norm(nodes[E]), end - (E - 1));
+    const u_of_t = (t) => {
+        for (let k = 0; k < E; k++) {
+            const t0 = skeleton.node_t_norm(nodes[k]);
+            const t1 = skeleton.node_t_norm(nodes[k + 1]);
+            if (t <= t1) {
+                return k + (t1 > t0 ? clamp((t - t0) / (t1 - t0), 0, 1) : 0);
+            }
+        }
+        return end;
+    };
+    const us = [];
+    for (let k = 0; k < E; k++) {
+        if (k < end) us.push(k);
+        if (k + 0.5 < end) us.push(k + 0.5);
+    }
+    us.push(end);
+    for (const cc of collars) {
+        if (cc.t_c > t_first && cc.t_c < t_last) us.push(u_of_t(cc.t_c));
+    }
+    for (const kn of knots) {
+        if (kn.t_k > t_first && kn.t_k < t_last) us.push(u_of_t(kn.t_k));
+    }
+    us.sort((x, y) => x - y);
+    let n = 0;
+    for (let i = 0; i < us.length; i++) {
+        if (n === 0 || us[i] - us[n - 1] > 1e-6) us[n++] = us[i];
+    }
+    us.length = n;
+    const C = n;
+
+    const plan = {
+        points: new Float64Array(C * 3),
+        frames: new Float64Array(C * 6),
+        radius: new Float64Array(C),
+        t_norm: new Float64Array(C),
+        arc: new Float64Array(C),
+        theta_offset: new Float64Array(C),
+        flare_env: new Float64Array(C),
+        flute_env: new Float64Array(C),
+        oval_ecc: new Float64Array(C),
+        collar_amp: new Float64Array(C),
+        knot_scale: new Float64Array(C),
+        unwelded: new Float64Array(C),
+        weld: new Float64Array(C)
+    };
+    const phase_hash = skeleton.branch_phase_hash[b];
+    let r_max = 0;
+    for (let c = 0; c < C; c++) {
+        const u = us[c];
+        const edge_idx = Math.min(E - 1, Math.floor(u));
+        const local_u = u - edge_idx;
+        skeleton.evaluate_segment_position(SCRATCH_P0, 0, edges[edge_idx], local_u);
+        skeleton.evaluate_segment_tangent(SCRATCH_T0, 0, edges[edge_idx], local_u);
+        const px = SCRATCH_P0[0], py = SCRATCH_P0[1], pz = SCRATCH_P0[2];
+        const tx = SCRATCH_T0[0], ty = SCRATCH_T0[1], tz = SCRATCH_T0[2];
+        if (c === 0) {
+            skeleton.node_read_tangent(SCRATCH_V_TAN, 0, nodes[0]);
+            skeleton.node_read_frame_r(SCRATCH_R0, 0, nodes[0]);
+            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 {
+            const p = (c - 1) * 3;
+            const fr = (c - 1) * 6;
+            spine_frame_double_reflection(
+                SCRATCH_RMF, 0,
+                plan.points[p], plan.points[p + 1], plan.points[p + 2],
+                SCRATCH_PLAN_T[0], SCRATCH_PLAN_T[1], SCRATCH_PLAN_T[2],
+                plan.frames[fr], plan.frames[fr + 1], plan.frames[fr + 2],
+                px, py, pz,
+                tx, ty, tz
+            );
+        }
+        SCRATCH_PLAN_T[0] = tx;
+        SCRATCH_PLAN_T[1] = ty;
+        SCRATCH_PLAN_T[2] = tz;
+        plan.points[c * 3] = px;
+        plan.points[c * 3 + 1] = py;
+        plan.points[c * 3 + 2] = pz;
+        for (let k = 0; k < 6; k++) plan.frames[c * 6 + k] = SCRATCH_RMF[k];
+
+        const v0 = nodes[edge_idx];
+        const v1 = nodes[edge_idx + 1];
+        const r = lerp(skeleton.node_read_radius(v0), skeleton.node_read_radius(v1), 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 last = c === C - 1;
+
+        let weld_factor = 0.0;
+        if (welded) {
+            if (c === 0) {
+                weld_factor = 1.0;
+            } else if (u <= weld_rings && !last && t_norm < 0.65) {
+                const u_collar = 1.0 - u / (weld_rings + 1);
+                weld_factor = u_collar * u_collar;
+            }
+        }
+        const unwelded = 1.0 - weld_factor;
+        const tip_roundness = last ? 0.0 : clamp((1.0 - t_norm) / 0.12, 0.0, 1.0);
+        let flare_env = 0.0;
+        if (lvl_cfg.flare_amplitude > 0.0 && t_norm < lvl_cfg.flare_height_ratio) {
+            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 horiz_sin = Math.sqrt(Math.max(0.0, 1.0 - ty * ty));
+
+        plan.radius[c] = r;
+        plan.t_norm[c] = t_norm;
+        plan.arc[c] = arc_s;
+        plan.theta_offset[c] = flare_lobe_phase_offset(arc_s, phase_hash);
+        plan.flare_env[c] = flare_env;
+        // young wood's flutes fade with its bark's age; the plan measures them at their fullest
+        plan.flute_env[c] = lvl_cfg.flute_amplitude * unwelded * tip_roundness;
+        plan.oval_ecc[c] = (lvl_cfg.oval_eccentricity ?? 0.0) * unwelded * horiz_sin * tip_roundness;
+        plan.collar_amp[c] = (lvl_cfg.parent_collar_bulge ?? 0.0) * unwelded * tip_roundness;
+        plan.knot_scale[c] = unwelded * tip_roundness;
+        plan.unwelded[c] = unwelded;
+        plan.weld[c] = weld_factor;
+        r_max = Math.max(r_max, r);
+    }
+
+    // each candidate's shape, measured all round
+    const M = Math.max(BARK_REFERENCE_SIDES, 4 * circle_sides(r_max, tolerance));
+    const measured = new Float64Array(C * M * 3);
+    for (let c = 0; c < C; c++) {
+        plan_fill_ring(plan, c, lvl_cfg, collars, knots);
+        for (let j = 0; j < M; j++) {
+            plan_ring_point(measured, (c * M + j) * 3, plan, c, PI2 * j / M);
+        }
+    }
+
+    // along the branch
+    const keep = new Uint8Array(C);
+    polyline_simplify_by_error(keep, C, tolerance, (a, z, out) => {
+        const span = plan.arc[z] - plan.arc[a];
+        out[0] = a + 1;
+        out[1] = -1;
+        for (let c = a + 1; c < z; c++) {
+            const w = span > 1e-9 ? (plan.arc[c] - plan.arc[a]) / span : (c - a) / (z - a);
+            let worst = 0;
+            for (let j = 0; j < M; j++) {
+                const pa = (a * M + j) * 3, pz = (z * M + j) * 3, pc = (c * M + j) * 3;
+                const dx = measured[pc] - (measured[pa] + w * (measured[pz] - measured[pa]));
+                const dy = measured[pc + 1] - (measured[pa + 1] + w * (measured[pz + 1] - measured[pa + 1]));
+                const dz = measured[pc + 2] - (measured[pa + 2] + w * (measured[pz + 2] - measured[pa + 2]));
+                worst = Math.max(worst, dx * dx + dy * dy + dz * dz);
+            }
+            worst = Math.sqrt(worst);
+            if (worst > out[1]) {
+                out[0] = c;
+                out[1] = worst;
+            }
+        }
+    });
+    if (welded) {
+        for (let c = 1; c < C; c++) {
+            if (us[c] <= weld_rings && us[c] === Math.floor(us[c])) keep[c] = 1;
+        }
+    }
+
+    // around each kept ring
+    const ring_u = [];
+    const ring_m = [];
+    const polygon = new Float64Array((M + 1) * 3);
+    for (let c = 0; c < C; c++) {
+        if (!keep[c]) continue;
+        plan_fill_ring(plan, c, lvl_cfg, collars, knots);
+        let sides = 3;
+        for (; sides < M; sides++) {
+            for (let k = 0; k <= sides; k++) {
+                plan_ring_point(polygon, k * 3, plan, c, PI2 * (k % sides) / sides);
+            }
+            let within = true;
+            for (let j = 0; j < M && within; j++) {
+                const k = Math.floor(j * sides / M);
+                within = point_segment_distance(measured, (c * M + j) * 3, polygon, k * 3, polygon, (k + 1) * 3) <= tolerance;
+            }
+            // a chord strays furthest from the wood at its middle
+            for (let k = 0; k < sides && within; k++) {
+                plan_ring_point(SCRATCH_PLAN_MID, 0, plan, c, PI2 * (k + 0.5) / sides);
+                within = point_segment_distance(SCRATCH_PLAN_MID, 0, polygon, k * 3, polygon, (k + 1) * 3) <= tolerance;
+            }
+            if (within) break;
+        }
+        ring_u.push(us[c]);
+        ring_m.push(sides);
+    }
+    return { u: ring_u, m: ring_m };
+}
+
+/**
+ * The smooth shape of a bark ring at angle `theta` about its spine, from `ring` ({@link RING}): root buttress lobes
+ * flowing into twisting flutes, reaction-wood ovalization on inclined boughs, the collar bosses of the branches it
+ * carries and the callus rims of those it shed. Bark relief and the collar weld are the caller's.
+ *
+ * Writes the radius multiplier, its derivative in `theta`, the UV grain warp and an AO factor into `out`.
+ *
+ * @param {Float64Array} out
+ * @param {number} theta
+ * @param {RING} ring
+ */
+function bark_ring_shape(out, theta, ring) {
+    const lvl_cfg = ring.lvl_cfg;
+    const rx = ring.rx, ry = ring.ry, rz = ring.rz;
+    const sx = ring.sx, sy = ring.sy, sz = ring.sz;
+    const t_norm = ring.t_norm;
+    const unwelded = ring.unwelded;
+    const cos_t = Math.cos(theta);
+    const sin_t = Math.sin(theta);
+    const n_rad_y = cos_t * ry + sin_t * sy;
+    const tan_theta_y = -sin_t * ry + cos_t * sy;
+
+    let r_mult = 1.0;
+    let d_rmult_dtheta = 0.0;
+    let u_warp = 0.0;
+    let vert_ao = 1.0;
+
+    // 1. Phase-locked root buttress lobes flowing continuously into twisting trunk flutes
+    const theta_flute = theta + ring.theta_offset;
+    const flare_env = ring.flare_env;
+    if (flare_env > 0.0) {
+        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);
+        }
+    }
+
+    const flute_env = ring.flute_env;
+    if (flute_env > 1e-5) {
+        const f_freq = Math.min(4, Math.max(2, lvl_cfg.flute_frequency | 0));
+        const flute_phase = f_freq * theta_flute;
+        r_mult += flute_env * Math.sin(flute_phase);
+        d_rmult_dtheta += flute_env * f_freq * Math.cos(flute_phase) * 0.45;
+    }
+
+    // 2. Biomechanical reaction-wood ovalization on inclined/horizontal boughs
+    const oval_ecc = ring.oval_ecc;
+    if (oval_ecc > 1e-4) {
+        r_mult += oval_ecc * (1.35 * (2.0 * n_rad_y * n_rad_y - 1.0) - 0.22 * n_rad_y);
+        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
+    const collars = ring.collars;
+    const parent_collar_amp = ring.collar_amp;
+    if (parent_collar_amp > 1e-4 && collars.length > 0) {
+        for (let c_idx = 0; c_idx < collars.length; c_idx++) {
+            const cc = 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. Branch scars: volcanic callus rims + UV grain streamline deflection
+    const knots = ring.knots;
+    const knot_scale = ring.knot_scale;
+    if (knot_scale > 0.05 && knots.length > 0) {
+        for (let k_idx = 0; k_idx < knots.length; k_idx++) {
+            const kn = knots[k_idx];
+            const dt = t_norm - kn.t_k;
+            if (Math.abs(dt) < 3.2 * kn.sigma_t) {
+                const theta_k = Math.atan2(
+                    kn.tx_k * sx + kn.ty_k * sy + kn.tz_k * sz,
+                    kn.tx_k * rx + kn.ty_k * ry + kn.tz_k * rz
+                );
+                const dtheta = Math.atan2(Math.sin(theta - theta_k), Math.cos(theta - 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 * knot_scale;
+                    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);
+                }
+            }
+        }
+    }
+
+    out[0] = r_mult;
+    out[1] = d_rmult_dtheta;
+    out[2] = u_warp;
+    out[3] = vert_ao;
+}
 
 /**
  * Helper to obtain a `Uint16Array` attribute on `Geometry` for `StandardAttributes.SkinningJoints`.
@@ -86,10 +595,8 @@ export function tree_mesh_build_bark(
 
     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 error = lod_cfg.error;
+    assert.greaterThan(error, 0, 'lod_config.error');
     const texel_density = Math.max(0.1, species.bark_material.texel_density ?? 1.2);
     const twist_uv = species.bark_material.twist_uv ?? 0.0;
 
@@ -114,45 +621,46 @@ export function tree_mesh_build_bark(
     let total_vertices = 0;
     let total_indices = 0;
 
+    // a branch is drawn while its wood is at least as thick as the error, and so is everything it carries
+    const meshed = new Uint8Array(branch_count);
     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 parent = skeleton.branch_parent[b];
+        if (2 * base_r < error) continue;
+        if (parent >= 0 && !meshed[parent]) continue;
 
         const lvl_cfg = species.branches[skeleton.branch_generator[b]];
-        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`
+        // Walk the node/segment spine of branch b via `skeleton.graph`, as far as its wood is as thick as the error
         const nodes = [];
         const edges = [];
         skeleton.collect_branch_chain(b, nodes, edges);
-
-        const E = edges.length;
+        let E = 0;
+        while (E < edges.length && 2 * skeleton.node_read_radius(nodes[E]) >= error) E++;
         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);
+        nodes.length = E + 1;
+        edges.length = E;
+        meshed[b] = 1;
+
+        const child_collars = bark_child_collars(skeleton, b, base_r);
+        const branch_knots = bark_branch_knots(skeleton, b, base_r, lvl_cfg.parent_collar_bulge);
+        // a child of drawn wood is welded into it, and the weld fades over its first rings
+        const welded = b > 0 && parent >= 0;
+        const weld_rings = welded ? Math.min(lvl_cfg.collar_weld_rings, E - 1) : 0;
+        const rings = bark_plan_rings(skeleton, b, lvl_cfg, nodes, edges, child_collars, branch_knots, welded, weld_rings, error);
+
+        const sample_steps = rings.u.length - 1;
+        // the last segment may end part-way, where the wood thins to the error
+        edges.length = Math.max(1, Math.ceil(rings.u[sample_steps] - 1e-9));
+        nodes.length = edges.length + 1;
+        const ring_m = rings.m;
         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);
+            branch_verts += ring_m[i] + 1;
             if (i > 0) {
-                branch_tris += (ring_m[i - 1] + m_i);
+                branch_tris += ring_m[i - 1] + ring_m[i];
             }
         }
 
@@ -169,7 +677,11 @@ export function tree_mesh_build_bark(
             nodes,
             edges,
             sample_steps,
-            ring_m
+            ring_u: rings.u,
+            ring_m,
+            weld_rings,
+            child_collars,
+            branch_knots
         });
 
         total_vertices += branch_verts;
@@ -254,54 +766,14 @@ export function tree_mesh_build_bark(
         const edges = plan.edges;
         const E = edges.length;
         const sample_steps = plan.sample_steps;
+        const ring_u = plan.ring_u;
         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)
-                });
-            }
-        }
-
-        // Knots: the healed scars of the branches this one shed (`TreeSkeleton.add_scar`). Each is the collar the branch
-        // had, outliving it as a callus rim around the eye, sized by the branch when it died
-        const branch_knots = [];
-        const collar_bulge = lvl_cfg.parent_collar_bulge;
-        if (collar_bulge > 0.0) {
-            for (let k = 0; k < skeleton.scar_count; k++) {
-                if (skeleton.scar_branch[k] !== b) continue;
-                const d = k * 5;
-                const scar_r = skeleton.scar_data[d + 4];
-                if (scar_r <= 0.0) continue;
-                const r_ratio = clamp(scar_r / Math.max(1e-4, base_r), 0.15, 0.82);
-                branch_knots.push({
-                    t_k: skeleton.scar_data[d],
-                    tx_k: skeleton.scar_data[d + 1],
-                    ty_k: skeleton.scar_data[d + 2],
-                    tz_k: skeleton.scar_data[d + 3],
-                    sigma_t: clamp(1.55 * scar_r / b_len, 0.035, 0.13),
-                    sigma_theta: clamp(0.60 * r_ratio + 0.22, 0.28, 0.72),
-                    amp_k: collar_bulge * (0.55 + 0.75 * r_ratio)
-                });
-            }
-        }
+        const child_collars = plan.child_collars;
+        const branch_knots = plan.branch_knots;
 
         // Parent branch attachment context from actual meshed parent frustum
         const parent_b = skeleton.branch_parent[b];
@@ -362,9 +834,9 @@ export function tree_mesh_build_bark(
             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 u_step1 = ring_u[1];
             const edge_idx1 = Math.min(E - 1, Math.floor(u_step1));
-            const local_u1 = 1 === sample_steps ? 1.0 : (u_step1 - edge_idx1);
+            const local_u1 = 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;
@@ -432,15 +904,15 @@ export function tree_mesh_build_bark(
             }
         }
 
-        const max_weld_rings = Math.min(lvl_cfg.collar_weld_rings, Math.max(0, sample_steps - 1));
+        const weld_rings = plan.weld_rings;
 
         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 u_branch = ring_u[i];
             const edge_idx = Math.min(E - 1, Math.floor(u_branch));
-            const local_u = i === sample_steps ? 1.0 : (u_branch - edge_idx);
+            const local_u = u_branch - edge_idx;
             const edge_id = edges[edge_idx];
             const v0 = nodes[edge_idx];
             const v1 = nodes[edge_idx + 1];
@@ -561,8 +1033,8 @@ export function tree_mesh_build_bark(
             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);
+                } else if (u_branch <= weld_rings && i < sample_steps && t_norm < 0.65) {
+                    const u_collar = 1.0 - u_branch / (weld_rings + 1);
                     weld_factor = u_collar * u_collar;
                 }
             }
@@ -581,7 +1053,6 @@ export function tree_mesh_build_bark(
             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;
@@ -591,6 +1062,24 @@ export function tree_mesh_build_bark(
             const wind_phase = clamp(phase_hash, 0.0, 1.0);
             const collar_ao = 1.0 - 0.16 * weld_factor;
 
+            RING.rx = rx;
+            RING.ry = ry;
+            RING.rz = rz;
+            RING.sx = sx;
+            RING.sy = sy;
+            RING.sz = sz;
+            RING.t_norm = t_norm;
+            RING.theta_offset = flare_lobe_phase_offset(arc_s, phase_hash);
+            RING.flare_env = flare_env;
+            RING.flute_env = flute_env;
+            RING.oval_ecc = oval_ecc;
+            RING.collar_amp = parent_collar_amp;
+            RING.knot_scale = unwelded * tip_roundness;
+            RING.unwelded = unwelded;
+            RING.lvl_cfg = lvl_cfg;
+            RING.collars = child_collars;
+            RING.knots = branch_knots;
+
             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;
@@ -608,99 +1097,14 @@ export function tree_mesh_build_bark(
                 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;
+                // The ring's smooth shape at theta (lobes, flutes, ovalization, collar bosses, knots), then its bark relief
+                bark_ring_shape(SCRATCH_SHAPE, theta, RING);
+                let r_mult = SCRATCH_SHAPE[0];
+                let d_rmult_dtheta = SCRATCH_SHAPE[1];
+                let u_warp = SCRATCH_SHAPE[2];
+                let vert_ao = collar_ao * SCRATCH_SHAPE[3];
                 let d_tan = 0.0;
 
-                // 1. Phase-locked root buttress lobes flowing continuously into twisting trunk flutes
-                const theta_flute = theta + flare_lobe_phase_offset(arc_s, phase_hash);
-                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. Branch scars: volcanic callus rims + 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 theta_k = Math.atan2(
-                                kn.tx_k * sx + kn.ty_k * sy + kn.tz_k * sz,
-                                kn.tx_k * rx + kn.ty_k * ry + kn.tz_k * rz
-                            );
-                            const dtheta = Math.atan2(Math.sin(theta - theta_k), Math.cos(theta - 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;
-                                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) {
@@ -852,6 +1256,7 @@ export function tree_mesh_build_bark(
             r_cz /= m_i;
 
             current_branch_rings.push({
+                start: ring_start,
                 cx: r_cx,
                 cy: r_cy,
                 cz: r_cz,