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(core): lift TIJ patterns into core (atlas-profiles, candidate-profile, chroma-repair)

Matt Kissinger84e3591bb8fd
diff --git a/imposter/__tests__/atlas-profiles.test.ts b/imposter/__tests__/atlas-profiles.test.ts
new file mode 100644
index 00000000..8aafaad8
--- /dev/null
+++ b/imposter/__tests__/atlas-profiles.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+ ATLAS_PROFILES,
+ ATLAS_PROFILE_NAMES,
+ isAtlasProfileName,
+ validateAgainstAtlasProfile,
+} from '../atlas-profiles';
+
+describe('atlas-profiles catalog', () => {
+ test('exports four named profiles', () => {
+ const names: string[] = [...ATLAS_PROFILE_NAMES];
+ expect(names.sort()).toEqual(
+ ['canopy-balanced', 'canopy-hero', 'ground-compact', 'mid-balanced'],
+ );
+ });
+
+ test('ground-compact does not require normal layer', () => {
+ expect(ATLAS_PROFILES['ground-compact'].normalRequired).toBe(false);
+ });
+
+ test('canopy-* and mid-balanced require normal layer', () => {
+ expect(ATLAS_PROFILES['mid-balanced'].normalRequired).toBe(true);
+ expect(ATLAS_PROFILES['canopy-balanced'].normalRequired).toBe(true);
+ expect(ATLAS_PROFILES['canopy-hero'].normalRequired).toBe(true);
+ });
+
+ test('hero allows the largest tiles', () => {
+ expect(ATLAS_PROFILES['canopy-hero'].maxTileSize).toBe(1024);
+ expect(ATLAS_PROFILES['ground-compact'].maxTileSize).toBe(256);
+ });
+});
+
+describe('isAtlasProfileName', () => {
+ test('accepts the four named profiles', () => {
+ expect(isAtlasProfileName('ground-compact')).toBe(true);
+ expect(isAtlasProfileName('mid-balanced')).toBe(true);
+ expect(isAtlasProfileName('canopy-balanced')).toBe(true);
+ expect(isAtlasProfileName('canopy-hero')).toBe(true);
+ });
+
+ test('rejects non-string and unknown values', () => {
+ expect(isAtlasProfileName('made-up-profile')).toBe(false);
+ expect(isAtlasProfileName(undefined)).toBe(false);
+ expect(isAtlasProfileName(42)).toBe(false);
+ expect(isAtlasProfileName(null)).toBe(false);
+ });
+});
+
+describe('validateAgainstAtlasProfile', () => {
+ test('clean ground-compact meta passes', () => {
+ const result = validateAgainstAtlasProfile(
+ { tileSize: 256, angles: 8 },
+ 'ground-compact',
+ );
+ expect(result.ok).toBe(true);
+ expect(result.violations).toEqual([]);
+ expect(result.profile).toBe('ground-compact');
+ });
+
+ test('flags tileSize over the profile max', () => {
+ const result = validateAgainstAtlasProfile(
+ { tileSize: 1024, angles: 8 },
+ 'ground-compact',
+ );
+ expect(result.ok).toBe(false);
+ expect(result.violations.some((v) => v.field === 'tileSize')).toBe(true);
+ });
+
+ test('flags angles over the profile max', () => {
+ const result = validateAgainstAtlasProfile(
+ { tileSize: 256, angles: 32 },
+ 'ground-compact',
+ );
+ expect(result.ok).toBe(false);
+ expect(result.violations.some((v) => v.field === 'angles')).toBe(true);
+ });
+
+ test('flags missing normal aux layer when required', () => {
+ const result = validateAgainstAtlasProfile(
+ { tileSize: 512, angles: 16, auxLayers: [], normalSpace: 'capture-view' },
+ 'mid-balanced',
+ );
+ expect(result.ok).toBe(false);
+ expect(result.violations.some((v) => v.field === 'normal-aux-layer')).toBe(true);
+ });
+
+ test('flags wrong normalSpace when normal layer is required', () => {
+ const result = validateAgainstAtlasProfile(
+ { tileSize: 512, angles: 16, auxLayers: ['normal'], normalSpace: 'world' },
+ 'canopy-balanced',
+ );
+ expect(result.ok).toBe(false);
+ expect(result.violations.some((v) => v.field === 'normal-space')).toBe(true);
+ });
+
+ test('passes valid canopy-hero meta with normal layer + capture-view space', () => {
+ const result = validateAgainstAtlasProfile(
+ {
+ tileSize: 1024,
+ angles: 32,
+ auxLayers: ['normal'],
+ normalSpace: 'capture-view',
+ },
+ 'canopy-hero',
+ );
+ expect(result.ok).toBe(true);
+ expect(result.limits.maxTileSize).toBe(1024);
+ });
+
+ test('skips numeric checks if fields are absent (read-only validator)', () => {
+ const result = validateAgainstAtlasProfile({}, 'ground-compact');
+ expect(result.ok).toBe(true);
+ });
+});
diff --git a/imposter/atlas-profiles.ts b/imposter/atlas-profiles.ts
new file mode 100644
index 00000000..766ba611
--- /dev/null
+++ b/imposter/atlas-profiles.ts
@@ -0,0 +1,107 @@
+/**
+ * Atlas profile rules for static (lat-lon / hemi-y) imposter bakes.
+ *
+ * Profiles define the maximum tile size, angle count, and whether a normal
+ * aux layer is required for a given imposter "tier" (ground cover vs canopy
+ * etc). Originally lived inline in scripts/validate-tij-vegetation-package.ts;
+ * lifted to core in W6 so non-TIJ consumers can reuse the same contract.
+ *
+ * Species-to-profile mapping stays in the consumer (e.g. TIJ vegetation
+ * pipeline) — profiles describe the *bake contract*, not the catalog.
+ */
+
+export const ATLAS_PROFILES = {
+ 'ground-compact': { maxTileSize: 256, maxAngles: 8, normalRequired: false },
+ 'mid-balanced': { maxTileSize: 512, maxAngles: 16, normalRequired: true },
+ 'canopy-balanced': { maxTileSize: 512, maxAngles: 32, normalRequired: true },
+ 'canopy-hero': { maxTileSize: 1024, maxAngles: 32, normalRequired: true },
+} as const;
+
+export type AtlasProfileName = keyof typeof ATLAS_PROFILES;
+export type AtlasProfileLimits = (typeof ATLAS_PROFILES)[AtlasProfileName];
+
+export const ATLAS_PROFILE_NAMES = Object.keys(ATLAS_PROFILES) as AtlasProfileName[];
+
+export function isAtlasProfileName(value: unknown): value is AtlasProfileName {
+ return typeof value === 'string' && value in ATLAS_PROFILES;
+}
+
+/**
+ * Subset of static-imposter sidecar fields the profile cares about.
+ * Accepts unknown so callers can pass JSON-parsed metadata directly.
+ */
+export interface AtlasProfileMetaInput {
+ tileSize?: unknown;
+ angles?: unknown;
+ auxLayers?: unknown;
+ normalSpace?: unknown;
+}
+
+export type AtlasProfileViolationField =
+ | 'tileSize'
+ | 'angles'
+ | 'normal-aux-layer'
+ | 'normal-space';
+
+export interface AtlasProfileViolation {
+ field: AtlasProfileViolationField;
+ message: string;
+}
+
+export interface AtlasProfileValidationResult {
+ ok: boolean;
+ profile: AtlasProfileName;
+ limits: AtlasProfileLimits;
+ violations: AtlasProfileViolation[];
+}
+
+/**
+ * Validates an imposter sidecar (or atlas metadata) against the named profile.
+ * Returns { ok, violations[] } so callers can render their own error format.
+ *
+ * Read-only. Does not throw — invalid profile names produce a violation list
+ * with `ok: false`. Pass a real `AtlasProfileName` (typed) and you'll get a
+ * clean limits echo on success.
+ */
+export function validateAgainstAtlasProfile(
+ meta: AtlasProfileMetaInput,
+ profile: AtlasProfileName,
+): AtlasProfileValidationResult {
+ const limits = ATLAS_PROFILES[profile];
+ const violations: AtlasProfileViolation[] = [];
+
+ if (typeof meta.tileSize === 'number' && meta.tileSize > limits.maxTileSize) {
+ violations.push({
+ field: 'tileSize',
+ message: `tileSize=${meta.tileSize} exceeds profile ${profile} max ${limits.maxTileSize}`,
+ });
+ }
+ if (typeof meta.angles === 'number' && meta.angles > limits.maxAngles) {
+ violations.push({
+ field: 'angles',
+ message: `angles=${meta.angles} exceeds profile ${profile} max ${limits.maxAngles}`,
+ });
+ }
+ if (limits.normalRequired) {
+ const aux = Array.isArray(meta.auxLayers) ? (meta.auxLayers as unknown[]) : [];
+ if (!aux.includes('normal')) {
+ violations.push({
+ field: 'normal-aux-layer',
+ message: `profile ${profile} requires the 'normal' aux layer`,
+ });
+ }
+ if (meta.normalSpace !== 'capture-view') {
+ violations.push({
+ field: 'normal-space',
+ message: `profile ${profile} requires normalSpace='capture-view' (got ${String(meta.normalSpace)})`,
+ });
+ }
+ }
+
+ return {
+ ok: violations.length === 0,
+ profile,
+ limits,
+ violations,
+ };
+}
diff --git a/imposter/index.ts b/imposter/index.ts
index 71e2d5db..b52bd82f 100644
--- a/imposter/index.ts
+++ b/imposter/index.ts
@@ -12,6 +12,21 @@
export { bakeImposter, openImposterSession } from './bake';
export type { BakeImposterOptions, BakeImposterResult, ImposterSession } from './bake';
+export {
+ ATLAS_PROFILES,
+ ATLAS_PROFILE_NAMES,
+ isAtlasProfileName,
+ validateAgainstAtlasProfile,
+} from './atlas-profiles';
+export type {
+ AtlasProfileLimits,
+ AtlasProfileMetaInput,
+ AtlasProfileName,
+ AtlasProfileValidationResult,
+ AtlasProfileViolation,
+ AtlasProfileViolationField,
+} from './atlas-profiles';
+
export {
IMPOSTER_SCHEMA_VERSION,
ImposterMetaSchema,
diff --git a/index.ts b/index.ts
index 5f8e6fba..fadab75a 100644
--- a/index.ts
+++ b/index.ts
@@ -212,6 +212,12 @@ export type {
AnimatedTileCamera,
BakeAnimatedImposterOptions,
BakeAnimatedImposterResult,
+ AtlasProfileLimits,
+ AtlasProfileMetaInput,
+ AtlasProfileName,
+ AtlasProfileValidationResult,
+ AtlasProfileViolation,
+ AtlasProfileViolationField,
NpcCharacterPackFactionMetrics,
NpcCharacterPackIssue,
NpcCharacterPackManifest,
@@ -231,9 +237,13 @@ export {
AnimatedImposterTextureLayoutSchema,
AnimatedImposterTextureModeSchema,
AnimatedImposterWarningSchema,
+ ATLAS_PROFILES,
+ ATLAS_PROFILE_NAMES,
ImposterMetaSchema,
IMPOSTER_SCHEMA_VERSION,
estimateAnimatedImposterStorage,
+ isAtlasProfileName,
+ validateAgainstAtlasProfile,
validateAnimatedImposterPreBake,
bakeAnimatedImposter,
enumerateOctahedralGrid,