3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { LOOK_NAMES, VIEW_TRANSFORM_NAMES } from './view-transform-names.js';
// Display transforms and look LUTs as plain functions, shared by the path tracer, the tests and the GLSL in
// view-transform-shader.js (which prints the constants below, so the three cannot drift apart).
// - aces is the Narkowicz fit the rasterizer has always used, applied per channel.
// - agx is Blender 5.2's AgX (the sRGB view of its OCIO config: E-Gamut log2 between -12.47393 and 4.026069 EV, a per-channel
// sigmoid, a 2.4 power, a matrix back to Rec.709) as a fit of AgX_Base_sRGB.cube, not the 57-point LUT itself. The
// older Filament/three.js polynomial put 0.18 grey 0.04 above Blender (0.501 against 0.461).
// - neutral is the Khronos PBR Neutral tone mapper: base colours below 0.76 pass unchanged.
// - standard is Blender's Standard: the sRGB encoding of the clipped scene value, with no tone curve. A value above 1 clips.
// All four take linear sRGB and return display-linear sRGB in 0 to 1; the caller encodes with a power of 1 / 2.2.
const rowsToColumns = rows => rows[0].map((_, column) => rows.map(row => row[column]));
/**
* Matrices as columns, as GLSL writes them. inset takes linear Rec.709 to the space the log and the sigmoid work in; outset
* takes the linearised sigmoid output back to Rec.709. Rows sum to 1, so grey stays grey. Both were fitted to the LUT, and
* the sigmoid to its grey diagonal. From the pivot (0.18 grey) it rises by scale * v / (1 + v ** power) ** (1 / power)
* with v = slope * distance / scale, and falls the same way with the toe's own scale and power.
*/
export const AGX_CONSTANTS = Object.freeze({
inset: rowsToColumns([[0.57215, 0.33216, 0.09569], [0.12368, 0.74091, 0.13541], [0.09814, 0.19729, 0.70457]]),
outset: rowsToColumns([[1.84762, -0.70741, -0.14021], [-0.2341, 1.3225, -0.0884], [-0.19713, -0.30062, 1.49775]]),
minimumEv: -12.47393,
maximumEv: 4.026069,
pivot: [0.60608, 0.48834],
slope: 2.39013,
toe: { scale: 0.56474, power: 1.50159 },
shoulder: { scale: 0.70613, power: 1.53357 },
encodingPower: 2.4,
});
export const NEUTRAL_CONSTANTS = Object.freeze({ startCompression: 0.8 - 0.04, desaturation: 0.15 });
function multiply(columns, vector) {
const result = [0, 0, 0];
for (let column = 0; column < 3; column++) {
for (let row = 0; row < 3; row++) result[row] += columns[column][row] * vector[column];
}
return result;
}
const clampUnit = value => Math.min(1, Math.max(0, value));
/** The rasterizer's ACES fit for one channel. */
export function acesChannel(value) {
const color = Math.max(value, 0);
return clampUnit((color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14));
}
function agxSigmoidSide(distance, side) {
const scaled = distance / side.scale;
return side.scale * scaled / (1 + scaled ** side.power) ** (1 / side.power);
}
function agxCurve(value) {
const { pivot, slope, toe, shoulder } = AGX_CONSTANTS;
const distance = slope * (value - pivot[0]);
return pivot[1] + (distance >= 0 ? agxSigmoidSide(distance, shoulder) : -agxSigmoidSide(-distance, toe));
}
export function agxColor(rgb) {
const { inset, outset, minimumEv, maximumEv, encodingPower } = AGX_CONSTANTS;
const linear = multiply(inset, rgb).map(channel => {
const logged = (Math.log2(Math.max(channel, 1e-10)) - minimumEv) / (maximumEv - minimumEv);
return Math.max(0, agxCurve(clampUnit(logged))) ** encodingPower;
});
return multiply(outset, linear).map(clampUnit);
}
export function neutralColor(rgb) {
const { startCompression, desaturation } = NEUTRAL_CONSTANTS;
const lowest = Math.min(...rgb);
const offset = lowest < 0.08 ? lowest - 6.25 * lowest * lowest : 0.04;
const shifted = rgb.map(channel => channel - offset);
const peak = Math.max(...shifted);
if (peak < startCompression) return shifted.map(clampUnit);
const distance = 1 - startCompression;
const newPeak = 1 - distance * distance / (peak + distance - startCompression);
const mix = 1 - 1 / (desaturation * (peak - newPeak) + 1);
return shifted.map(channel => clampUnit(channel * newPeak / peak * (1 - mix) + newPeak * mix));
}
/** The sRGB transfer function of one linear channel clipped to 0 to 1 (IEC 61966-2-1). */
export function srgbEncode(value) {
const color = clampUnit(value);
return color <= 0.0031308 ? color * 12.92 : 1.055 * color ** (1 / 2.4) - 0.055;
}
/** Blender Standard. The caller encodes with a power of 1 / 2.2, so this returns the value that power turns into the sRGB encoding. */
export function standardColor(rgb) {
return rgb.map(channel => srgbEncode(channel) ** 2.2);
}
const LARGEST_RADIANCE = 1e30;
// NaN reads as black and infinity as a very bright finite value, so one bad channel cannot turn the whole pixel into NaN
// through the matrices and the neutral compression.
const finiteChannel = value => (Number.isNaN(value) ? 0 : Math.min(LARGEST_RADIANCE, Math.max(-LARGEST_RADIANCE, value)));
/** Linear sRGB in, display transform out, still linear: the part before the 1 / 2.2 power. */
export function applyViewTransform(name, rgb) {
const finite = rgb.map(finiteChannel);
if (name === 'agx') return agxColor(finite);
if (name === 'neutral') return neutralColor(finite);
if (name === 'standard') return standardColor(finite);
if (name === 'aces' || name === undefined) return finite.map(acesChannel);
throw new RangeError(`viewTransform must be one of ${VIEW_TRANSFORM_NAMES.join(', ')}.`);
}
// ---- Looks ----
export const MAXIMUM_LOOK_SIZE = 65;
const MAXIMUM_LOOK_TEXT = 16 * 1024 * 1024;
function parseCubeTriple(keyword, rest) {
const triple = rest.map(Number);
if (triple.length !== 3 || !triple.every(Number.isFinite)) throw new RangeError(`${keyword} needs three finite numbers.`);
return triple;
}
/** A look is { size, data }: size cubed RGB triples in 0 to 1, red varying fastest, applied to display-encoded colour. */
export function parseCube(text) {
if (typeof text !== 'string' || text.length > MAXIMUM_LOOK_TEXT) throw new RangeError('A .cube look must be text of at most 16 MiB.');
let size = 0;
let domainMinimum = [0, 0, 0];
let domainMaximum = [1, 1, 1];
const values = [];
for (const rawLine of text.split(/\r?\n/)) {
const line = rawLine.replace(/#.*/, '').trim();
if (line === '' || line.startsWith('TITLE')) continue;
const [keyword, ...rest] = line.split(/\s+/);
if (keyword === 'LUT_3D_SIZE') size = rest.length === 1 && /^\d+$/.test(rest[0]) ? Number(rest[0]) : 0;
else if (keyword === 'LUT_1D_SIZE') throw new RangeError('Only 3D .cube looks are supported (LUT_3D_SIZE).');
else if (keyword === 'DOMAIN_MIN') domainMinimum = parseCubeTriple(keyword, rest);
else if (keyword === 'DOMAIN_MAX') domainMaximum = parseCubeTriple(keyword, rest);
else if (/^[-+0-9.]/.test(keyword)) values.push(...parseCubeTriple('A .cube row', [keyword, ...rest]));
else throw new RangeError(`Unknown .cube line: ${keyword}`);
}
if (!Number.isInteger(size) || size < 2 || size > MAXIMUM_LOOK_SIZE) throw new RangeError(`LUT_3D_SIZE must be an integer from 2 to ${MAXIMUM_LOOK_SIZE}.`);
if (domainMaximum.some((maximum, channel) => !(maximum > domainMinimum[channel]))) throw new RangeError('DOMAIN_MAX must be above DOMAIN_MIN in every channel.');
if (values.length !== size ** 3 * 3 || values.some(value => !Number.isFinite(value))) throw new RangeError(`A ${size}x${size}x${size} .cube look needs ${size ** 3} finite RGB rows.`);
const data = new Float32Array(values.length);
for (let index = 0; index < values.length; index++) {
const channel = index % 3;
const range = domainMaximum[channel] - domainMinimum[channel];
data[index] = clampUnit((values[index] - domainMinimum[channel]) / range);
}
return { size, data };
}
function lookFromFunction(size, grade) {
const data = new Float32Array(size ** 3 * 3);
let offset = 0;
for (let blue = 0; blue < size; blue++) {
for (let green = 0; green < size; green++) {
for (let red = 0; red < size; red++) {
data.set(grade([red / (size - 1), green / (size - 1), blue / (size - 1)]).map(clampUnit), offset);
offset += 3;
}
}
}
return { size, data };
}
const smooth = value => value * value * (3 - 2 * value);
const NAMED_LOOK_GRADES = {
warm: ([red, green, blue]) => [red * 1.06 + 0.01, green, blue * 0.92],
cool: ([red, green, blue]) => [red * 0.93, green, blue * 1.07 + 0.01],
contrast: color => color.map(channel => channel * 0.5 + smooth(channel) * 0.5),
faded: color => {
const gray = color[0] * 0.2126 + color[1] * 0.7152 + color[2] * 0.0722;
return color.map(channel => 0.06 + 0.88 * (channel * 0.85 + gray * 0.15));
},
};
/** One of the LOOK_NAMES, as a 17-point look. */
export function namedLook(name) {
if (!LOOK_NAMES.includes(name)) throw new RangeError(`look must be one of ${LOOK_NAMES.join(', ')}.`);
return lookFromFunction(17, NAMED_LOOK_GRADES[name]);
}
/** Trilinear lookup of a display-encoded colour, as the GPU filters the 3D texture. */
export function sampleLook(look, rgb) {
const { size, data } = look;
const position = rgb.map(channel => clampUnit(finiteChannel(channel)) * (size - 1));
const base = position.map(value => Math.min(Math.floor(value), size - 2));
const result = [0, 0, 0];
for (let corner = 0; corner < 8; corner++) {
const offsets = [corner & 1, (corner >> 1) & 1, (corner >> 2) & 1];
let weight = 1;
for (let axis = 0; axis < 3; axis++) {
const fraction = position[axis] - base[axis];
weight *= offsets[axis] ? fraction : 1 - fraction;
}
const index = ((base[2] + offsets[2]) * size * size + (base[1] + offsets[1]) * size + base[0] + offsets[0]) * 3;
for (let channel = 0; channel < 3; channel++) result[channel] += data[index + channel] * weight;
}
return result;
}
/** Linear radiance to the display-encoded colour in 0 to 1 that the rasterizer's frame holds for it. */
export function displayColor(rgb, { viewTransform = 'aces', look = null } = {}) {
const encoded = applyViewTransform(viewTransform, rgb).map(channel => channel ** (1 / 2.2));
return look ? sampleLook(look, encoded) : encoded;
}