3D engine that AI agents drive
Add the instanced-versus-flattened equivalence test and bench variants (#896)
Nguyen Xuan An1613c0830c02
diff --git a/bench/instancing/copies-scene.mjs b/bench/instancing/copies-scene.mjsnew file mode 100644index 00000000..c2a1447d--- /dev/null+++ b/bench/instancing/copies-scene.mjs@@ -0,0 +1,93 @@+// The scene of the instancing benches and the equivalence test: N copies of one small mesh placed on a grid.+// A variant sets how the copies are placed: translate, rotscale (rotated, non-uniform scale), mirror (negative+// determinant), mirror-rotscale, or emissive (translate, with one emissive material).+export const COPY_VARIANTS = ['translate', 'rotscale', 'mirror', 'mirror-rotscale', 'emissive'];++function midpoint(positions, first, second) {+ return [0, 1, 2].map(axis => (positions[first * 3 + axis] + positions[second * 3 + axis]) / 2);+}++// An icosphere: 20 triangles, each split in four per level, so level 2 has 320.+function icosphere(levels) {+ const golden = (1 + Math.sqrt(5)) / 2;+ let positions = [-1, golden, 0, 1, golden, 0, -1, -golden, 0, 1, -golden, 0, 0, -1, golden, 0, 1, golden, 0, -1, -golden, 0, 1, -golden, golden, 0, -1, golden, 0, 1, -golden, 0, -1, -golden, 0, 1];+ let indices = [0, 11, 5, 0, 5, 1, 0, 1, 7, 0, 7, 10, 0, 10, 11, 1, 5, 9, 5, 11, 4, 11, 10, 2, 10, 7, 6, 7, 1, 8, 3, 9, 4, 3, 4, 2, 3, 2, 6, 3, 6, 8, 3, 8, 9, 4, 9, 5, 2, 4, 11, 6, 2, 10, 8, 6, 7, 9, 8, 1];+ for (let level = 0; level < levels; level++) {+ const next = [];+ const cache = new Map();+ const middle = (first, second) => {+ const key = first < second ? `${first}:${second}` : `${second}:${first}`;+ if (!cache.has(key)) {+ cache.set(key, positions.length / 3);+ positions = positions.concat(midpoint(positions, first, second));+ }+ return cache.get(key);+ };+ for (let triangle = 0; triangle < indices.length; triangle += 3) {+ const [a, b, c] = indices.slice(triangle, triangle + 3);+ const ab = middle(a, b);+ const bc = middle(b, c);+ const ca = middle(c, a);+ next.push(a, ab, ca, b, bc, ab, c, ca, bc, ab, bc, ca);+ }+ indices = next;+ }+ const unit = new Float32Array(positions.length);+ for (let vertex = 0; vertex < positions.length / 3; vertex++) {+ const length = Math.hypot(positions[vertex * 3], positions[vertex * 3 + 1], positions[vertex * 3 + 2]);+ for (let axis = 0; axis < 3; axis++) unit[vertex * 3 + axis] = positions[vertex * 3 + axis] / length;+ }+ return { positions: unit, normals: Float32Array.from(unit), indices: Uint32Array.from(indices) };+}++const MATERIALS = [+ { color: [0.8, 0.25, 0.2], roughness: 0.5 },+ { color: [0.2, 0.6, 0.85], roughness: 0.3, metallic: 0.8 },+ { color: [0.85, 0.8, 0.3], roughness: 0.7 },+];+const EMISSIVE_MATERIAL = { color: [1, 0.6, 0.2], roughness: 0.7, emission: 4 };++// Column-major matrix of a rotation about a unit axis, times a per-axis scale, moved by `translation`.+function transformMatrix(scales, angle, translation) {+ const axis = [0.3, 0.8, 0.5];+ const length = Math.hypot(...axis);+ const [x, y, z] = axis.map(value => value / length);+ const cosine = Math.cos(angle);+ const sine = Math.sin(angle);+ const rotation = [+ [cosine + x * x * (1 - cosine), x * y * (1 - cosine) - z * sine, x * z * (1 - cosine) + y * sine],+ [y * x * (1 - cosine) + z * sine, cosine + y * y * (1 - cosine), y * z * (1 - cosine) - x * sine],+ [z * x * (1 - cosine) - y * sine, z * y * (1 - cosine) + x * sine, cosine + z * z * (1 - cosine)],+ ];+ const column = axisIndex => [0, 1, 2].map(row => rotation[row][axisIndex] * scales[axisIndex]);+ return [...column(0), 0, ...column(1), 0, ...column(2), 0, ...translation, 1];+}++function scalesFor(variant, index) {+ const uniform = 0.3 + 0.1 * ((index * 7) % 5) / 4;+ const mirrored = variant.startsWith('mirror');+ const stretched = variant.endsWith('rotscale');+ const stretch = stretched ? [1.4, 0.7, 1 + 0.1 * (index % 3)] : [1, 1, 1];+ return stretch.map((factor, axis) => uniform * factor * (mirrored && axis === 0 ? -1 : 1));+}++function buildParts(geometry, variant, copyCount) {+ const side = Math.ceil(Math.cbrt(copyCount));+ const rotates = variant.endsWith('rotscale');+ return Array.from({ length: copyCount }, (_, index) => {+ const column = index % side;+ const row = Math.floor(index / side) % side;+ const layer = Math.floor(index / (side * side));+ const translation = [(column - side / 2) * 1.1, (row - side / 2) * 1.1, -layer * 1.1];+ const matrix = transformMatrix(scalesFor(variant, index), rotates ? 0.4 + index * 0.37 : 0, translation);+ const material = variant === 'emissive' && index % 4 === 0 ? EMISSIVE_MATERIAL : MATERIALS[index % MATERIALS.length];+ return { name: `copy-${index}`, geometry, matrix, material };+ });+}+++export function buildCopyScene(variant, copyCount) {+ if (!COPY_VARIANTS.includes(variant)) throw new RangeError(`Pass one of ${COPY_VARIANTS.join(', ')} as the variant.`);+ const geometry = icosphere(2);+ return { geometry, parts: buildParts(geometry, variant, copyCount), environment: { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] } };+}diff --git a/bench/instancing/render-copies.mjs b/bench/instancing/render-copies.mjsindex 3a0cf89c..46fd64e1 100644--- a/bench/instancing/render-copies.mjs+++ b/bench/instancing/render-copies.mjs@@ -1,93 +1,39 @@// Renders N copies of one small mesh through the native "cycles" kernel, either as shared instances or flattened into one// triangle soup, and writes the linear RGBA floats beside a JSON report. Usage:-// node bench/instancing/render-copies.mjs <instanced|flattened> <output folder> [copies] [width] [height] [samples]+// node bench/instancing/render-copies.mjs <instanced|flattened> <output folder> [copies] [width] [height] [samples] [variant] [seed]+// A variant sets how the copies are placed: translate (default), rotscale (rotated, non-uniform scale), mirror (negative+// determinant), mirror-rotscale, or emissive (translate, with one emissive material).import { mkdirSync, writeFileSync } from 'node:fs';import { buildNativeInputV2, traceNative } from '../../packages/render-native/index.mjs';+import { buildCopyScene } from './copies-scene.mjs';import { createCamera } from '../../src/path-tracer.js';import { buildTraceScene } from '../../src/path-tracer-scene.js';-const [mode, outputFolder, copiesText = '1000', widthText = '160', heightText = '120', samplesText = '64'] = process.argv.slice(2);+const [mode, outputFolder, copiesText = '1000', widthText = '160', heightText = '120', samplesText = '64', variant = 'translate', seedText = '1'] = process.argv.slice(2);if (mode !== 'instanced' && mode !== 'flattened') throw new RangeError('Pass "instanced" or "flattened" as the first argument.');const copyCount = Number(copiesText);const width = Number(widthText);const height = Number(heightText);const samples = Number(samplesText);+const seed = Number(seedText);-function midpoint(positions, first, second) {- return [0, 1, 2].map(axis => (positions[first * 3 + axis] + positions[second * 3 + axis]) / 2);-}--// An icosphere: 20 triangles, each split in four per level, so level 2 has 320.-function icosphere(levels) {- const golden = (1 + Math.sqrt(5)) / 2;- let positions = [-1, golden, 0, 1, golden, 0, -1, -golden, 0, 1, -golden, 0, 0, -1, golden, 0, 1, golden, 0, -1, -golden, 0, 1, -golden, golden, 0, -1, golden, 0, 1, -golden, 0, -1, -golden, 0, 1];- let indices = [0, 11, 5, 0, 5, 1, 0, 1, 7, 0, 7, 10, 0, 10, 11, 1, 5, 9, 5, 11, 4, 11, 10, 2, 10, 7, 6, 7, 1, 8, 3, 9, 4, 3, 4, 2, 3, 2, 6, 3, 6, 8, 3, 8, 9, 4, 9, 5, 2, 4, 11, 6, 2, 10, 8, 6, 7, 9, 8, 1];- for (let level = 0; level < levels; level++) {- const next = [];- const cache = new Map();- const middle = (first, second) => {- const key = first < second ? `${first}:${second}` : `${second}:${first}`;- if (!cache.has(key)) {- cache.set(key, positions.length / 3);- positions = positions.concat(midpoint(positions, first, second));- }- return cache.get(key);- };- for (let triangle = 0; triangle < indices.length; triangle += 3) {- const [a, b, c] = indices.slice(triangle, triangle + 3);- const ab = middle(a, b);- const bc = middle(b, c);- const ca = middle(c, a);- next.push(a, ab, ca, b, bc, ab, c, ca, bc, ab, bc, ca);- }- indices = next;- }- const unit = new Float32Array(positions.length);- for (let vertex = 0; vertex < positions.length / 3; vertex++) {- const length = Math.hypot(positions[vertex * 3], positions[vertex * 3 + 1], positions[vertex * 3 + 2]);- for (let axis = 0; axis < 3; axis++) unit[vertex * 3 + axis] = positions[vertex * 3 + axis] / length;- }- return { positions: unit, normals: Float32Array.from(unit), indices: Uint32Array.from(indices) };-}--const MATERIALS = [- { color: [0.8, 0.25, 0.2], roughness: 0.5 },- { color: [0.2, 0.6, 0.85], roughness: 0.3, metallic: 0.8 },- { color: [0.85, 0.8, 0.3], roughness: 0.7 },-];--function buildParts(geometry) {- const side = Math.ceil(Math.cbrt(copyCount));- return Array.from({ length: copyCount }, (_, index) => {- const column = index % side;- const row = Math.floor(index / side) % side;- const layer = Math.floor(index / (side * side));- const scale = 0.3 + 0.1 * ((index * 7) % 5) / 4;- // Every seventh copy is mirrored, which flips the winding and exercises the negative-scale flag.- const mirror = index % 7 === 0 ? -1 : 1;- const matrix = [scale * mirror, 0, 0, 0, 0, scale, 0, 0, 0, 0, scale, 0, (column - side / 2) * 1.1, (row - side / 2) * 1.1, -layer * 1.1, 1];- return { name: `copy-${index}`, geometry, matrix, material: MATERIALS[index % MATERIALS.length] };- });-}--const geometry = icosphere(2);-const parts = buildParts(geometry);-const environment = { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] };+const { geometry, parts, environment } = buildCopyScene(variant, copyCount);const camera = createCamera({ eye: [0, 0, 14], target: [0, 0, -3], fov: 50 }, width, height);const packStarted = performance.now();const scene = buildTraceScene(parts, environment, { instancing: mode === 'instanced' });-const input = buildNativeInputV2(scene, camera, { width, height, samples, seed: 1 });+const input = buildNativeInputV2(scene, camera, { width, height, samples, seed });const packSeconds = (performance.now() - packStarted) / 1000;const traced = traceNative(input, { width, height, samples, kernel: 'cycles' });+const stem = `${variant}-${mode}-seed${seed}`;mkdirSync(outputFolder, { recursive: true });-writeFileSync(`${outputFolder}/${mode}.f32`, Buffer.from(traced.rgba.buffer, traced.rgba.byteOffset, traced.rgba.byteLength));+writeFileSync(`${outputFolder}/${stem}.f32`, Buffer.from(traced.rgba.buffer, traced.rgba.byteOffset, traced.rgba.byteLength));const report = {- mode, copyCount, width, height, samples, adapter: traced.adapter, packSeconds,+ mode, variant, seed, copyCount, width, height, samples, adapter: traced.adapter, packSeconds,instanceCount: input.instanceCount, triangleCount: input.triangleCount, geometryTriangles: geometry.indices.length / 3,trianglesBytes: input.triangles.byteLength, instancesBytes: input.instances.byteLength,setupSeconds: traced.setupSeconds, accelerationBuildSeconds: traced.accelerationBuildSeconds, uploadSeconds: traced.uploadSeconds,};-writeFileSync(`${outputFolder}/${mode}.json`, JSON.stringify(report, null, 2));+writeFileSync(`${outputFolder}/${stem}.json`, JSON.stringify(report, null, 2));console.log(JSON.stringify(report));diff --git a/tests/native-instancing-equivalence.test.js b/tests/native-instancing-equivalence.test.jsnew file mode 100644index 00000000..764c7e73--- /dev/null+++ b/tests/native-instancing-equivalence.test.js@@ -0,0 +1,72 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { buildNativeInputV2, findNativeAddon, traceNative } from '../packages/render-native/index.mjs';+import { buildCopyScene } from '../bench/instancing/copies-scene.mjs';+import { createCamera } from '../src/path-tracer.js';+import { buildTraceScene } from '../src/path-tracer-scene.js';++// Instanced copies against the same scene flattened, on the native "cycles" kernel. Skipped without the built addon or a+// ray query adapter. The bounds sit well above what Modal's A10 measured at 1024 samples (relMSE under 6e-5, tiles within+// 1.2 percent) and near the seed-to-seed noise of the flattened scene itself (relMSE about 1.5e-4).+const COPIES = 200;+const WIDTH = 128;+const HEIGHT = 96;+const SAMPLES = 1024;+const TILES = 8;++function render(variant, instancing, seed) {+ const { parts, environment } = buildCopyScene(variant, COPIES);+ const camera = createCamera({ eye: [0, 0, 14], target: [0, 0, -3], fov: 50 }, WIDTH, HEIGHT);+ const scene = buildTraceScene(parts, environment, { instancing });+ const input = buildNativeInputV2(scene, camera, { width: WIDTH, height: HEIGHT, samples: SAMPLES, seed });+ return traceNative(input, { width: WIDTH, height: HEIGHT, samples: SAMPLES, kernel: 'cycles' }).rgba;+}++function relativeMeanSquaredError(candidate, reference) {+ let total = 0;+ for (let pixel = 0; pixel < WIDTH * HEIGHT; pixel++) {+ for (let channel = 0; channel < 3; channel++) {+ const expected = reference[pixel * 4 + channel];+ const difference = candidate[pixel * 4 + channel] - expected;+ total += (difference * difference) / (expected * expected + 0.01);+ }+ }+ return total / (WIDTH * HEIGHT * 3);+}++function tileMeanRatios(candidate, reference) {+ const ratios = [];+ for (let tileRow = 0; tileRow < TILES; tileRow++) {+ for (let tileColumn = 0; tileColumn < TILES; tileColumn++) {+ let candidateSum = 0;+ let referenceSum = 0;+ for (let row = Math.floor(tileRow * HEIGHT / TILES); row < Math.floor((tileRow + 1) * HEIGHT / TILES); row++) {+ for (let column = Math.floor(tileColumn * WIDTH / TILES); column < Math.floor((tileColumn + 1) * WIDTH / TILES); column++) {+ for (let channel = 0; channel < 3; channel++) {+ candidateSum += candidate[(row * WIDTH + column) * 4 + channel];+ referenceSum += reference[(row * WIDTH + column) * 4 + channel];+ }+ }+ }+ if (referenceSum > 1e-3) ratios.push(candidateSum / referenceSum);+ }+ }+ return ratios;+}++const addonSkip = findNativeAddon() ? false : 'the native addon is not built';++for (const variant of ['translate', 'rotscale', 'emissive']) {+ test(`instanced ${variant} copies render the flattened image within tolerance`, { skip: addonSkip }, t => {+ let flattened;+ try {+ flattened = render(variant, false, 1);+ } catch (error) {+ if (/adapter|Vulkan|ray quer/i.test(error.message)) return t.skip(error.message);+ throw error;+ }+ const instanced = render(variant, true, 1);+ assert.ok(relativeMeanSquaredError(instanced, flattened) < 5e-4);+ for (const ratio of tileMeanRatios(instanced, flattened)) assert.ok(ratio > 0.98 && ratio < 1.02, `tile mean ratio ${ratio}`);+ });+}