Skip to content

3D engine that AI agents drive

20.9 KB
Raw Blame
// Icon sheets: the pure part of the `icons` render job (docs/agent-render-jobs.md, "Icons"). Validation of the job settings, the camera
// and light rig, the framing arithmetic that fits one silhouette, the atlas layout and the icons.json manifest. No browser, no files.
import { invalidField } from './field-error.js';
import { BREAKDOWN_ORDER, SKETCH_CAPABILITIES, normalizeSketchSettings, seedFrom, sketchPass } from './icon-sketch.js';

export const ICON_LIMITS = Object.freeze({
  maximumItems: 256,
  sizes: Object.freeze([64, 128, 256, 512]),
  styles: Object.freeze(['clean', 'toon', 'sketch']),
  scales: Object.freeze(['fit', 'relative']),
  angles: Object.freeze([1, 4, 8]),
  maximumFrames: 256,
  maximumAtlasSide: 4096,
  minimumPadding: 0.02,
  maximumPadding: 0.4,
  defaultPadding: 0.08,
  defaultView: Object.freeze({ azimuth: 35, elevation: 25 }),
  maximumElevation: 89,
});

/** What `icons` leaves out of this release, named so an error can say it is coming and not that it is unknown. */
const COMING_FIELDS = Object.freeze({
  lighting: 'an HDRI rig (the three-point rig is fixed)',
  background: 'a background colour (icons are transparent)',
  outline: 'an outline colour and width',
});

const ASSET_ID = /^[0-9a-f]{64}$/;
const URL_SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
const DERIVED_FIELDS = ['width', 'height', 'fps', 'duration', 'transparent'];
const SETTING_FIELDS = ['kind', 'items', 'size', 'style', 'viewpoint', 'scale', 'padding', 'angles', 'breakdown', 'seed', 'sketch', ...DERIVED_FIELDS];
const SKETCH_ONLY_FIELDS = ['sketch', 'seed'];
const MAXIMUM_ITEM_LENGTH = 260;

export const ICON_ARTIFACTS = Object.freeze({ atlas: 'atlas.png', manifest: 'icons.json' });

export function iconArtifactName(index) {
  return `icon-${index}.png`;
}

/** The breakdown strip of one item. The job folder is flat, so the item number is in the name and not in a folder. */
export function breakdownArtifactName(itemIndex) {
  return `breakdown-${itemIndex}.png`;
}

/**
 * Every artifact of an icons job, in the order the runner writes them: one PNG per frame (an item at one angle), the breakdown
 * strip of each item when asked, the atlas, then icons.json. `options.itemCount` names how many items get a strip; leave it out for none.
 */
export function iconArtifactNames(frameCount, options = {}) {
  const frames = Array.from({ length: frameCount }, (_, index) => iconArtifactName(index));
  const strips = Array.from({ length: options.itemCount ?? 0 }, (_, index) => breakdownArtifactName(index));
  return [...frames, ...strips, ICON_ARTIFACTS.atlas, ICON_ARTIFACTS.manifest];
}

/** How many items fit one atlas at this size: a square grid no wider than the atlas limit. */
export function atlasCapacity(size) {
  return (ICON_LIMITS.maximumAtlasSide / size) ** 2;
}

/**
 * How many items one job takes at this size and angle count. One angle packs a square grid. More angles give each item a row
 * of its own (one cell per angle), so the rows must fit the atlas side, and so must the cells of a row.
 */
export function itemCapacity(size, angles) {
  if (angles === 1) return Math.min(ICON_LIMITS.maximumFrames, atlasCapacity(size));
  if (angles * size > ICON_LIMITS.maximumAtlasSide) return 0;
  return Math.min(Math.floor(ICON_LIMITS.maximumFrames / angles), Math.floor(ICON_LIMITS.maximumAtlasSide / size));
}

function itemFrom(item, position) {
  const label = `items[${position}]`;
  if (typeof item === 'string') item = { source: item };
  if (!item || Object.getPrototypeOf(item) !== Object.prototype || typeof item.source !== 'string') {
    throw invalidField(label, typeof item, 'a catalog GLB name from scene_asset_catalog, such as "sword.glb", or its 64 hexadecimal asset id', TypeError);
  }
  const source = item.source;
  if (!source || source.length > MAXIMUM_ITEM_LENGTH) {
    throw invalidField(label, `${source.length} characters`, `a catalog GLB name of 1 to ${MAXIMUM_ITEM_LENGTH} characters`, RangeError);
  }
  if (URL_SCHEME.test(source)) {
    throw invalidField(label, source.slice(0, 60), 'a catalog GLB name from scene_asset_catalog (inside --assets or --packs); remote URLs are not accepted', RangeError);
  }
  if (item.asset !== undefined && (typeof item.asset !== 'string' || !ASSET_ID.test(item.asset))) {
    throw invalidField(`${label}.asset`, String(item.asset).slice(0, 20), 'the 64 hexadecimal characters of a catalog asset id', RangeError);
  }
  return item.asset === undefined ? { source } : { source, asset: item.asset };
}

