Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.mjs
new file mode 100644
index 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.mjs
index 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.js
new file mode 100644
index 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}`);
+ });
+}