3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { createSlicer } from './cooperative.js';
import { createEnvironmentMap, MAXIMUM_ENVIRONMENT_SIZE } from './environment.js';
import { alignEnvironmentRows } from './environment-orientation.js';
const MAXIMUM_FILE_BYTES = 256 * 1024 ** 2;
const MINIMUM_RUN_LENGTH_WIDTH = 8;
const MAXIMUM_RUN_LENGTH_WIDTH = 32767;
function readLine(bytes, start) {
let end = start;
while (end < bytes.length && bytes[end] !== 0x0a) end++;
if (end >= bytes.length) throw new Error('Radiance HDR header is truncated.');
const text = String.fromCharCode(...bytes.subarray(start, Math.min(end, start + 256)));
return { text: text.replace(/\r$/, ''), next: end + 1 };
}
function parseHeader(bytes) {
let line = readLine(bytes, 0);
if (!line.text.startsWith('#?')) throw new Error('Not a Radiance HDR file: missing #? signature.');
let formatFound = false;
let position = line.next;
for (;;) {
line = readLine(bytes, position);
position = line.next;
if (line.text === '') break;
if (line.text.startsWith('FORMAT=')) {
if (line.text !== 'FORMAT=32-bit_rle_rgbe') throw new Error(`Unsupported Radiance HDR format: ${line.text}.`);
formatFound = true;
}
}
if (!formatFound) throw new Error('Radiance HDR header has no FORMAT=32-bit_rle_rgbe line.');
line = readLine(bytes, position);
const resolution = /^-Y (\d+) \+X (\d+)$/.exec(line.text);
if (!resolution) throw new Error('Unsupported Radiance HDR orientation. Only "-Y height +X width" is supported.');
const height = Number(resolution[1]);
const width = Number(resolution[2]);
if (width < 1 || height < 1 || width > MAXIMUM_ENVIRONMENT_SIZE || height > MAXIMUM_ENVIRONMENT_SIZE) throw new RangeError('Radiance HDR dimensions are outside the supported range.');
return { width, height, dataStart: line.next };
}
function readRunLengthScanline(bytes, startPosition, width, scanline) {
let position = startPosition + 4;
for (let channel = 0; channel < 4; channel++) {
let column = 0;
while (column < width) {
if (position >= bytes.length) throw new Error('Radiance HDR pixel data is truncated.');
const count = bytes[position++];
const isRun = count > 128;
const length = isRun ? count - 128 : count;
if (length === 0 || column + length > width) throw new Error('Radiance HDR run length is invalid.');
if (isRun) {
if (position >= bytes.length) throw new Error('Radiance HDR pixel data is truncated.');
const value = bytes[position++];
for (let index = 0; index < length; index++) scanline[(column + index) * 4 + channel] = value;
} else {
if (position + length > bytes.length) throw new Error('Radiance HDR pixel data is truncated.');
for (let index = 0; index < length; index++) scanline[(column + index) * 4 + channel] = bytes[position + index];
position += length;
}
column += length;
}
}
return position;
}
// Flat scanlines may use the pre-1991 run form: a pixel of 1,1,1 repeats the previous pixel by its exponent byte,
// and each further repeat in a row shifts the count up by 8 bits.
function readFlatScanline(bytes, startPosition, width, scanline) {
let position = startPosition;
let repeatShift = 0;
let column = 0;
while (column < width) {
if (position + 4 > bytes.length) throw new Error('Radiance HDR pixel data is truncated.');
const isRepeat = bytes[position] === 1 && bytes[position + 1] === 1 && bytes[position + 2] === 1;
if (!isRepeat) {
scanline.set(bytes.subarray(position, position + 4), column * 4);
position += 4;
column++;
repeatShift = 0;
continue;
}
const length = bytes[position + 3] << repeatShift;
if (column === 0 || length === 0 || column + length > width) throw new Error('Radiance HDR repeat run is invalid.');
for (let index = 0; index < length; index++) scanline.copyWithin((column + index) * 4, (column - 1) * 4, column * 4);
position += 4;
column += length;
repeatShift += 8;
}
return position;
}
function startsRunLengthScanline(bytes, position, width) {
return width >= MINIMUM_RUN_LENGTH_WIDTH && width <= MAXIMUM_RUN_LENGTH_WIDTH
&& bytes[position] === 2 && bytes[position + 1] === 2
&& ((bytes[position + 2] << 8) | bytes[position + 3]) === width;
}
// Old-format rows are the smallest: one pixel and at most two repeat pixels (255 and 65280 pixels each), and a
// run-length row never costs less than that, so this bound holds for both.
function allocatePixels(availableBytes, width, height) {
const repeatPixels = Math.min(2, Math.ceil(Math.log(width) / Math.log(256)));
if (availableBytes < height * 4 * (1 + repeatPixels)) {
throw new RangeError(`Radiance HDR pixel data is truncated: the header says ${width}x${height} but the file holds ${availableBytes} bytes; pass the whole file.`);
}
return new Float32Array(width * height * 3);
}
function requireBytes(buffer) {
if (buffer instanceof Uint8Array) return buffer;
if (buffer instanceof ArrayBuffer) return new Uint8Array(buffer);
throw new TypeError('parseRadianceHdr needs an ArrayBuffer or Uint8Array.');
}
// Decodes one scanline per step, so a caller can run it to the end at once or hand the thread back between rows.
function* decodeRadianceRows(buffer) {
const bytes = requireBytes(buffer);
if (bytes.length > MAXIMUM_FILE_BYTES) throw new RangeError('Radiance HDR file is larger than 256 MiB.');
const { width, height, dataStart } = parseHeader(bytes);
let data;
const scanline = new Uint8Array(width * 4);
let position = dataStart;
for (let row = 0; row < height; row++) {
if (startsRunLengthScanline(bytes, position, width)) {
position = readRunLengthScanline(bytes, position, width, scanline);
} else {
position = readFlatScanline(bytes, position, width, scanline);
}
data ??= allocatePixels(bytes.length - dataStart, width, height);
for (let column = 0; column < width; column++) {
const exponent = scanline[column * 4 + 3];
const target = (row * width + column) * 3;
if (exponent === 0) continue;
const scale = 2 ** (exponent - 136);
data[target] = scanline[column * 4] * scale;
data[target + 1] = scanline[column * 4 + 1] * scale;
data[target + 2] = scanline[column * 4 + 2] * scale;
}
yield row;
}
return { width, height, data };
}
// Parses Radiance RGBE (.hdr) data into linear RGB floats, top row first.
export function parseRadianceHdr(buffer) {
const rows = decodeRadianceRows(buffer);
let step = rows.next();
while (!step.done) step = rows.next();
return step.value;
}
// The same result as parseRadianceHdr, with `checkpoint()` awaited between rows so a large map does not block the page.
export async function parseRadianceHdrInSlices(buffer, checkpoint) {
const rows = decodeRadianceRows(buffer);
let step = rows.next();
while (!step.done) {
await checkpoint();
step = rows.next();
}
return step.value;
}
// Fetches a .hdr file (for example a 1k or 2k Poly Haven HDRI) and returns an environment map descriptor.
export async function loadHdri(url, { intensity, rotation, showBackground, backgroundBlur, signal, fetchImplementation = globalThis.fetch } = {}) {
const response = await fetchImplementation(url, { signal });
if (!response.ok) throw new Error(`HDRI download failed: HTTP ${response.status}.`);
const parsed = await parseRadianceHdrInSlices(await response.arrayBuffer(), createSlicer());
return createEnvironmentMap({ ...alignEnvironmentRows(parsed), intensity, rotation, showBackground, backgroundBlur });
}
export { createEnvironmentMap };
const SUN_PEAK_TO_MEAN_RATIO = 20;
const SUN_SEARCH_RADIUS = Math.PI / 18;
function luminanceAt(data, offset) {
return 0.2126 * data[offset] + 0.7152 * data[offset + 1] + 0.0722 * data[offset + 2];
}
// Equirect pixel to a direction in the map's own frame (the inverse of the shader lookup, before `rotation`).
function mapDirection(column, row, width, height) {
const azimuth = ((column + 0.5) / width - 0.5) * 2 * Math.PI;
const polar = ((row + 0.5) / height) * Math.PI;
return [Math.sin(polar) * Math.sin(azimuth), Math.cos(polar), -Math.sin(polar) * Math.cos(azimuth)];
}
// The shader turns a world direction into the map frame with a turn about +Y; this is the inverse.
function worldFromMapDirection([x, y, z], rotation) {
const cosine = Math.cos(rotation);
const sine = Math.sin(rotation);
return [cosine * x + sine * z, y, -sine * x + cosine * z];
}
/**
* Finds the sun in an HDR environment map: the brightest 3 by 3 block, then the luminance-weighted centre of the pixels
* within 10 degrees of it that reach half its brightness, so a single hot pixel does not move it.
* Returns `{ lightDirection, keyColor, keyIntensity }` (world direction toward the sun with `rotation` applied, colour
* with its largest channel at 1, and `irradiance / PI` of the sun disc scaled by the map intensity), or `null` when the
* peak is under 20 times the mean luminance, as on an overcast sky.
*/
export function sunFromEnvironmentMap(map) {
const { width, height, channels, data } = map;
const rowWeights = Float64Array.from({ length: height }, (_, row) => Math.sin(((row + 0.5) / height) * Math.PI));
const luminance = new Float32Array(width * height);
let weightedTotal = 0;
for (let row = 0; row < height; row++) {
for (let column = 0; column < width; column++) {
const value = luminanceAt(data, (row * width + column) * channels);
luminance[row * width + column] = value;
weightedTotal += value * rowWeights[row];
}
}
const meanLuminance = weightedTotal / (rowWeights.reduce((sum, weight) => sum + weight, 0) * width);
let peakValue = 0;
let peakColumn = 0;
let peakRow = 0;
for (let row = 1; row < height - 1; row++) {
for (let column = 0; column < width; column++) {
let blockSum = 0;
for (let rowOffset = -1; rowOffset <= 1; rowOffset++) {
for (let columnOffset = -1; columnOffset <= 1; columnOffset++) {
blockSum += luminance[(row + rowOffset) * width + ((column + columnOffset + width) % width)];
}
}
if (blockSum / 9 > peakValue) {
peakValue = blockSum / 9;
peakColumn = column;
peakRow = row;
}
}
}
if (!(peakValue > SUN_PEAK_TO_MEAN_RATIO * meanLuminance)) return null;
const peakDirection = mapDirection(peakColumn, peakRow, width, height);
const minimumCosine = Math.cos(SUN_SEARCH_RADIUS);
const pixelSolidAngle = ((2 * Math.PI) / width) * (Math.PI / height);
const centre = [0, 0, 0];
const colorSum = [0, 0, 0];
let irradiance = 0;
for (let row = 0; row < height; row++) {
for (let column = 0; column < width; column++) {
const value = luminance[row * width + column];
if (value < peakValue * 0.5) continue;
const direction = mapDirection(column, row, width, height);
const cosine = direction[0] * peakDirection[0] + direction[1] * peakDirection[1] + direction[2] * peakDirection[2];
if (cosine < minimumCosine) continue;
const weight = value * rowWeights[row];
for (let axis = 0; axis < 3; axis++) {
centre[axis] += direction[axis] * weight;
colorSum[axis] += data[(row * width + column) * channels + axis] * weight;
}
irradiance += value * rowWeights[row] * pixelSolidAngle * Math.max(cosine, 0);
}
}
const length = Math.hypot(...centre);
const brightest = Math.max(...colorSum);
return {
lightDirection: worldFromMapDirection(centre.map((component) => component / length), map.rotation),
keyColor: colorSum.map((component) => component / brightest),
keyIntensity: (irradiance * map.intensity) / Math.PI,
};
}
function isPoint(point) {
return Array.isArray(point) && point.length === 3 && point.every(Number.isFinite);
}
function requireBounds(bounds) {
if (!isPoint(bounds?.min) || !isPoint(bounds?.max)) {
throw new TypeError('keyLightFromHdri bounds must be { min, max } of three finite numbers each.');
}
}
/**
* Lights a scene from the HDRI sun. Spread the result into the renderer's `environment` and pass its `shadowBounds`:
* `{ environment: { lightDirection, keyColor, keyIntensity }, shadowBounds }`. The shadow view looks at the middle of
* `bounds` ({ min, max }) from the sun side and covers its bounding sphere. Without a distinct sun it returns `null`,
* so the caller keeps its defaults.
*/
export function keyLightFromHdri(map, bounds) {
requireBounds(bounds);
const sun = sunFromEnvironmentMap(map);
if (!sun) return null;
const target = bounds.min.map((minimum, axis) => (minimum + bounds.max[axis]) / 2);
const extent = Math.max(Math.hypot(...bounds.max.map((maximum, axis) => maximum - bounds.min[axis])) / 2, 1e-3);
const eye = target.map((component, axis) => component + sun.lightDirection[axis] * extent * 2);
const { lightDirection, keyColor, keyIntensity } = sun;
return { environment: { lightDirection, keyColor, keyIntensity }, shadowBounds: { target, eye, extent, near: extent * 0.5, far: extent * 3.5 } };
}