function viewFrom(view) {
  if (view === undefined || view === 'three-quarter') return { ...ICON_LIMITS.defaultView };
  if (!view || Object.getPrototypeOf(view) !== Object.prototype) {
    throw invalidField('viewpoint', typeof view, '"three-quarter" or { azimuth, elevation } in degrees', TypeError);
  }
  for (const key of Object.keys(view)) {
    if (!['azimuth', 'elevation'].includes(key)) throw invalidField(`viewpoint.${key}`, 'an unknown field', 'only azimuth and elevation, in degrees', TypeError);
  }
  const azimuth = view.azimuth ?? ICON_LIMITS.defaultView.azimuth;
  const elevation = view.elevation ?? ICON_LIMITS.defaultView.elevation;
  if (!Number.isFinite(azimuth) || azimuth < -180 || azimuth > 180) throw invalidField('viewpoint.azimuth', azimuth, 'degrees from -180 to 180', RangeError);
  if (!Number.isFinite(elevation) || Math.abs(elevation) > ICON_LIMITS.maximumElevation) {
    throw invalidField('viewpoint.elevation', elevation, `degrees from -${ICON_LIMITS.maximumElevation} to ${ICON_LIMITS.maximumElevation}`, RangeError);
  }
  return { azimuth, elevation };
}

/**
 * The settings of an icons job as the store keeps them, every default filled in and every limit checked. `items` may be bare
 * strings (the caller's form) or `{ source, asset }` (the pinned form the runtime stores, where `asset` is the catalog id).
 * It also fills the frame fields the rest of the job store reads (width, height, fps, duration), so an icons job has a size
 * and a frame count like any other job: one frame per item.
 */
export function normalizeIconSettings(input) {
  if (!input || Object.getPrototypeOf(input) !== Object.prototype) throw new TypeError('settings must be a plain object.');
  for (const key of Object.keys(input)) {
    if (COMING_FIELDS[key] !== undefined) {
      throw invalidField(`settings.${key}`, 'a field the first icons release leaves out', `no ${key}: ${COMING_FIELDS[key]} is coming (issue #2031)`, RangeError);
    }
    if (!SETTING_FIELDS.includes(key)) {
      throw new TypeError(`Unknown settings field: ${key}. Allowed fields for kind icons: ${SETTING_FIELDS.filter(field => !DERIVED_FIELDS.includes(field)).join(', ')}.`);
    }
  }
  if (!Array.isArray(input.items) || input.items.length < 1 || input.items.length > ICON_LIMITS.maximumItems) {
    throw invalidField('items', Array.isArray(input.items) ? input.items.length : typeof input.items, `a list of 1 to ${ICON_LIMITS.maximumItems} catalog GLB names (the count of items it holds is shown when it is a list)`, RangeError);
  }
  const size = input.size ?? 256;
  if (!ICON_LIMITS.sizes.includes(size)) throw invalidField('size', size, `one of ${ICON_LIMITS.sizes.join(', ')} (pixels per icon side)`, RangeError);
  const angles = input.angles ?? 1;
  if (!ICON_LIMITS.angles.includes(angles)) throw invalidField('angles', String(angles), `one of ${ICON_LIMITS.angles.join(', ')} (views around the item; 4 and 8 give a turnaround row per item)`, RangeError);
  const capacity = itemCapacity(size, angles);
  if (input.items.length > capacity) {
    const reason = angles === 1 ? `the atlas side is capped at ${ICON_LIMITS.maximumAtlasSide} px` : `${angles} angles make one row of ${angles} icons per item, and a job holds ${ICON_LIMITS.maximumFrames} icons and an atlas side of ${ICON_LIMITS.maximumAtlasSide} px`;
    throw invalidField('items', input.items.length, `at most ${capacity} items at size ${size} with ${angles} angle${angles === 1 ? '' : 's'} (${reason}), or a smaller size or fewer angles`, RangeError);
  }
  const style = input.style ?? 'clean';
  if (!ICON_LIMITS.styles.includes(style)) throw invalidField('style', String(style), `one of ${ICON_LIMITS.styles.join(', ')}`, RangeError);
  if (style !== 'sketch') {
    for (const field of SKETCH_ONLY_FIELDS) {
      if (input[field] !== undefined) throw invalidField(field, 'a field of the sketch style', `no ${field} unless style is "sketch" (the style is ${style})`, RangeError);
    }
  }
  if (input.breakdown !== undefined && typeof input.breakdown !== 'boolean') throw invalidField('breakdown', typeof input.breakdown, 'true or false', TypeError);
  const breakdown = input.breakdown ?? false;
  if (breakdown && style !== 'sketch') {
    throw invalidField('breakdown', 'true', `a style that is drawn in steps: set style to "sketch" (the style is ${style}); clean and toon have no steps to show`, RangeError);
  }
  const scale = input.scale ?? 'fit';
  if (!ICON_LIMITS.scales.includes(scale)) throw invalidField('scale', String(scale), `fit (every item fills its frame) or relative (one scale for the set)`, RangeError);
  const padding = input.padding ?? ICON_LIMITS.defaultPadding;
  if (!Number.isFinite(padding) || padding < ICON_LIMITS.minimumPadding || padding > ICON_LIMITS.maximumPadding) {
    throw invalidField('padding', padding, `a fraction of the icon side from ${ICON_LIMITS.minimumPadding} to ${ICON_LIMITS.maximumPadding}`, RangeError);
  }
  const items = input.items.map(itemFrom);
  const settings = {
    kind: 'icons', size, width: size, height: size, fps: 1, duration: 1, frameCount: items.length * angles, transparent: true,
    items, style, viewpoint: viewFrom(input.viewpoint), scale, padding, angles,
  };
  if (breakdown) settings.breakdown = true;
  if (style === 'sketch') Object.assign(settings, { sketch: normalizeSketchSettings(input.sketch), seed: seedFrom(input.seed) });
  return settings;
}

