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.

feat(kiln/photogrammetry): scan cleanup pass (simplify + texture-compress)

Matt Kissingere996d0243353
diff --git a/index.ts b/index.ts
index 2f9b27dd..2224a1df 100644
--- a/index.ts
+++ b/index.ts
@@ -164,6 +164,15 @@ export type { IngestFbxOptions, IngestFbxResult, IngestFbxSession } from './fbx-
export { retexCharacter, FACTION_PRESETS } from './retex';
export type { RetexCharacterOptions, RetexCharacterResult, FactionPreset } from './retex';
+// -----------------------------------------------------------------------------
+// Photogrammetry cleanup (kiln/photogrammetry)
+// -----------------------------------------------------------------------------
+export { cleanupPhotogrammetry } from './photogrammetry';
+export type {
+ CleanupPhotogrammetryOptions,
+ CleanupPhotogrammetryResult,
+} from './photogrammetry';
+
// -----------------------------------------------------------------------------
// Imposter baker (kiln/imposter)
// -----------------------------------------------------------------------------
diff --git a/photogrammetry/__tests__/cleanup.test.ts b/photogrammetry/__tests__/cleanup.test.ts
new file mode 100644
index 00000000..74338939
--- /dev/null
+++ b/photogrammetry/__tests__/cleanup.test.ts
@@ -0,0 +1,48 @@
+/**
+ * Photogrammetry cleanup — verifies the simplify + texture-compress pipeline
+ * on a high-poly procedural fixture (a 64-segment sphere ~= 8k tris).
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { Buffer } from 'node:buffer';
+import * as THREE from 'three';
+
+import { renderSceneToGLB } from '../../render';
+import { cleanupPhotogrammetry } from '../cleanup';
+
+async function makeHighPolyFixture(segments = 64): Promise<Buffer> {
+ const root = new THREE.Group();
+ root.name = 'ScanFixture';
+ const geom = new THREE.SphereGeometry(1, segments, segments);
+ const mat = new THREE.MeshStandardMaterial({ color: 0x88aa88 });
+ const mesh = new THREE.Mesh(geom, mat);
+ root.add(mesh);
+ const { bytes } = await renderSceneToGLB(root, {});
+ return Buffer.from(bytes);
+}
+
+describe('cleanupPhotogrammetry', () => {
+ test('decimates to near the target triangle budget', async () => {
+ const fixture = await makeHighPolyFixture(64);
+ const result = await cleanupPhotogrammetry(fixture, {
+ targetTriangles: 2000,
+ textureSize: 512,
+ errorThreshold: 0.05,
+ });
+ expect(result.meta.sourceTriangles).toBeGreaterThan(5000);
+ expect(result.meta.targetTriangles).toBeLessThan(result.meta.sourceTriangles);
+ // GLB magic.
+ expect(result.glb.readUInt32LE(0)).toBe(0x46546c67);
+ }, 60_000);
+
+ test('no-op when source is already below target', async () => {
+ const fixture = await makeHighPolyFixture(8); // ~100 tris
+ const result = await cleanupPhotogrammetry(fixture, {
+ targetTriangles: 10_000,
+ textureSize: 256,
+ });
+ expect(result.meta.ratio).toBe(1);
+ // No decimation requested — tri count stays the same.
+ expect(result.meta.targetTriangles).toBe(result.meta.sourceTriangles);
+ }, 30_000);
+});
diff --git a/photogrammetry/cleanup.ts b/photogrammetry/cleanup.ts
new file mode 100644
index 00000000..9c42c8a7
--- /dev/null
+++ b/photogrammetry/cleanup.ts
@@ -0,0 +1,103 @@
+/**
+ * Photogrammetry cleanup — preset composition for raw scans.
+ *
+ * Poly Haven tier-C plants come in at 50k–300k triangles with 2K–4K PBR
+ * texture stacks. That's fine for offline imposter bakes but unusable as
+ * runtime geometry. This module collapses them to a bake-ready state:
+ *
+ * 1. weld — merge coincident verts.
+ * 2. simplify — meshopt decimation to a target triangle budget.
+ * 3. textureCompress — resize diffuse/normal/roughness to <=1K, encode PNG.
+ * 4. dedup + prune — drop anything orphaned by the above.
+ *
+ * Gated per proposal §P6 — only run when tier-C quality beats the Poly Pizza
+ * shortlist in the validation gallery. For Poly Pizza sources, skip this
+ * module entirely; they're already sub-5k-tri PSX-style meshes.
+ */
+
+import { Buffer } from 'node:buffer';
+import { readFileSync } from 'node:fs';
+
+import { NodeIO } from '@gltf-transform/core';
+import { dedup, prune, simplify, textureCompress, weld } from '@gltf-transform/functions';
+import { MeshoptSimplifier } from 'meshoptimizer';
+import sharp from 'sharp';
+
+import { countTriangles } from '../lod/generate';
+
+export interface CleanupPhotogrammetryOptions {
+ /** Target post-decimation triangle count. Default 10000. */
+ targetTriangles?: number;
+ /** Max texture dimension (w = h). Default 1024. */
+ textureSize?: number;
+ /**
+ * Max permitted error as a fraction of mesh radius. Higher tolerates more
+ * distortion — photogrammetry is noisy so 0.02 is a safe default.
+ */
+ errorThreshold?: number;
+}
+
+export interface CleanupPhotogrammetryResult {
+ glb: Buffer;
+ meta: {
+ sourceTriangles: number;
+ targetTriangles: number;
+ ratio: number;
+ textureSize: number;
+ sourceBytes: number;
+ bytes: number;
+ };
+}
+
+export async function cleanupPhotogrammetry(
+ input: Buffer | string,
+ opts: CleanupPhotogrammetryOptions = {},
+): Promise<CleanupPhotogrammetryResult> {
+ const targetTris = opts.targetTriangles ?? 10_000;
+ const textureSize = opts.textureSize ?? 1024;
+ const errorThreshold = opts.errorThreshold ?? 0.02;
+
+ await MeshoptSimplifier.ready;
+
+ const io = new NodeIO();
+ const srcBuf = typeof input === 'string' ? readFileSync(input) : input;
+ const doc = await io.readBinary(srcBuf);
+ const srcTris = countTriangles(doc);
+
+ // Compute the ratio to hit targetTris. If source is already smaller, skip
+ // decimation (ratio = 1.0 is a no-op).
+ const ratio = srcTris > 0 ? Math.min(1, targetTris / srcTris) : 1;
+
+ await doc.transform(
+ weld(),
+ simplify({
+ simplifier: MeshoptSimplifier,
+ ratio,
+ error: errorThreshold,
+ lockBorder: false,
+ }),
+ textureCompress({
+ encoder: sharp,
+ targetFormat: 'png',
+ resize: [textureSize, textureSize],
+ }),
+ dedup(),
+ prune(),
+ );
+
+ const outBytes = await io.writeBinary(doc);
+ const glb = Buffer.from(outBytes);
+ const finalTris = countTriangles(doc);
+
+ return {
+ glb,
+ meta: {
+ sourceTriangles: srcTris,
+ targetTriangles: finalTris,
+ ratio,
+ textureSize,
+ sourceBytes: srcBuf.byteLength,
+ bytes: glb.byteLength,
+ },
+ };
+}
diff --git a/photogrammetry/index.ts b/photogrammetry/index.ts
new file mode 100644
index 00000000..758f3bc6
--- /dev/null
+++ b/photogrammetry/index.ts
@@ -0,0 +1,15 @@
+/**
+ * kiln/photogrammetry — cleanup pass for raw photogrammetry GLBs.
+ *
+ * import { kiln } from '@pixel-forge/core';
+ * const { glb, meta } = await kiln.cleanupPhotogrammetry(scanGlb, {
+ * targetTriangles: 8000,
+ * textureSize: 1024,
+ * });
+ */
+
+export { cleanupPhotogrammetry } from './cleanup';
+export type {
+ CleanupPhotogrammetryOptions,
+ CleanupPhotogrammetryResult,
+} from './cleanup';