@woosh/meep-engine 3.57.0 → 3.58.0

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

@@ -9,7 +9,7 @@
  * @property {Float32Array} up `count * 3` unit card outward normal U
  * @property {Float32Array} right `count * 3` unit card width axis W = F x U (so W x F = +U)
  * @property {Float32Array} scales `count` per-card size multiplier
- * @property {Float32Array} ranks `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+ * @property {Float32Array} attach_t `count` where each card attaches along its carrier, as `t_norm`
  * @property {Float32Array} phases `count` per-card wind phase in [0, 1)
  * @property {Float32Array} branch_sway `count` parent branch sway weight in [0, 1]
  * @property {Float32Array} color_jitter `count` per-card luminance/tint jitter in [-1, 1]
@@ -41,9 +41,27 @@
  * @param {TreeSpeciesConfig} [config]
  * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout} [cutout] shape of the foliage atlas the
  *        cards will show; fitted from `config.foliage_material` when omitted
+ * @param {ReturnType<typeof tree_mesh_compute_branch_rings>} [rings] the bark's rings the cards anchor on, at the error
+ *        of `config.lods[0]` (`tree_mesh_compute_branch_rings`); planned here when omitted
  * @returns {FoliageAttachmentSet}
  */
-export function foliage_collect_attachments(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, config?: TreeSpeciesConfig, cutout?: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout): FoliageAttachmentSet;
+export function foliage_collect_attachments(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, config?: TreeSpeciesConfig, cutout?: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout, rings?: Map<number, {
+    cx: number;
+    cy: number;
+    cz: number;
+    r: number;
+    m: number;
+    t_norm: number;
+    flute_amp: number;
+    j0: number;
+    j1: number;
+    j2: number;
+    j3: number;
+    w0: number;
+    w1: number;
+    w2: number;
+    w3: number;
+}[]>): FoliageAttachmentSet;
 /**
  * Flat typed-array structure holding all phyllotactic foliage attachment points and oriented card frames.
  */
@@ -77,9 +95,9 @@ export type FoliageAttachmentSet = {
      */
     scales: Float32Array;
     /**
-     * `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+     * `count` where each card attaches along its carrier, as `t_norm`
      */
-    ranks: Float32Array;
+    attach_t: Float32Array;
     /**
      * `count` per-card wind phase in [0, 1)
      */

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

@@ -1 +1 @@
-{"version":3,"file":"foliage_collect_attachments.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/foliage_collect_attachments.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sDANW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,WACjB,OAAO,mCAAmC,EAAE,kBAAkB,GAE5D,oBAAoB,CAgiBhC;;;;;;;;WAxkBa,MAAM;;;;cACN,WAAW;;;;eACX,YAAY;;;;aACZ,YAAY;;;;QACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;iBACZ,YAAY;;;;kBACZ,YAAY;;;;gBACZ,YAAY;;;;kBACZ,YAAY;;;;qBACZ,UAAU;;;;aACV,YAAY;;;;WACZ,YAAY;;;;;gBACZ,MAAM;;;;YAEN,WAAW;;;;aACX,YAAY;;kCA5DQ,gCAAgC"}
+{"version":3,"file":"foliage_collect_attachments.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/foliage_collect_attachments.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,sDARW,OAAO,6BAA6B,EAAE,YAAY,WAClD,iBAAiB,WACjB,OAAO,mCAAmC,EAAE,kBAAkB;;;;;;;;;;;;;;;;OAI5D,oBAAoB,CA0iBhC;;;;;;;;WAplBa,MAAM;;;;cACN,WAAW;;;;eACX,YAAY;;;;aACZ,YAAY;;;;QACZ,YAAY;;;;WACZ,YAAY;;;;YACZ,YAAY;;;;cACZ,YAAY;;;;YACZ,YAAY;;;;iBACZ,YAAY;;;;kBACZ,YAAY;;;;gBACZ,YAAY;;;;kBACZ,YAAY;;;;qBACZ,UAAU;;;;aACV,YAAY;;;;WACZ,YAAY;;;;;gBACZ,MAAM;;;;YAEN,WAAW;;;;aACX,YAAY;;kCA5DQ,gCAAgC"}

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