/** The azimuth of the k-th of `angles` views around the item, in degrees from -180 to 180, starting at the base azimuth. */
export function turnaroundAzimuth(baseAzimuth, angleIndex, angles) {
  const turned = (baseAzimuth + angleIndex * 360 / angles) % 360;
  return turned > 180 ? turned - 360 : turned <= -180 ? turned + 360 : turned;
}

/**
 * Every icon the job draws, item by item and angle by angle (the order of icon-<n>.png and of the atlas): the item, the angle
 * number and the view. An item at one angle is one frame.
 */
export function iconFrames(settings) {
  return settings.items.flatMap((item, itemIndex) => Array.from({ length: settings.angles }, (_, angleIndex) => ({
    itemIndex,
    angleIndex,
    view: { azimuth: turnaroundAzimuth(settings.viewpoint.azimuth, angleIndex, settings.angles), elevation: settings.viewpoint.elevation },
  })));
}

/** The lowercase unit vector from the subject toward the camera, and the camera's right and up axes, for a azimuth and elevation in degrees. */
export function cameraBasis({ azimuth, elevation }) {
  const azimuthRadians = azimuth * Math.PI / 180;
  const elevationRadians = elevation * Math.PI / 180;
  const toCamera = [Math.sin(azimuthRadians) * Math.cos(elevationRadians), Math.sin(elevationRadians), Math.cos(azimuthRadians) * Math.cos(elevationRadians)];
  const right = [Math.cos(azimuthRadians), 0, -Math.sin(azimuthRadians)];
  const up = [
    toCamera[1] * right[2] - toCamera[2] * right[1],
    toCamera[2] * right[0] - toCamera[0] * right[2],
    toCamera[0] * right[1] - toCamera[1] * right[0],
  ];
  return { toCamera, right, up };
}

/** A framing that holds the whole bounding sphere: the first guess, before any silhouette is measured. */
export function sphereFraming(bounds) {
  const center = [0, 1, 2].map(axis => (bounds.min[axis] + bounds.max[axis]) / 2);
  const radius = Math.max(1e-6, Math.hypot(...[0, 1, 2].map(axis => (bounds.max[axis] - bounds.min[axis]) / 2)));
  return { center, radius, orthoScale: radius * 2 };
}

/** The orthographic camera of a framing: square view, `orthoScale` metres tall, looking at the center along the view direction. */
export function cameraForFraming(framing, view) {
  const { toCamera } = cameraBasis(view);
  const distance = framing.radius * 3;
  return {
    eye: framing.center.map((value, axis) => value + toCamera[axis] * distance),
    target: [...framing.center],
    up: [0, 1, 0],
    projection: 'orthographic',
    orthoScale: framing.orthoScale,
    near: Math.max(0.001, distance - framing.radius * 1.1),
    far: distance + framing.radius * 1.1,
  };
}

