Skip to content

3D engine that AI agents drive

9.1 KB
Raw Blame
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import test from 'node:test';
import { fileURLToPath } from 'node:url';

import { box } from '../src/geometry.js';
import { createCamera } from '../src/path-tracer.js';
import * as pack from '../src/path-tracer-gpu-pack.js';
import { buildTraceScene } from '../src/path-tracer-scene.js';
import { cookInstalled, cookModule, cookTest } from './support/cook.js';

const { buildNativeInput, findNativeAddon, traceNative } = (await cookModule()) ?? {};

const skipWithoutAddon = !cookInstalled || findNativeAddon() === null ? 'the native addon is not built' : false;
const SIZE = 16;
const FLOOR_ALBEDO = 0.8;
const LAMP_HEIGHT = 2;
const LAMP_INTENSITY = 8;
const CAMERA_HEIGHT = 6;
const CAMERA_FIELD_OF_VIEW_DEGREES = 30;
const PATCH_SIDE = 4;
const cameraDescription = { eye: [0, CAMERA_HEIGHT, 0], target: [0, 0, 0], up: [0, 0, -1], fov: CAMERA_FIELD_OF_VIEW_DEGREES };

function floorPart() {
  const matrix = new Float32Array([20, 0, 0, 0, 0, 0.1, 0, 0, 0, 0, 20, 0, 0, -0.05, 0, 1]);
  const material = { tag: 'surface', metallic: 0, roughness: 1, specular: 0, emission: 0, color: [FLOOR_ALBEDO, FLOOR_ALBEDO, FLOOR_ALBEDO] };
  return { name: 'floor', geometry: box(0, 1), matrix, material };
}

function renderFloorUnderLamp(radius, lampKind = 'point', lampFields = {}) {
  const environment = {
    keyColor: [0, 0, 0],
    lightDirection: [0, 1, 0],
    ambientIntensity: 0,
    fillIntensity: 0,
    pointLights: [],
    spotLights: [],
  };
  const lamp = { position: [0, LAMP_HEIGHT, 0], color: [1, 1, 1], intensity: LAMP_INTENSITY, radius, castShadow: true, ...lampFields };
  if (lampKind === 'spot') {
    environment.spotLights.push({ direction: [0, -1, 0], angle: 1.2, penumbra: 0, ...lamp });
  } else {
    environment.pointLights.push(lamp);
  }
  const scene = buildTraceScene([floorPart()], environment);
  const camera = createCamera(cameraDescription, SIZE, SIZE);
  const input = buildNativeInput(scene, camera, { width: SIZE, height: SIZE, samples: 256, bounces: 2, seed: 1 }, pack);
  return traceNative(input, { width: SIZE, height: SIZE, samples: 256, bounces: 2, kernel: 'cycles' }).rgba;
}

function centreRadiance(rgba) {
  let sum = 0;
  const first = (SIZE - PATCH_SIDE) / 2;
  for (let row = first; row < first + PATCH_SIDE; row++) {
    for (let column = first; column < first + PATCH_SIDE; column++) {
      sum += rgba[(row * SIZE + column) * 4 + 1];
    }
  }
  return sum / (PATCH_SIDE * PATCH_SIDE);
}

// Where the centre of a pixel column or row lands on the floor, in metres from the point under the lamp.
function floorOffsetOfPixel(pixelIndex) {
  const halfExtent = CAMERA_HEIGHT * Math.tan((CAMERA_FIELD_OF_VIEW_DEGREES * Math.PI) / 360);
  return (((pixelIndex + 0.5) / SIZE) * 2 - 1) * halfExtent;
}

function sphereIrradianceAt(distanceSquared) {
  return (LAMP_INTENSITY * LAMP_HEIGHT) / distanceSquared ** 1.5;
}

// A soft falloff light (Cycles' oriented disk of radius r, radiance I / (pi r^2)) faces the floor point at distance d, so every point
// of the disk is at t^2 = d^2 + rho^2 with the cosine d / t at the lamp. Integrating the cosine at a floor point whose normal makes
// the angle beta with the line to the lamp over the disk (the azimuth term of the floor cosine integrates to zero) gives
// E = I cos(beta) / (d^2 + r^2), with cos(beta) = h / d. It is the point light value with d^2 raised by r^2 under the cube.
function softFalloffIrradianceAt(radius) {
  return distanceSquared => (LAMP_INTENSITY * LAMP_HEIGHT) / (Math.sqrt(distanceSquared) * (distanceSquared + radius * radius));
}

// A sphere light of intensity I lights a diffuse floor point at a horizontal distance s, with every part of the sphere above
// the floor, with I * h / (h^2 + s^2)^(3/2), whatever its radius: the power stays fixed as the radius grows. The pixels the
// test averages reach about 0.5 m from the point under the lamp, where the floor is a few percent darker than at that point.
function closedFormCentreRadiance(irradianceAt = sphereIrradianceAt) {
  let sum = 0;
  const first = (SIZE - PATCH_SIDE) / 2;
  for (let row = first; row < first + PATCH_SIDE; row++) {
    for (let column = first; column < first + PATCH_SIDE; column++) {
      const distanceSquared = LAMP_HEIGHT * LAMP_HEIGHT + floorOffsetOfPixel(row) ** 2 + floorOffsetOfPixel(column) ** 2;
      sum += (FLOOR_ALBEDO / Math.PI) * irradianceAt(distanceSquared);
    }
  }
  return sum / (PATCH_SIDE * PATCH_SIDE);
}

