@woosh/meep-engine 3.52.0 → 3.53.0

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

@@ -0,0 +1,802 @@
+import { PI2 } from "../../../core/math/PI2.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { 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 { BarkMaterialConfig } from "../config/BarkMaterialConfig.js";
+
+const SCRATCH_WORLEY = new Float32Array(3);
+const SCRATCH_WORLEY2 = new Float32Array(3);
+
+/**
+ * Fast deterministic integer hash in [0, 1).
+ * @param {number} ix
+ * @param {number} iy
+ * @param {number} seed
+ * @returns {number}
+ */
+function cell_hash_01(ix, iy, seed) {
+    let h = (ix * 374761393 + iy * 668265263 + seed * 1442695041) | 0;
+    h = Math.imul(h ^ (h >>> 13), 1274126177);
+    h = (h ^ (h >>> 16)) >>> 0;
+    return h / 4294967296.0;
+}
+
+/**
+ * Evaluates a seamlessly tileable 2D cellular Worley (Voronoi) noise on `[0, 1)^2`
+ * with periodic lattice dimensions `(cells_u, cells_v)`.
+ * Writes `[F1, F2 - F1, cell_id]` into `out`.
+ *
+ * @param {Float32Array|number[]} out
+ * @param {number} u
+ * @param {number} v
+ * @param {number} cells_u
+ * @param {number} cells_v
+ * @param {number} seed
+ */
+function sample_tileable_worley(out, u, v, cells_u, cells_v, seed) {
+    const cu = Math.max(1, cells_u | 0);
+    const cv = Math.max(1, cells_v | 0);
+    const u_wrap = ((u % 1.0) + 1.0) % 1.0;
+    const v_wrap = ((v % 1.0) + 1.0) % 1.0;
+
+    const gx = u_wrap * cu;
+    const gy = v_wrap * cv;
+    const ix0 = Math.floor(gx);
+    const iy0 = Math.floor(gy);
+
+    let d1 = 1e9;
+    let d2 = 1e9;
+    let best_id = 0.0;
+
+    for (let dy = -1; dy <= 1; dy++) {
+        const ny = iy0 + dy;
+        const wy = ((ny % cv) + cv) % cv;
+        for (let dx = -1; dx <= 1; dx++) {
+            const nx = ix0 + dx;
+            const wx = ((nx % cu) + cu) % cu;
+
+            const jx = cell_hash_01(wx, wy, seed);
+            const jy = cell_hash_01(wx, wy, seed ^ 0x6C8E9CF5);
+            const cid = cell_hash_01(wx, wy, seed ^ 0xB5297A4D);
+
+            const px = nx + 0.15 + 0.70 * jx - gx;
+            const py = ny + 0.15 + 0.70 * jy - gy;
+            const dist2 = px * px + py * py;
+
+            if (dist2 < d1) {
+                d2 = d1;
+                d1 = dist2;
+                best_id = cid;
+            } else if (dist2 < d2) {
+                d2 = dist2;
+            }
+        }
+    }
+
+    const f1 = Math.sqrt(d1);
+    const f2 = Math.sqrt(d2);
+    out[0] = f1;
+    out[1] = clamp(f2 - f1, 0.0, 1.0);
+    out[2] = best_id;
+}
+
+/**
+ * Evaluates a seamlessly tileable 2D periodic gradient noise value on `[0, 1)^2`
+ * with integer periods `(freq_u, freq_v)` and zero allocation overhead.
+ *
+ * @param {number} u
+ * @param {number} v
+ * @param {number} freq_u integer circumferential frequency
+ * @param {number} freq_v integer vertical frequency
+ * @param {number} ox seed offset X
+ * @param {number} oy seed offset Y
+ * @param {number} oz seed offset Z
+ * @returns {number} value in [-1, 1]
+ */
+function sample_tileable_bark_noise(u, v, freq_u, freq_v, ox, oy, oz) {
+    const pu = Math.max(1, freq_u | 0);
+    const pv = Math.max(1, freq_v | 0);
+    const seed_mix = ((ox * 73856093) ^ (oy * 19349663) ^ (oz * 83492791)) | 0;
+
+    const u_wrap = ((u % 1.0) + 1.0) % 1.0;
+    const v_wrap = ((v % 1.0) + 1.0) % 1.0;
+    const gx = u_wrap * pu;
+    const gy = v_wrap * pv;
+
+    const ix0 = Math.floor(gx);
+    const iy0 = Math.floor(gy);
+    const fx = gx - ix0;
+    const fy = gy - iy0;
+
+    const x0 = ((ix0 % pu) + pu) % pu;
+    const x1 = (x0 + 1) % pu;
+    const y0 = ((iy0 % pv) + pv) % pv;
+    const y1 = (y0 + 1) % pv;
+
+    const ux = fx * fx * fx * (fx * (fx * 6.0 - 15.0) + 10.0);
+    const uy = fy * fy * fy * (fy * (fy * 6.0 - 15.0) + 10.0);
+
+    const grad_dot = (ix, iy, dx, dy) => {
+        let h = (ix * 374761393 + iy * 668265263 + seed_mix) | 0;
+        h = Math.imul(h ^ (h >>> 13), 1274126177);
+        const g = (h ^ (h >>> 16)) & 7;
+        switch (g) {
+            case 0: return dx + dy;
+            case 1: return -dx + dy;
+            case 2: return dx - dy;
+            case 3: return -dx - dy;
+            case 4: return dx * 1.41421356;
+            case 5: return -dx * 1.41421356;
+            case 6: return dy * 1.41421356;
+            default: return -dy * 1.41421356;
+        }
+    };
+
+    const n00 = grad_dot(x0, y0, fx, fy);
+    const n10 = grad_dot(x1, y0, fx - 1.0, fy);
+    const n01 = grad_dot(x0, y1, fx, fy - 1.0);
+    const n11 = grad_dot(x1, y1, fx - 1.0, fy - 1.0);
+
+    const nx0 = n00 + ux * (n10 - n00);
+    const nx1 = n01 + ux * (n11 - n01);
+    return clamp((nx0 + uy * (nx1 - nx0)) * 0.95, -1.0, 1.0);
+}
+
+/**
+ * Generates deterministic knot/scar centers in the mature trunk zone `v in [0.16, 0.62]`.
+ * Since `V in [0, 1]` spans ~8x more world distance than `U in [0, 1)`, `ry` is ~8x smaller than `rx`
+ * so knots and birch-eye scars appear naturally round/horizontally-ovoid in 3D world space!
+ *
+ * @param {number} seed
+ * @param {number} count
+ * @param {string} bark_type
+ * @returns {Array<{u: number, v: number, rx: number, ry: number, phase: number}>}
+ */
+function build_bark_knot_sites(seed, count, bark_type) {
+    const rng = seededRandom((seed ^ 0x7F4A7C15) | 0);
+    const sites = [];
+    for (let k = 0; k < count; k++) {
+        sites.push({
+            u: ((k + 0.22 + 0.55 * rng()) / Math.max(1, count)) % 1.0,
+            v: 0.18 + (k + 0.18 + 0.60 * rng()) / Math.max(1, count) * 0.44,
+            rx: bark_type === "birch" ? (0.075 + 0.030 * rng()) : (0.055 + 0.025 * rng()),
+            ry: bark_type === "birch" ? (0.008 + 0.004 * rng()) : (0.011 + 0.005 * rng()),
+            phase: rng() * PI2
+        });
+    }
+    return sites;
+}
+
+/**
+ * Evaluates the low-frequency 3D macro-relief heightfield and smooth UV grain flow at `(u, v)`.
+ * Used by `tree_mesh_build_bark` for 3D cross-sectional undulation (strictly band-limited to
+ * low circumferential frequencies `<= 3` so polygon rings never suffer Nyquist aliasing creases!).
+ *
+ * Writes `[height, dh_du, u_flow_warp, knot_mask]` to `out`.
+ *
+ * @param {Float32Array|number[]} out
+ * @param {number} u
+ * @param {number} v
+ * @param {BarkMaterialConfig} cfg
+ * @param {number} [seed=1]
+ */
+export function evaluate_bark_relief(out, u, v, cfg, seed = 1) {
+    const u0 = ((u % 1.0) + 1.0) % 1.0;
+    const v0 = clamp(v, 0.0, 1.0);
+
+    const ox = ((seed * 1664525 + 1013904223) & 0xFFFF) * 0.003 - 98.0;
+    const oy = (((seed ^ 0x5A3C9E17) * 1664525) & 0xFFFF) * 0.003 - 98.0;
+    const oz = (((seed ^ 0x2DDFA232) * 1664525) & 0xFFFF) * 0.003 - 98.0;
+
+    const knot_amt = clamp(cfg.knot_amount ?? 0.55, 0.0, 1.0);
+    const bark_type = (cfg.bark_type || "fissured").toLowerCase();
+
+    // Ontogenetic attenuation: old basal/mid bark has macro-relief, young upper twigs are smooth
+    const young_fade = 1.0 - 0.82 * smoothStep(0.60, 0.84, v0);
+
+    let u_flow = 0.0;
+    let knot_height = 0.0;
+    let knot_mask = 0.0;
+
+    if (knot_amt > 0.0 && young_fade > 0.2) {
+        for (let k = 0; k < 3; k++) {
+            const ku = ((k * 0.37 + 0.19 + ((seed * (k + 3)) & 255) / 255.0 * 0.15) % 1.0);
+            const kv = 0.18 + ((k * 0.31 + 0.11 + ((seed * (k + 7)) & 255) / 255.0 * 0.12) % 0.44);
+            let du = u0 - ku;
+            if (du > 0.5) du -= 1.0;
+            else if (du < -0.5) du += 1.0;
+            const dv = v0 - kv;
+
+            const rx = 0.08;
+            const ry = 0.045;
+            const xk = du / rx;
+            const yk = dv / ry;
+            const rho2 = xk * xk + yk * yk;
+
+            if (rho2 < 5.0) {
+                const exp_w = Math.exp(-0.55 * rho2);
+                u_flow += -du * 0.16 * exp_w * knot_amt * young_fade;
+            }
+            if (rho2 < 3.0) {
+                const rho = Math.sqrt(rho2);
+                const rim = 0.22 * Math.exp(-Math.pow((rho - 0.72) / 0.35, 2.0));
+                const w_k = smoothStep(1.65, 0.25, rho) * knot_amt * young_fade;
+                if (w_k > knot_mask) knot_mask = w_k;
+                knot_height += rim * knot_amt * young_fade;
+            }
+        }
+    }
+
+    // Band-limited (freq_u = 2..3) 3D macro-relief so 12..18-gon rings vary organically along V without Nyquist striping
+    const v_tile = ((v0 * 3.0) % 1.0 + 1.0) % 1.0;
+    const warp_u = clamp(
+        (sample_tileable_bark_noise(u0, v_tile, 2, 5, ox + 11.3, oy + 7.1, oz + 3.7) * 0.009 + u_flow) * young_fade,
+        -0.014,
+        0.014
+    );
+
+    const n_macro1 = sample_tileable_bark_noise(u0, v_tile, 2, 7, ox, oy, oz);
+    const n_macro2 = sample_tileable_bark_noise(u0, v_tile, 3, 12, ox + 37.0, oy + 19.0, oz + 53.0);
+    const amp = bark_type === "birch" ? 0.34 : 0.46;
+    const h = clamp(0.5 + (0.58 * n_macro1 + 0.42 * n_macro2) * amp * young_fade + knot_height, 0.0, 1.0);
+
+    const eps = 0.02;
+    const n_plus = sample_tileable_bark_noise(u0 + eps, v_tile, 2, 6, ox, oy, oz);
+    const dh_du = clamp(((n_plus - n_macro1) / eps) * amp * young_fade, -1.0, 1.0);
+
+    out[0] = h;
+    out[1] = dh_du;
+    out[2] = warp_u;
+    out[3] = knot_mask;
+}
+
+/**
+ * Synthesizes a turn-key procedural PBR `StandardShadeMaterial` for tree bark, including
+ * Albedo (`ColorSpace.SRGB`), 2-channel Tangent-Space Normal (`ColorSpace.LinearSRGB`,
+ * `TextureFilterType.LinearNormal`), and ORM (`R=Occlusion, G=Roughness, B=Metalness=0`) textures.
+ *
+ * The horizontal axis `U in [0, 1)` tiles seamlessly around branch circumferences (`wrapS = Repeat`),
+ * while the vertical axis `V in [0, 1]` (`wrapT = ClampToEdge`) encodes continuous ontogenetic bark
+ * evolution from old ruptured basal trunk bark (`V ~ 0`) through mature trunk/bough bark (`V ~ 0.35`)
+ * to smooth young upper shoot/twig bark (`V ~ 0.9`).
+ *
+ * Because `V in [0, 1]` spans the full ontogenetic height of the tree (~8x longer in world space than
+ * a single circumference wrap `U in [0, 1)`), vertical texture resolution (`height = width * 4`) and
+ * vertical cellular/noise frequencies are scaled by the world-space aspect ratio so bark plates,
+ * fissures, and lenticels have crisp, isotropic world-space proportions without vertical stretching.
+ *
+ * @param {BarkMaterialConfig|Object} [config]
+ * @param {number} [seed=1]
+ * @returns {StandardShadeMaterial}
+ */
+export function make_bark_material(config = new BarkMaterialConfig(), seed = 1) {
+    const cfg = config && config.isBarkMaterialConfig ? config : BarkMaterialConfig.from(config);
+    const width = Math.max(16, cfg.resolution | 0);
+    const v_aspect = width >= 128 ? 4 : 1;
+    const height = width * v_aspect;
+    const rng = seededRandom((seed ^ 0x2DDFA232) | 0);
+
+    const ox = (rng() - 0.5) * 200.0;
+    const oy = (rng() - 0.5) * 200.0;
+    const oz = (rng() - 0.5) * 200.0;
+
+    const albedo_sampler = Sampler2D.uint8(4, width, height);
+    const normal_sampler = Sampler2D.uint8(2, width, height);
+    const orm_sampler = Sampler2D.uint8(4, width, height);
+
+    const albedo_data = albedo_sampler.data;
+    const normal_data = normal_sampler.data;
+    const orm_data = orm_sampler.data;
+
+    const height_field = new Float32Array(width * height);
+    const rough_field = new Float32Array(width * height);
+
+    const freq_u = Math.max(1, cfg.fissure_frequency | 0);
+    const depth = clamp(cfg.fissure_depth, 0.0, 1.0);
+    const lenticel = clamp(cfg.lenticel_amount, 0.0, 1.0);
+    const peel_amt = clamp(cfg.peel_amount ?? 0.35, 0.0, 1.0);
+    const terrace = clamp(cfg.plate_terrace ?? 0.42, 0.0, 1.0);
+    const knot_amt = clamp(cfg.knot_amount ?? 0.55, 0.0, 1.0);
+    const moss_amt = clamp(cfg.moss_amount, 0.0, 1.0);
+    const base_rough = clamp(Math.max(0.86, cfg.roughness), 0.86, 0.98);
+
+    // Determine effective archetype
+    let bark_type = (cfg.bark_type || "fissured").toLowerCase();
+    if (bark_type === "fissured" && lenticel > 0.55 && cfg.primary_color.r > 0.72) {
+        bark_type = "birch";
+    }
+
+    const r1 = cfg.primary_color.r, g1 = cfg.primary_color.g, b1 = cfg.primary_color.b;
+    const r2 = cfg.secondary_color.r, g2 = cfg.secondary_color.g, b2 = cfg.secondary_color.b;
+    const ri = cfg.inner_bark_color?.r ?? 0.34;
+    const gi = cfg.inner_bark_color?.g ?? 0.27;
+    const bi = cfg.inner_bark_color?.b ?? 0.22;
+    const rm = cfg.moss_color.r, gm = cfg.moss_color.g, bm = cfg.moss_color.b;
+
+    const knot_sites = build_bark_knot_sites(seed, bark_type === "birch" ? 6 : 5, bark_type);
+
+    // Pass 1: Synthesize species-specific ontogenetic bark heightfield and albedo
+    for (let y = 0; y < height; y++) {
+        const v = (y + 0.5) / height;
+        // Ontogenetic zone weights along V in [0, 1]:
+        // - basal_w: [0.0, 0.20] (coarse buttress base & ruptured dark birch skirt)
+        // - mature_w: [0.18, 0.65] (characteristic trunk & primary bough bark)
+        // - young_w: [0.72, 1.0] (smooth finely striated young branch & shoot bark)
+        const basal_w = smoothStep(0.22, 0.03, v);
+        const young_w = smoothStep(0.62, 0.80, v);
+        const mature_w = 1.0 - young_w;
+
+        for (let x = 0; x < width; x++) {
+            const u = x / width;
+            const p_idx = y * width + x;
+
+            // 1. World-aspect-corrected knot / branch-collar scar geometry in mature/basal zone
+            let u_flow = 0.0;
+            let knot_h = 0.0;
+            let knot_scar_mask = 0.0;
+            let knot_rim_mask = 0.0;
+
+            if (knot_amt > 0.0 && mature_w > 0.15) {
+                for (let k = 0; k < knot_sites.length; k++) {
+                    const ks = knot_sites[k];
+                    let du = u - ks.u;
+                    if (du > 0.5) du -= 1.0;
+                    else if (du < -0.5) du += 1.0;
+                    const dv = v - ks.v;
+
+                    const xk = du / ks.rx;
+                    const yk = dv / ks.ry;
+                    const rho2 = xk * xk + yk * yk;
+                    if (rho2 >= 5.5) {
+                        continue;
+                    }
+
+                    u_flow += -du * 0.20 * Math.exp(-0.55 * rho2) * knot_amt * mature_w;
+
+                    if (bark_type === "birch") {
+                        // Characteristic dark craggy chevron "Birch Eye" branch-collar scar
+                        const y_chev = yk + 0.45 * Math.pow(Math.abs(xk), 1.15);
+                        const chev_ridge = Math.exp(-3.4 * y_chev * y_chev) * Math.exp(-1.10 * xk * xk);
+                        const eye_pit = Math.exp(-2.6 * (xk * xk * 0.9 + (yk + 0.35) * (yk + 0.35) * 1.5));
+                        const crag = sample_tileable_bark_noise(u, v, 10, 80, ox + 91.0, oy + 43.0, oz + 17.0);
+                        const scar_val = clamp((chev_ridge * 0.80 + eye_pit * 0.90) * (0.85 + 0.25 * crag) * knot_amt * mature_w, 0.0, 1.0);
+                        if (scar_val > knot_scar_mask) knot_scar_mask = scar_val;
+                        knot_h += (0.04 * chev_ridge - 0.12 * eye_pit) * knot_amt * mature_w;
+                    } else if (rho2 < 3.2) {
+                        const rho = Math.sqrt(rho2);
+                        const pit = rho < 0.55 ? -0.26 * Math.pow(Math.cos((rho / 0.55) * Math.PI * 0.5), 1.8) : 0.0;
+                        const rim = 0.22 * Math.exp(-Math.pow((rho - 0.76) / 0.30, 2.0));
+                        knot_h += (pit + rim) * knot_amt * mature_w;
+                        if (rho < 0.60) {
+                            knot_scar_mask = Math.max(knot_scar_mask, smoothStep(0.60, 0.18, rho) * knot_amt * mature_w);
+                        }
+                        knot_rim_mask = Math.max(knot_rim_mask, rim * knot_amt * mature_w);
+                    }
+                }
+            }
+
+            let h = 0.5;
+            let cr = r1, cg = g1, cb = b1;
+            let rough = base_rough;
+
+            if (bark_type === "birch") {
+                // --- ARCHETYPE 2: SILVER / PAPER BIRCH (WORLD-ASPECT CALIBRATED) ---
+                const n_low = sample_tileable_bark_noise(u, v, 2, 16, ox, oy, oz);
+                const n_med = sample_tileable_bark_noise(u, v, 4, 64, ox + 37.0, oy + 19.0, oz + 53.0);
+                const n_high = sample_tileable_bark_noise(u, v, 8, 160, ox + 73.0, oy + 41.0, oz + 89.0);
+                const n_sheet = sample_tileable_bark_noise(u, v, 1, 96, ox + 15.0, oy + 67.0, oz + 31.0);
+
+                // 1) Jagged basal rupture zone (v in [0, 0.17]): dark charcoal deeply fissured basal skirt
+                const basal_warp = sample_tileable_bark_noise(u, v, 4, 24, ox + 51.0, oy + 13.0, oz + 77.0) * 0.04;
+                const fissure_wave = Math.pow(Math.abs(Math.sin((u + basal_warp) * Math.PI * (freq_u * 2))), 0.65);
+                const basal_crag_v = sample_tileable_bark_noise(u, v, freq_u * 2, 48, ox + 88.0, oy + 31.0, oz + 19.0);
+                const basal_cutoff = 0.15 + 0.04 * n_low + 0.045 * (1.0 - fissure_wave);
+                const birch_basal_mask = smoothStep(basal_cutoff + 0.035, basal_cutoff - 0.025, v);
+
+                // 2) Young shoot zone (v in [0.68, 1.0]): smooth warm bronze/copper-brown young birch bark
+                const young_cutoff = 0.70 + 0.025 * n_low;
+                const birch_young_mask = smoothStep(young_cutoff - 0.05, young_cutoff + 0.05, v);
+
+                // 3) Mature chalk-white periderm with crisp horizontal paper striations & lenticel dashes
+                const horiz_band = 0.5 + 0.5 * Math.sin(v * PI2 * 140.0 + n_low * 1.1 + n_sheet * 0.8);
+                const fine_horiz = 0.5 + 0.5 * Math.sin(v * PI2 * 280.0 + n_med * 0.7);
+
+                // Crisp thin horizontal lenticel dashes (3x220 and 6x360 cells so dashes are thin in world Y!)
+                sample_tileable_worley(SCRATCH_WORLEY, u + n_low * 0.012, v, 3, 220, seed ^ 0x13579BDF);
+                sample_tileable_worley(SCRATCH_WORLEY2, u + n_med * 0.008, v, 6, 360, seed ^ 0x2468ACE0);
+                const lent_dash1 = smoothStep(0.28, 0.07, SCRATCH_WORLEY[0]) * (SCRATCH_WORLEY[2] < lenticel * 0.55 ? 1.0 : 0.0);
+                const lent_dash2 = smoothStep(0.25, 0.06, SCRATCH_WORLEY2[0]) * (SCRATCH_WORLEY2[2] < lenticel * 0.65 ? 1.0 : 0.0);
+                const lent_line = Math.pow(Math.max(0.0, Math.sin(v * PI2 * 180.0 + n_low * 1.4)), 7.0)
+                    * smoothStep(0.30, 0.75, n_med * 0.5 + 0.5);
+                const lent_mask = clamp(
+                    Math.max(lent_dash1 * 0.85, Math.max(lent_dash2 * 0.70, lent_line * 0.60)) * lenticel,
+                    0.0,
+                    1.0
+                );
+
+                // Sparse horizontal warm-cinnamon exfoliating paper strips
+                const peel_wave = sample_tileable_bark_noise(u, v, 1, 56, ox + 129.0, oy + 59.0, oz + 103.0) * 0.70
+                    + sample_tileable_bark_noise(u, v, 3, 112, ox + 17.0, oy + 83.0, oz + 47.0) * 0.30;
+                const peel_thresh = 0.45 - peel_amt * 0.26;
+                const peel_inner_mask = (peel_amt > 0.02 && peel_wave > peel_thresh && knot_scar_mask < 0.3)
+                    ? clamp((peel_wave - peel_thresh) * 5.5, 0.0, 0.72) * (1.0 - birch_basal_mask) * (1.0 - birch_young_mask)
+                    : 0.0;
+
+                const h_mature = 0.72
+                    + 0.042 * horiz_band
+                    + 0.024 * fine_horiz
+                    + 0.020 * n_med
+                    - 0.080 * lent_mask
+                    - 0.060 * peel_inner_mask
+                    + knot_h;
+
+                const h_basal = 0.14 + 0.46 * fissure_wave + 0.14 * basal_crag_v;
+                const h_young = 0.68 + 0.015 * horiz_band + 0.010 * n_high - 0.022 * lent_dash2;
+
+                h = lerp(h_mature, h_basal, birch_basal_mask);
+                h = clamp(lerp(h, h_young, birch_young_mask), 0.0, 1.0);
+
+                // Mature chalk-white periderm color
+                const paper_shade = 0.90 + 0.07 * horiz_band + 0.05 * fine_horiz - 0.04 * (n_low * 0.5 + 0.5);
+                cr = clamp(r1 * paper_shade, 0.0, 1.0);
+                cg = clamp(g1 * paper_shade, 0.0, 1.0);
+                cb = clamp(b1 * paper_shade, 0.0, 1.0);
+
+                if (peel_inner_mask > 0.0) {
+                    const inner_var = 0.92 + 0.14 * horiz_band;
+                    cr = lerp(cr, ri * inner_var, peel_inner_mask);
+                    cg = lerp(cg, gi * inner_var, peel_inner_mask);
+                    cb = lerp(cb, bi * inner_var, peel_inner_mask);
+                }
+
+                if (lent_mask > 0.0) {
+                    const lm = lent_mask * 0.80 * (1.0 - birch_young_mask * 0.6);
+                    cr = lerp(cr, r2 * 1.20, lm);
+                    cg = lerp(cg, g2 * 1.15, lm);
+                    cb = lerp(cb, b2 * 1.10, lm);
+                }
+
+                if (knot_scar_mask > 0.0) {
+                    cr = lerp(cr, r2 * 0.68, knot_scar_mask);
+                    cg = lerp(cg, g2 * 0.68, knot_scar_mask);
+                    cb = lerp(cb, b2 * 0.68, knot_scar_mask);
+                }
+
+                if (birch_basal_mask > 0.0) {
+                    const b_shade = 0.52 + 0.72 * fissure_wave + 0.18 * basal_crag_v;
+                    const br = clamp(r2 * 1.35 * b_shade, 0.06, 0.40);
+                    const bg = clamp(g2 * 1.32 * b_shade, 0.06, 0.38);
+                    const bb = clamp(b2 * 1.28 * b_shade, 0.06, 0.36);
+                    cr = lerp(cr, br, birch_basal_mask);
+                    cg = lerp(cg, bg, birch_basal_mask);
+                    cb = lerp(cb, bb, birch_basal_mask);
+                }
+
+                if (birch_young_mask > 0.0) {
+                    const y_shade = 0.90 + 0.14 * horiz_band + 0.06 * n_med;
+                    let yr = clamp(ri * 0.92 * y_shade, 0.18, 0.62);
+                    let yg = clamp(gi * 0.88 * y_shade, 0.12, 0.46);
+                    let yb = clamp(bi * 0.82 * y_shade, 0.08, 0.34);
+                    const speck = lent_dash2 * 0.45;
+                    yr = lerp(yr, 0.68, speck);
+                    yg = lerp(yg, 0.60, speck);
+                    yb = lerp(yb, 0.50, speck);
+
+                    cr = lerp(cr, yr, birch_young_mask);
+                    cg = lerp(cg, yg, birch_young_mask);
+                    cb = lerp(cb, yb, birch_young_mask);
+                }
+
+                rough = clamp(base_rough + 0.05 * birch_basal_mask - 0.02 * birch_young_mask, 0.85, 0.97);
+            } else if (bark_type === "plated") {
+                // --- ARCHETYPE 3: RAGGED FLAKY CONIFER SCALE BARK (PINE / SPRUCE, WORLD-ASPECT CALIBRATED) ---
+                const warp_u = (
+                    sample_tileable_bark_noise(u, v, 3, 20, ox + 11.3, oy + 7.1, oz + 3.7) * 0.042
+                    + sample_tileable_bark_noise(u, v, freq_u * 2, 56, ox + 61.0, oy + 23.0, oz + 89.0) * 0.028
+                    + u_flow
+                );
+                const warp_v = (
+                    sample_tileable_bark_noise(u, v, 3, 18, ox + 29.1, oy + 13.7, oz + 61.9) * 0.008
+                    + sample_tileable_bark_noise(u, v, freq_u * 2, 48, ox + 43.0, oy + 79.0, oz + 17.0) * 0.005
+                );
+                const uw = ((u + warp_u) % 1.0 + 1.0) % 1.0;
+                const vw = ((v + warp_v) % 1.0 + 1.0) % 1.0;
+
+                // World-aspect-calibrated scale lattice: 6x28 primary scales + 12x56 secondary scales
+                const cells_v = Math.max(12, Math.round(freq_u * 4.5));
+                sample_tileable_worley(SCRATCH_WORLEY, uw, vw, freq_u, cells_v, seed);
+                sample_tileable_worley(SCRATCH_WORLEY2, uw, vw, freq_u * 2, cells_v * 2, seed ^ 0x9E3779B9);
+
+                const df1 = SCRATCH_WORLEY[1];
+                const cid1 = SCRATCH_WORLEY[2];
+                const df2 = SCRATCH_WORLEY2[1];
+                const cid2 = SCRATCH_WORLEY2[2];
+
+                const fiber_n = sample_tileable_bark_noise(u, v, freq_u * 3, 64, ox + 53.0, oy + 97.0, oz + 23.0);
+                const fine_striation = sample_tileable_bark_noise(u, v, freq_u * 4, 48, ox + 19.0, oy + 71.0, oz + 41.0);
+
+                // Ragged scale edges + exfoliating stepped terraces
+                const jag_df1 = df1 + fiber_n * 0.065;
+                const plate_edge = smoothStep(0.02, 0.22, jag_df1) * smoothStep(0.01, 0.11, df2 + fiber_n * 0.04 + 0.03);
+                const contour_raw = clamp(jag_df1 * 1.55 + fiber_n * 0.08, 0.0, 0.999);
+                const contour_step = Math.floor(contour_raw * 4.0) / 4.0;
+                const contour_fract = (contour_raw * 4.0) - Math.floor(contour_raw * 4.0);
+                const step_lip = smoothStep(0.18, 0.02, contour_fract) * plate_edge;
+
+                const h_mature = clamp(
+                    plate_edge * (0.46 + 0.24 * cid1 + 0.20 * lerp(contour_raw, contour_step, terrace) + 0.06 * cid2)
+                    + fiber_n * 0.06
+                    - basal_w * (1.0 - plate_edge) * 0.16
+                    + knot_h,
+                    0.0,
+                    1.0
+                );
+
+                // Young conifer shoot bark (v > 0.72): finely striated, low-relief reddish-grey shoot bark
+                const h_young = 0.56 + 0.038 * fine_striation + 0.025 * fiber_n;
+                h = clamp(lerp(h_mature, h_young, young_w), 0.0, 1.0);
+
+                const crevice_mix = smoothStep(0.04, 0.36, plate_edge) * (1.0 - 0.70 * knot_scar_mask);
+                const plate_tint = 0.88 + 0.20 * cid1 + 0.07 * step_lip + 0.05 * fiber_n;
+                const pr_col = lerp(r1, ri, 0.28) * plate_tint;
+                const pg_col = lerp(g1, gi, 0.28) * plate_tint;
+                const pb_col = lerp(b1, bi, 0.28) * plate_tint;
+
+                const mr = lerp(r2 * 0.75, pr_col, crevice_mix);
+                const mg = lerp(g2 * 0.75, pg_col, crevice_mix);
+                const mb = lerp(b2 * 0.75, pb_col, crevice_mix);
+
+                const y_tint = 0.94 + 0.07 * fine_striation + 0.04 * fiber_n;
+                const yr = lerp(r1, r2, 0.25) * y_tint;
+                const yg = lerp(g1, g2, 0.25) * y_tint;
+                const yb = lerp(b1, b2, 0.25) * y_tint;
+
+                cr = lerp(mr, yr, young_w);
+                cg = lerp(mg, yg, young_w);
+                cb = lerp(mb, yb, young_w);
+                rough = clamp(lerp(0.95, base_rough, crevice_mix) * (1.0 - 0.03 * young_w), 0.86, 0.98);
+            } else if (bark_type === "ringed") {
+                // --- ARCHETYPE 4: RINGED / FIBROUS TRUNK BARK (PALM / SHRUB / FERN) ---
+                const n1 = sample_tileable_bark_noise(u, v, 2, 24, ox, oy, oz);
+                const n2 = sample_tileable_bark_noise(u, v, 12, 48, ox + 41.0, oy + 29.0, oz + 73.0);
+                const ring_wave = Math.pow(Math.abs(Math.sin(v * Math.PI * 56.0 + 0.25 * Math.sin(u * PI2 * 5.0) + n1 * 0.50)), 0.60);
+                const fiber_weave = 0.5 + 0.25 * Math.sin((u * 18.0 + v * 24.0) * PI2 + n2) + 0.25 * Math.sin((u * 18.0 - v * 24.0) * PI2 - n2);
+
+                const h_mature = clamp(0.65 * ring_wave + 0.25 * fiber_weave + 0.10 * n2 + knot_h, 0.0, 1.0);
+                const h_young = 0.58 + 0.08 * ring_wave + 0.06 * fiber_weave;
+                h = clamp(lerp(h_mature, h_young, young_w), 0.0, 1.0);
+
+                const mix_col = clamp(lerp(1.0 - depth * (1.0 - 0.65 * young_w), 1.0, h), 0.0, 1.0);
+                cr = lerp(r2, r1, mix_col);
+                cg = lerp(g2, g1, mix_col);
+                cb = lerp(b2, b1, mix_col);
+                rough = clamp(base_rough + (1.0 - h) * 0.08, 0.86, 0.98);
+            } else {
+                // --- ARCHETYPE 1: FISSURED / BRAIDED RIDGE BARK (OAK / WILLOW / MAPLE, WORLD-ASPECT CALIBRATED) ---
+                // Vertical frequencies are scaled to match the 1:8 world-space U:V aspect ratio so ridges anastomose
+                // naturally every 30-50cm along the trunk instead of stretching into 6-meter stripes!
+                const warp_u = (
+                    sample_tileable_bark_noise(u, v, 3, 20, ox + 11.3, oy + 7.1, oz + 3.7) * 0.065
+                    + sample_tileable_bark_noise(u, v, freq_u, 42, ox + 47.0, oy + 29.0, oz + 13.0) * 0.032
+                    + u_flow
+                );
+                const warp_v = sample_tileable_bark_noise(u, v, 3, 16, ox + 23.1, oy + 17.9, oz + 41.2) * 0.008;
+                const uw = ((u + warp_u) % 1.0 + 1.0) % 1.0;
+                const vw = ((v + warp_v) % 1.0 + 1.0) % 1.0;
+
+                // Braided cellular Voronoi ridges + multi-harmonic vertical canyons + craggy transverse breaks
+                const cells_v = Math.max(10, Math.round(freq_u * 3.6));
+                sample_tileable_worley(SCRATCH_WORLEY, uw, vw, freq_u, cells_v, seed);
+                sample_tileable_worley(SCRATCH_WORLEY2, uw, vw, freq_u * 2, cells_v * 2, seed ^ 0x5A3C9E17);
+
+                const detail_n1 = sample_tileable_bark_noise(uw, vw, freq_u, 24, ox, oy, oz);
+                const detail_n2 = sample_tileable_bark_noise(uw, vw, freq_u * 2, 48, ox + 37.0, oy + 19.0, oz + 53.0);
+                const fiber_n3 = sample_tileable_bark_noise(u, v, freq_u * 4, 36, ox + 83.0, oy + 59.0, oz + 19.0);
+
+                // Anastomosing vertical ridges that split and merge around elongated cellular plates
+                const ridge_primary = Math.pow(Math.abs(Math.sin(uw * Math.PI * freq_u + detail_n1 * 1.35)), 0.62);
+                const ridge_secondary = Math.pow(Math.abs(Math.sin(uw * Math.PI * (freq_u * 2) + detail_n2 * 0.95)), 0.72);
+                const cell_ridge = smoothStep(0.03, 0.42, SCRATCH_WORLEY[1]) * (0.75 + 0.25 * smoothStep(0.02, 0.30, SCRATCH_WORLEY2[1]));
+                const braid = 0.44 * ridge_primary + 0.24 * ridge_secondary + 0.32 * cell_ridge;
+
+                let h_macro = smoothStep(0.14, 0.84, braid);
+                const h_terrace = Math.round(h_macro * 4.0) / 4.0;
+                h_macro = lerp(h_macro, h_terrace, terrace * 0.35);
+
+                // Basal zone has deeper, wider crevices; young zone transitions to smooth finely striated shoot bark
+                const h_mature = clamp(
+                    h_macro * (1.0 - 0.14 * basal_w) + detail_n2 * 0.12 + fiber_n3 * 0.08 + knot_h,
+                    0.0,
+                    1.0
+                );
+                const h_young = 0.56 + 0.048 * ridge_secondary + 0.040 * fiber_n3 + 0.022 * detail_n2;
+                h = clamp(lerp(h_mature, h_young, young_w), 0.0, 1.0);
+
+                // Muted weathered ash-grey/taupe color ramp on mature trunk
+                const plate_mix = clamp(
+                    lerp(1.0 - depth * 0.92, 1.0, Math.pow(h_mature, 1.12)) * (1.0 - 0.60 * knot_scar_mask),
+                    0.0,
+                    1.0
+                );
+                const cell_var = 0.92 + 0.14 * SCRATCH_WORLEY[2] + 0.06 * fiber_n3;
+                let mr = lerp(r2, r1 * cell_var, plate_mix);
+                let mg = lerp(g2, g1 * cell_var, plate_mix);
+                let mb = lerp(b2, b1 * cell_var, plate_mix);
+
+                // Subtle warm inner-bark tint deep inside active basal/mature fissures
+                const phloem_seam = smoothStep(0.05, 0.14, h_mature) * smoothStep(0.24, 0.14, h_mature) * depth;
+                mr = lerp(mr, ri, phloem_seam * 0.26);
+                mg = lerp(mg, gi, phloem_seam * 0.26);
+                mb = lerp(mb, bi, phloem_seam * 0.26);
+
+                // Subtle weathered silver-ash highlight on ridge crests
+                const ridge_crest = smoothStep(0.70, 0.92, h_mature) * 0.045 + knot_rim_mask * 0.05;
+                mr = clamp(mr + ridge_crest, 0.0, 1.0);
+                mg = clamp(mg + ridge_crest * 0.98, 0.0, 1.0);
+                mb = clamp(mb + ridge_crest * 0.94, 0.0, 1.0);
+
+                // Smooth finely striated young shoot bark (v in [0.74, 1.0]): cohesive olive-taupe/grey-brown
+                const young_var = 0.95 + 0.07 * fiber_n3 + 0.04 * ridge_secondary;
+                const yr = lerp(r2, r1, 0.68) * young_var;
+                const yg = lerp(g2, g1, 0.70) * young_var;
+                const yb = lerp(b2, b1, 0.66) * young_var;
+
+                cr = lerp(mr, yr, young_w);
+                cg = lerp(mg, yg, young_w);
+                cb = lerp(mb, yb, young_w);
+
+                rough = clamp(base_rough + (1.0 - h) * 0.08 - young_w * 0.03, 0.86, 0.98);
+            }
+
+            // Lichen / moss flecking (concentrated toward basal skirt and deep crevices on lower trunk)
+            const eff_moss = moss_amt * (0.45 + 0.55 * basal_w) * (1.0 - young_w);
+            if (eff_moss > 0.0) {
+                const m_noise = sample_tileable_bark_noise(u, v, 4, 28, ox + 113.0, oy + 61.0, oz + 97.0);
+                const m_score = (m_noise * 0.5 + 0.5) * 0.72 + (1.0 - h) * 0.28;
+                const moss_mask = smoothStep(1.0 - eff_moss * 1.45, 1.0, m_score) * eff_moss;
+                cr = lerp(cr, rm, moss_mask);
+                cg = lerp(cg, gm, moss_mask);
+                cb = lerp(cb, bm, moss_mask);
+                rough = clamp(rough + moss_mask * 0.06, 0.86, 0.99);
+            }
+
+            height_field[p_idx] = h;
+            rough_field[p_idx] = rough;
+
+            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] = 255;
+        }
+    }
+
+    // Pass 2: 3x3 rotationally invariant Scharr normal map + multi-radius Laplacian cavity AO
+    const res_scale = Math.max(1.0, width / 64.0);
+    const base_slope = (bark_type === "birch"
+        ? (2.10 * depth + 0.45)
+        : (2.35 * depth + 0.52)) * res_scale;
+    const r_ao = Math.max(1, Math.round(width / 64));
+
+    for (let y = 0; y < height; y++) {
+        // Clamp Y at ontogenetic boundaries so basal trunk (y=0) never bleeds into young shoots (y=height-1)
+        const ym1 = Math.max(0, y - 1);
+        const yp1 = Math.min(height - 1, y + 1);
+        const ym_ao = Math.max(0, y - r_ao);
+        const yp_ao = Math.min(height - 1, y + r_ao);
+
+        for (let x = 0; x < width; x++) {
+            const xm1 = (x - 1 + width) % width;
+            const xp1 = (x + 1) % width;
+            const xm_ao = (x - r_ao + width) % width;
+            const xp_ao = (x + r_ao) % width;
+
+            const p_idx = y * width + x;
+            const h_c = height_field[p_idx];
+
+            const h_mm = height_field[ym1 * width + xm1];
+            const h_0m = height_field[ym1 * width + x];
+            const h_pm = height_field[ym1 * width + xp1];
+            const h_m0 = height_field[y * width + xm1];
+            const h_p0 = height_field[y * width + xp1];
+            const h_mp = height_field[yp1 * width + xm1];
+            const h_0p = height_field[yp1 * width + x];
+            const h_pp = height_field[yp1 * width + xp1];
+
+            // 3x3 Scharr derivative
+            const gu = (3.0 * (h_pm - h_mm) + 10.0 * (h_p0 - h_m0) + 3.0 * (h_pp - h_mp)) / 32.0;
+            const gv = (3.0 * (h_mp - h_mm) + 10.0 * (h_0p - h_0m) + 3.0 * (h_pp - h_pm)) / 32.0;
+
+            let nx = -gu * base_slope;
+            let ny = -gv * base_slope;
+            let nz = 1.0;
+            const nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+            nx /= nl;
+            ny /= nl;
+
+            const i2 = p_idx * 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);
+
+            // Multi-scale neighborhood average for local concavity / crevice shadow
+            const h_avg = 0.125 * (
+                height_field[y * width + xm_ao] +
+                height_field[y * width + xp_ao] +
+                height_field[ym_ao * width + x] +
+                height_field[yp_ao * width + x] +
+                h_m0 + h_p0 + h_0m + h_0p
+            );
+            const cavity = Math.max(0.0, h_avg - h_c);
+            const ao = clamp(
+                lerp(1.0 - depth * 0.78, 1.0, Math.pow(h_c, 0.82)) - cavity * 2.2,
+                0.08,
+                1.0
+            );
+
+            const i4 = p_idx * 4;
+            orm_data[i4] = clamp(Math.round(ao * 255), 0, 255);
+            orm_data[i4 + 1] = clamp(Math.round(rough_field[p_idx] * 255), 0, 255);
+            orm_data[i4 + 2] = 0;
+            orm_data[i4 + 3] = 255;
+        }
+    }
+
+    const albedo_image = ShadeImage.fromSampler2D(albedo_sampler);
+    albedo_image.color_space = ColorSpace.SRGB;
+    albedo_image.alpha_mode = AlphaMode.Opaque;
+    const texture_albedo = ShadeTexture.from(albedo_image);
+    texture_albedo.label = "foliage_bark_albedo";
+    texture_albedo.color_space = ColorSpace.SRGB;
+    texture_albedo.mipmapGenerationFilter = TextureFilterType.Linear;
+    texture_albedo.wrapS = TextureWrapType.Repeat;
+    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_bark_normal";
+    texture_normal.color_space = ColorSpace.LinearSRGB;
+    texture_normal.mipmapGenerationFilter = TextureFilterType.LinearNormal;
+    texture_normal.wrapS = TextureWrapType.Repeat;
+    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_bark_orm";
+    texture_orm.color_space = ColorSpace.LinearSRGB;
+    texture_orm.wrapS = TextureWrapType.Repeat;
+    texture_orm.wrapT = TextureWrapType.ClampToEdge;
+
+    const material = new StandardShadeMaterial();
+    material.name = "foliage_bark_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;
+    material.ior_factor = 1.25;
+    material.transmission_factor = 0.0;
+    // CRITICAL: StandardShadeMaterial defaults ambient_factors to LinearModifier(1, 1);
+    // set offset to 0 so ORM.r and vertex color AO actually darken crevices!
+    material.ambient_factors.a = 1.0;
+    material.ambient_factors.b = 0.0;
+    material.transparency_mode = TransparencyMode.Opaque;
+    material.transparency = TransparencyMode.Opaque;
+    material.draw_side = ShadeDrawSide.Front;
+
+    return material;
+}