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.

docs: give every hero its own render instead of one collage

Matt Kissingerc92fca444cf3
diff --git a/README.md b/README.md
index a5a67fe7..c9a42f74 100644
--- a/README.md
+++ b/README.md
@@ -6,22 +6,35 @@ Kiln turns a sentence into a game-ready GLB by having a model *write a program*,
rendered, and fix it — not by sampling a mesh. The output is a small program with named parts, not
an opaque blob: editable, diffable, parametric, and readable by the next agent that touches it.
-![Seven assets built by Kiln: a field gun, a street lamp, a diving helmet, a penny-farthing, a walking mech, an arcade cabinet and a sushi yatai](examples/gallery.png)
-
-Every asset above is a checked-in program in [`examples/`](examples/). No mesh was sampled, no
-geometry was hand-authored, and none of it was touched in a DCC tool. A model wrote each one,
-rendered it, looked at the result, and revised — which is also why each file's header comment reads
-like a post-mortem.
-
-| Asset | Tris | Authored by | What it exists to show |
-|---|---|---|---|
-| [`field-gun`](examples/field-gun.kiln.js) | 15,544 | Claude Opus 5 | booleans and arrays |
-| [`street-lamp`](examples/street-lamp.kiln.js) | 13,036 | Claude Opus 5 | revolved profiles, emissive + glass |
-| [`diving-helmet`](examples/diving-helmet.kiln.js) | 16,416 | Claude Opus 5 | material contrast |
-| [`penny-farthing`](examples/penny-farthing.kiln.js) | 12,450 | Claude Opus 5 | curves and radial arrays |
-| [`mech`](examples/mech.kiln.js) | 18,398 | Claude Opus 5 | armour oriented along a bone |
-| [`arcade-cabinet`](examples/arcade-cabinet.kiln.js) | 19,916 | **Gemini 3.8 Flash** | silhouette from a swept profile |
-| [`sushi-yatai`](examples/sushi-yatai.kiln.js) | 27,538 | Claude Opus 5 | repetition without looking generated |
+Ten hero assets, each one a checked-in program in [`examples/`](examples/). Click any image for
+the full-size render. No mesh was sampled, no geometry was hand-authored, and none of it was
+touched in a DCC tool. A model wrote each program, rendered it, looked at the result, and revised
+— which is also why each file's header comment reads like a post-mortem.
+
+<table>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/field-gun.png"><img src="examples/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris &middot; Claude Opus 5<br><sub>booleans and arrays</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/street-lamp.png"><img src="examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris &middot; Claude Opus 5<br><sub>revolved profiles, emissive + glass</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/diving-helmet.png"><img src="examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris &middot; Claude Opus 5<br><sub>material contrast</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/penny-farthing.png"><img src="examples/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris &middot; Claude Opus 5<br><sub>curves and radial arrays</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/mech.png"><img src="examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="examples/mech.kiln.js">mech</a></b><br>18,398 tris &middot; Claude Opus 5<br><sub>armour oriented along a bone</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/arcade-cabinet.png"><img src="examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris &middot; <b>Gemini 3.8 Flash</b><br><sub>silhouette from a swept profile</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/sushi-store.png"><img src="examples/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris &middot; Claude Opus 5<br><sub>a facade as layered depth</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/cafe-racer.png"><img src="examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,410 tris &middot; Claude Opus 5<br><sub>a tapered sweep along a curve</sub></td>
+ <td width="33%" valign="top"><a href="examples/renders/beam-engine.png"><img src="examples/renders/beam-engine.png" alt="a rotative beam engine, generated by Kiln"></a><br><b><a href="examples/beam-engine.kiln.js">beam-engine</a></b><br>15,396 tris &middot; Claude Opus 5<br><sub>an animated four-bar linkage</sub></td>
+</tr>
+<tr>
+ <td width="33%" valign="top"><a href="examples/renders/lunar-lander.png"><img src="examples/renders/lunar-lander.png" alt="a lunar module on four legs, generated by Kiln"></a><br><b><a href="examples/lunar-lander.kiln.js">lunar-lander</a></b><br>13,208 tris &middot; Claude Opus 5<br><sub>crumpled foil, and asymmetry on purpose</sub></td>
+</tr>
+</table>
+
+Every shot above is regenerated by `bun scripts/hero-shots.ts`, straight from the checked-in
+programs through the same PBR render port the agent loop uses. Nothing in this README was
+retouched.
The arcade cabinet is the one that matters most here. It was authored end to end by a **different
vendor's model in a different harness** — Gemini 3.8 Flash driving the same plugin through the
diff --git a/examples/gallery.png b/examples/gallery.png
deleted file mode 100644
index 4b4a3a39..00000000
Binary files a/examples/gallery.png and /dev/null differ
diff --git a/scripts/hero-shots.ts b/scripts/hero-shots.ts
new file mode 100644
index 00000000..2bf73e34
--- /dev/null
+++ b/scripts/hero-shots.ts
@@ -0,0 +1,140 @@
+/**
+ * Render one beauty shot per hero example into `examples/renders/`.
+ *
+ * The README used to carry a single stitched contact-sheet collage. That was
+ * the wrong artifact for two reasons: every asset got the same 380 px cell no
+ * matter how much detail it had, and a reader who wanted to look closely at one
+ * of them had no way to. So each hero now gets its own full-size PNG.
+ *
+ * This goes through the same PBR render port the `kiln render --views` path
+ * uses, at a larger per-view size and with no cell label or axis gnomon, so the
+ * output is a picture of the asset rather than a diagnostic sheet.
+ *
+ * bun scripts/hero-shots.ts # every hero
+ * bun scripts/hero-shots.ts mech lunar-lander
+ * bun scripts/hero-shots.ts --size 1400 --cpu
+ *
+ * Renders come off the port as raw RGB PNGs -- 8 MB each at 1200 px, which is
+ * not something to put ten of in a git history for a README to load. They are
+ * downscaled once and re-encoded at full compression on the way out, which is
+ * also a free supersample: a 1200 px render shown at 1000 px is antialiased.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import sharp from 'sharp';
+
+import { captureViewPngsViaPort } from '../src/agent/generate';
+import { buildRenderPort } from '../src/cli-render-mode';
+import { resolveEvaluatorPortV1 } from '../src/evaluator/protocol';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, '..');
+const EXAMPLES = join(REPO, 'examples');
+const OUT_DIR = join(EXAMPLES, 'renders');
+
+/**
+ * The hero set, in the order the README presents them.
+ *
+ * Kept as an explicit list rather than a glob of `examples/*.kiln.js`, because
+ * the examples directory also holds the small teaching programs (crate, well)
+ * that are deliberately NOT heroes and should not appear in the gallery.
+ */
+const HEROES = [
+ 'field-gun',
+ 'diving-helmet',
+ 'penny-farthing',
+ 'street-lamp',
+ 'mech',
+ 'arcade-cabinet',
+ 'sushi-store',
+ 'cafe-racer',
+ 'beam-engine',
+ 'lunar-lander',
+] as const;
+
+/**
+ * Slightly higher and further round than the contact sheet's 3/4 cell.
+ *
+ * The diagnostic 3/4 sits at [0.7, 0.5, 0.7] because it has to keep the front
+ * readable next to five other cells. A single hero shot has no such duty, so it
+ * can take the angle that actually flatters a silhouette: a touch more azimuth
+ * to open up the side, a touch less elevation so the asset is not looked down
+ * on. `zoom` is the frame padding — 1.06 leaves a hair of air at the edges.
+ */
+const HERO_DIR: [number, number, number] = [0.82, 0.44, 0.58];
+const HERO_ZOOM = 1.06;
+
+/** Width the shot is published at. Render size stays higher, for the downsample. */
+const DISPLAY_PX = 1000;
+
+function parseArgs(argv: string[]): { names: string[]; size: number; cpu: boolean } {
+ const names: string[] = [];
+ let size = 1200;
+ let cpu = false;
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]!;
+ if (a === '--size') size = Number(argv[++i]);
+ else if (a === '--cpu') cpu = true;
+ else if (a.startsWith('-')) throw new Error(`unknown flag ${a}`);
+ else names.push(a.replace(/\.kiln\.js$/, ''));
+ }
+ if (!Number.isFinite(size) || size < 64 || size > 4096) {
+ throw new Error(`--size must be between 64 and 4096, got ${size}`);
+ }
+ return { names: names.length ? names : [...HEROES], size, cpu };
+}
+
+async function main(): Promise<void> {
+ const { names, size, cpu } = parseArgs(process.argv.slice(2));
+ await mkdir(OUT_DIR, { recursive: true });
+
+ const context = await buildRenderPort(cpu ? 'cpu' : 'auto', undefined);
+ if (!context.viewRenderPort) {
+ // The CPU rasterizer is geometry-flat: it draws shape, not materials. That
+ // is the right fallback for an in-loop diagnostic and the wrong one for a
+ // gallery image, so say so rather than quietly shipping grey renders.
+ console.warn('no GPU render port — shots will be geometry-flat, not material-faithful');
+ }
+ const evaluator = resolveEvaluatorPortV1(undefined, 'trusted-local');
+
+ for (const name of names) {
+ const src = join(EXAMPLES, `${name}.kiln.js`);
+ const code = await readFile(src, 'utf8');
+ const rendered = await evaluator.render(code);
+
+ let png: Uint8Array | undefined;
+ if (context.viewRenderPort) {
+ const ported = await captureViewPngsViaPort(
+ context.viewRenderPort,
+ rendered.glb,
+ context.viewRenderTimeoutMs ?? 120_000,
+ [HERO_DIR],
+ size,
+ );
+ if (ported.ok) png = ported.pngs[0];
+ else console.warn(` ${name}: port declined (${ported.reason}), falling back to CPU`);
+ }
+ if (!png) {
+ const { renderGlbViewGrid } = await import('../src/views');
+ const grid = await renderGlbViewGrid(rendered.glb, {
+ capture: { preset: '1x1', cells: [{ azimuthDeg: 35, elevationDeg: 26, zoom: HERO_ZOOM }] },
+ });
+ png = grid.png;
+ }
+
+ const encoded = await sharp(Buffer.from(png))
+ .resize(DISPLAY_PX)
+ .png({ compressionLevel: 9, effort: 10 })
+ .toBuffer();
+ const out = join(OUT_DIR, `${name}.png`);
+ await writeFile(out, encoded);
+ console.log(
+ ` ${basename(out)} ${DISPLAY_PX}px ${(encoded.byteLength / 1024).toFixed(0)} KB` +
+ ` (from ${(png.byteLength / 1024 / 1024).toFixed(1)} MB raw)`,
+ );
+ }
+}
+
+await main();