Skip to content

3D engine that AI agents drive

11.3 KB
Raw Blame
import assert from 'node:assert/strict';

import { box } from '../src/geometry.js';
import { createEnvironmentMap } from '../src/hdri.js';
import { createCamera, describeIgnoredFeatures } from '../src/path-tracer.js';
import { cookInstalled, cookModule, cookTest } from './support/cook.js';
import { buildTraceScene } from '../src/path-tracer-scene.js';

const cook = await cookModule();
const { STRUCT_STRIDES_V2, buildNativeInputV2, findNativeAddon, traceNative } = cook ?? {};

const hasAddon = cookInstalled && findNativeAddon() !== null;
const skipWithoutAddon = hasAddon ? false : 'the native addon is not built';

const LIGHT_FLAG_PORTAL = 8;
const LIGHT_FLAG_WORD_INDEX = 7;
// `portal_count` (byte 308, FORMAT-v2.md section 1) and `camera_env_scale` (byte 304).
const PORTAL_COUNT_PARAM_WORD = 77;
const CAMERA_ENV_SCALE_PARAM_WORD = 76;
const SEEDS = [1, 2, 3, 4];

// The room is 4 wide, 3 high and 4 deep, its walls are 0.2 thick slabs, and its west wall has a window 2 wide and 1 high.
function slab(centerX, centerY, centerZ, sizeX, sizeY, sizeZ) {
  const matrix = new Float32Array([sizeX, 0, 0, 0, 0, sizeY, 0, 0, 0, 0, sizeZ, 0, centerX, centerY, centerZ, 1]);
  return { name: 'wall', geometry: box(0, 1), matrix, material: { color: [0.35, 0.35, 0.35] } };
}

function roomParts({ withCeiling, withOutsideBox }) {
  const parts = [
    slab(0, -0.1, 0, 4.8, 0.2, 4.8),
    slab(0, 0, -2.1, 4.8, 6, 0.2),
    slab(0, 0, 2.1, 4.8, 6, 0.2),
    slab(2.1, 0, 0, 0.2, 6, 4.8),
    slab(-2.1, 0.5, 0, 0.2, 1, 4),
    slab(-2.1, 2.5, 0, 0.2, 1, 4),
    slab(-2.1, 1.5, -1.5, 0.2, 1, 1),
    slab(-2.1, 1.5, 1.5, 0.2, 1, 1),
  ];
  if (withCeiling) parts.push(slab(0, 3.1, 0, 4.8, 0.2, 4.8));
  if (withOutsideBox) parts.push(slab(-5, 0.75, 0, 1.5, 1.5, 1.5));
  return parts;
}

function skyMap() {
  const width = 32;
  const height = 16;
  const data = new Float32Array(width * height * 3);
  for (let row = 0; row < height; row++) {
    const radiance = row < height / 2 ? 4 : 0.5;
    for (let column = 0; column < width; column++) data.fill(radiance, (row * width + column) * 3, (row * width + column) * 3 + 3);
  }
  return createEnvironmentMap({ width, height, data, intensity: 1 });
}

// Faces into the room (+x) and covers the window exactly, on the wall's inner plane.
const WINDOW_PORTAL = { position: [-2, 1.5, 0], direction: [1, 0, 0], up: [0, 1, 0], width: 2, height: 1, portal: true };

function buildRoomScene({ withPortal, withCeiling = true, withOutsideBox = false }) {
  const environment = { map: skyMap(), areaLights: withPortal ? [WINDOW_PORTAL] : [] };
  return buildTraceScene(roomParts({ withCeiling, withOutsideBox }), environment);
}

const ROOM_CAMERA = { eye: [1.6, 1.4, 1.7], target: [-1, 1, -0.6], fov: 70 };
// Looks away from the window at the wall it lights, so the seeds differ only by the light that reaches the room, not by the
// anti-aliased edge of the bright window.
const WALL_CAMERA = { eye: [-1.4, 1.3, 1.2], target: [2, 1, -0.5], fov: 70 };

function trace(scene, options, cameraDescription = ROOM_CAMERA) {
  const camera = createCamera(cameraDescription, options.width, options.height);
  const input = buildNativeInputV2(scene, camera, options);
  return traceNative(input, { ...options, kernel: 'cycles' });
}

function meanRgb(rgba) {
  const sum = [0, 0, 0];
  const pixelCount = rgba.length / 4;
  for (let pixel = 0; pixel < pixelCount; pixel++) {
    for (let channel = 0; channel < 3; channel++) sum[channel] += rgba[pixel * 4 + channel];
  }
  return sum.map(value => value / pixelCount);
}

