@call-me-sensei/toonlab 0.3.1 → 0.4.20

package/src/rockgen/lod/rockLodPlanner.js

@@ -0,0 +1,372 @@
+import { meshDocument } from '../mesh/meshDocument.js';
+import { getGeometryTriangleCount } from './rockLodMetrics.js';
+import {
+  createReferenceRockLodPolicyForDocument,
+  createRockLodTriangleTargets,
+  resolveReferenceRockLodPolicy,
+} from './rockLodPolicy.js';
+import {
+  matchRockGeometryBounds,
+  simplifyRockGeometryToTriangleBudget,
+} from './rockLodSimplifier.js';
+import { validateRockLodLevels } from './rockLodValidation.js';
+
+function clampInteger(value, min, max) {
+  return Math.min(Math.max(Math.round(Number(value)), min), max);
+}
+
+/**
+ * Surface meshes scale approximately with resolution squared, so a triangle
+ * target uses sqrt(target/reference) rather than the exporter's historical
+ * direct half/quarter resolution convention.
+ */
+export function estimateSurfaceNetsResolution({
+  maxResolution = 320,
+  minResolution = 8,
+  referenceResolution,
+  referenceTriangles,
+  targetTriangles,
+}) {
+  const min = clampInteger(minResolution, 8, 320);
+  const max = clampInteger(maxResolution, min, 320);
+  const resolution = clampInteger(referenceResolution, min, max);
+  const triangles = Math.max(Number(referenceTriangles) || 1, 1);
+  const target = Math.max(Number(targetTriangles) || 1, 1);
+  return clampInteger(resolution * Math.sqrt(target / triangles), min, max);
+}
+
+function selectMeasurement(measurements, target, preference) {
+  const candidates = [...measurements.values()].filter((entry) => !entry.invalid);
+  if (candidates.length === 0) return null;
+  const under = candidates.filter((entry) => entry.triangleCount <= target);
+  if (preference === 'under' && under.length > 0) {
+    under.sort((left, right) => (
+      right.triangleCount - left.triangleCount
+      || right.resolution - left.resolution
+    ));
+    return under[0];
+  }
+  candidates.sort((left, right) => (
+    Math.abs(left.triangleCount - target) - Math.abs(right.triangleCount - target)
+    || Number(left.triangleCount > target) - Number(right.triangleCount > target)
+    || left.resolution - right.resolution
+  ));
+  return candidates[0];
+}
+
+/**
+ * Searches integer grid resolutions around the Surface Nets sqrt estimate.
+ * The callback may return either a triangle count or `{ triangleCount, ... }`.
+ * Results include every sampled resolution for diagnostics and reuse.
+ */
+export function searchSurfaceNetsResolution({
+  maxResolution = 320,
+  measureTriangles,
+  minResolution = 8,
+  neighborhood = 2,
+  preference = 'under',
+  reference = null,
+  targetTriangles,
+}) {
+  if (typeof measureTriangles !== 'function') {
+    throw new TypeError('searchSurfaceNetsResolution requires a measureTriangles callback.');
+  }
+  const min = clampInteger(minResolution, 8, 320);
+  const max = clampInteger(maxResolution, min, 320);
+  const target = Math.max(Math.round(Number(targetTriangles) || 1), 1);
+  const measurements = new Map();
+  const measure = (value) => {
+    const resolution = clampInteger(value, min, max);
+    if (measurements.has(resolution)) return measurements.get(resolution);
+    const raw = measureTriangles(resolution);
+    const data = typeof raw === 'number' ? { triangleCount: raw } : raw;
+    const triangleCount = Math.max(Math.round(Number(data?.triangleCount) || 0), 0);
+    const measured = { ...data, resolution, triangleCount };
+    measurements.set(resolution, measured);
+    return measured;
+  };
+
+  const minimum = measure(min);
+  if (min === max) {
+    if (minimum.invalid) {
+      throw new Error(`No non-empty Surface Nets mesh exists at resolution ${min}.`);
+    }
+    return {
+      ...minimum,
+      limitedByMinimum: minimum.triangleCount > target,
+      samples: [...measurements.values()],
+      targetTriangles: target,
+    };
+  }
+
+  const referenceResolution = Number.isFinite(reference?.resolution)
+    ? Math.round(reference.resolution)
+    : Math.round((min + max) * 0.5);
+  const referenceTriangles = Number.isFinite(reference?.triangleCount)
+    ? Math.max(Math.round(reference.triangleCount), 1)
+    : measure(clampInteger(referenceResolution, min, max)).triangleCount;
+  const estimate = estimateSurfaceNetsResolution({
+    maxResolution: max,
+    minResolution: min,
+    referenceResolution,
+    referenceTriangles,
+    targetTriangles: target,
+  });
+  const estimated = measure(estimate);
+
+  let lower = estimated.triangleCount <= target ? estimated.resolution : null;
+  let upper = estimated.triangleCount > target ? estimated.resolution : null;
+  let cursor = estimated.resolution;
+  let step = 1;
+  if (lower !== null) {
+    while (cursor < max && upper === null) {
+      const next = Math.min(cursor + step, max);
+      const measured = measure(next);
+      if (measured.triangleCount <= target) lower = next;
+      else upper = next;
+      if (next === max) break;
+      cursor = next;
+      step *= 2;
+    }
+  } else {
+    while (cursor > min && lower === null) {
+      const next = Math.max(cursor - step, min);
+      const measured = measure(next);
+      if (measured.triangleCount <= target) lower = next;
+      else upper = next;
+      if (next === min) break;
+      cursor = next;
+      step *= 2;
+    }
+  }
+
+  if (lower !== null && upper !== null) {
+    let low = Math.min(lower, upper);
+    let high = Math.max(lower, upper);
+    while (high - low > 1) {
+      const middle = Math.floor((low + high) / 2);
+      const measured = measure(middle);
+      if (measured.triangleCount <= target) low = middle;
+      else high = middle;
+    }
+    lower = low;
+    upper = high;
+  }
+
+  const anchors = new Set([min, estimate]);
+  if (lower !== null) anchors.add(lower);
+  if (upper !== null) anchors.add(upper);
+  for (const anchor of anchors) {
+    for (let offset = -neighborhood; offset <= neighborhood; offset += 1) {
+      const resolution = anchor + offset;
+      if (resolution >= min && resolution <= max) measure(resolution);
+    }
+  }
+
+  let selected = selectMeasurement(measurements, target, preference);
+  if (!selected) {
+    for (let resolution = min; resolution <= max && !selected; resolution += 1) {
+      measure(resolution);
+      selected = selectMeasurement(measurements, target, preference);
+    }
+  }
+  if (!selected) {
+    throw new Error(`No non-empty Surface Nets mesh exists between resolutions ${min} and ${max}.`);
+  }
+  return {
+    ...selected,
+    limitedByMinimum: selected.resolution === min && selected.triangleCount > target,
+    samples: [...measurements.values()].sort((left, right) => left.resolution - right.resolution),
+    targetTriangles: target,
+  };
+}
+
+/**
+ * Meshes and plans a deterministic LOD set for a legacy procedural document.
+ * Returned geometries can be passed straight to an exporter; callers that
+ * only need resolutions may set `keepGeometries: false` after validation.
+ * Source-mesh reference documents deliberately fail through meshDocument;
+ * their exact authored LODs are loaded by referenceAssetLoader instead.
+ */
+export function planRockLodMeshes(document, {
+  includeHelpers = false,
+  keepGeometries = true,
+  maxResolution = null,
+  mesh = meshDocument,
+  meshOptions = {},
+  policy: policyOption = null,
+  validate = true,
+} = {}) {
+  if (!document || typeof document !== 'object') {
+    throw new TypeError('planRockLodMeshes requires a rock document.');
+  }
+  if (typeof mesh !== 'function') throw new TypeError('The rock LOD mesh callback must be a function.');
+  const policyHasExplicitBudget = policyOption && typeof policyOption === 'object'
+    && (Object.hasOwn(policyOption, 'triangleBudgets')
+      || Object.hasOwn(policyOption, 'targetTriangles'));
+  let policy = policyOption === null
+    ? createReferenceRockLodPolicyForDocument(document)
+    : resolveReferenceRockLodPolicy(policyOption, {
+      ...(!policyHasExplicitBudget && Number.isFinite(Number(document.reference?.targetTriangles))
+        ? { targetTriangles: Number(document.reference.targetTriangles) }
+        : {}),
+    });
+  const maximum = clampInteger(
+    maxResolution ?? document.meshing?.exportResolution ?? policy.maxResolution,
+    policy.minResolution,
+    policy.maxResolution,
+  );
+  const geometries = new Map();
+  const invalidResolutions = new Set();
+  const measureTriangles = (resolution) => {
+    if (invalidResolutions.has(resolution)) {
+      return { geometry: null, invalid: true, triangleCount: 0 };
+    }
+    if (!geometries.has(resolution)) {
+      try {
+        const geometry = mesh(document, {
+          ...meshOptions,
+          includeHelpers,
+          resolution,
+        });
+        geometries.set(resolution, geometry);
+      } catch (error) {
+        if (!String(error?.message ?? error).includes('produced an empty surface')) throw error;
+        invalidResolutions.add(resolution);
+        return { geometry: null, invalid: true, triangleCount: 0 };
+      }
+    }
+    const geometry = geometries.get(resolution);
+    return { geometry, triangleCount: getGeometryTriangleCount(geometry) };
+  };
+
+  // Very thin or strongly elongated rocks can fall entirely between the
+  // samples of an 8-cell grid. That is a grid limitation, not an empty rock.
+  // If the nominal minimum is empty, scan through the probe neighborhood and
+  // choose the first resolution after the last aliasing gap. Thin shapes can
+  // briefly appear and disappear again (for example at grids 9 and 16), so
+  // stopping at the first non-empty sample is not sufficient.
+  let viableMinimum = policy.minResolution;
+  if (measureTriangles(viableMinimum).invalid) {
+    let lastEmpty = viableMinimum;
+    let consecutiveSurfaces = 0;
+    const scanFloor = Math.min(
+      maximum,
+      Math.max(policy.probeResolution, policy.minResolution + 8),
+    );
+    for (let resolution = policy.minResolution + 1;
+      resolution <= maximum;
+      resolution += 1) {
+      const measurement = measureTriangles(resolution);
+      if (!measurement.invalid) {
+        consecutiveSurfaces += 1;
+      } else {
+        lastEmpty = resolution;
+        consecutiveSurfaces = 0;
+      }
+      if (resolution >= scanFloor && consecutiveSurfaces >= 4) break;
+    }
+    viableMinimum = lastEmpty + 1;
+  }
+  if (viableMinimum > maximum) {
+    throw new Error(
+      `Rock LOD planning could not find a non-empty mesh between resolutions ${policy.minResolution} and ${maximum}.`,
+    );
+  }
+  if (viableMinimum !== policy.minResolution) {
+    policy = resolveReferenceRockLodPolicy({
+      ...policy,
+      minResolution: viableMinimum,
+      probeResolution: Math.max(policy.probeResolution, viableMinimum),
+    });
+  }
+
+  const probeResolution = Math.min(policy.probeResolution, maximum);
+  const probe = measureTriangles(probeResolution);
+  const baseSearch = searchSurfaceNetsResolution({
+    maxResolution: maximum,
+    measureTriangles,
+    minResolution: policy.minResolution,
+    reference: { resolution: probeResolution, triangleCount: probe.triangleCount },
+    targetTriangles: policy.triangleBudgets[0],
+  });
+  // Author LOD0 from a stable probe-or-better surface, then edge-collapse to
+  // the audited budget. Selecting a raw 8-cell mesh merely because it is
+  // under budget can already destroy thin shelves before LOD reduction starts.
+  let sourceResolution = Math.max(probeResolution, baseSearch.resolution);
+  let sourceMeasurement = measureTriangles(sourceResolution);
+  while (sourceMeasurement.invalid && sourceResolution < maximum) {
+    sourceResolution += 1;
+    sourceMeasurement = measureTriangles(sourceResolution);
+  }
+  if (sourceMeasurement.invalid) {
+    sourceResolution = baseSearch.resolution;
+    sourceMeasurement = baseSearch;
+  }
+  const authoredBase = simplifyRockGeometryToTriangleBudget(
+    sourceMeasurement.geometry,
+    policy.triangleBudgets[0],
+  );
+  const baseLevel = {
+    actualRatio: 1,
+    geometry: authoredBase.geometry,
+    level: 0,
+    limitedByMinimum: authoredBase.triangleCount > policy.triangleBudgets[0],
+    method: authoredBase.retainedSource ? 'surface-nets' : 'simplified',
+    removedVertices: authoredBase.removedVertices,
+    reducible: false,
+    resolution: sourceResolution,
+    retainedTopology: false,
+    retentionReason: null,
+    targetRatio: 1,
+    targetTriangles: policy.triangleBudgets[0],
+    triangleBudget: policy.triangleBudgets[0],
+    triangleCount: authoredBase.triangleCount,
+  };
+  const targets = createRockLodTriangleTargets(baseLevel.triangleCount, policy);
+  const levels = [baseLevel];
+
+  for (let index = 1; index < policy.levelCount; index += 1) {
+    const previous = levels[index - 1];
+    const target = targets[index];
+    const simplified = simplifyRockGeometryToTriangleBudget(
+      sourceMeasurement.geometry,
+      target.targetTriangles,
+    );
+    if (!simplified.retainedSource) {
+      matchRockGeometryBounds(simplified.geometry, baseLevel.geometry);
+    }
+    const retainedTopology = simplified.triangleCount >= previous.triangleCount;
+    levels.push({
+      actualRatio: simplified.triangleCount / baseLevel.triangleCount,
+      geometry: simplified.geometry,
+      level: index,
+      limitedByMinimum: simplified.retainedSource && baseLevel.limitedByMinimum,
+      method: simplified.retainedSource ? 'retained' : 'simplified',
+      removedVertices: simplified.removedVertices,
+      reducible: !retainedTopology,
+      resolution: baseLevel.resolution,
+      retainedTopology,
+      retentionReason: retainedTopology
+        ? simplified.retainedSource ? 'minimum-topology' : 'topology-plateau'
+        : null,
+      targetRatio: target.ratio,
+      targetTriangles: target.targetTriangles,
+      triangleBudget: target.triangleBudget,
+      triangleCount: simplified.triangleCount,
+    });
+  }
+
+  const validation = validate
+    ? validateRockLodLevels(levels, { policy })
+    : null;
+  const resultLevels = keepGeometries
+    ? levels
+    : levels.map(({ geometry, ...level }) => level);
+  return {
+    levels: resultLevels,
+    policy,
+    sampledResolutions: [...geometries.keys()].sort((left, right) => left - right),
+    validation,
+  };
+}

