Skip to content

3D engine that AI agents drive

20.8 KB
Raw Blame
// The emission ramp of a local volume (#1046): a blackbody curve or a short colour ramp read by the density or by a grid's temperature or flame channel.
// The pure tests check the blackbody against a published table, the field, the packing and the CPU path tracer; the browser test draws a graded
// sphere in the rasterizer (headless Chrome on SwiftShader, from the Vite dev server) and in the CPU path tracer and compares the light per region.
// It skips when Chrome cannot start. Set LOCAL_VOLUME_RAMP_ARTIFACTS to a folder to also write the numbers there.
import './support/load-agent-scene-modules.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import { spawn } from 'node:child_process';
import { mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { freePort } from './helpers/free-port.js';
import { launchChrome, skipOrThrow } from './helpers/dev-server-browser.js';
import { createAgentScene } from '../src/agent-scene.js';
import { renderPathTracedImage } from '../src/path-tracer.js';
import { applyViewTransform } from '../src/view-transform.js';
import { resolveLocalVolumes, createLocalVolumeBuffers, packLocalVolumes } from '../src/local-volumes.js';
import { LOCAL_VOLUME_RAMP_STOPS } from '../src/local-volume-ramp.js';
import { blackbodyChromaticity, blackbodyRampColor, bakeEmissionRamp, sampleBakedRamp } from '../src/local-volume-ramp-bake.js';
import { createLocalVolumeCrossing } from '../src/path-tracer-volume.js';
import { assertWebGpuLocalVolumes, webGpuVolumeFeatures } from '../src/path-tracer-webgpu-local-volumes.js';
import { encodeVolumeGrid, decodeVolumeGrid } from '../src/volume-grid.js';

// Mitchell Charity, "What color is a blackbody?", bbr_color.txt (version 2001-Jun-22), http://www.vendian.org/mncharity/dir3/blackbody/:
// the CIE 1931 2 degree rows, columns R G B (linear sRGB, normalised so the largest is 1, out of gamut channels clipped to 0).
const CHARITY_TABLE = [
  [1000, 1.0, 0.0337, 0.0],
  [1200, 1.0, 0.0846, 0.0],
  [1400, 1.0, 0.1341, 0.0],
  [1600, 1.0, 0.1806, 0.0],
  [1800, 1.0, 0.2235, 0.0],
  [2000, 1.0, 0.2647, 0.0033],
  [2200, 1.0, 0.3126, 0.0219],
  [2400, 1.0, 0.3589, 0.0454],
  [2600, 1.0, 0.4034, 0.0734],
  [2800, 1.0, 0.4461, 0.1054],
  [3000, 1.0, 0.4870, 0.1411],
];
const TABLE_TOLERANCE = 0.02;

test('the blackbody hue from 1000 K to 3000 K matches the Charity table within 2 percent of full scale per channel', () => {
  const colour = new Float64Array(3);
  for (const [kelvin, ...expected] of CHARITY_TABLE) {
    blackbodyChromaticity(kelvin, colour);
    expected.forEach((reference, channel) => {
      assert.ok(Math.abs(colour[channel] - reference) <= TABLE_TOLERANCE, `${kelvin} K channel ${channel}: ${colour[channel].toFixed(4)} against the table's ${reference}`);
    });
  }
});

test('a blackbody ramp is dimmer where it is cooler, by the fourth power of the temperature', () => {
  const hot = blackbodyRampColor(3000, 3000, new Float64Array(3));
  const cool = blackbodyRampColor(1500, 3000, new Float64Array(3));
  assert.equal(hot[0], 1);
  assert.ok(Math.abs(cool[0] - 0.5 ** 4) < 1e-12);
  assert.ok(cool[2] < cool[0] * 0.01, 'a 1500 K body is orange: almost no blue');
});

test('baking a blackbody ramp samples eight temperatures and applies the exposure; stops keep their own count', () => {
  const [volume] = resolveLocalVolumes([{ shape: 'sphere', center: [0, 0, 0], radius: 1, emissionRamp: { kelvin: [1000, 3000], exposure: 2 } }]);
  const baked = bakeEmissionRamp(volume.emissionRamp);
  assert.equal(baked.count, LOCAL_VOLUME_RAMP_STOPS);
  assert.ok(Math.abs(baked.colors[(LOCAL_VOLUME_RAMP_STOPS - 1) * 3] - 2) < 1e-12);
  const [stopped] = resolveLocalVolumes([{ shape: 'sphere', center: [0, 0, 0], radius: 1, emissionRamp: { stops: [[1, 0.2, 0], [1, 1, 1], [0, 0, 1]] } }]);
  const stopBake = bakeEmissionRamp(stopped.emissionRamp);
  assert.equal(stopBake.count, 3);
  const middle = sampleBakedRamp(stopBake, 0.25, new Float64Array(3));
  assert.deepEqual(Array.from(middle), [1, 0.6, 0.5]);
});

test('the baked 8 stop blackbody ramp stays within 2 percent of the exact curve between its stops', () => {
  const [volume] = resolveLocalVolumes([{ shape: 'sphere', center: [0, 0, 0], radius: 1, emissionRamp: { kelvin: [1000, 3000] } }]);
  const baked = bakeEmissionRamp(volume.emissionRamp);
  const exact = new Float64Array(3);
  const sampled = new Float64Array(3);
  for (let step = 0; step <= 40; step++) {
    const position = step / 40;
    blackbodyRampColor(1000 + 2000 * position, 3000, exact);
    sampleBakedRamp(baked, position, sampled);
    for (let channel = 0; channel < 3; channel++) assert.ok(Math.abs(sampled[channel] - exact[channel]) <= 0.02, `position ${position} channel ${channel}: ${sampled[channel]} against ${exact[channel]}`);
  }
});

test('emissionRamp fills its defaults, resolves to itself again and names the field in every error', () => {
  const [volume] = resolveLocalVolumes([{ shape: 'box', center: [0, 0, 0], size: [1, 1, 1], emissionRamp: { kelvin: [1000, 3000] } }]);
  assert.deepEqual(volume.emissionRamp, { source: 'density', range: [0, 1], exposure: 1, kelvin: [1000, 3000] });
  assert.deepEqual(resolveLocalVolumes([volume])[0], volume);
  const label = 'environment.localVolumes[0].emissionRamp';
  const sphere = ramp => resolveLocalVolumes([{ shape: 'sphere', center: [0, 0, 0], radius: 1, emissionRamp: ramp }], 'environment.localVolumes');
  assert.throws(() => sphere('hot'), new RegExp(`${label.replaceAll('.', '\\.').replaceAll('[', '\\[').replaceAll(']', '\\]')} must be an object`));
  assert.throws(() => sphere({ kelvin: [1000, 3000], colour: 1 }), /emissionRamp has no field "colour"; use source, range, exposure, kelvin, stops/);
  assert.throws(() => sphere({}), /exactly one of kelvin .* or stops/);
  assert.throws(() => sphere({ kelvin: [1000, 3000], stops: [[1, 1, 1], [0, 0, 0]] }), /exactly one of kelvin/);
  assert.throws(() => sphere({ kelvin: [3000, 1000] }), /emissionRamp\.kelvin must be \[cool, hot\] with cool below hot/);
  assert.throws(() => sphere({ kelvin: [100, 3000] }), /emissionRamp\.kelvin\[0\]/);
  assert.throws(() => sphere({ stops: [[1, 1, 1]] }), /emissionRamp\.stops must be a list of 2 to 8 colours/);
  assert.throws(() => sphere({ stops: Array.from({ length: 9 }, () => [1, 1, 1]) }), /2 to 8 colours/);
  assert.throws(() => sphere({ kelvin: [1000, 3000], exposure: -1 }), /emissionRamp\.exposure/);
  assert.throws(() => sphere({ kelvin: [1000, 3000], range: [1, 0] }), /emissionRamp\.range must be \[low, high\]/);
  assert.throws(() => sphere({ kelvin: [1000, 3000], source: 'smoke' }), /emissionRamp\.source must be one of density, temperature, flame/);
  assert.throws(() => sphere({ kelvin: [1000, 3000], source: 'temperature' }), /"temperature" is a channel of a grid volume/);
  assert.throws(() => resolveLocalVolumes([{ shape: 'mesh', part: 'room', emissionRamp: { kelvin: [1000, 3000] } }]), /belongs to a box, a sphere or a grid/);
});

test('a volume without emissionRamp resolves with no ramp field and packs no ramp, so it draws as before', () => {
  const plain = { shape: 'sphere', center: [0, 1, 0], radius: 1, emission: [1, 0.5, 0.2], emissionStrength: 3 };
  const [resolved] = resolveLocalVolumes([plain]);
  assert.equal('emissionRamp' in resolved, false);
  const buffers = createLocalVolumeBuffers();
  packLocalVolumes([resolved], buffers);
  assert.ok(buffers.rampSetup.every(value => value === 0));
  assert.ok(buffers.rampColors.every(value => value === 0));
});

test('packing a ramp writes the source code, the stop count, the range and the colours times the strength', () => {
  const buffers = createLocalVolumeBuffers();
  const volumes = resolveLocalVolumes([
    { shape: 'sphere', center: [0, 0, 0], radius: 1 },
    { shape: 'sphere', center: [0, 0, 0], radius: 1, emissionStrength: 4, emissionRamp: { stops: [[1, 0.5, 0.25], [2, 2, 2]], range: [0.5, 2], exposure: 0.5 } },
  ]);
  packLocalVolumes(volumes, buffers);
  assert.deepEqual(Array.from(buffers.rampSetup.slice(4, 8)), [1, 2, 0.5, 2]);
  assert.deepEqual(Array.from(buffers.rampColors.slice(LOCAL_VOLUME_RAMP_STOPS * 4, LOCAL_VOLUME_RAMP_STOPS * 4 + 8)), [2, 1, 0.5, 0, 4, 4, 4, 0]);
  assert.deepEqual(Array.from(buffers.rampSetup.slice(0, 4)), [0, 0, 0, 0]);
});

// A ray straight through a volume, as the CPU path tracer marches it.
function crossAt(volume, origin, direction, length = 10) {
  const crossing = createLocalVolumeCrossing(resolveLocalVolumes([volume]), null);
  const throughput = new Float64Array([1, 1, 1]);
  const emitted = new Float64Array(3);
  crossing(origin[0], origin[1], origin[2], direction[0], direction[1], direction[2], length, 0.5, throughput, emitted);
  return Array.from(emitted);
}

const FIREBALL = { shape: 'sphere', center: [0, 0, 0], radius: 1, falloff: 1, absorption: [0, 0, 0], steps: 32, emissionRamp: { kelvin: [1000, 3000] } };

test('the CPU path tracer grades a sphere from a white core to an orange edge', () => {
  const core = crossAt(FIREBALL, [0, 0, 5], [0, 0, -1]);
  const edge = crossAt(FIREBALL, [0.85, 0, 5], [0, 0, -1]);
  assert.ok(core.every(value => value > 0) && edge[0] > 0 && edge[1] > 0, `core ${core}, edge ${edge}`);
  const coreBlueShare = core[2] / core[0];
  const edgeBlueShare = edge[2] / edge[0];
  assert.ok(coreBlueShare > 0.1, `core blue over red ${coreBlueShare}`);
  assert.ok(edgeBlueShare < coreBlueShare * 0.5, `edge blue over red ${edgeBlueShare} against core ${coreBlueShare}`);
  assert.ok(core[0] > edge[0] * 3, `core red ${core[0]} against edge red ${edge[0]}`);
});

test('the exposure scales the light and exposure 0 gives none', () => {
  const base = crossAt(FIREBALL, [0, 0, 5], [0, 0, -1]);
  const doubled = crossAt({ ...FIREBALL, emissionRamp: { kelvin: [1000, 3000], exposure: 2 } }, [0, 0, 5], [0, 0, -1]);
  base.forEach((value, channel) => assert.ok(Math.abs(doubled[channel] - 2 * value) < 1e-9));
  assert.deepEqual(crossAt({ ...FIREBALL, emissionRamp: { kelvin: [1000, 3000], exposure: 0 } }, [0, 0, 5], [0, 0, -1]), [0, 0, 0]);
});

test('the ramp adds to the constant emission and a volume without it emits exactly emission times strength times the profile length', () => {
  const plain = { shape: 'sphere', center: [0, 0, 0], radius: 1, falloff: 0, absorption: [0, 0, 0], emission: [0.2, 0.1, 0.05], emissionStrength: 2, steps: 16 };
  const emitted = crossAt(plain, [0, 0, 5], [0, 0, -1]);
  [0.2, 0.1, 0.05].forEach((channel, index) => assert.ok(Math.abs(emitted[index] - channel * 2 * 2) < 1e-9, `channel ${index}: ${emitted[index]}`));
  const withRamp = crossAt({ ...plain, emissionRamp: { stops: [[0, 0, 0], [1, 1, 1]] } }, [0, 0, 5], [0, 0, -1]);
  withRamp.forEach((value, index) => assert.ok(value > emitted[index] + 0.5));
});

function gridBytes(channels) {
  // 32 voxels a side, so the ramp to empty across the faces and the cubic temperature (#1752) stay within a few percent of the flame channel.
  const voxels = 32 * 32 * 32;
  return decodeVolumeGrid(encodeVolumeGrid({ resolution: [32, 32, 32], channels: Object.fromEntries(Object.entries(channels).map(([name, value]) => [name, new Float32Array(voxels).fill(value)])) }));
}

function gridVolume(grid, rampFields) {
  const [resolved] = resolveLocalVolumes([{ shape: 'grid', grid: 'ramp-test', center: [0, 0, 0], size: [2, 2, 2], density: 1, absorption: [0, 0, 0], emissionRamp: { stops: [[0, 0, 0], [1, 1, 1]], ...rampFields } }]);
  return { ...resolved, gridData: grid };
}

test('a grid volume reads its ramp from the channel named by source, and no light where that channel is 0', () => {
  const hot = gridVolume(gridBytes({ density: 0.5, temperature: 1, flame: 0 }), { source: 'temperature' });
  const cold = gridVolume(gridBytes({ density: 0.5, temperature: 0, flame: 1 }), { source: 'temperature' });
  const flame = gridVolume(gridBytes({ density: 0.5, temperature: 0, flame: 1 }), { source: 'flame' });
  const lightOf = volume => {
    const crossing = createLocalVolumeCrossing([volume], null);
    const throughput = new Float64Array([1, 1, 1]);
    const emitted = new Float64Array(3);
    crossing(0, 0, 5, 0, 0, -1, 10, 0.5, throughput, emitted);
    return Array.from(emitted);
  };
  assert.ok(lightOf(hot)[0] > 1, `a hot cell glows: ${lightOf(hot)}`);
  assert.deepEqual(lightOf(cold), [0, 0, 0]);
  const [flameLight, hotLight] = [lightOf(flame)[0], lightOf(hot)[0]];
  assert.ok(Math.abs(flameLight - hotLight) < 0.03 * flameLight, `the temperature ramp ${hotLight} matches the flame ramp ${flameLight} to the cubic filter`);
});

// ---- The rasterizer against the CPU path tracer ----

async function startServer(port) {
  const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
  await new Promise((resolve, reject) => {
    const timeout = setTimeout(() => reject(new Error('The dev server did not start.')), 30000);
    server.stdout.on('data', data => {
      if (/ready in/.test(data.toString())) {
        clearTimeout(timeout);
        resolve();
      }
    });
    server.on('exit', code => {
      clearTimeout(timeout);
      reject(new Error(`The dev server exited ${code}.`));
    });
  });
  return server;
}

const SIZE = 64;
const CPU_SIZE = 32;
const CPU_SAMPLES = 8;
const CELL = 8;
const CAMERA = { eye: [0, 0, 6], target: [0, 0, 0], up: [0, 1, 0], fov: 40 };
const COMPARED_SPHERE = { shape: 'sphere', center: [0, 0, 0], radius: 1.6, falloff: 0.9, absorption: [0, 0, 0], steps: 32, emissionRamp: { kelvin: [1000, 3000], exposure: 0.6 } };

async function rasterFrames(page, volumeLists) {
  const task = async ({ size, lists, camera }) => {
    const { CrucibleRenderer } = await import('/src/renderer.js');
    const { createFloatOutput, readFloatPixels } = await import('/src/float-output.js');
    await import('/src/fog-shader.js');
    const canvas = document.createElement('canvas');
    canvas.width = size;
    canvas.height = size;
    canvas.style.width = size + 'px';
    canvas.style.height = size + 'px';
    document.body.append(canvas);
    const renderer = new CrucibleRenderer(canvas, [], { hdr: true, depth: true, samples: 1, pixelRatio: 1, ground: false });
    const output = createFloatOutput(renderer.context, size, size);
    const dark = [0, 0, 0];
    const frames = lists.map(localVolumes => {
      renderer.render({ ...camera, time: 0, environment: { keyIntensity: 0, fillIntensity: 0, ambientIntensity: 0, skyTop: dark, skyBottom: dark, localVolumes }, outputFramebuffer: output.framebuffer });
      return Array.from(readFloatPixels(renderer.context, output.framebuffer, size, size));
    });
    const glError = renderer.context.getError();
    output.dispose();
    renderer.dispose?.();
    return { frames, glError };
  };
  return page.evaluate(task, { size: SIZE, lists: volumeLists, camera: CAMERA });
}

// The display shows aces(light) ^ (1 / 2.2); this undoes both for a channel.
function lightOf(displayed) {
  let low = 0;
  let high = 64;
  for (let round = 0; round < 40; round++) {
    const middle = (low + high) / 2;
    if (applyViewTransform('aces', [middle, middle, middle])[0] ** (1 / 2.2) < displayed) low = middle;
    else high = middle;
  }
  return low;
}

// The linear light of a raster frame, three values per pixel, top row first.
function rasterLight(frame) {
  const result = new Float64Array(SIZE * SIZE * 3);
  for (let row = 0; row < SIZE; row++) {
    for (let column = 0; column < SIZE; column++) {
      for (let channel = 0; channel < 3; channel++) result[(row * SIZE + column) * 3 + channel] = lightOf(frame[((SIZE - 1 - row) * SIZE + column) * 4 + channel]);
    }
  }
  return result;
}

// A path trace needs one part; this black triangle sits far behind the sphere, out of the frame, and adds no light.
const FAR_TRIANGLE = { positions: new Float32Array([-1, -1, -50, 1, -1, -50, 0, 1, -50]), normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]), uvs: new Float32Array([0, 0, 1, 0, 0.5, 1]), indices: new Uint32Array([0, 1, 2]) };
const BLACK_MATERIAL = { tag: 'surface', metallic: 0, roughness: 1, color: [0, 0, 0], ior: 1, emission: 0 };

