@woosh/meep-engine 3.57.0 → 3.59.0

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

@@ -0,0 +1,354 @@
+import { assert } from "../../../core/assert.js";
+import { tree_cluster_atlas_pack } from "../material/tree_cluster_atlas_pack.js";
+import { tree_cluster_press } from "../material/tree_cluster_press.js";
+import { tree_cluster_tiles } from "../material/tree_cluster_tiles.js";
+import { foliage_scale_spread } from "./foliage_scale_spread.js";
+
+/**
+ * Bytes a texel of the cluster atlas costs, its maps' base levels: albedo RGBA8, normal two channels, ORM RGBA8
+ * (`tree_cluster_bake`).
+ * @type {number}
+ */
+const CLUSTER_TEXEL_BYTES = 4 + 2 + 4;
+
+const SCRATCH_A = new Float32Array(3);
+const SCRATCH_B = new Float32Array(3);
+
+/**
+ * Where a cut's tile would lie, and what the cut looks like.
+ *
+ * @typedef {Object} CutShape
+ * @property {number} lod
+ * @property {number} card index into that LOD's cards
+ * @property {number} size m, the side of the square as large as what it draws: its pressed leaves' cards and its twigs'
+ *           bands as they show on its plane
+ * @property {number} log_size
+ * @property {number} coverage what it draws over the area its content spans
+ * @property {number} hang_offset how far from its content's middle it hangs, over the side of its content's span
+ * @property {number} hang_u where it hangs, on its plane along its tile's u, m from its origin
+ * @property {number} hang_v
+ * @property {number} bytes its tile's, at its LOD's texel
+ */
+
+/**
+ * How unlike a cut is from a representative: how far the representative is magnified to its size (the log of the
+ * ratio), how much denser or sparser its leaves cover, and how far from its middle each hangs, all as fractions.
+ *
+ * @param {CutShape} a
+ * @param {CutShape} b
+ * @returns {number}
+ */
+function cut_distance(a, b) {
+    return Math.abs(a.log_size - b.log_size) + Math.abs(a.coverage - b.coverage) + Math.abs(a.hang_offset - b.hang_offset);
+}
+
+/**
+ * One LOD's cluster cards, and the error it is drawn to.
+ *
+ * @typedef {Object} TreeClusterLOD
+ * @property {import("./tree_clusters.js").TreeCluster[]} clusters
+ * @property {import("./tree_cluster_cards.js").TreeClusterCard[]} cards
+ * @property {number} error m
+ */
+
+/**
+ * A few cuts' tiles for every cut of every LOD.
+ *
+ * @typedef {Object} TreeClusterRepresentatives
+ * @property {import("./tree_cluster_cards.js").TreeClusterCard[]} cards the representatives' cards, to bake
+ * @property {Float64Array} texels each representative's texel, m
+ * @property {number[][]} sources each representative's `[lod, card]`
+ * @property {Array<{rep: Int32Array, frames: Float64Array}>} placements per LOD, per card: its representative, and the
+ *           12 floats placing that tile on the card, `[origin, e1, e2, n]`: a point `(a, b)` of the representative's
+ *           plane (along its tile's u and v from its origin, m) lands at `origin + e1 a + e2 b`
+ */
+
+/**
+ * Chooses a few cuts whose tiles every cut of every LOD is drawn with (`tree_clusters`, `tree_cluster_cards`), no more
+ * than `budget` bytes of atlas hold.
+ *
+ * - **Texel.** LOD0, seen from any distance, is drawn at the finest texel the budget affords for the whole cover: the
+ *   leaf material's own (`fine_texel`, as sharp as the leaf), coarsened by halves while the cover does not fit, to
+ *   `legible_texel`, the coarsest that still tells the leaf from another, and past it where even that does not fit
+ *   (the conifers' and the shrub's: a pine's cuts are whole boughs). A blurred leaf is still the tree's; a tile drawn
+ *   at a size its leaves do not grow to is not, its twigs as thick as boughs. A coarser LOD is seen no nearer than
+ *   where the LOD before it is drawn to a pixel, so its texel is that LOD's error, or LOD0's if finer. A cut uses only
+ *   representatives at its LOD's texel or finer.
+ * - **Choice.** The fewest that draw every cut at a size the tree's own leaves grow to: a cut drawn with a
+ *   representative magnifies its leaves by their size ratio, and the tree's leaves already span the 10th to the 90th
+ *   percentile of `attachments.scales` about their median, so within that a magnified leaf is one the tree grows.
+ *   Greedily, the cut that draws the most cuts not yet drawn, the least unlike them (magnification, leaf coverage,
+ *   where it hangs) where several do, while the packed atlas fits `budget`. Past that, another tile adds only
+ *   variety the tree already shows. The first is chosen whatever it costs: a tree with leaves draws them.
+ * - **Match.** Each cut is drawn with the least unlike of those that draw it at a size the tree grows.
+ * - **Placement.** A cut draws its representative on its own plane, as large as it draws (its leaves' area and its
+ *   twigs', so the crown keeps its leaf area and its density), hanging where it hangs, turned so that each runs out
+ *   from where it hangs the same way.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} leaves every leaf's card, in attachment order
+ * @param {TreeClusterLOD[]} lods finest first
+ * @param {number} fine_texel m, the leaf material's own (`FoliageTileLayout.texel`)
+ * @param {number} legible_texel m, the coarsest LOD0 is drawn at while its cover fits (`FoliageTileLayout.legible_texel`)
+ * @param {number} budget bytes of atlas, its maps' base levels
+ * @returns {TreeClusterRepresentatives}
+ */
+export function tree_cluster_representatives(skeleton, attachments, leaves, lods, fine_texel, legible_texel, budget) {
+    assert.greaterThan(lods.length, 0, 'lods.length');
+    assert.greaterThan(fine_texel, 0, 'fine_texel');
+    assert.greaterThan(legible_texel, 0, 'legible_texel');
+
+    // every cut's leaves pressed onto it, whatever the texel
+    const pressed_lods = lods.map(lod => tree_cluster_press(leaves, attachments, lod.cards));
+    // Ends: a cut's size is never under a texel, so once a texel is as large as every cut, one tile draws them all
+    for (let texel = Math.min(fine_texel, legible_texel); ; texel = texel < legible_texel ? Math.min(2 * texel, legible_texel) : 2 * texel) {
+        const representatives = choose(skeleton, attachments, leaves, lods, pressed_lods, texel, budget);
+        if (representatives !== null) return representatives;
+    }
+}
+
+/**
+ * The representatives at LOD0's texel `leaf_texel` (`tree_cluster_representatives`), or `null` when the atlas cannot
+ * hold tiles that draw every cut at a size the tree grows.
+ *
+ * @returns {TreeClusterRepresentatives|null}
+ */
+function choose(skeleton, attachments, leaves, lods, pressed_lods, leaf_texel, budget) {
+
+    // ---- every cut's shape and tile, at its LOD's texel
+    const lod_texels = lods.map((lod, k) => k === 0 ? leaf_texel : Math.max(leaf_texel, lods[k - 1].error));
+    /** @type {CutShape[]} */
+    const shapes = [];
+    const lod_first = [];
+    const lod_tiles = [];
+    for (let k = 0; k < lods.length; k++) {
+        const { clusters, cards } = lods[k];
+        lod_first.push(shapes.length);
+        const pressed = pressed_lods[k];
+        const texel = lod_texels[k];
+        const tiles = tree_cluster_tiles(skeleton, cards, pressed, cards.map(() => texel));
+        lod_tiles.push(tiles);
+        const P = pressed.positions;
+        const nodes = [], edges = [];
+        const index = leaves.index.data;
+        const tris_per_leaf = index.length / 3 / attachments.count;
+        for (let i = 0; i < cards.length; i++) {
+            const card = cards[i];
+            const f = i * 12;
+            const w = tiles.extents[i * 4 + 2] - tiles.extents[i * 4] - 2 * texel;
+            const h = tiles.extents[i * 4 + 3] - tiles.extents[i * 4 + 1] - 2 * texel;
+            const span = Math.max(texel * texel, w * h);
+            // pressed flat, a leaf's triangles show their whole area
+            let area = 0;
+            for (let j = 0; j < card.leaves.length; j++) {
+                const c = card.leaves[j];
+                // from the leaf's vertices to the card's pressed copy's
+                const shift = (pressed.first[i] + j - c) * pressed.verts_per_leaf;
+                for (let t = c * tris_per_leaf; t < (c + 1) * tris_per_leaf; t++) {
+                    const i0 = (index[t * 3] + shift) * 3, i1 = (index[t * 3 + 1] + shift) * 3, i2 = (index[t * 3 + 2] + shift) * 3;
+                    const ax = P[i1] - P[i0], ay = P[i1 + 1] - P[i0 + 1], az = P[i1 + 2] - P[i0 + 2];
+                    const bx = P[i2] - P[i0], by = P[i2 + 1] - P[i0 + 1], bz = P[i2 + 2] - P[i0 + 2];
+                    area += 0.5 * Math.hypot(ay * bz - az * by, az * bx - ax * bz, ax * by - ay * bx);
+                }
+            }
+            // a twig shows its length on the plane by its diameter
+            const n = card.normal;
+            for (let s2 = 0; s2 < card.segments.length; s2 += 2) {
+                skeleton.collect_branch_chain(card.segments[s2], nodes, edges);
+                const va = nodes[card.segments[s2 + 1]], vb = nodes[card.segments[s2 + 1] + 1];
+                skeleton.node_read_position(SCRATCH_A, 0, va);
+                skeleton.node_read_position(SCRATCH_B, 0, vb);
+                const ex = SCRATCH_B[0] - SCRATCH_A[0], ey = SCRATCH_B[1] - SCRATCH_A[1], ez = SCRATCH_B[2] - SCRATCH_A[2];
+                const along = ex * n[0] + ey * n[1] + ez * n[2];
+                const shown = Math.hypot(ex - along * n[0], ey - along * n[1], ez - along * n[2]);
+                area += shown * (skeleton.node_read_radius(va) + skeleton.node_read_radius(vb));
+            }
+            const size = Math.sqrt(Math.max(texel * texel, area));
+            const H = clusters[card.cluster].position;
+            const dx = H[0] - tiles.frames[f], dy = H[1] - tiles.frames[f + 1], dz = H[2] - tiles.frames[f + 2];
+            const hang_u = dx * tiles.frames[f + 3] + dy * tiles.frames[f + 4] + dz * tiles.frames[f + 5];
+            const hang_v = dx * tiles.frames[f + 6] + dy * tiles.frames[f + 7] + dz * tiles.frames[f + 8];
+            shapes.push({
+                lod: k,
+                card: i,
+                size,
+                log_size: Math.log(size),
+                coverage: area / span,
+                hang_offset: Math.hypot(hang_u, hang_v) / Math.sqrt(span),
+                hang_u,
+                hang_v,
+                bytes: tiles.sizes[i * 2] * tiles.sizes[i * 2 + 1] * CLUSTER_TEXEL_BYTES
+            });
+        }
+    }
+
+    // ---- the fewest representatives that draw every cut at a size the tree's own leaves grow to, while the atlas fits
+    const spread = foliage_scale_spread(attachments.scales, attachments.scales.length);
+    const shrink = Math.log(spread.low);
+    const grow = Math.log(spread.high);
+    // whether representative `r` draws cut `c` as the tree would grow it: no finer LOD's cut, its leaves magnified
+    // within their own spread
+    const draws = (c, r) => {
+        if (shapes[r].lod > shapes[c].lod) return false;
+        const m = shapes[c].log_size - shapes[r].log_size;
+        return m >= shrink && m <= grow;
+    };
+    const n = shapes.length;
+    const drawn = new Uint8Array(n);
+    let undrawn = n;
+    const chosen = [];
+    const chosen_sizes = [];
+    const taken = new Uint8Array(n);
+    let spent = 0;
+    // a tree with leaves draws them: the first is chosen among LOD0's cuts that fit, or among them all when none does
+    const lod0_end = lods.length > 1 ? lod_first[1] : n;
+    let affordable = false;
+    for (let c = 0; c < lod0_end; c++) {
+        if (shapes[c].bytes <= budget) affordable = true;
+    }
+    // How many cuts not yet drawn each would draw: those of its LOD or coarser, their sizes within its window. Cuts
+    // ordered by size, one Fenwick tree a LOD over that order holds those not yet drawn; a window is a range of it.
+    const by_size = Int32Array.from({ length: n }, (_, i) => i).sort((a, b) => shapes[a].log_size - shapes[b].log_size || a - b);
+    const rank = new Int32Array(n);
+    for (let i = 0; i < n; i++) rank[by_size[i]] = i;
+    const undrawn_of_lod = lods.map(() => new Int32Array(n + 1));
+    const fenwick_add = (tree, i, v) => {
+        for (let j = i + 1; j <= n; j += j & -j) tree[j] += v;
+    };
+    const fenwick_sum = (tree, end) => {
+        let s = 0;
+        for (let j = end; j > 0; j -= j & -j) s += tree[j];
+        return s;
+    };
+    for (let c = 0; c < n; c++) fenwick_add(undrawn_of_lod[shapes[c].lod], rank[c], 1);
+    // the first rank, in size order, whose cut is magnified from `log_size` by at least `m` (or past it, `past`)
+    const first_rank = (log_size, m, past) => {
+        let lo = 0, hi = n;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            const d = shapes[by_size[mid]].log_size - log_size;
+            if (past ? d > m : d >= m) hi = mid;
+            else lo = mid + 1;
+        }
+        return lo;
+    };
+    const counts = new Int32Array(n);
+    const window = new Int32Array(n);
+    while (undrawn > 0) {
+        // the one that draws the most cuts not yet drawn, the least unlike them where several do
+        let pick_count = 0;
+        for (let r = 0; r < n; r++) {
+            counts[r] = 0;
+            if (taken[r]) continue;
+            if (chosen.length === 0 ? affordable && shapes[r].bytes > budget : spent + shapes[r].bytes > budget) continue;
+            const s = shapes[r];
+            const from = first_rank(s.log_size, shrink, false);
+            const to = first_rank(s.log_size, grow, true);
+            let count = 0;
+            for (let k = s.lod; k < lods.length; k++) {
+                count += fenwick_sum(undrawn_of_lod[k], to) - fenwick_sum(undrawn_of_lod[k], from);
+            }
+            counts[r] = count;
+            if (count > pick_count) pick_count = count;
+        }
+        let pick = -1, pick_unlike = Infinity;
+        if (pick_count > 0) {
+            for (let r = 0; r < n; r++) {
+                if (counts[r] !== pick_count) continue;
+                // the cuts it draws, from its window, summed in the order of the cuts
+                const s = shapes[r];
+                const to = first_rank(s.log_size, grow, true);
+                let w = 0;
+                for (let i = first_rank(s.log_size, shrink, false); i < to; i++) {
+                    const c = by_size[i];
+                    if (!drawn[c] && shapes[c].lod >= s.lod) window[w++] = c;
+                }
+                window.subarray(0, w).sort();
+                let unlike = 0;
+                for (let i = 0; i < w; i++) unlike += cut_distance(shapes[window[i]], s);
+                if (unlike < pick_unlike) {
+                    pick = r;
+                    pick_unlike = unlike;
+                }
+            }
+        }
+        if (pick < 0) break;
+        const s = shapes[pick];
+        chosen_sizes.push(lod_tiles[s.lod].sizes[s.card * 2], lod_tiles[s.lod].sizes[s.card * 2 + 1]);
+        taken[pick] = 1;
+        if (chosen.length > 0) {
+            const packed = tree_cluster_atlas_pack(chosen_sizes, chosen.length + 1);
+            if (packed.atlas_w * packed.atlas_h * CLUSTER_TEXEL_BYTES > budget) {
+                // its tile fits the sum but not the packing
+                chosen_sizes.length -= 2;
+                continue;
+            }
+        }
+        chosen.push(pick);
+        spent += s.bytes;
+        for (let c = lod_first[s.lod]; c < n; c++) {
+            if (!drawn[c] && draws(c, pick)) {
+                drawn[c] = 1;
+                undrawn--;
+                fenwick_add(undrawn_of_lod[shapes[c].lod], rank[c], -1);
+            }
+        }
+    }
+    if (undrawn > 0) return null;
+
+    // ---- every cut's nearest, and where it lands
+    const placements = [];
+    for (let k = 0; k < lods.length; k++) {
+        const count = lods[k].cards.length;
+        const rep = new Int32Array(count);
+        const frames = new Float64Array(count * 12);
+        const tiles = lod_tiles[k];
+        for (let i = 0; i < count; i++) {
+            const own = lod_first[k] + i;
+            const c = shapes[own];
+            // among those that draw it as the tree would grow it, the least unlike
+            let r_best = -1, d_best = Infinity;
+            for (let r = 0; r < chosen.length; r++) {
+                if (!draws(own, chosen[r])) continue;
+                const d = cut_distance(c, shapes[chosen[r]]);
+                if (d < d_best) {
+                    d_best = d;
+                    r_best = r;
+                }
+            }
+            rep[i] = r_best;
+            const s = shapes[chosen[r_best]];
+            const scale = c.size / s.size;
+            // each runs out from where it hangs towards its middle: turn the one onto the other
+            let turn = 0;
+            if (c.hang_offset > 1e-6 && s.hang_offset > 1e-6) {
+                turn = Math.atan2(-c.hang_v, -c.hang_u) - Math.atan2(-s.hang_v, -s.hang_u);
+            }
+            const cos = Math.cos(turn) * scale, sin = Math.sin(turn) * scale;
+            // (a, b) -> hang_c + scale R ((a, b) - hang_s)
+            const tu = c.hang_u - (cos * s.hang_u - sin * s.hang_v);
+            const tv = c.hang_v - (sin * s.hang_u + cos * s.hang_v);
+            const f = i * 12;
+            for (let d = 0; d < 3; d++) {
+                const e1 = tiles.frames[f + 3 + d], e2 = tiles.frames[f + 6 + d];
+                frames[f + d] = tiles.frames[f + d] + e1 * tu + e2 * tv;
+                frames[f + 3 + d] = e1 * cos + e2 * sin;
+                frames[f + 6 + d] = -e1 * sin + e2 * cos;
+                frames[f + 9 + d] = tiles.frames[f + 9 + d];
+            }
+        }
+        placements.push({ rep, frames });
+    }
+
+    const texels = new Float64Array(chosen.length);
+    const cards = [];
+    const sources = [];
+    for (let r = 0; r < chosen.length; r++) {
+        const s = shapes[chosen[r]];
+        texels[r] = lod_texels[s.lod];
+        cards.push(lods[s.lod].cards[s.card]);
+        sources.push([s.lod, s.card]);
+    }
+    return { cards, texels, sources, placements };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * What one cluster card draws: the wood an LOD's error leaves undrawn where it joins drawn wood, with everything on
+ * it, and where it hangs.
+ *
+ * @typedef {Object} TreeCluster
+ * @property {number} branch the drawn branch it hangs from, `-1` when its tree draws no wood at all
+ * @property {number} t where along that branch, as `t_norm`
+ * @property {number} root the root branch of that tree when `branch` is `-1`, else `-1`
+ * @property {number[]} leaves attachment indices of its leaves
+ * @property {number[]} wood the undrawn branches it holds
+ * @property {Float64Array} position where it hangs: on its branch's drawn bark, or its tree's root
+ * @property {Uint16Array} joints the four skinning joints of that point
+ * @property {Float32Array} weights their weights
+ */
+/**
+ * The clusters of a tree drawn to an error, one per cut (`LOD_REWORK_BRIEF_2026_10_27.md`, L2):
+ *
+ * - each undrawn branch whose parent is drawn, with every branch and leaf it carries, hanging where it joins;
+ * - each drawn branch's undrawn tip, past where its wood thins to the error, with what grows there;
+ * - a leaf on drawn wood joins the cluster of its own branch nearest to it; a branch with none gathers its leaves into
+ *   one, at their mean place.
+ *
+ * Every leaf and every undrawn branch belongs to exactly one cluster. A tree whose wood is all thinner than the error
+ * is one cluster, hanging from its root; so is each tree of a skeleton that holds several (a species' prototypes).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {Map<number, Array<{t_norm: number, cx: number, cy: number, cz: number}>>} rings the drawn wood's rings at the
+ *        error (`tree_mesh_compute_branch_rings`)
+ * @returns {TreeCluster[]}
+ */
+export function tree_clusters(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, attachments: import("./foliage_collect_attachments.js").FoliageAttachmentSet, rings: Map<number, Array<{
+    t_norm: number;
+    cx: number;
+    cy: number;
+    cz: number;
+}>>): TreeCluster[];
+/**
+ * Where `cluster` hangs, and how the wind carries that point: on its branch's drawn bark at its `t`, skinned as that
+ * bark is there; a whole tree's cut (`branch` -1) from its tree's root.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton bound to the rig `rings` were planned with
+ * @param {Map<number, Array<{t_norm: number, cx: number, cy: number, cz: number}>>} rings
+ * @param {ReturnType<typeof tree_skeleton_read_joint_motion>} joint_motion
+ * @param {TreeCluster} cluster its `branch`, `t` and `root` read, its `position`, `joints` and `weights` written
+ */
+export function tree_cluster_hang(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, rings: Map<number, Array<{
+    t_norm: number;
+    cx: number;
+    cy: number;
+    cz: number;
+}>>, joint_motion: ReturnType<typeof tree_skeleton_read_joint_motion>, cluster: TreeCluster): void;
+/**
+ * What one cluster card draws: the wood an LOD's error leaves undrawn where it joins drawn wood, with everything on
+ * it, and where it hangs.
+ */
+export type TreeCluster = {
+    /**
+     * the drawn branch it hangs from, `-1` when its tree draws no wood at all
+     */
+    branch: number;
+    /**
+     * where along that branch, as `t_norm`
+     */
+    t: number;
+    /**
+     * the root branch of that tree when `branch` is `-1`, else `-1`
+     */
+    root: number;
+    /**
+     * attachment indices of its leaves
+     */
+    leaves: number[];
+    /**
+     * the undrawn branches it holds
+     */
+    wood: number[];
+    /**
+     * where it hangs: on its branch's drawn bark, or its tree's root
+     */
+    position: Float64Array;
+    /**
+     * the four skinning joints of that point
+     */
+    joints: Uint16Array;
+    /**
+     * their weights
+     */
+    weights: Float32Array;
+};
+import { tree_skeleton_read_joint_motion } from "../skeleton/tree_skeleton_read_joint_motion.js";
+//# sourceMappingURL=tree_clusters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree_clusters.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_clusters.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wCANW,OAAO,6BAA6B,EAAE,YAAY,eAClD,OAAO,kCAAkC,EAAE,oBAAoB,SAC/D,IAAI,MAAM,EAAE,MAAM;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,GAEtE,WAAW,EAAE,CAsGzB;AAED;;;;;;;;GAQG;AACH,4CALW,OAAO,6BAA6B,EAAE,YAAY,SAClD,IAAI,MAAM,EAAE,MAAM;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,gBACxE,WAAW,sCAAsC,CAAC,WAClD,WAAW,QAoCrB;;;;;;;;;YA5Ka,MAAM;;;;OACN,MAAM;;;;UACN,MAAM;;;;YACN,MAAM,EAAE;;;;UACR,MAAM,EAAE;;;;cACR,YAAY;;;;YACZ,WAAW;;;;aACX,YAAY;;gDAnBsB,gDAAgD"}

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