package/src/rockgen/lod/rockLodPolicy.js

@@ -0,0 +1,235 @@
+// Legacy procedural-rock LOD policy, calibrated from the reference inventory.
+// Actual source-mesh references bypass this policy and preserve every exact
+// authored LOD; Surface Nets generation uses it only for retained old presets.
+
+export const REFERENCE_ROCK_LOD_RATIOS = Object.freeze([1, 0.5, 0.25]);
+
+// LOD0 ceilings are rounded, modest-headroom versions of the studied asset
+// roles: single boulders peak near 290 triangles, clumps near 850, and the
+// representative cliff near 430. Landmark and hero roles are explicit escape
+// hatches for authored silhouettes that genuinely need more geometry.
+const ROLE_LOD0_BUDGETS = Object.freeze({
+  boulder: 320,
+  cliff: 512,
+  cluster: 960,
+  hero: 4096,
+  landmark: 2048,
+});
+
+function budgetsFromLod0(lod0) {
+  return Object.freeze(REFERENCE_ROCK_LOD_RATIOS.map((ratio) => (
+    Math.max(Math.round(lod0 * ratio), 1)
+  )));
+}
+
+export const REFERENCE_ROCK_LOD_ROLE_BUDGETS = Object.freeze(Object.fromEntries(
+  Object.entries(ROLE_LOD0_BUDGETS).map(([role, lod0]) => [role, budgetsFromLod0(lod0)]),
+));
+
+export const REFERENCE_ROCK_LOD_ROLES = Object.freeze(
+  Object.keys(REFERENCE_ROCK_LOD_ROLE_BUDGETS),
+);
+
+const ROLE_ALIASES = Object.freeze({
+  boulderClump: 'cluster',
+  'boulder-clump': 'cluster',
+  clump: 'cluster',
+  'cliff-piece': 'cliff',
+  cliffFace: 'cliff',
+  'column-piece': 'cliff',
+  'column-rock': 'cliff',
+  'hoodoo-cliff': 'cliff',
+  hoodoo: 'cliff',
+  'layered-rock': 'boulder',
+  'metric-block': 'boulder',
+  'mountain-backdrop': 'landmark',
+  platform: 'cluster',
+  'ridge-clump': 'cluster',
+  rock: 'boulder',
+  'rock-clump': 'cluster',
+  setPiece: 'landmark',
+  shelf: 'cluster',
+  'slanted-rock': 'boulder',
+  spire: 'landmark',
+  'vertical-clump': 'cluster',
+});
+
+function finiteInteger(value, fallback, { max = Infinity, min = -Infinity } = {}) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(Math.max(Math.round(number), min), max);
+}
+
+function finiteNumber(value, fallback, { max = Infinity, min = -Infinity } = {}) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(Math.max(number, min), max);
+}
+
+function normalizeRole(value) {
+  const requested = String(value ?? 'boulder').trim();
+  const role = ROLE_ALIASES[requested] ?? requested;
+  if (!Object.hasOwn(REFERENCE_ROCK_LOD_ROLE_BUDGETS, role)) {
+    throw new Error(
+      `Unknown rock LOD role "${requested}" (expected ${REFERENCE_ROCK_LOD_ROLES.join(', ')}).`,
+    );
+  }
+  return role;
+}
+
+function normalizeRatios(value) {
+  if (!Array.isArray(value) || value.length !== 3) return [...REFERENCE_ROCK_LOD_RATIOS];
+  const ratios = value.map((entry, index) => finiteNumber(
+    entry,
+    REFERENCE_ROCK_LOD_RATIOS[index],
+    { max: 1, min: 0.001 },
+  ));
+  ratios[0] = 1;
+  for (let index = 1; index < ratios.length; index += 1) {
+    ratios[index] = Math.min(ratios[index], ratios[index - 1]);
+  }
+  return ratios;
+}
+
+function normalizeBudgets(value, role, ratios) {
+  const roleBudgets = REFERENCE_ROCK_LOD_ROLE_BUDGETS[role];
+  if (!Array.isArray(value) || value.length !== 3) return [...roleBudgets];
+  const budgets = value.map((entry, index) => finiteInteger(
+    entry,
+    roleBudgets[index],
+    { min: 1 },
+  ));
+  for (let index = 1; index < budgets.length; index += 1) {
+    budgets[index] = Math.min(budgets[index], budgets[index - 1]);
+  }
+  // A custom LOD0-only budget can be expressed by passing [N, null, null].
+  for (let index = 1; index < budgets.length; index += 1) {
+    if (value[index] === null || value[index] === undefined) {
+      budgets[index] = Math.max(Math.round(budgets[0] * ratios[index]), 1);
+    }
+  }
+  return budgets;
+}
+
+/**
+ * Creates a normalized procedural-rock LOD policy with up to three levels.
+ *
+ * Role budgets are hard ceilings when an integer Surface Nets resolution can
+ * attain them. `minResolution` mirrors meshDocument's hard minimum of 8; a
+ * budget below what that grid can represent is reported as minimum-limited,
+ * rather than pretending that the cap was met.
+ */
+export function createReferenceRockLodPolicy(options = {}) {
+  const role = normalizeRole(options.role);
+  const ratios = normalizeRatios(options.ratios);
+  const targetTriangles = Number(options.targetTriangles);
+  const requestedBudgets = options.triangleBudgets ?? (
+    Number.isFinite(targetTriangles) && targetTriangles > 0
+      ? [targetTriangles, null, null]
+      : null
+  );
+  const triangleBudgets = normalizeBudgets(requestedBudgets, role, ratios);
+  const minResolution = finiteInteger(options.minResolution, 8, { max: 320, min: 8 });
+  const maxResolution = finiteInteger(options.maxResolution, 320, {
+    max: 320,
+    min: minResolution,
+  });
+  const probeResolution = finiteInteger(options.probeResolution, 24, {
+    max: maxResolution,
+    min: minResolution,
+  });
+  const silhouetteThreshold = finiteNumber(options.silhouetteThreshold, 0.72, { max: 1, min: 0 });
+  const silhouetteThresholds = Array.isArray(options.silhouetteThresholds)
+    && options.silhouetteThresholds.length === 3
+    ? options.silhouetteThresholds.map((entry, level) => finiteNumber(
+      entry,
+      level === 2 ? Math.max(silhouetteThreshold - 0.02, 0) : silhouetteThreshold,
+      { max: 1, min: 0 },
+    ))
+    : [1, silhouetteThreshold, Math.max(silhouetteThreshold - 0.02, 0)];
+
+  return Object.freeze({
+    allowTinyTopologyRetention: options.allowTinyTopologyRetention !== false,
+    boundsCenterTolerance: finiteNumber(options.boundsCenterTolerance, 0.1, { max: 1, min: 0 }),
+    boundsSizeTolerance: finiteNumber(options.boundsSizeTolerance, 0.18, { max: 1, min: 0 }),
+    levelCount: finiteInteger(options.levelCount, 3, { max: 3, min: 1 }),
+    maxResolution,
+    minResolution,
+    probeResolution,
+    ratioTolerance: finiteNumber(options.ratioTolerance, 0.4, { max: 2, min: 0 }),
+    ratios: Object.freeze(ratios),
+    role,
+    silhouetteGridSize: finiteInteger(options.silhouetteGridSize, 40, { max: 128, min: 12 }),
+    silhouetteThreshold,
+    silhouetteThresholds: Object.freeze(silhouetteThresholds),
+    tinyTriangleThreshold: finiteInteger(options.tinyTriangleThreshold, 96, { min: 0 }),
+    triangleBudgets: Object.freeze(triangleBudgets),
+  });
+}
+
+export function resolveReferenceRockLodPolicy(roleOrPolicy = 'boulder', overrides = {}) {
+  if (typeof roleOrPolicy === 'string' || roleOrPolicy === null || roleOrPolicy === undefined) {
+    return createReferenceRockLodPolicy({ ...overrides, role: roleOrPolicy ?? 'boulder' });
+  }
+  if (typeof roleOrPolicy !== 'object' || Array.isArray(roleOrPolicy)) {
+    throw new TypeError('Rock LOD policy must be a role name or an options object.');
+  }
+  return createReferenceRockLodPolicy({ ...roleOrPolicy, ...overrides });
+}
+
+/**
+ * Resolves catalog/reference metadata without coupling the planner to a
+ * catalog schema. Explicit options win; otherwise `reference.targetTriangles`
+ * becomes LOD0 and the policy derives its half/quarter budgets.
+ */
+export function createReferenceRockLodPolicyForDocument(document, options = {}) {
+  const reference = document?.reference && typeof document.reference === 'object'
+    ? document.reference
+    : {};
+  const explicitBudgets = Object.hasOwn(options, 'triangleBudgets')
+    || Object.hasOwn(options, 'targetTriangles');
+  const referenceLevels = Array.isArray(reference.lodTriangles)
+    ? reference.lodTriangles
+      .slice(0, 3)
+      .map((entry) => finiteInteger(entry, 0, { min: 0 }))
+      .filter((entry) => entry > 0)
+    : [];
+  const exactLevelCount = referenceLevels.length;
+  const exactBudgets = [...referenceLevels];
+  const exactRatios = referenceLevels.map((entry) => entry / referenceLevels[0]);
+  while (exactBudgets.length > 0 && exactBudgets.length < 3) {
+    const level = exactBudgets.length;
+    exactBudgets.push(Math.max(Math.round(exactBudgets[0] * REFERENCE_ROCK_LOD_RATIOS[level]), 1));
+    exactRatios.push(exactBudgets[level] / exactBudgets[0]);
+  }
+  return createReferenceRockLodPolicy({
+    ...(!explicitBudgets && exactLevelCount > 0 ? {
+      levelCount: exactLevelCount,
+      ratios: exactRatios,
+      triangleBudgets: exactBudgets,
+    } : {}),
+    ...options,
+    // Catalog `role` describes inventory use (core form / metric utility /
+    // backdrop); `archetype` describes the geometry budget class. Older
+    // callers may still put the geometry role directly in `reference.role`.
+    role: options.role ?? reference.archetype ?? reference.role ?? 'boulder',
+    ...(!explicitBudgets && exactLevelCount === 0
+      && Number.isFinite(Number(reference.targetTriangles))
+      ? { targetTriangles: Number(reference.targetTriangles) }
+      : {}),
+  });
+}
+
+/** Returns actual triangle targets for a measured LOD0 mesh. */
+export function createRockLodTriangleTargets(lod0Triangles, roleOrPolicy = 'boulder') {
+  const policy = resolveReferenceRockLodPolicy(roleOrPolicy);
+  const base = finiteInteger(lod0Triangles, 1, { min: 1 });
+  return Object.freeze(policy.ratios.map((ratio, level) => Object.freeze({
+    level,
+    ratio,
+    triangleBudget: policy.triangleBudgets[level],
+    targetTriangles: level === 0
+      ? Math.min(base, policy.triangleBudgets[0])
+      : Math.min(Math.max(Math.round(base * ratio), 1), policy.triangleBudgets[level]),
+  })));
+}