async function cpuLight(volumes) {
  const { linear } = await renderPathTracedImage(
    { parts: [{ name: 'far-plane', geometry: FAR_TRIANGLE, material: BLACK_MATERIAL }], environment: { localVolumes: volumes }, camera: CAMERA },
    { width: CPU_SIZE, height: CPU_SIZE, denoise: false, threads: 1, bounces: 1, samples: CPU_SAMPLES },
  );
  return linear;
}

// The mean over a square cell of an image of `size` pixels, the cell given in the units of a 64 pixel frame, for one channel.
function cellMean(values, size, column, row, channel) {
  const scale = size / SIZE;
  let total = 0;
  let count = 0;
  for (let y = Math.floor(row * CELL * scale); y < Math.floor((row + 1) * CELL * scale); y++) {
    for (let x = Math.floor(column * CELL * scale); x < Math.floor((column + 1) * CELL * scale); x++) {
      total += values[(y * size + x) * 3 + channel];
      count++;
    }
  }
  return total / count;
}

test('the rasterizer and the CPU path tracer draw the same graded fireball, and exposure 0 draws the plain scene', async context => {
  let chromium;
  try {
    ({ chromium } = await import('playwright'));
  } catch {
    skipOrThrow(context, 'playwright is not installed');
    return;
  }
  const port = await freePort();
  const server = await startServer(port);
  let browser;
  try {
    try {
      browser = await launchChrome(chromium);
    } catch (error) {
      skipOrThrow(context, `Chrome did not start: ${error.message.split('\n')[0]}`);
      return;
    }
    const page = await browser.newPage();
    await page.goto(`http://127.0.0.1:${port}/`, { waitUntil: 'domcontentloaded' });
    const switchedOff = { ...COMPARED_SPHERE, emissionRamp: { ...COMPARED_SPHERE.emissionRamp, exposure: 0 } };
    const { frames, glError } = await rasterFrames(page, [[COMPARED_SPHERE], [switchedOff], []]);
    assert.equal(glError, 0);
    const [graded, off, empty] = frames.map(rasterLight);
    assert.deepEqual(Array.from(off), Array.from(empty), 'a ramp at exposure 0 draws the scene with no volume');
    const added = graded.map((value, index) => value - empty[index]);
    const cpu = await cpuLight([COMPARED_SPHERE]);
    let squaredError = 0;
    let squaredMean = 0;
    let largestCell = 0;
    const rows = [];
    for (let row = 0; row < SIZE / CELL; row++) {
      for (let column = 0; column < SIZE / CELL; column++) {
        for (let channel = 0; channel < 3; channel++) {
          const raster = cellMean(added, SIZE, column, row, channel);
          const traced = cellMean(cpu, CPU_SIZE, column, row, channel);
          squaredError += (raster - traced) ** 2;
          squaredMean += traced ** 2;
          largestCell = Math.max(largestCell, Math.abs(raster - traced));
          rows.push({ column, row, channel, raster, traced });
        }
      }
    }
    const relativeRmse = Math.sqrt(squaredError / squaredMean);
    if (process.env.LOCAL_VOLUME_RAMP_ARTIFACTS) {
      mkdirSync(process.env.LOCAL_VOLUME_RAMP_ARTIFACTS, { recursive: true });
      writeFileSync(join(process.env.LOCAL_VOLUME_RAMP_ARTIFACTS, 'ramp-raster-vs-cpu.json'), JSON.stringify({ relativeRmse, largestCell, rows }, null, 1));
    }
    const centerCell = (SIZE / CELL / 2) | 0;
    assert.ok(cellMean(added, SIZE, centerCell, centerCell, 2) / cellMean(added, SIZE, centerCell, centerCell, 0) > 0.08, 'the core is whiter than the edge');
    assert.ok(relativeRmse < 0.03, `relative RMSE between the rasterizer and the path tracer ${relativeRmse}, largest cell ${largestCell}`);
  } finally {
    await browser?.close();
    server.kill();
  }
});

