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.

Fix palette snapping for render previews

Matt Kissingerda2fd3adc27e
diff --git a/src/__tests__/scene-palette.test.ts b/src/__tests__/scene-palette.test.ts
index ac0eb456..034b7b6f 100644
--- a/src/__tests__/scene-palette.test.ts
+++ b/src/__tests__/scene-palette.test.ts
@@ -22,7 +22,12 @@ import {
} from '../render';
import { collectGlbMetrics } from '../metrics';
import { hexToLinearRgb, buildSlotIndex, chooseSlot } from '../palette-snap';
-import { renderPaletteDirective, OPTIMIZED_PALETTE } from '../palette';
+import {
+ renderPaletteDirective,
+ OPTIMIZED_PALETTE,
+ GENERAL_RENDER_PALETTE,
+ paletteToSnapSlots,
+} from '../palette';
const hue = (i: number, n: number): number => new THREE.Color().setHSL(i / n, 0.7, 0.5).getHex();
@@ -84,6 +89,20 @@ describe('palette-snap (pure)', () => {
expect(chooseSlot(idx, { baseLinear: [0.5, 0.6, 0.7], transparent: true })).toBe(1);
expect(chooseSlot(idx, { baseLinear: [0.05, 0.05, 0.05] })).toBe(0); // opaque fallback
});
+
+ it('general render palette keeps dark foliage green and bark brown', () => {
+ const slots = paletteToSnapSlots(GENERAL_RENDER_PALETTE);
+ const idx = buildSlotIndex(slots);
+ const pickName = (hex: string): string | undefined => {
+ const slotI = chooseSlot(idx, { baseLinear: hexToLinearRgb(hex) });
+ return slotI === undefined ? undefined : GENERAL_RENDER_PALETTE[slotI]?.name;
+ };
+
+ expect(pickName('#2d5a27')).toBe('leaf-dark');
+ expect(pickName('#35503a')).toBe('leaf-dark');
+ expect(pickName('#556b2f')).toBe('leaf-olive');
+ expect(pickName('#4a3424')).toBe('bark');
+ });
});
describe('snapGlbToPalette', () => {
diff --git a/src/palette-snap.ts b/src/palette-snap.ts
index c4d4008c..81ca9a58 100644
--- a/src/palette-snap.ts
+++ b/src/palette-snap.ts
@@ -24,8 +24,16 @@ export interface SnapSlot {
color: string;
/** Defaults to 'opaque'. transparent→glass, emissive→glow. */
kind?: SnapSlotKind;
+ /** Optional PBR values applied by material-bake callers. */
+ metalness?: number;
+ roughness?: number;
+ /** Opacity for glass slots. */
+ opacity?: number;
}
+/** Public palette slot shape shared by GLB snapping and CPU preview snapping. */
+export type SnapPaletteSlot = SnapSlot;
+
export type Vec3 = [number, number, number];
// ── sRGB → linear. Matches three's SRGBToLinear (the gamma transfer function),
diff --git a/src/palette.ts b/src/palette.ts
index c4fda6e9..e9a5e146 100644
--- a/src/palette.ts
+++ b/src/palette.ts
@@ -19,6 +19,8 @@
* never drift.
*/
+import type { SnapPaletteSlot } from './palette-snap';
+
/** One material role in the canonical palette. A PBR spec the directive names and
* a future shared palette texture bakes from. */
export interface PaletteSlot {
@@ -43,7 +45,7 @@ export interface PaletteSlot {
}
/**
- * The canonical 19-slot palette covering war / city / fantasy / sci-fi / organic /
+ * The canonical 22-slot palette covering war / city / fantasy / sci-fi / organic /
* character domains. Stable order; values are tunable. `glass` is the only
* transparent slot and `glow` the only emissive — keeping the alpha-mode story
* simple (opaque everything + the one glass slot).
@@ -204,8 +206,52 @@ export const OPTIMIZED_PALETTE: readonly PaletteSlot[] = [
emissive: true,
use: 'lamps, neon, fire cores, vfx — the ONE emissive slot',
},
+ {
+ index: 19,
+ name: 'leaf-dark',
+ color: '#2f5a2a',
+ metalness: 0.0,
+ roughness: 0.9,
+ use: 'dark evergreen leaves, shadowed foliage, conifers',
+ },
+ {
+ index: 20,
+ name: 'leaf-olive',
+ color: '#586a30',
+ metalness: 0.0,
+ roughness: 0.9,
+ use: 'olive foliage, dry leaves, canvas greens',
+ },
+ {
+ index: 21,
+ name: 'bark',
+ color: '#46301f',
+ metalness: 0.0,
+ roughness: 0.85,
+ use: 'tree bark, dark roots, rough brown wood',
+ },
];
+/**
+ * Default snap target for optimized/theme render policy. It aliases the canonical
+ * optimized palette so GLBs and CPU previews share one material-color contract when
+ * a caller explicitly chooses palette coherence over faithful source colors.
+ */
+export const GENERAL_RENDER_PALETTE: readonly PaletteSlot[] = OPTIMIZED_PALETTE;
+
+/** Convert authoring palette slots into the snap shape used by GLB + CPU preview bakes. */
+export function paletteToSnapSlots(
+ slots: readonly PaletteSlot[] = GENERAL_RENDER_PALETTE,
+): SnapPaletteSlot[] {
+ return slots.map((s) => ({
+ color: s.color,
+ kind: s.transparent ? 'glass' : s.emissive ? 'glow' : 'opaque',
+ metalness: s.metalness,
+ roughness: s.roughness,
+ ...(s.opacity !== undefined ? { opacity: s.opacity } : {}),
+ }));
+}
+
/**
* Render the authoring directive appended to the agent prompt when the
* "Optimized palette" toggle is on (or a custom scene palette is chosen). Natural-
diff --git a/src/render.ts b/src/render.ts
index fe6818aa..d596190e 100644
--- a/src/render.ts
+++ b/src/render.ts
@@ -24,7 +24,13 @@ import {
mergeDocuments,
} from '@gltf-transform/functions';
-import { buildSlotIndex, chooseSlot, hexToLinearRgb, type SnapSlot } from './palette-snap';
+import {
+ buildSlotIndex,
+ chooseSlot,
+ hexToLinearRgb,
+ type SnapSlot,
+ type SnapPaletteSlot,
+} from './palette-snap';
import { buildSandboxGlobals, countTriangles } from './primitives';
import {
@@ -77,6 +83,7 @@ const TYPE_VEC4: AccessorTypeStr = 'VEC4';
* from GLB bytes, so it travels in provenance. See plan/05-product-depth.md §3.4.
*/
export type AssetRole = 'ground' | 'building' | 'wonder' | 'poi' | 'prop' | 'fill' | 'vehicle';
+export type { SnapPaletteSlot } from './palette-snap';
export interface KilnCodeMeta {
name?: string;
@@ -983,18 +990,6 @@ export async function optimizeGlbBytes(
// Palette snap (scene palettes) — web-side hard snap to a user-defined palette
// =============================================================================
-/** One slot the GLB snap targets: a color + kind + optional PBR/opacity. */
-export interface SnapPaletteSlot {
- /** sRGB hex (e.g. `#9fc9a3`). */
- color: string;
- /** Defaults to 'opaque'. transparent material → glass, emissive → glow. */
- kind?: 'opaque' | 'glass' | 'glow';
- metalness?: number;
- roughness?: number;
- /** Opacity for a glass slot (default 0.4). */
- opacity?: number;
-}
-
/** Result of {@link snapGlbToPalette}. */
export interface SnapGlbResult {
/** The snapped + consolidated GLB bytes. */
diff --git a/src/views/__tests__/views.test.ts b/src/views/__tests__/views.test.ts
index 7c498cf3..02c3bcd9 100644
--- a/src/views/__tests__/views.test.ts
+++ b/src/views/__tests__/views.test.ts
@@ -8,9 +8,12 @@ import {
renderInteriorGrid,
hideNodeInScene,
SIX_VIEWS,
+ snapSceneToPalette,
} from '../index';
import { encodePng } from '../png';
import { executeKilnCode } from '../../render';
+import { GENERAL_RENDER_PALETTE, paletteToSnapSlots } from '../../palette';
+import { hexToLinearRgb } from '../../palette-snap';
const BOX_CODE = `
const meta = { name: 'test-box', category: 'prop' };
@@ -21,6 +24,15 @@ function build() {
}
`;
+const DARK_FOLIAGE_CODE = `
+const meta = { name: 'dark-foliage', category: 'environment' };
+function build() {
+ const root = createRoot('Root');
+ createPart('Mesh_Leaf', boxGeo(1, 1, 1), gameMaterial('#2d5a27'), { parent: root, position: [0, 0.5, 0] });
+ return root;
+}
+`;
+
// Elongated along +X (correct kiln frame for a "forward" asset).
const LONG_X_CODE = `
const meta = { name: 'long-x', category: 'prop' };
@@ -159,6 +171,29 @@ describe('renderViewGrid / renderCodeViewGrid', () => {
const result = await renderViewGrid(root, { size: 32 });
expect(result.png.length).toBeGreaterThan(100);
});
+
+ test('snapSceneToPalette applies the general render palette before CPU previews', async () => {
+ const { root } = await executeKilnCode(DARK_FOLIAGE_CODE);
+ const snap = snapSceneToPalette(root, paletteToSnapSlots(GENERAL_RENDER_PALETTE));
+ expect(snap.snapped).toBe(1);
+ expect(snap.skipped).toBe(0);
+
+ let color: { r: number; g: number; b: number } | undefined;
+ (
+ root as {
+ traverse: (
+ cb: (obj: { isMesh?: boolean; material?: { color?: typeof color } }) => void,
+ ) => void;
+ }
+ ).traverse((obj) => {
+ if (obj.isMesh && obj.material?.color) color = obj.material.color;
+ });
+
+ const expected = hexToLinearRgb('#2f5a2a');
+ expect(color?.r).toBeCloseTo(expected[0], 5);
+ expect(color?.g).toBeCloseTo(expected[1], 5);
+ expect(color?.b).toBeCloseTo(expected[2], 5);
+ });
});
// A roof group (named 'Roof') of child meshes — the rasterizer culls per-mesh, so
diff --git a/src/views/index.ts b/src/views/index.ts
index 4e94ec05..54b0dd4f 100644
--- a/src/views/index.ts
+++ b/src/views/index.ts
@@ -29,6 +29,13 @@ import {
stampLabel,
type DuckClip,
} from './pose';
+import {
+ buildSlotIndex,
+ chooseSlot,
+ hexToLinearRgb,
+ type SnapPaletteSlot,
+ type Vec3,
+} from '../palette-snap';
export { rasterizeView, measureBounds, hideNodeInScene, SIX_VIEWS, coverage } from './raster';
export type { RasterOptions, ViewSpec } from './raster';
@@ -48,6 +55,120 @@ export {
const PAD = 4;
const PAD_COLOR: [number, number, number] = [10, 11, 13];
+interface DuckColor {
+ r: number;
+ g: number;
+ b: number;
+}
+
+interface DuckMaterial {
+ color?: DuckColor;
+ emissive?: DuckColor;
+ emissiveIntensity?: number;
+ transparent?: boolean;
+ opacity?: number;
+ metalness?: number;
+ roughness?: number;
+ map?: unknown;
+ vertexColors?: boolean;
+}
+
+interface DuckMesh {
+ isMesh?: boolean;
+ material?: DuckMaterial | DuckMaterial[];
+}
+
+interface DuckObject3D {
+ traverse?: (cb: (obj: DuckMesh) => void) => void;
+}
+
+export interface ScenePaletteSnapResult {
+ snapped: number;
+ skipped: number;
+}
+
+function setLinearColor(color: DuckColor | undefined, rgb: Vec3): void {
+ if (!color) return;
+ color.r = rgb[0];
+ color.g = rgb[1];
+ color.b = rgb[2];
+}
+
+function snapMaterialToPalette(
+ mat: DuckMaterial,
+ slots: readonly SnapPaletteSlot[],
+ idx: ReturnType<typeof buildSlotIndex>,
+): boolean | undefined {
+ if (!mat.color) return undefined;
+ if (mat.map || mat.vertexColors) return false;
+
+ const emissive =
+ mat.emissive && (mat.emissiveIntensity ?? 1) > 0
+ ? ([
+ mat.emissive.r * (mat.emissiveIntensity ?? 1),
+ mat.emissive.g * (mat.emissiveIntensity ?? 1),
+ mat.emissive.b * (mat.emissiveIntensity ?? 1),
+ ] as Vec3)
+ : undefined;
+ const slotI = chooseSlot(idx, {
+ baseLinear: [mat.color.r, mat.color.g, mat.color.b],
+ ...(emissive ? { emissiveLinear: emissive } : {}),
+ transparent: mat.transparent === true || (mat.opacity !== undefined && mat.opacity < 0.98),
+ });
+ if (slotI === undefined) return false;
+
+ const slot = slots[slotI]!;
+ const kind = slot.kind ?? 'opaque';
+ const rgb = hexToLinearRgb(slot.color);
+ setLinearColor(mat.color, rgb);
+ if (mat.metalness !== undefined) mat.metalness = slot.metalness ?? 0;
+ if (mat.roughness !== undefined)
+ mat.roughness = slot.roughness ?? (kind === 'glass' ? 0.1 : 0.85);
+
+ if (kind === 'glass') {
+ mat.transparent = true;
+ mat.opacity = slot.opacity ?? 0.4;
+ } else {
+ if (mat.transparent !== undefined) mat.transparent = false;
+ if (mat.opacity !== undefined) mat.opacity = 1;
+ }
+
+ if (mat.emissive) {
+ if (kind === 'glow') {
+ setLinearColor(mat.emissive, rgb);
+ mat.emissiveIntensity = Math.max(mat.emissiveIntensity ?? 1, 1);
+ } else {
+ setLinearColor(mat.emissive, [0, 0, 0]);
+ if (mat.emissiveIntensity !== undefined) mat.emissiveIntensity = 0;
+ }
+ }
+ return true;
+}
+
+/** Snap flat-color scene materials to a palette before CPU preview rasterization. */
+export function snapSceneToPalette(
+ root: unknown,
+ slots: readonly SnapPaletteSlot[],
+): ScenePaletteSnapResult {
+ if (slots.length === 0) return { snapped: 0, skipped: 0 };
+ const traverse = (root as DuckObject3D | undefined)?.traverse;
+ if (!traverse) return { snapped: 0, skipped: 0 };
+
+ const idx = buildSlotIndex(slots);
+ let snapped = 0;
+ let skipped = 0;
+ traverse.call(root, (obj: DuckMesh) => {
+ if (!obj.isMesh || !obj.material) return;
+ const materials = Array.isArray(obj.material) ? obj.material : [obj.material];
+ for (const mat of materials) {
+ const didSnap = snapMaterialToPalette(mat, slots, idx);
+ if (didSnap === true) snapped++;
+ else if (didSnap === false) skipped++;
+ }
+ });
+ return { snapped, skipped };
+}
+
export interface ViewGridResult {
png: Buffer;
width: number;
@@ -58,6 +179,8 @@ export interface ViewGridResult {
export interface ViewGridOptions extends RasterOptions {
views?: ViewSpec[];
+ /** Snap flat-color materials before rasterization. Mutates the provided scene root. */
+ snapPalette?: readonly SnapPaletteSlot[];
}
/** Render a (possibly sandbox-created) Three.js scene root into the 3x2 grid. */
@@ -67,6 +190,7 @@ export async function renderViewGrid(
): Promise<ViewGridResult> {
const size = opts.size ?? 256;
const views = opts.views ?? SIX_VIEWS;
+ if (opts.snapPalette?.length) snapSceneToPalette(root, opts.snapPalette);
const cols = 3;
const rows = Math.ceil(views.length / cols);
const width = cols * size + (cols + 1) * PAD;