@@ -57,7 +57,7 @@ const SCRATCH_SPANS = [];
  * @property {Float32Array} up `count * 3` unit card outward normal U
  * @property {Float32Array} right `count * 3` unit card width axis W = F x U (so W x F = +U)
  * @property {Float32Array} scales `count` per-card size multiplier
- * @property {Float32Array} ranks `count` golden-ratio low-discrepancy decimation rank in [0, 1)
+ * @property {Float32Array} attach_t `count` where each card attaches along its carrier, as `t_norm`
  * @property {Float32Array} phases `count` per-card wind phase in [0, 1)
  * @property {Float32Array} branch_sway `count` parent branch sway weight in [0, 1]
  * @property {Float32Array} color_jitter `count` per-card luminance/tint jitter in [-1, 1]
@@ -90,9 +90,11 @@ const SCRATCH_SPANS = [];
  * @param {TreeSpeciesConfig} [config]
  * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout} [cutout] shape of the foliage atlas the
  *        cards will show; fitted from `config.foliage_material` when omitted
+ * @param {ReturnType<typeof tree_mesh_compute_branch_rings>} [rings] the bark's rings the cards anchor on, at the error
+ *        of `config.lods[0]` (`tree_mesh_compute_branch_rings`); planned here when omitted
  * @returns {FoliageAttachmentSet}
  */
