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.

11.6 KB
Raw Blame
import type * as THREE from 'three';

export type GeometryExportPolicy = 'warn' | 'strict';
export const EXPORTED_GEOMETRY_ATTRIBUTES: Readonly<Record<string, number | readonly number[]>> = {
  position: 3,
  normal: 3,
  uv: 2,
  uv1: 2,
  tangent: 4,
  color: [3, 4],
  // Delivery contract custom attributes (bakeSurfaceAttributes), written as _EDGE/_CAVITY.
  _edge: 1,
  _cavity: 1,
};

/** Custom float attributes both converters write: three.js name to glTF name. */
export const CUSTOM_EXPORT_ATTRIBUTES: Readonly<Record<string, string>> = {
  _edge: '_EDGE',
  _cavity: '_CAVITY',
};

/**
 * Author attributes: a lowercase three.js name such as `_wet` is written by both converters as a
 * float glTF attribute `_WET`, which GLTFLoader reads back as `_wet`. Other names would not
 * round-trip, so they stay unsupported.
 */
export const AUTHOR_ATTRIBUTE_PATTERN = /^_[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
export const AUTHOR_ATTRIBUTE_COMPONENTS: readonly number[] = [1, 2, 3, 4];
const AUTHOR_ATTRIBUTE_MAX_NAME = 64;

/** glTF semantic for a three.js custom attribute name, or null when it is not one. */
export function customAttributeSemantic(key: string): string | null {
  if (key.length > AUTHOR_ATTRIBUTE_MAX_NAME || !AUTHOR_ATTRIBUTE_PATTERN.test(key)) return null;
  return CUSTOM_EXPORT_ATTRIBUTES[key] ?? key.toUpperCase();
}

/** Material texture slots whose UV channel export must preserve. */
const TEXTURE_SLOTS = [
  'map',
  'normalMap',
  'roughnessMap',
  'metalnessMap',
  'aoMap',
  'emissiveMap',
] as const;

const THREE_GEOMETRY_ATTRIBUTES = {
  ...EXPORTED_GEOMETRY_ATTRIBUTES,
  uv2: 2,
  uv3: 2,
  skinIndex: 4,
  skinWeight: 4,
} as const;

/** Shared by export validation and host capability discovery. */
export function geometryExportAttributes(
  exporter: 'legacy' | 'three',
): Readonly<Record<string, number | readonly number[]>> {
  return exporter === 'three' ? THREE_GEOMETRY_ATTRIBUTES : EXPORTED_GEOMETRY_ATTRIBUTES;
}

/** Both converters require a complete, non-overlapping triangle partition. */
export function validateMaterialGroups(
  geometry: THREE.BufferGeometry,
  materialCount: number,
  name: string,
) {
  const length = geometry.getIndex()?.count ?? geometry.getAttribute('position').count;
  const groups = [...geometry.groups].sort((a, b) => a.start - b.start);
  let covered = 0;
  for (const group of groups) {
    const materialIndex = group.materialIndex ?? 0;
    if (
      group.start !== covered ||
      !Number.isInteger(group.start) ||
      !Number.isInteger(group.count) ||
      group.count <= 0 ||
      group.start % 3 ||
      group.count % 3 ||
      group.start + group.count > length ||
      !Number.isInteger(materialIndex) ||
      materialIndex < 0 ||
      materialIndex >= materialCount
    )
      throw new TypeError(
        `${name}: material groups must cover every triangle exactly once with valid material indices.`,
      );
    covered = group.start + group.count;
  }
  if (covered !== length)
    throw new TypeError(`${name}: material groups do not cover every triangle.`);
  return groups;
}

/** Read logical values, including interleaved stride/offset and normalized integer attributes. */
export function geometryAttributeValues(
  attribute: THREE.BufferAttribute | THREE.InterleavedBufferAttribute,
): Float32Array<ArrayBuffer> {
  const values = new Float32Array(attribute.count * attribute.itemSize);
  for (let vertex = 0; vertex < attribute.count; vertex++) {
    for (let component = 0; component < attribute.itemSize; component++) {
      values[vertex * attribute.itemSize + component] = attribute.getComponent(vertex, component);
    }
  }
  return values;
}

/** The glTF validator's tolerance for unit-length NORMAL vectors. */
const UNIT_NORMAL_TOLERANCE = 0.0005;

/**
 * Written NORMAL values, each off-unit vector scaled to unit length. A shader normalises before
 * it lights, so the image is unchanged; the validator rejects the file without this. Vectors
 * within tolerance keep their exact bytes. Inspection has already refused zero-length vectors.
 */
export function unitNormalValues(
  attribute: THREE.BufferAttribute | THREE.InterleavedBufferAttribute,
): Float32Array<ArrayBuffer> {
  const values = geometryAttributeValues(attribute);
  for (let i = 0; i < values.length; i += 3) {
    const length = Math.hypot(values[i]!, values[i + 1]!, values[i + 2]!);
    if (Math.abs(length - 1) <= UNIT_NORMAL_TOLERANCE || length === 0) continue;
    for (let component = 0; component < 3; component++) values[i + component]! /= length;
  }
  return values;
}

/** Count off-unit normals; a zero-length normal has no direction to keep, so it fails. */
function offUnitNormals(
  normal: THREE.BufferAttribute | THREE.InterleavedBufferAttribute,
  name: string,
): number {
  let count = 0;
  for (let vertex = 0; vertex < normal.count; vertex++) {
    const length = Math.hypot(normal.getX(vertex), normal.getY(vertex), normal.getZ(vertex));
    if (length < 1e-6)
      throw new TypeError(
        `${name}: normal at vertex ${vertex} has zero length, so it has no direction to export. Build revolved profiles with lathe or revolveGeo, or recompute the normals with creaseNormals.`,
      );
    if (Math.abs(length - 1) > UNIT_NORMAL_TOLERANCE) count++;
  }
  return count;
}

/** One helper note (a code and message, or a legacy string) and the meshes that carry it. */
type GeometryNoteGroup = {
  code?: string;
  text?: string;
  meshes: Set<THREE.Object3D>;
  names: string[];
};

const NOTE_NAMES_SHOWN = 3;

/** Name the first few distinct meshes; repeated names carry a count instead of repeating. */
function noteMeshList(names: readonly string[]): string {
  const counts = new Map<string, number>();
  for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
  const shown = [...counts].slice(0, NOTE_NAMES_SHOWN);
  const covered = shown.reduce((sum, [, count]) => sum + count, 0);
  const parts = shown.map(([name, count]) => (count > 1 ? `${name} x${count}` : name));
  if (names.length > covered) parts.push(`+${names.length - covered} more`);
  return parts.join(', ');
}

function formatNoteGroup({ code, text, names }: GeometryNoteGroup): string {
  if (code === undefined) {
    const who = names.length === 1 ? names[0] : `${names.length} meshes (${noteMeshList(names)})`;
    return `${who}: ${text}`;
  }
  if (names.length === 1) return `${names[0]}: ${code}${text === undefined ? '' : ` ${text}`}`;
  return `${code} (${names.length} meshes: ${noteMeshList(names)})${text === undefined ? '' : `: ${text}`}`;
}

/** Check export data before bounds, texture baking or GLB conversion can obscure its origin. */
export function inspectGeometryExport(
  root: THREE.Object3D,
  policy: GeometryExportPolicy = 'warn',
  exporter: 'legacy' | 'three' = 'legacy',
): string[] {
  // Helper notes repeat on every mesh a helper built. One line per distinct note, in order of
  // first occurrence, keeps a 17-part loft from producing 17 identical warnings.
  const warnings: (string | GeometryNoteGroup)[] = [];
  const noteGroups = new Map<string, GeometryNoteGroup>();
  const addNote = (mesh: THREE.Object3D, name: string, code?: string, text?: string) => {
    const key = JSON.stringify([code ?? null, text ?? null]);
    let group = noteGroups.get(key);
    if (!group) {
      group = { code, text, meshes: new Set(), names: [] };
      noteGroups.set(key, group);
      warnings.push(group);
    }
    if (group.meshes.has(mesh)) return;
    group.meshes.add(mesh);
    group.names.push(name);
  };
  const attributes = geometryExportAttributes(exporter);
  root.traverse((node) => {
    const mesh = node as THREE.Mesh;
    if (!mesh.isMesh) return;
    const geometry = mesh.geometry;
    const name = mesh.name || '<unnamed mesh>';
    const unsupported = (feature: string, hint = '') => {
      const message = `EXPORT_ATTRIBUTE_UNSUPPORTED ${name}: ${feature} is not preserved by the GLB bridge.${hint}`;
      if (policy === 'strict') throw new TypeError(message);
      warnings.push(message);
    };
    const position = geometry.getAttribute('position');
    if (position?.itemSize !== 3) throw new TypeError(`${name}: position requires xyz vertices.`);
    for (const [key, attribute] of Object.entries(geometry.attributes)) {
      const expected =
        attributes[key] ?? (customAttributeSemantic(key) ? AUTHOR_ATTRIBUTE_COMPONENTS : undefined);
      if (expected === undefined) {
        unsupported(
          key,
          key.startsWith('_')
            ? ' Author attributes use a lowercase name such as _wet (exported as _WET) with 1 to 4 float components.'
            : '',
        );
        continue;
      }
      const sizes = typeof expected === 'number' ? [expected] : expected;
      if (!sizes.includes(attribute.itemSize) || attribute.count !== position.count) {
        throw new TypeError(
          `${name}: ${key} requires ${position.count} vertices with ${sizes.join(' or ')} components each.`,
        );
      }
      for (let vertex = 0; vertex < attribute.count; vertex++) {
        for (let component = 0; component < attribute.itemSize; component++) {
          if (!Number.isFinite(attribute.getComponent(vertex, component))) {
            throw new TypeError(`${name}: ${key} contains a non-finite value at vertex ${vertex}.`);
          }
        }
      }
    }
    const normal = geometry.getAttribute('normal');
    const offUnit = normal?.itemSize === 3 ? offUnitNormals(normal, name) : 0;
    if (offUnit > 0)
      addNote(
        mesh,
        name,
        'NORMALS_NORMALISED',
        `${offUnit} non-unit normals were scaled to unit length on export.`,
      );
    const index = geometry.getIndex();
    if ((index?.count ?? position.count) % 3 !== 0)
      throw new TypeError(`${name}: triangle indices/vertices must be a multiple of three.`);
    if (index) {
      for (let i = 0; i < index.count; i++) {
        const value = index.getX(i);
        if (!Number.isInteger(value) || value < 0 || value >= position.count)
          throw new TypeError(`${name}: index ${i} is outside the position attribute.`);
      }
    }
    // A texture's UV channel must reach the GLB, or it would silently sample UV0.
    for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
      for (const slot of TEXTURE_SLOTS) {
        const texture = (material as unknown as Record<string, THREE.Texture | null | undefined>)[
          slot
        ];
        const channel = texture?.isTexture ? (texture.channel ?? 0) : 0;
        if (channel === 0) continue;
        const uv = `uv${channel}`;
        if (attributes[uv] === undefined) unsupported(`${slot} UV channel ${channel}`);
        else if (!geometry.getAttribute(uv))
          throw new TypeError(`${name}: ${slot} samples ${uv}, which the geometry lacks.`);
      }
    }
    if (exporter === 'three' && Array.isArray(mesh.material))
      validateMaterialGroups(geometry, mesh.material.length, name);
    if (exporter === 'legacy') {
      for (const key of Object.keys(geometry.morphAttributes)) unsupported(`morph ${key}`);
      if ((mesh as THREE.SkinnedMesh).isSkinnedMesh) unsupported('skinning');
    }
    for (const key of ['kilnAttributeWarnings', 'kilnGeometryWarnings']) {
      const notes: unknown = geometry.userData[key];
      if (!Array.isArray(notes)) continue;
      for (const note of notes) {
        if (typeof note === 'string') addNote(mesh, name, undefined, note);
        else if (note && typeof note === 'object' && 'code' in note)
          addNote(
            mesh,
            name,
            String(note.code),
            'message' in note ? String(note.message) : undefined,
          );
      }
    }
  });
  return warnings.map((warning) =>
    typeof warning === 'string' ? warning : formatNoteGroup(warning),
  );
}