@@ -0,0 +1,187 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { tree_skeleton_read_joint_motion } from "../skeleton/tree_skeleton_read_joint_motion.js";
+import { interpolate_ring_skin_weights4 } from "./interpolate_ring_skin_weights4.js";
+
+const SCRATCH_P = new Float32Array(3);
+const SCRATCH_JOINTS4 = new Int32Array(4);
+const SCRATCH_WEIGHTS4 = new Float64Array(4);
+
+/**
+ * What one cluster card draws: the wood an LOD's error leaves undrawn where it joins drawn wood, with everything on
+ * it, and where it hangs.
+ *
+ * @typedef {Object} TreeCluster
+ * @property {number} branch the drawn branch it hangs from, `-1` when its tree draws no wood at all
+ * @property {number} t where along that branch, as `t_norm`
+ * @property {number} root the root branch of that tree when `branch` is `-1`, else `-1`
+ * @property {number[]} leaves attachment indices of its leaves
+ * @property {number[]} wood the undrawn branches it holds
+ * @property {Float64Array} position where it hangs: on its branch's drawn bark, or its tree's root
+ * @property {Uint16Array} joints the four skinning joints of that point
+ * @property {Float32Array} weights their weights
+ */
+
+/**
+ * The clusters of a tree drawn to an error, one per cut (`LOD_REWORK_BRIEF_2026_10_27.md`, L2):
+ *
+ * - each undrawn branch whose parent is drawn, with every branch and leaf it carries, hanging where it joins;
+ * - each drawn branch's undrawn tip, past where its wood thins to the error, with what grows there;
+ * - a leaf on drawn wood joins the cluster of its own branch nearest to it; a branch with none gathers its leaves into
+ *   one, at their mean place.
+ *
+ * Every leaf and every undrawn branch belongs to exactly one cluster. A tree whose wood is all thinner than the error
+ * is one cluster, hanging from its root; so is each tree of a skeleton that holds several (a species' prototypes).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {Map<number, Array<{t_norm: number, cx: number, cy: number, cz: number}>>} rings the drawn wood's rings at the
+ *        error (`tree_mesh_compute_branch_rings`)
+ * @returns {TreeCluster[]}
+ */
+export function tree_clusters(skeleton, attachments, rings) {
+    const branch_count = skeleton.branch_count;
+    const end_t = (b) => {
+        const list = rings.get(b);
+        return list[list.length - 1].t_norm;
+    };
+
+    // the undrawn branch a cut hangs from: the highest undrawn ancestor, whose parent is drawn or the root
+    const cut_root = new Int32Array(branch_count).fill(-1);
+    for (let b = 0; b < branch_count; b++) {
+        if (rings.has(b)) continue;
+        const p = skeleton.branch_parent[b];
+        cut_root[b] = p >= 0 && !rings.has(p) ? cut_root[p] : b;
+    }
+
+    /** @type {TreeCluster[]} */
+    const clusters = [];
+    // a cut's cluster, by its root; a drawn branch's tip cluster, by the branch
+    const of_root = new Map();
+    const of_tip = new Map();
+    const make = (branch, t, root = -1) => {
+        const cluster = { branch, t, root, leaves: [], wood: [], position: new Float64Array(3), joints: new Uint16Array(4), weights: new Float32Array(4) };
+        clusters.push(cluster);
+        return cluster;
+    };
+    const tip_of = (b) => {
+        let c = of_tip.get(b);
+        if (c === undefined) {
+            c = make(b, end_t(b));
+            of_tip.set(b, c);
+        }
+        return c;
+    };
+    const cluster_of_root = (r) => {
+        let c = of_root.get(r);
+        if (c !== undefined) return c;
+        const p = skeleton.branch_parent[r];
+        if (p < 0) {
+            c = make(-1, 0, r);
+        } else {
+            const t = skeleton.branch_parent_attach_t[r];
+            c = t > end_t(p) ? tip_of(p) : make(p, t);
+        }
+        of_root.set(r, c);
+        return c;
+    };
+
+    for (let b = 0; b < branch_count; b++) {
+        if (cut_root[b] >= 0) cluster_of_root(cut_root[b]).wood.push(b);
+    }
+
+    // leaves; those on drawn wood wait for their branch's clusters
+    const on_drawn = [];
+    for (let c = 0; c < attachments.count; c++) {
+        const b = attachments.carriers[c];
+        if (!rings.has(b)) {
+            cluster_of_root(cut_root[b]).leaves.push(c);
+        } else if (attachments.attach_t[c] > end_t(b)) {
+            tip_of(b).leaves.push(c);
+        } else {
+            on_drawn.push(c);
+        }
+    }
+    const of_branch = new Map();
+    for (const cluster of clusters) {
+        if (cluster.branch < 0) continue;
+        let list = of_branch.get(cluster.branch);
+        if (list === undefined) of_branch.set(cluster.branch, list = []);
+        list.push(cluster);
+    }
+    const gathered = new Map();
+    for (const c of on_drawn) {
+        const b = attachments.carriers[c];
+        const t = attachments.attach_t[c];
+        const list = of_branch.get(b);
+        if (list !== undefined) {
+            let best = list[0];
+            for (const cluster of list) {
+                if (Math.abs(cluster.t - t) < Math.abs(best.t - t)) best = cluster;
+            }
+            best.leaves.push(c);
+        } else {
+            let cluster = gathered.get(b);
+            if (cluster === undefined) {
+                cluster = make(b, 0);
+                gathered.set(b, cluster);
+            }
+            cluster.leaves.push(c);
+        }
+    }
+    for (const cluster of gathered.values()) {
+        let sum = 0;
+        for (const c of cluster.leaves) sum += attachments.attach_t[c];
+        cluster.t = sum / cluster.leaves.length;
+    }
+
+    // where each hangs, and how the wind carries that point
+    const joint_motion = tree_skeleton_read_joint_motion(skeleton);
+    for (const cluster of clusters) tree_cluster_hang(skeleton, rings, joint_motion, cluster);
+    return clusters;
+}
+
+/**
+ * Where `cluster` hangs, and how the wind carries that point: on its branch's drawn bark at its `t`, skinned as that
+ * bark is there; a whole tree's cut (`branch` -1) from its tree's root.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton bound to the rig `rings` were planned with
+ * @param {Map<number, Array<{t_norm: number, cx: number, cy: number, cz: number}>>} rings
+ * @param {ReturnType<typeof tree_skeleton_read_joint_motion>} joint_motion
+ * @param {TreeCluster} cluster its `branch`, `t` and `root` read, its `position`, `joints` and `weights` written
+ */
+export function tree_cluster_hang(skeleton, rings, joint_motion, cluster) {
+    if (cluster.branch < 0) {
+        // a whole tree's cut hangs from that tree's root
+        const root = skeleton.branch_root_vertex[cluster.root];
+        skeleton.node_read_position(SCRATCH_P, 0, root);
+        cluster.position[0] = SCRATCH_P[0];
+        cluster.position[1] = SCRATCH_P[1];
+        cluster.position[2] = SCRATCH_P[2];
+        cluster.joints[0] = skeleton.node_read_joint(root, 0);
+        cluster.weights[0] = 1;
+        return;
+    }
+    const list = rings.get(cluster.branch);
+    let k = list.length - 2;
+    for (let i = 0; i < list.length - 1; i++) {
+        if (cluster.t <= list[i + 1].t_norm) {
+            k = i;
+            break;
+        }
+    }
+    const ra = list[k];
+    const rb = list[k + 1];
+    const xi = clamp((cluster.t - ra.t_norm) / Math.max(1e-9, rb.t_norm - ra.t_norm), 0, 1);
+    const px = lerp(ra.cx, rb.cx, xi);
+    const py = lerp(ra.cy, rb.cy, xi);
+    const pz = lerp(ra.cz, rb.cz, xi);
+    cluster.position[0] = px;
+    cluster.position[1] = py;
+    cluster.position[2] = pz;
+    interpolate_ring_skin_weights4(SCRATCH_JOINTS4, 0, SCRATCH_WEIGHTS4, 0, ra, rb, xi, joint_motion, px, py, pz);
+    for (let s = 0; s < 4; s++) {
+        cluster.joints[s] = SCRATCH_JOINTS4[s];
+        cluster.weights[s] = SCRATCH_WEIGHTS4[s];
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"tree_mesh_build_bark.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_mesh_build_bark.js"],"names":[],"mappings":"AA4CA;;;;;GAKG;AACH,2DAJW,QAAQ,SACR,MAAM,GACJ,WAAW,CAevB;AAED;;;;;;;;;;GAUG;AACH,+CANW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,eACjB,aAAa,QACb,OAAO,8CAA8C,EAAE,QAAQ,yBAC7D,QAAQ,CA65BpB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDAVW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,eACjB,aAAa,GACX,IAAI,MAAM,EAAE,MAAM;IAC9B,EAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IACvC,CAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAC5D,EAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IACnD,EAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAC/C,CAAC,CAAC,CAQL;yBA1/BwB,8CAA8C;kCAOrC,gCAAgC;8BADpC,4BAA4B"}
+{"version":3,"file":"tree_mesh_build_bark.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_mesh_build_bark.js"],"names":[],"mappings":"AA+iBA;;;;;GAKG;AACH,2DAJW,QAAQ,SACR,MAAM,GACJ,WAAW,CAevB;AAED;;;;;;;;;;GAUG;AACH,+CANW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,eACjB,aAAa,QACb,OAAO,8CAA8C,EAAE,QAAQ,yBAC7D,QAAQ,CAyxBpB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDAVW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,eACjB,aAAa,GACX,IAAI,MAAM,EAAE,MAAM;IAC9B,EAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IACvC,CAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAC5D,EAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IACnD,EAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAC/C,CAAC,CAAC,CAQL;yBAv3CwB,8CAA8C;kCAOrC,gCAAgC;8BADpC,4BAA4B"}