/**
 * The fixed three-point rig: a key from above the camera's left, a fill and a rim from the studio's two fill lights, and a soft
 * ambient term. The key direction follows the view, so every icon of a set is lit from the same side of its own picture.
 */
export function lightRigEnvironment(view) {
  const { toCamera, right, up } = cameraBasis(view);
  const lightDirection = [0, 1, 2].map(axis => -right[axis] * 0.55 + up[axis] * 0.7 + toCamera[axis] * 0.6);
  const length = Math.hypot(...lightDirection);
  // No ground and no sky: an icon is the item alone on a transparent background.
  return { ground: false, world: false, lightDirection: lightDirection.map(value => value / length), keyIntensity: 1, fillIntensity: 0.6, ambientIntensity: 0.7 };
}

/** The line width of the toon style in output pixels: the same share of the picture at every size. */
export function toonLineWidth(size) {
  return Math.max(0.75, size / 128);
}

/**
 * The scene recipe that draws one catalog asset as an icon: the asset at the origin, the light rig, line art for toon, and for
 * sketch the sketch user pass. `sketch` and `seed` are the job's normalized settings; `stage` is a step of the breakdown strip.
 */
export function iconRecipe({ assetId, style, view, size, sketch, seed = 0, stage = 'final' }) {
  const environment = lightRigEnvironment(view);
  if (style === 'toon') environment.lines = { width: toonLineWidth(size), toon: 3 };
  const recipe = { format: 'crucible.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [{ id: 'icon', asset: { id: assetId } }], environment };
  if (style === 'sketch') recipe.postPasses = [sketchPass({ settings: { sketch, seed }, size, stage })];
  return recipe;
}

/** The sketch pass of one breakdown step, for `set-post-passes` on a session that already holds the item. */
export function sketchStagePass({ sketch, seed, size, stage }) {
  return sketchPass({ settings: { sketch, seed }, size, stage });
}

/** The steps of a breakdown strip, left to right. */
export const BREAKDOWN_STEPS = BREAKDOWN_ORDER;

/** The pixel box of the pixels whose alpha passes `threshold`, with exclusive right and bottom, or null when nothing is drawn. */
export function alphaBounds(rgba, width, height, threshold = 1) {
  let left = width;
  let top = height;
  let right = -1;
  let bottom = -1;
  for (let row = 0; row < height; row++) {
    for (let column = 0; column < width; column++) {
      if (rgba[(row * width + column) * 4 + 3] < threshold) continue;
      if (column < left) left = column;
      if (column > right) right = column;
      if (row < top) top = row;
      if (row > bottom) bottom = row;
    }
  }
  return right < 0 ? null : { left, top, right: right + 1, bottom: bottom + 1 };
}

/**
 * The framing that puts a measured silhouette in the middle of its icon. `fixedScale` keeps the view height (the relative
 * scale of a set); without it the view height changes so the longer side of the silhouette spans the icon minus its padding.
 * The view is orthographic, so a box measured in the picture maps back to the view plane by a plain ratio.
 */
export function refineFraming(framing, box, { size, view, padding, fixedScale }) {
  const metresPerPixel = framing.orthoScale / size;
  const { right, up } = cameraBasis(view);
  const shiftRight = ((box.left + box.right) / 2 - size / 2) * metresPerPixel;
  const shiftUp = -((box.top + box.bottom) / 2 - size / 2) * metresPerPixel;
  const center = framing.center.map((value, axis) => value + right[axis] * shiftRight + up[axis] * shiftUp);
  const extent = Math.max(box.right - box.left, box.bottom - box.top);
  const fitScale = framing.orthoScale * extent / (size * (1 - 2 * padding));
  return { center, radius: framing.radius, orthoScale: Math.max(framing.radius * 0.02, fixedScale ?? fitScale) };
}

/** Whether a silhouette sits in its frame: centred within a pixel, inside the edges, and (for `fit`) spanning the padded side within 2 pixels. */
export function isFramed(box, { size, padding, fit = true }) {
  const centeredColumn = Math.abs((box.left + box.right) / 2 - size / 2) <= 1;
  const centeredRow = Math.abs((box.top + box.bottom) / 2 - size / 2) <= 1;
  const inside = box.left >= 1 && box.top >= 1 && box.right <= size - 1 && box.bottom <= size - 1;
  if (!inside || !centeredColumn || !centeredRow) return false;
  if (!fit) return true;
  const extent = Math.max(box.right - box.left, box.bottom - box.top);
  return Math.abs(extent - size * (1 - 2 * padding)) <= 2;
}

/** The view height of the whole set at one scale: the largest fitted view height, so the biggest item fills its icon and the rest stay smaller. */
export function relativeScale(fittedScales) {
  return Math.max(...fittedScales);
}

/** A grid of cells, row by row: the atlas rectangle of every frame. Near square unless `columns` is given (a turnaround sheet has one column per angle). */
export function layoutAtlas(count, size, columns = Math.ceil(Math.sqrt(count))) {
  const rows = Math.ceil(count / columns);
  const rectangles = Array.from({ length: count }, (_, index) => ({ x: index % columns * size, y: Math.floor(index / columns) * size, width: size, height: size }));
  return { columns, rows, width: columns * size, height: rows * size, rectangles };
}

/** Unique, file-safe names for the items: the file name without folder or extension, with the item number added to a repeat. */
export function iconNames(sources) {
  const bases = sources.map(source => (source.split(/[\\/]/).pop() ?? source).replace(/\.glb$/i, '').replace(/[^A-Za-z0-9._-]+/g, '-') || 'item');
  const counts = new Map();
  for (const base of bases) counts.set(base, (counts.get(base) ?? 0) + 1);
  return bases.map((base, index) => (counts.get(base) > 1 ? `${base}-${index}` : base));
}

/** The icons.json document: plain JSON a game engine or web page reads without a converter. */
export function iconManifest({ settings, layout, entries }) {
  const names = iconNames(settings.items.map(item => item.source));
  return {
    version: 1,
    size: settings.size,
    style: settings.style,
    scale: settings.scale,
    padding: settings.padding,
    viewpoint: settings.viewpoint,
    angles: settings.angles,
    ...(settings.style === 'sketch' ? { sketch: settings.sketch, seed: settings.seed } : {}),
    atlas: { file: ICON_ARTIFACTS.atlas, width: layout.width, height: layout.height, columns: layout.columns, rows: layout.rows },
    // One entry per frame. `angle` is the azimuth in degrees the frame is drawn from; `item` and `turn` say which item and which
    // of its views it is. The strip of an item hangs on its first view (turn 0).
    icons: iconFrames(settings).map(({ itemIndex, angleIndex, view }, frameIndex) => ({
      name: names[itemIndex],
      file: iconArtifactName(frameIndex),
      source: settings.items[itemIndex].source,
      asset: settings.items[itemIndex].asset,
      item: itemIndex,
      turn: angleIndex,
      angle: view.azimuth,
      rect: layout.rectangles[frameIndex],
      bounds: entries[frameIndex].bounds,
      viewHeight: entries[frameIndex].viewHeight,
      ...(settings.breakdown && angleIndex === 0 ? { breakdown: breakdownArtifactName(itemIndex) } : {}),
    })),
  };
}

/** What `scene_capabilities` jobs reports for kind icons: the limits the validator enforces and the files a job writes. */
export const ICON_CAPABILITIES = Object.freeze({
  kind: 'icons',
  note: 'settings.kind icons draws each item (a catalog GLB name or asset id from scene_asset_catalog) as a transparent square icon with an orthographic three-quarter view, a fixed three-point light rig and a silhouette fit. Writes icon-<n>.png per item and angle, atlas.png and icons.json (name, angle, atlas rect, source, bounds). angles 4 or 8 turns each item around into a row of the atlas. The submitted scene is not drawn.',
  maximumItems: ICON_LIMITS.maximumItems,
  maximumIcons: ICON_LIMITS.maximumFrames,
  sizes: ICON_LIMITS.sizes,
  styles: ICON_LIMITS.styles,
  angles: ICON_LIMITS.angles,
  sketch: SKETCH_CAPABILITIES,
  scales: ICON_LIMITS.scales,
  viewpoint: Object.freeze({ default: 'three-quarter', azimuth: ICON_LIMITS.defaultView.azimuth, elevation: ICON_LIMITS.defaultView.elevation, maximumElevation: ICON_LIMITS.maximumElevation }),
  padding: Object.freeze({ default: ICON_LIMITS.defaultPadding, minimum: ICON_LIMITS.minimumPadding, maximum: ICON_LIMITS.maximumPadding }),
  maximumAtlasSide: ICON_LIMITS.maximumAtlasSide,
  itemsPerSize: Object.freeze(Object.fromEntries(ICON_LIMITS.sizes.map(size => [size, itemCapacity(size, 1)]))),
  itemsPerSizeAndAngles: Object.freeze(Object.fromEntries(ICON_LIMITS.angles.filter(angles => angles > 1).map(angles => [angles, Object.freeze(Object.fromEntries(ICON_LIMITS.sizes.map(size => [size, itemCapacity(size, angles)])))]))),
  notYet: Object.freeze(Object.keys(COMING_FIELDS)),
});