// Mean absolute difference per colour value, over every pair of the frames.
function meanSeedDifference(frames) {
  let total = 0;
  let count = 0;
  for (let first = 0; first < frames.length; first++) {
    for (let second = first + 1; second < frames.length; second++) {
      for (let index = 0; index < frames[first].length; index++) {
        if (index % 4 === 3) continue;
        total += Math.abs(frames[first][index] - frames[second][index]);
        count += 1;
      }
    }
  }
  return total / count;
}

function packRoom(areaLights) {
  const scene = buildTraceScene(roomParts({ withCeiling: true, withOutsideBox: false }), { map: skyMap(), areaLights });
  return buildNativeInputV2(scene, createCamera(ROOM_CAMERA, 8, 8), { width: 8, height: 8, samples: 1 });
}

function parameterWord(packed, wordIndex) {
  return new Uint32Array(packed.kernelParams.buffer, packed.kernelParams.byteOffset)[wordIndex];
}

function lightRecordWords(packed, index) {
  return new Uint32Array(packed.lights.buffer, packed.lights.byteOffset + index * STRUCT_STRIDES_V2.light, STRUCT_STRIDES_V2.light / 4);
}

cookTest('buildTraceScene keeps a portal out of the emitting area lights and carries its rectangle', () => {
  const emitter = { position: [0, 2.9, 0], direction: [0, -1, 0], width: 1, height: 1, color: [1, 1, 1], intensity: 5 };
  const { areas, portals } = buildTraceScene(roomParts({ withCeiling: false, withOutsideBox: false }), { areaLights: [emitter, WINDOW_PORTAL] }).lights;
  assert.equal(areas.length, 1);
  assert.equal(portals.length, 1);
  assert.deepEqual(portals[0].position, [-2, 1.5, 0]);
  assert.deepEqual(portals[0].normal, [1, 0, 0]);
  assert.equal(portals[0].width, 2);
  assert.equal(portals[0].height, 1);
  assert.equal(portals[0].intensity, undefined, 'a portal has no power');
});

cookTest('a portal must be a rect light with a size, and says what to pass instead', () => {
  assert.throws(
    () => buildTraceScene(roomParts({ withCeiling: false, withOutsideBox: false }), { areaLights: [{ ...WINDOW_PORTAL, shape: 'disk' }] }),
    /environment\.areaLights\[0\]\.portal is only supported on a rect area light, got shape "disk"/
  );
  assert.throws(
    () => buildTraceScene(roomParts({ withCeiling: false, withOutsideBox: false }), { areaLights: [{ ...WINDOW_PORTAL, width: 0 }] }),
    /portal needs a width above 0/
  );
});

cookTest('the v2 packer appends a portal record after the emitters and counts it apart', () => {
  const emitter = { position: [0, 2.9, 0], direction: [0, -1, 0], width: 1, height: 1, color: [1, 1, 1], intensity: 5 };
  const packed = packRoom([WINDOW_PORTAL, emitter]);
  assert.equal(packed.lightCount, 1, 'the portal is not an emitter');
  assert.equal(packed.portalCount, 1);
  assert.equal(parameterWord(packed, PORTAL_COUNT_PARAM_WORD), 1);
  assert.equal(packed.lightTreeEmitterCount, 1, 'the light tree holds the emitter only');
  assert.equal(lightRecordWords(packed, 0)[LIGHT_FLAG_WORD_INDEX] & LIGHT_FLAG_PORTAL, 0);
  const portalRecord = lightRecordWords(packed, 1);
  assert.equal(portalRecord[LIGHT_FLAG_WORD_INDEX], LIGHT_FLAG_PORTAL);
  assert.deepEqual(Array.from(new Float32Array(portalRecord.buffer, portalRecord.byteOffset, 3)), [-2, 1.5, 0]);
  assert.deepEqual(Array.from(new Float32Array(portalRecord.buffer, portalRecord.byteOffset + 16, 3)), [0, 0, 0], 'radiance');
});

cookTest('the portal count has its own word, next to the camera environment scale, and a scene without portals leaves it 0', () => {
  const withoutPortal = packRoom([]);
  assert.equal(parameterWord(withoutPortal, PORTAL_COUNT_PARAM_WORD), 0);
  assert.equal(withoutPortal.portalCount, 0);
  const scene = buildTraceScene(roomParts({ withCeiling: true, withOutsideBox: false }), { map: skyMap(), areaLights: [WINDOW_PORTAL], cameraIntensity: 0.2 });
  const packed = buildNativeInputV2(scene, createCamera(ROOM_CAMERA, 8, 8), { width: 8, height: 8, samples: 1 });
  assert.equal(parameterWord(packed, PORTAL_COUNT_PARAM_WORD), 1);
  assert.notEqual(parameterWord(packed, CAMERA_ENV_SCALE_PARAM_WORD), 0, 'the camera environment scale is kept');
});

