Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

5.4 KB
Raw Blame
/**
 * A delivery derivative with as few draw calls as the asset allows. Every repeated mesh becomes a
 * GPU batch, then the one-off parts left over merge per material within spatial cells, so a viewer
 * can still cull a large asset by region.
 *
 * Unlike `optimize: 'full'` this runs no `palette()`, which rewrites materials, and no `weld()`,
 * which splits the accessors shared parts rely on: on a 16 MB cathedral `weld()` alone added 10 MB.
 * Saved revisions are never rewritten by this pass; `exportAssetGlb` derives from them.
 */
import { type Document, Logger } from '@gltf-transform/core';
import { prune } from '@gltf-transform/functions';
import {
  refreshAtlasDocumentProvenance,
  validateAtlasDocumentProvenance,
} from './atlas-provenance';
import { createGltfIO } from './gltf-io';
import {
  countInstanceBatches,
  instanceByHandedness,
  instancingBlocker,
} from './instance-handedness';
import { collectGlbMetrics } from './metrics';
import { assertFinalGlbValid } from './qa/gltf';
import { mergeRigidGroups, type RigidMergeSummary } from './rigid-merge';

/** Metres. Near the size a viewer's culling can use; set per export with `drawCellSize`. */
export const DEFAULT_DRAW_CELL_SIZE = 15;

/** Two copies already save a draw. The bake pass's higher threshold protects node names. */
const REPEAT_MIN = 2;

/**
 * Metres a merged vertex may move through float32 rounding in its destination frame. The strict
 * default rejects a metre-sized part baked 100 m from its destination, which rounds by about
 * 8 micrometres. 0.1 mm stays far below a pixel at any distance the part is visible from.
 */
const POSITION_TOLERANCE = 1e-4;

export interface DrawReductionV1 {
  drawsBefore: number;
  drawsAfter: number;
  batches: number;
  instances: number;
  /** Why no copy was batched, when something in the asset rules batching out. */
  batchingSkipped?: string;
  /**
   * Each batch node, its mesh and the names of the nodes it replaced, in instance order: copy `i`
   * is the batch's instance `i`. A batched copy loses its mesh, and one with no children or
   * extensions is removed with its name; this is where its geometry went.
   */
  instancing: { node: string; mesh: string; count: number; instances: string[] }[];
  merges: number;
  cellSize: number;
  /** Primitives the merge left alone, by reason. */
  locked: Record<string, number>;
  /** Buckets left as authored because building or checking the join failed. */
  rejected: RigidMergeSummary['rejected'];
}

export function assertDrawCellSize(cellSize: number): void {
  if (!Number.isFinite(cellSize) || cellSize <= 0)
    throw new Error('The draw cell size must be a positive number of metres');
}

/** Reduce a finished document's draw calls in place. */
export async function reduceDrawCalls(
  doc: Document,
  options: { cellSize?: number } = {},
): Promise<DrawReductionV1> {
  const cellSize = options.cellSize ?? DEFAULT_DRAW_CELL_SIZE;
  assertDrawCellSize(cellSize);
  // Transform progress must not corrupt CLI JSON on stdout.
  doc.setLogger(new Logger(Logger.Verbosity.WARN));
  const drawsBefore = collectGlbMetrics(doc).drawCalls;

  const batchingSkipped = instancingBlocker(doc);
  const created = batchingSkipped ? [] : await instanceByHandedness(doc, REPEAT_MIN);
  const { batches, instances } = countInstanceBatches(doc);
  // `instance()` leaves batch nodes unnamed. Naming each after its first copy, uniquely, makes it
  // addressable whether or not the exporter named the mesh.
  const names = new Set(
    doc
      .getRoot()
      .listNodes()
      .map((node) => node.getName()),
  );
  const instancing = created.map(({ node, instances: copies }) => {
    const mesh = node.getMesh()?.getName() ?? '';
    const base = `${copies[0] || mesh || 'Mesh'}_Instances`;
    let name = base;
    for (let k = 1; names.has(name); k++) name = `${base}_${k}`;
    names.add(name);
    node.setName(name);
    return { node: name, mesh, count: copies.length, instances: copies };
  });

  // Repeats are batches now. A copy left over shares its mesh with a batch, and baking it would
  // duplicate geometry; mixed into a bucket it can also push the join past the vertex limit,
  // which strands the true one-offs beside it. Only meshes with a single user merge.
  const merge = mergeRigidGroups(doc, {
    cellSize,
    positionTolerance: POSITION_TOLERANCE,
    expandSharedMeshes: false,
  });
  await doc.transform(prune({ keepLeaves: true, keepExtras: true, keepSolidTextures: true }));

  const locked: Record<string, number> = {};
  for (const { reason, primitives } of merge.locked)
    locked[reason] = (locked[reason] ?? 0) + primitives;
  return {
    drawsBefore,
    drawsAfter: collectGlbMetrics(doc).drawCalls,
    batches,
    instances,
    ...(batchingSkipped ? { batchingSkipped } : {}),
    instancing,
    merges: merge.merges,
    cellSize,
    locked,
    rejected: merge.rejected,
  };
}

/** {@link reduceDrawCalls} over GLB bytes, validated before they are handed back. */
export async function reduceGlbDrawCalls(
  bytes: Uint8Array,
  options: { cellSize?: number } = {},
): Promise<{ glb: Uint8Array; summary: DrawReductionV1 }> {
  const io = createGltfIO();
  const doc = await io.readBinary(bytes);
  await validateAtlasDocumentProvenance(doc);
  const summary = await reduceDrawCalls(doc, options);
  await refreshAtlasDocumentProvenance(doc);
  await validateAtlasDocumentProvenance(doc);
  const glb = await io.writeBinary(doc);
  await assertFinalGlbValid(glb);
  return { glb, summary };
}