-export function foliage_collect_attachments(skeleton, config = new TreeSpeciesConfig(), cutout) {
+export function foliage_collect_attachments(skeleton, config = new TreeSpeciesConfig(), cutout, rings) {
 	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
 	const fol = species.foliage;
 	if (species.foliage_rules.length === 0 || skeleton.branch_count === 0) {
@@ -105,7 +107,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 			up: new Float32Array(0),
 			right: new Float32Array(0),
 			scales: new Float32Array(0),
-			ranks: new Float32Array(0),
+			attach_t: new Float32Array(0),
 			phases: new Float32Array(0),
 			branch_sway: new Float32Array(0),
 			color_jitter: new Float32Array(0),
@@ -119,7 +121,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 			weights: new Float32Array(0),
 			joints4: new Uint16Array(0),
 			weights4: new Float32Array(0),
-			attr_ranks: Attribute.from(new Float32Array(0), 1, "foliage_ranks"),
+			attr_attach_t: Attribute.from(new Float32Array(0), 1, "foliage_attach_t"),
 			attr_phases: Attribute.from(new Float32Array(0), 1, "foliage_phases"),
 			attr_branch_sway: Attribute.from(new Float32Array(0), 1, "foliage_branch_sway"),
 			attr_color_jitter: Attribute.from(new Float32Array(0), 1, "foliage_color_jitter"),
@@ -131,7 +133,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 	}
 
 	const rng = seededRandom((species.seed ^ 0x5A3C9E17) | 0);
-	const branch_rings = tree_mesh_compute_branch_rings(skeleton, species, species.lods?.[0]);
+	const branch_rings = rings ?? tree_mesh_compute_branch_rings(skeleton, species, species.lods?.[0]);
 	const layout = foliage_tile_layout(species);
 	const variant_count = layout.variant_count;
 	const needle_shoot = species.foliage_material.tile_content === FoliageTileContent.NeedleShoot;
@@ -247,7 +249,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 	const up = new Float32Array(total_count * 3);
 	const right = new Float32Array(total_count * 3);
 	const scales = new Float32Array(total_count);
-	const ranks = new Float32Array(total_count);
+	const attach_t = new Float32Array(total_count);
 	const phases = new Float32Array(total_count);
 	const branch_sway = new Float32Array(total_count);
 	const color_jitter = new Float32Array(total_count);
@@ -353,11 +355,22 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 			const c4 = cursor * 4;
 			const c2 = cursor * 2;
 
-			if (b_rings && b_rings.length >= 2) {
-				const ring_idx = Math.min(seg_idx, b_rings.length - 2);
+			// the bark's rings stand where its error needs them, and stop where the wood grows thinner than the error
+			let ring_idx = -1;
+			if (b_rings && b_rings.length >= 2 && t_attach <= b_rings[b_rings.length - 1].t_norm) {
+				ring_idx = b_rings.length - 2;
+				for (let k = 0; k < b_rings.length - 1; k++) {
+					if (t_attach <= b_rings[k + 1].t_norm) {
+						ring_idx = k;
+						break;
+					}
+				}
+			}
+
+			if (ring_idx >= 0) {
 				const ra = b_rings[ring_idx];
 				const rb = b_rings[ring_idx + 1];
-				const xi = clamp((t_attach - ra.t_norm) / Math.max(1e-5, rb.t_norm - ra.t_norm), 0.05, 0.95);
+				const xi = clamp((t_attach - ra.t_norm) / Math.max(1e-5, rb.t_norm - ra.t_norm), 0.0, 1.0);
 
 				px = lerp(ra.cx, rb.cx, xi);
 				py = lerp(ra.cy, rb.cy, xi);
@@ -537,8 +550,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 			t64.updateMatrix();
 			transforms[cursor] = t64;
 
-			// Golden-ratio low-discrepancy rank in [0, 1)
-			ranks[cursor] = ((cursor * GOLDEN_CONJUGATE) + b_phase * 0.13) % 1.0;
+			attach_t[cursor] = t_attach;
 			phases[cursor] = (b_phase + k * 0.17) % 1.0;
 			branch_sway[cursor] = clamp((level + t_attach) * 0.28, 0.1, 1.0);
 			const c_jit = rng() * 2.0 - 1.0;
@@ -593,7 +605,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 	// shed leaves leave the arrays longer than the cards that remain: views of what remains
 	const n = cursor;
 	transforms.length = n;
-	const out_ranks = ranks.subarray(0, n);
+	const out_attach_t = attach_t.subarray(0, n);
 	const out_phases = phases.subarray(0, n);
 	const out_branch_sway = branch_sway.subarray(0, n);
 	const out_color_jitter = color_jitter.subarray(0, n);
@@ -611,7 +623,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 		up: up.subarray(0, n * 3),
 		right: right.subarray(0, n * 3),
 		scales: scales.subarray(0, n),
-		ranks: out_ranks,
+		attach_t: out_attach_t,
 		phases: out_phases,
 		branch_sway: out_branch_sway,
 		color_jitter: out_color_jitter,
@@ -625,7 +637,7 @@ export function foliage_collect_attachments(skeleton, config = new TreeSpeciesCo
 		weights: out_weights,
 		joints4: joints4.subarray(0, n * 4),
 		weights4: weights4.subarray(0, n * 4),
-		attr_ranks: Attribute.from(out_ranks, 1, "foliage_ranks"),
+		attr_attach_t: Attribute.from(out_attach_t, 1, "foliage_attach_t"),
 		attr_phases: Attribute.from(out_phases, 1, "foliage_phases"),
 		attr_branch_sway: Attribute.from(out_branch_sway, 1, "foliage_branch_sway"),
 		attr_color_jitter: Attribute.from(out_color_jitter, 1, "foliage_color_jitter"),

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

@@ -0,0 +1,61 @@
+/**
+ * The flat card a cluster is drawn on.
+ *
+ * @typedef {Object} TreeClusterCard
+ * @property {number} cluster index into the clusters
+ * @property {Float64Array} normal unit, facing away from the crown's centre
+ * @property {Float64Array} axis the card's first in-plane axis, its tile's u
+ * @property {Float64Array} origin a point of its plane: the middle of what it draws
+ * @property {number[]} leaves attachment indices
+ * @property {number[]} segments its twig segments, pairs of (branch, segment along the branch)
+ */
+/**
+ * One card per cluster, in the plane what it draws spreads in most: its leaves' cards and its twigs' bands, each by
+ * its area. Through their middle, its normal the direction they spread least in (least squares), its first axis the one
+ * they spread most in, facing away from the crown's centre. Where its leaves attach is not enough: a palm's leaves
+ * attach along its rachis, which arches in a vertical plane, while they spread to either side of it.
+ *
+ * Its leaves are pressed onto it when it is baked (`tree_cluster_bake`), so the card holds each leaf's whole area:
+ * averaged over every direction it is seen from, a flat leaf shows half its area whichever way it faces, and so does
+ * the card. Measured against every leaf drawn as its own card, this one card keeps the crown's FIA density closer than
+ * the leaves projected onto it, or projected or pressed onto three cards along the axes of their orientations
+ * (`LOD_REWORK_BRIEF_2026_10_27.md`, L2).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card, in attachment
+ *        order (`tree_mesh_build_foliage`), or `null` for a tree without leaves
+ * @param {import("./tree_clusters.js").TreeCluster[]} clusters
+ * @returns {TreeClusterCard[]}
+ */
+export function tree_cluster_cards(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, attachments: import("./foliage_collect_attachments.js").FoliageAttachmentSet, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null, clusters: import("./tree_clusters.js").TreeCluster[]): TreeClusterCard[];
+/**
+ * The flat card a cluster is drawn on.
+ */
+export type TreeClusterCard = {
+    /**
+     * index into the clusters
+     */
+    cluster: number;
+    /**
+     * unit, facing away from the crown's centre
+     */
+    normal: Float64Array;
+    /**
+     * the card's first in-plane axis, its tile's u
+     */
+    axis: Float64Array;
+    /**
+     * a point of its plane: the middle of what it draws
+     */
+    origin: Float64Array;
+    /**
+     * attachment indices
+     */
+    leaves: number[];
+    /**
+     * its twig segments, pairs of (branch, segment along the branch)
+     */
+    segments: number[];
+};
+//# sourceMappingURL=tree_cluster_cards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree_cluster_cards.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_cluster_cards.js"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,6CAPW,OAAO,6BAA6B,EAAE,YAAY,eAClD,OAAO,kCAAkC,EAAE,oBAAoB,UAC/D,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,YAEpE,OAAO,oBAAoB,EAAE,WAAW,EAAE,GACxC,eAAe,EAAE,CA2E7B;;;;;;;;aApGa,MAAM;;;;YACN,YAAY;;;;UACZ,YAAY;;;;YACZ,YAAY;;;;YACZ,MAAM,EAAE;;;;cACR,MAAM,EAAE"}

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

@@ -0,0 +1,114 @@
+import { matrix_symmetric_3x3_eigen } from "../../../core/math/linalg/eigen/matrix_symmetric_3x3_eigen.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+
+const SCRATCH_VALUES = new Float64Array(3);
+const SCRATCH_VECTORS = new Float64Array(9);
+const SCRATCH_M = new Float64Array(9);
+const SCRATCH_P = new Float32Array(3);
+const SCRATCH_Q = new Float32Array(3);
+
+/**
+ * The flat card a cluster is drawn on.
+ *
+ * @typedef {Object} TreeClusterCard
+ * @property {number} cluster index into the clusters
+ * @property {Float64Array} normal unit, facing away from the crown's centre
+ * @property {Float64Array} axis the card's first in-plane axis, its tile's u
+ * @property {Float64Array} origin a point of its plane: the middle of what it draws
+ * @property {number[]} leaves attachment indices
+ * @property {number[]} segments its twig segments, pairs of (branch, segment along the branch)
+ */
+
+/**
+ * One card per cluster, in the plane what it draws spreads in most: its leaves' cards and its twigs' bands, each by
+ * its area. Through their middle, its normal the direction they spread least in (least squares), its first axis the one
+ * they spread most in, facing away from the crown's centre. Where its leaves attach is not enough: a palm's leaves
+ * attach along its rachis, which arches in a vertical plane, while they spread to either side of it.
+ *
+ * Its leaves are pressed onto it when it is baked (`tree_cluster_bake`), so the card holds each leaf's whole area:
+ * averaged over every direction it is seen from, a flat leaf shows half its area whichever way it faces, and so does
+ * the card. Measured against every leaf drawn as its own card, this one card keeps the crown's FIA density closer than
+ * the leaves projected onto it, or projected or pressed onto three cards along the axes of their orientations
+ * (`LOD_REWORK_BRIEF_2026_10_27.md`, L2).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card, in attachment
+ *        order (`tree_mesh_build_foliage`), or `null` for a tree without leaves
+ * @param {import("./tree_clusters.js").TreeCluster[]} clusters
+ * @returns {TreeClusterCard[]}
+ */
+export function tree_cluster_cards(skeleton, attachments, leaves, clusters) {
+    const crown = skeleton.crown_center;
+    const positions = leaves !== null ? leaves.getAttribute(StandardAttributes.Position).data : null;
+    const index = leaves !== null ? leaves.index.data : null;
+    const tris_per_leaf = leaves !== null && attachments.count > 0 ? index.length / 3 / attachments.count : 0;
+    const nodes = [], edges = [];
+    /** @type {TreeClusterCard[]} */
+    const cards = [];
+
+    for (let i = 0; i < clusters.length; i++) {
+        const cluster = clusters[i];
+        // the plane is fitted to what the card draws, each part by its area: every leaf's card (its triangles'
+        // corners, a third of the triangle's area each) and every twig segment's band (its ends, half each)
+        const segments = [];
+        let weight = 0, mx = 0, my = 0, mz = 0;
+        const weighted = [];
+        const add = (x, y, z, w) => {
+            weighted.push(x, y, z, w);
+            weight += w;
+            mx += w * x;
+            my += w * y;
+            mz += w * z;
+        };
+        for (const c of cluster.leaves) {
+            for (let t = c * tris_per_leaf; t < (c + 1) * tris_per_leaf; t++) {
+                const i0 = index[t * 3] * 3, i1 = index[t * 3 + 1] * 3, i2 = index[t * 3 + 2] * 3;
+                const ax = positions[i1] - positions[i0], ay = positions[i1 + 1] - positions[i0 + 1], az = positions[i1 + 2] - positions[i0 + 2];
+                const bx = positions[i2] - positions[i0], by = positions[i2 + 1] - positions[i0 + 1], bz = positions[i2 + 2] - positions[i0 + 2];
+                const third = Math.hypot(ay * bz - az * by, az * bx - ax * bz, ax * by - ay * bx) / 6;
+                for (const v of [i0, i1, i2]) add(positions[v], positions[v + 1], positions[v + 2], third);
+            }
+        }
+        for (const b of cluster.wood) {
+            skeleton.collect_branch_chain(b, nodes, edges);
+            for (let s = 0; s < edges.length; s++) {
+                skeleton.node_read_position(SCRATCH_P, 0, nodes[s]);
+                skeleton.node_read_position(SCRATCH_Q, 0, nodes[s + 1]);
+                segments.push(b, s);
+                const length = Math.hypot(SCRATCH_Q[0] - SCRATCH_P[0], SCRATCH_Q[1] - SCRATCH_P[1], SCRATCH_Q[2] - SCRATCH_P[2]);
+                const half = 0.5 * length * (skeleton.node_read_radius(nodes[s]) + skeleton.node_read_radius(nodes[s + 1]));
+                add(SCRATCH_P[0], SCRATCH_P[1], SCRATCH_P[2], half);
+                add(SCRATCH_Q[0], SCRATCH_Q[1], SCRATCH_Q[2], half);
+            }
+        }
+        if (!(weight > 0)) {
+            // it draws nothing: a card where it hangs
+            add(cluster.position[0], cluster.position[1], cluster.position[2], 1);
+        }
+        mx /= weight;
+        my /= weight;
+        mz /= weight;
+        SCRATCH_M.fill(0);
+        for (let k = 0; k < weighted.length; k += 4) {
+            const x = weighted[k] - mx, y = weighted[k + 1] - my, z = weighted[k + 2] - mz, w = weighted[k + 3];
+            SCRATCH_M[0] += w * x * x;
+            SCRATCH_M[1] += w * x * y;
+            SCRATCH_M[2] += w * x * z;
+            SCRATCH_M[4] += w * y * y;
+            SCRATCH_M[5] += w * y * z;
+            SCRATCH_M[8] += w * z * z;
+        }
+        // eigenvalues ascend: the least spread is the normal, the most the first axis
+        matrix_symmetric_3x3_eigen(SCRATCH_VALUES, SCRATCH_VECTORS, SCRATCH_M);
+        const normal = Float64Array.from(SCRATCH_VECTORS.subarray(0, 3));
+        const axis = Float64Array.from(SCRATCH_VECTORS.subarray(6, 9));
+        if ((mx - crown[0]) * normal[0] + (my - crown[1]) * normal[1] + (mz - crown[2]) * normal[2] < 0) {
+            normal[0] = -normal[0];
+            normal[1] = -normal[1];
+            normal[2] = -normal[2];
+        }
+        cards.push({ cluster: i, normal, axis, origin: Float64Array.from([mx, my, mz]), leaves: cluster.leaves, segments });
+    }
+    return cards;
+}

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

@@ -0,0 +1,121 @@
+/**
+ * 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, but
+ *   never past `legible_texel`, the coarsest that still tells the leaf from another. 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, or of all when
+ *   the budget ran out first.
+ * - **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 (`FoliageTileLayout.legible_texel`)
+ * @param {number} budget bytes of atlas, its maps' base levels
+ * @returns {TreeClusterRepresentatives}
+ */
+export function tree_cluster_representatives(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, attachments: import("./foliage_collect_attachments.js").FoliageAttachmentSet, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry, lods: TreeClusterLOD[], fine_texel: number, legible_texel: number, budget: number): TreeClusterRepresentatives;
+/**
+ * Where a cut's tile would lie, and what the cut looks like.
+ */
+export type CutShape = {
+    lod: number;
+    /**
+     * index into that LOD's cards
+     */
+    card: number;
+    /**
+     * 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
+     */
+    size: number;
+    log_size: number;
+    /**
+     * what it draws over the area its content spans
+     */
+    coverage: number;
+    /**
+     * how far from its content's middle it hangs, over the side of its content's span
+     */
+    hang_offset: number;
+    /**
+     * where it hangs, on its plane along its tile's u, m from its origin
+     */
+    hang_u: number;
+    hang_v: number;
+    /**
+     * its tile's, at its LOD's texel
+     */
+    bytes: number;
+};
+/**
+ * One LOD's cluster cards, and the error it is drawn to.
+ */
+export type TreeClusterLOD = {
+    clusters: import("./tree_clusters.js").TreeCluster[];
+    cards: import("./tree_cluster_cards.js").TreeClusterCard[];
+    /**
+     * m
+     */
+    error: number;
+};
+/**
+ * A few cuts' tiles for every cut of every LOD.
+ */
+export type TreeClusterRepresentatives = {
+    /**
+     * the representatives' cards, to bake
+     */
+    cards: import("./tree_cluster_cards.js").TreeClusterCard[];
+    /**
+     * each representative's texel, m
+     */
+    texels: Float64Array;
+    /**
+     * each representative's `[lod, card]`
+     */
+    sources: number[][];
+    /**
+     * 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`
+     */
+    placements: Array<{
+        rep: Int32Array;
+        frames: Float64Array;
+    }>;
+};
+//# sourceMappingURL=tree_cluster_representatives.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree_cluster_representatives.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_cluster_representatives.js"],"names":[],"mappings":"AA2CA;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,uDATW,OAAO,6BAA6B,EAAE,YAAY,eAClD,OAAO,kCAAkC,EAAE,oBAAoB,UAC/D,OAAO,8CAA8C,EAAE,QAAQ,QAC/D,cAAc,EAAE,cAChB,MAAM,iBACN,MAAM,UACN,MAAM,GACJ,0BAA0B,CAetC;;;;;SAxFa,MAAM;;;;UACN,MAAM;;;;;UACN,MAAM;cAEN,MAAM;;;;cACN,MAAM;;;;iBACN,MAAM;;;;YACN,MAAM;YACN,MAAM;;;;WACN,MAAM;;;;;;cAmBN,OAAO,oBAAoB,EAAE,WAAW,EAAE;WAC1C,OAAO,yBAAyB,EAAE,eAAe,EAAE;;;;WACnD,MAAM;;;;;;;;;WAON,OAAO,yBAAyB,EAAE,eAAe,EAAE;;;;YACnD,YAAY;;;;aACZ,MAAM,EAAE,EAAE;;;;;;gBACV,MAAM;QAAC,GAAG,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAC,CAAC"}