cookTest('a scene with only a portal has no emitters and no light tree', () => {
  const packed = packRoom([WINDOW_PORTAL]);
  assert.equal(packed.lightCount, 0);
  assert.equal(packed.portalCount, 1);
  assert.equal(packed.lightTreeNodeCount, 0);
  assert.equal(lightRecordWords(packed, 0)[LIGHT_FLAG_WORD_INDEX], LIGHT_FLAG_PORTAL);
});

cookTest('the v2 packer rejects a disk portal', () => {
  const scene = buildTraceScene(roomParts({ withCeiling: false, withOutsideBox: false }), {});
  scene.lights.areas.push({ bit: 26, shape: 'disk', portal: true, position: [0, 1, 0], normal: [1, 0, 0], width: 1, height: 1 });
  assert.throws(() => buildNativeInputV2(scene, createCamera(ROOM_CAMERA, 8, 8), { width: 8, height: 8, samples: 1 }), /needs a rect light/);
});

cookTest('the WebGL tracer is told that a portal draws nothing, the CPU and WebGPU tracers and the native kernel are not', () => {
  const environment = { areaLights: [WINDOW_PORTAL] };
  assert.match(describeIgnoredFeatures([], environment, 'gpu').join(' '), /Light portals .* are ignored/);
  assert.doesNotMatch(describeIgnoredFeatures([], environment, 'cpu').join(' '), /portal/);
  assert.doesNotMatch(describeIgnoredFeatures([], environment, 'webgpu').join(' '), /portal/);
  assert.doesNotMatch(describeIgnoredFeatures([], environment, 'native', { kernelMaterials: true }).join(' '), /portal/);
  assert.doesNotMatch(describeIgnoredFeatures([], { areaLights: [] }, 'cpu').join(' '), /portal/);
});

cookTest('a portal keeps the mean of a room lit through a window', { skip: skipWithoutAddon }, t => {
  const common = { width: 48, height: 32, samples: 2048, samplesPerDispatch: 64, seed: 7 };
  const without = meanRgb(trace(buildRoomScene({ withPortal: false }), common).rgba);
  const withPortal = meanRgb(trace(buildRoomScene({ withPortal: true }), common).rgba);
  t.diagnostic(`mean ${withPortal.map((value, channel) => (value / without[channel]).toFixed(4)).join(' ')} (portal over no portal, per channel)`);
  for (let channel = 0; channel < 3; channel++) {
    assert.ok(without[channel] > 0.05, `channel ${channel} is lit`);
    assert.ok(Math.abs(withPortal[channel] / without[channel] - 1) < 0.01, `channel ${channel}: ${withPortal[channel]} with a portal against ${without[channel]} without`);
  }
});

cookTest('a portal cuts the change between seeds of a frozen camera by at least 4 times', { skip: skipWithoutAddon }, t => {
  const common = { width: 48, height: 32, samples: 64, samplesPerDispatch: 64 };
  const framesOf = withPortal => SEEDS.map(seed => trace(buildRoomScene({ withPortal }), { ...common, seed }, WALL_CAMERA).rgba);
  const differenceWithout = meanSeedDifference(framesOf(false));
  const differenceWith = meanSeedDifference(framesOf(true));
  const ratio = differenceWithout / differenceWith;
  t.diagnostic(`mean seed difference ${differenceWithout.toFixed(5)} without, ${differenceWith.toFixed(5)} with a portal, ratio ${ratio.toFixed(2)}`);
  assert.ok(ratio >= 4, `seed difference fell ${ratio.toFixed(2)} times (${differenceWithout} to ${differenceWith})`);
});

cookTest('a portal does not darken sky seen directly or an object outside the window', { skip: skipWithoutAddon }, t => {
  const common = { width: 48, height: 32, samples: 2048, samplesPerDispatch: 64, seed: 11 };
  const without = meanRgb(trace(buildRoomScene({ withPortal: false, withCeiling: false, withOutsideBox: true }), common).rgba);
  const withPortal = meanRgb(trace(buildRoomScene({ withPortal: true, withCeiling: false, withOutsideBox: true }), common).rgba);
  t.diagnostic(`open scene mean ${withPortal.map((value, channel) => (value / without[channel]).toFixed(4)).join(' ')} (portal over no portal, per channel)`);
  for (let channel = 0; channel < 3; channel++) {
    assert.ok(Math.abs(withPortal[channel] / without[channel] - 1) < 0.015, `channel ${channel}: ${withPortal[channel]} with a portal against ${without[channel]} without`);
  }
});