test('the WebGPU path tracer draws a ramp (#1785): it accepts it and compiles the ramp light in only for a scene that has one', () => {
  const [volume] = resolveLocalVolumes([{ shape: 'sphere', center: [0, 0, 0], radius: 1, emissionRamp: { kelvin: [1000, 3000] } }]);
  assert.doesNotThrow(() => assertWebGpuLocalVolumes({ localVolumes: [volume] }));
  assert.equal(webGpuVolumeFeatures([volume]).hasEmissionRamp, true);
  assert.equal(webGpuVolumeFeatures([{ ...volume, emissionRamp: undefined }]).hasEmissionRamp, false);
});

test('a scene recipe resolves emissionRamp through the on-demand module and an edit with a bad ramp throws at build time', () => {
  const recipe = environment => ({ format: 'crucible.scene', schemaVersion: 1, geometries: [{ id: 'box', type: 'box', bevel: 0 }], materials: [{ id: 'finish', color: [0.6, 0.6, 0.6], emission: 0 }], nodes: [{ id: 'block', geometry: 'box', material: 'finish' }], camera: { eye: [4, 3, 5], target: [0, 0, 0] }, environment });
  const volume = { shape: 'sphere', center: [0, 1, 0], radius: 1, emissionRamp: { kelvin: [1000, 3000] } };
  const scene = createAgentScene(recipe({ localVolumes: [volume] }));
  assert.deepEqual(scene.exportRecipe().environment.localVolumes[0].emissionRamp, { source: 'density', range: [0, 1], exposure: 1, kelvin: [1000, 3000] });
  assert.throws(() => createAgentScene(recipe({ localVolumes: [{ ...volume, emissionRamp: { kelvin: [3000, 1000] } }] })), /localVolumes\[0\]\.emissionRamp\.kelvin must be \[cool, hot\]/);
});