test('the Cycles reference script follows each light softFalloff, off when absent, unless --soft-falloff overrides it', () => {
  const source = readFileSync(new URL('../bench/cycles-parity/render-cycles.py', import.meta.url), 'utf8');
  assert.match(source, /if "--soft-falloff" not in argument_list:\s+return SOFT_FALLOFF_FROM_SCENE/, 'without the flag each light follows its scene entry');
  assert.match(source, /light_data\.use_soft_falloff = light_entry\.get\("softFalloff"\) is True/, 'a light without the field is a sphere');
  assert.match(source, /read_flag_value\(argument_list, "--soft-falloff", "off"\)/, 'an explicit flag value is read');
  assert.match(source, /light_data\.use_soft_falloff = soft_falloff_setting/, 'the explicit setting reaches the light');
  const callCount = source.split('apply_soft_falloff_setting(').length - 1;
  assert.equal(callCount, 3, 'the definition and one call each for point lights and spot lights');
});

for (const radius of [0, 0.18, 0.5]) {
  cookTest(`the native cycles kernel keeps the power of a point light of radius ${radius} m`, { skip: skipWithoutAddon }, () => {
    const expected = closedFormCentreRadiance();
    const measured = centreRadiance(renderFloorUnderLamp(radius));
    assert.ok(Math.abs(measured / expected - 1) < 0.03, `floor radiance ${measured} against the closed form ${expected}`);
  });
}

for (const lampKind of ['point', 'spot']) {
  for (const radius of [0.18, 0.5, 1]) {
    cookTest(`the native cycles kernel lights a floor under a soft falloff ${lampKind} light of radius ${radius} m as an oriented disk`, { skip: skipWithoutAddon }, () => {
      const expected = closedFormCentreRadiance(softFalloffIrradianceAt(radius));
      const measured = centreRadiance(renderFloorUnderLamp(radius, lampKind, { softFalloff: true }));
      assert.ok(Math.abs(measured / expected - 1) < 0.03, `floor radiance ${measured} against the closed form ${expected}`);
    });
  }
}

cookTest('a light without softFalloff stays a sphere: the floor under a 1 m lamp keeps the sphere value', { skip: skipWithoutAddon }, () => {
  const expected = closedFormCentreRadiance();
  const measured = centreRadiance(renderFloorUnderLamp(1, 'point', { softFalloff: false }));
  assert.ok(Math.abs(measured / expected - 1) < 0.03, `floor radiance ${measured} against the closed form ${expected}`);
});

// Boxes of the lamp scenes that overlap or share a coplanar front face made Cook and Cycles disagree by a column of pixels
// on the shade (#1070), so the scenes must be made of boxes that only touch.
function boxBounds(part) {
  const matrix = part.matrix;
  return [0, 1, 2].map((axis) => ({ low: matrix[12 + axis] - matrix[axis * 5] / 2, high: matrix[12 + axis] + matrix[axis * 5] / 2 }));
}

function boxesOverlapInVolume(firstBounds, secondBounds) {
  const overlapPerAxis = [0, 1, 2].map((axis) => Math.min(firstBounds[axis].high, secondBounds[axis].high) - Math.max(firstBounds[axis].low, secondBounds[axis].low));
  return overlapPerAxis.every((overlap) => overlap > 1e-9);
}

test('the shade of the lamp scenes is built from boxes that do not overlap', () => {
  const workDirectory = mkdtempSync(join(tmpdir(), 'sphere-light-scenes-'));
  try {
    const baseScenePath = join(workDirectory, 'base.json');
    const roomParts = Array.from({ length: 5 }, (_, index) => ({ name: `room-${index}`, geometry: 0, matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 100 * index, 0, 0, 1], material: 0 }));
    writeFileSync(baseScenePath, JSON.stringify({ id: 'base', parts: roomParts, environment: {} }));
    execFileSync('node', [fileURLToPath(new URL('../bench/cycles-parity/make-sphere-light-scenes.mjs', import.meta.url)), baseScenePath, workDirectory], { stdio: 'ignore' });
    for (const sceneName of ['enclosed-r0.18', 'enclosed-hidden-r0.18', 'poking-r0.18', 'poking-hidden-r0.18']) {
      const scene = JSON.parse(readFileSync(join(workDirectory, 'scenes', `${sceneName}.json`), 'utf8'));
      const shadeParts = scene.parts.filter((part) => part.name.startsWith('shade-'));
      assert.equal(shadeParts.length, 5, `${sceneName} has a lid and four walls`);
      for (let first = 0; first < shadeParts.length; first++) {
        for (let second = first + 1; second < shadeParts.length; second++) {
          const overlaps = boxesOverlapInVolume(boxBounds(shadeParts[first]), boxBounds(shadeParts[second]));
          assert.equal(overlaps, false, `${sceneName}: ${shadeParts[first].name} and ${shadeParts[second].name} overlap`);
        }
      }
    }
  } finally {
    rmSync(workDirectory, { recursive: true, force: true });
  }
});