Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add JS67_NATIVE_INSTANCING, the table bytes in the job report and a real native job check (#896)

Nguyen Xuan Andce07a5af797
diff --git a/bench/instancing/native-job-check.mjs b/bench/instancing/native-job-check.mjs
new file mode 100644
index 00000000..436f9063
--- /dev/null
+++ b/bench/instancing/native-job-check.mjs
@@ -0,0 +1,98 @@
+// A real native render job through the MCP runtime and a headless browser, to see which path the scene took.
+// node bench/instancing/native-job-check.mjs run <repeated|distinct> <output folder> [samples] [mcp entry]
+// Starts the MCP server (JS67_NATIVE_INSTANCING in the environment is passed on), creates the scene, submits one
+// native path-traced image job, and writes <scene>.png and <scene>.json (the job report, the PNG digest and the
+// card memory in use before and during the job, from nvidia-smi).
+// node bench/instancing/native-job-check.mjs compare <candidate.png> <reference.png>
+// Mean ratio, relative MSE (epsilon 0.01) and 8x8 tiles within 5 percent between two job images (8-bit, sRGB).
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { recipeFor } from './native-job-scenes.mjs';
+import { meanRatioRgb, relativeMeanSquaredError, tileMeanRatios } from './image-compare.mjs';
+
+const WIDTH = 160;
+const HEIGHT = 120;
+
+function cardMemoryMiB() {
+ const answer = spawnSync('nvidia-smi', ['--query-gpu=memory.used', '--format=csv,noheader,nounits'], { encoding: 'utf8' });
+ return answer.status === 0 ? Number(answer.stdout.split('\n')[0]) : null;
+}
+
+async function run(scene, outputFolder, samples, entry) {
+ const { Client } = await import('@modelcontextprotocol/client');
+ const { StdioClientTransport } = await import('@modelcontextprotocol/client/stdio');
+ const workFolder = mkdtempSync(join(tmpdir(), '67js-native-job-'));
+ const transport = new StdioClientTransport({ command: process.execPath,
+ args: [resolve(entry), '--backend', 'gpu', '--memory', '192', '--jobs', join(workFolder, 'jobs'), ...(process.env.CHROME_PATH ? ['--browser', process.env.CHROME_PATH] : [])],
+ cwd: workFolder, env: { ...process.env }, stderr: 'pipe' });
+ let diagnostics = '';
+ transport.stderr.on('data', bytes => { diagnostics = (diagnostics + bytes).slice(-4096); });
+ const client = new Client({ name: '67js-native-job-check', version: '1' });
+ await client.connect(transport);
+ const call = async (name, argumentsValue) => {
+ const result = await client.callTool({ name, arguments: argumentsValue }, { timeout: 60000 });
+ if (result.isError) throw new Error(`${name}: ${result.content?.find(item => item.type === 'text')?.text}`);
+ return result.structuredContent ?? result;
+ };
+ try {
+ const created = await call('scene_create', { recipe: recipeFor(scene) });
+ const baseline = cardMemoryMiB();
+ let peak = baseline;
+ const sampler = setInterval(() => { peak = Math.max(peak ?? 0, cardMemoryMiB() ?? 0); }, 150);
+ const submitted = await call('scene_render_submit', { sessionId: created.sessionId, expectedRevision: created.revision ?? 0, settings: {
+ kind: 'image', width: WIDTH, height: HEIGHT,
+ renderer: { type: 'pathTracer', backend: 'native', samples, bounces: 4, denoise: false, seed: 1, maxSeconds: 300 },
+ } });
+ let record;
+ for (let attempt = 0; attempt < 1200; attempt++) {
+ record = await call('scene_render_status', { jobId: submitted.jobId });
+ if (['completed', 'failed', 'cancelled', 'interrupted'].includes(record.state)) break;
+ await delay(500);
+ }
+ clearInterval(sampler);
+ if (record.state !== 'completed') throw new Error(`job ${record.state}: ${record.reason ?? ''} ${diagnostics}`);
+ const result = await call('scene_render_result', { jobId: submitted.jobId });
+ const artifact = result.artifacts[0];
+ const bytes = readFileSync(artifact.path);
+ mkdirSync(outputFolder, { recursive: true });
+ writeFileSync(join(outputFolder, `${scene}.png`), bytes);
+ const summary = { scene, instancingEnvironment: process.env.JS67_NATIVE_INSTANCING ?? 'default', samples,
+ pngSha256: createHash('sha256').update(bytes).digest('hex'), cardMemoryMiB: { before: baseline, peak },
+ report: result.metrics?.pathTracer };
+ writeFileSync(join(outputFolder, `${scene}.json`), JSON.stringify(summary, null, 2));
+ console.log(JSON.stringify(summary));
+ } finally {
+ await client.close();
+ }
+}
+
+async function compare(candidatePath, referencePath) {
+ const { default: sharp } = await import('sharp');
+ const decode = async path => {
+ const { data, info } = await sharp(path).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+ return { pixels: Float32Array.from(data, value => value / 255), width: info.width, height: info.height };
+ };
+ const candidate = await decode(candidatePath);
+ const reference = await decode(referencePath);
+ const pixelCount = candidate.width * candidate.height;
+ const ratios = tileMeanRatios(candidate.pixels, reference.pixels, candidate.width, candidate.height, 8);
+ console.log(JSON.stringify({
+ meanRatioRgb: meanRatioRgb(candidate.pixels, reference.pixels, pixelCount).map(value => Number(value.toFixed(4))),
+ relativeMse: Number(relativeMeanSquaredError(candidate.pixels, reference.pixels, pixelCount, 0.01).toPrecision(3)),
+ tilesWithin5Percent: ratios.filter(ratio => Math.abs(ratio - 1) <= 0.05).length,
+ eligibleTiles: ratios.length,
+ }));
+}
+
+const [command, first, second, third, fourth] = process.argv.slice(2);
+if (command === 'run' && (first === 'repeated' || first === 'distinct') && second) {
+ await run(first, second, Number(third ?? 1024), fourth ?? 'bin/67js-mcp.mjs');
+} else if (command === 'compare' && first && second) {
+ await compare(first, second);
+} else {
+ throw new RangeError('Usage: run <repeated|distinct> <output folder> [samples] [mcp entry], or compare <candidate.png> <reference.png>.');
+}
diff --git a/bench/instancing/native-job-scenes.mjs b/bench/instancing/native-job-scenes.mjs
new file mode 100644
index 00000000..7971c2c3
--- /dev/null
+++ b/bench/instancing/native-job-scenes.mjs
@@ -0,0 +1,51 @@
+// The two scenes of native-job-check.mjs: 200 copies of one mesh with an emissive shared mesh and a shadow-only copy, and
+// twelve meshes none of which is shared.
+function repeatedRecipe() {
+ const nodes = [];
+ const side = 6;
+ for (let index = 0; index < 200; index++) {
+ const column = index % side;
+ const row = Math.floor(index / side) % side;
+ const layer = Math.floor(index / (side * side));
+ const glowing = index % 10 === 0;
+ nodes.push({
+ id: `ball-${index}`,
+ geometry: 'ball',
+ material: glowing ? 'glow' : ['red', 'blue', 'gold'][index % 3],
+ translation: [(column - side / 2) * 1.2, (row - side / 2) * 1.2, -layer * 1.2],
+ scale: [0.4 + 0.05 * (index % 3), 0.4, 0.4 + 0.05 * (index % 4)],
+ });
+ }
+ nodes.push({ id: 'lamp-left', geometry: 'panel', material: 'glow', translation: [-5, 0, 4], scale: [0.2, 2, 2] });
+ nodes.push({ id: 'lamp-right', geometry: 'panel', material: 'glow', translation: [5, 0, 4], scale: [0.2, 2, 2] });
+ nodes.push({ id: 'gobo', geometry: 'panel', material: 'red', translation: [0, 4, 3], scale: [3, 0.1, 1], shadowOnly: true });
+ return nodes;
+}
+
+function distinctRecipe() {
+ const nodes = [];
+ for (let index = 0; index < 12; index++) {
+ nodes.push({
+ id: `solid-${index}`,
+ geometry: `solid-${index}`,
+ material: ['red', 'blue', 'gold', 'glow'][index % 4],
+ translation: [((index % 4) - 1.5) * 1.6, (Math.floor(index / 4) - 1) * 1.6, 0],
+ scale: [0.5, 0.5, 0.5],
+ });
+ }
+ return nodes;
+}
+
+export function recipeFor(scene) {
+ const materials = [
+ { id: 'red', color: [0.8, 0.2, 0.15], roughness: 0.5 },
+ { id: 'blue', color: [0.15, 0.4, 0.85], roughness: 0.3, metallic: 0.8 },
+ { id: 'gold', color: [0.9, 0.75, 0.25], roughness: 0.6 },
+ { id: 'glow', color: [1, 0.7, 0.4], roughness: 0.7, emission: 4 },
+ ];
+ const camera = { eye: [0, 0, 14], target: [0, 0, -2], fov: 50, near: 0.1, far: 60 };
+ const geometries = scene === 'repeated'
+ ? [{ id: 'ball', type: 'sphere', segments: 16, rings: 8 }, { id: 'panel', type: 'box', bevel: 0 }]
+ : Array.from({ length: 12 }, (_, index) => ({ id: `solid-${index}`, type: index % 2 ? 'box' : 'sphere', ...(index % 2 ? { bevel: 0 } : { segments: 12 + index, rings: 8 }) }));
+ return { format: '67js.scene', schemaVersion: 1, geometries, materials, nodes: scene === 'repeated' ? repeatedRecipe() : distinctRecipe(), camera };
+}
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index e6ae81ca..9c538fb2 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -64,7 +64,7 @@ Also checked before any ray is traced: samples times pixels times bounces at mos
- Limits: 400,000 triangles counted once per shared geometry, 1,024 distinct geometries (the part limit, counted on geometries) and 65,536 instances. An instanced scene has no world-space triangle arrays or CPU BVH, so only `buildNativeInputV2` reads it.
- A part's material is its own entry in `materials`, so copies may differ in material; a multi-material mesh stays one geometry with the materials the part names.
- `buildNativeInput` (the `legacy` kernel) refuses an instanced scene with an error; build the scene without `instancing` for that kernel. `traceNative` with `kernel: "legacy"` refuses a FORMAT-v2 input the same way.
-- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, or a scene where no geometry is shared, the job exports flattened tables exactly as before.
+- Render jobs with `renderer.backend: "native"` keep repeated geometry as instances when the job traces with the `cycles` kernel (the default): the job page exports FORMAT-v2 tables of the unique triangles and one record per part, the job runner rebuilds the input for `traceNative`, and the report names the `instances` and counts `triangles` once per shared geometry. With `JS67_NATIVE_KERNEL=legacy`, `JS67_NATIVE_INSTANCING=off` (flattened triangles on the `cycles` kernel, to compare the two), or a scene where no geometry is shared, the job exports flattened tables exactly as before.
- A part with `shadowOnly: true` becomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep one `local_emissive_offset` for all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index.
The same scene and options give the same bytes. Random numbers come from a hash of the pixel, the sample and the seed, never from `Math.random` or the clock, and a pixel does not depend on which thread drew it.
diff --git a/scripts/agent-native-trace.mjs b/scripts/agent-native-trace.mjs
index 95ffee23..5b963696 100644
--- a/scripts/agent-native-trace.mjs
+++ b/scripts/agent-native-trace.mjs
@@ -83,6 +83,11 @@ function decodeTablesV2(exported) {
return input;
}
+// The bytes of every table the tracer is handed, which is what it uploads to the card (before alignment).
+function tableBytes(tables) {
+ return Object.values(tables).reduce((total, value) => total + (ArrayBuffer.isView(value) ? value.byteLength : 0), 0);
+}
+
function decodeTables(exported) {
if (exported.schemaVersion !== undefined) return decodeTablesV2(exported);
const input = { triangleCount: exported.triangleCount };
@@ -124,6 +129,14 @@ export function chooseNativeKernel(environment = process.env) {
return requested === undefined || requested === '' ? 'cycles' : requested;
}
+/**
+ * Whether a job keeps repeated geometry as instances: on with the "cycles" kernel, off with the legacy kernel and when
+ * JS67_NATIVE_INSTANCING=off asks for flattened triangles (to compare the two, or to rule instancing out of a bug).
+ */
+export function chooseNativeInstancing(environment = process.env) {
+ return chooseNativeKernel(environment) === 'cycles' && environment.JS67_NATIVE_INSTANCING !== 'off';
+}
+
/**
* The traced colour after the GPU a-trous filter, three floats per pixel. The cycles kernel already returned it when the
* trace asked for `denoise: "atrous"`; otherwise (the legacy kernel, or the filter after OIDN failed) the tracer filters
@@ -181,7 +194,8 @@ export async function denoiseFrameWithOidn({ tracer, denoiser, width, height, co
export async function traceFrameNative({ tracer, exported, width, height, samples, bounces, seed, denoise, denoiser, maxSeconds, noiseThreshold = 0, kernel = chooseNativeKernel() }) {
const started = performance.now();
const filtersInTrace = denoise === 'atrous' && kernel === 'cycles';
- const traced = tracer.traceNative(decodeTables(exported), { width, height, samples, maxSeconds, kernel, noiseThreshold, ...(filtersInTrace ? { denoise: 'atrous' } : {}) });
+ const tables = decodeTables(exported);
+ const traced = tracer.traceNative(tables, { width, height, samples, maxSeconds, kernel, noiseThreshold, ...(filtersInTrace ? { denoise: 'atrous' } : {}) });
const tracedSeconds = (performance.now() - started) / 1000;
const pixelCount = width * height;
const features = { color: withoutAlpha(traced.rgba, pixelCount), albedo: traced.albedo, normal: traced.normal,
@@ -190,7 +204,7 @@ export async function traceFrameNative({ tracer, exported, width, height, sample
const report = { width, height, samples, bounces, seed, denoised: false, denoiser: 'none', threads: 1, backend: 'native',
gpu: traced.adapter, nativeBackend: traced.backend, nativeFeatures: traced.features, setupSeconds: traced.setupSeconds, compileSeconds: traced.compileSeconds,
uploadSeconds: traced.uploadSeconds, accelerationBuildSeconds: traced.accelerationBuildSeconds,
- kernel, averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, ...(exported.instances === undefined ? {} : { instances: exported.instances }), tracedSeconds, ignored: exported.ignored };
+ kernel, averageSamples: traced.averageSamples ?? samples, noiseThreshold, triangles: exported.triangles, inputBytes: tableBytes(tables), ...(exported.instances === undefined ? {} : { instances: exported.instances }), tracedSeconds, ignored: exported.ignored };
let linear = features.color;
const denoiseStarted = performance.now();
if (denoise === 'oidn') {
diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjs
index d9debc0b..e6d5dd25 100644
--- a/scripts/agent-runtime.mjs
+++ b/scripts/agent-runtime.mjs
@@ -15,7 +15,7 @@ import { MATERIAL_SNIPPET_CAPABILITIES } from '../src/material-snippet.js';
import { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS, RENDER_PASS_NAMES, RENDER_PASS_DEPTH_RANGE, VIDEO_ENCODERS, MAXIMUM_VIDEO_SECONDS, MAXIMUM_JOB_SIDE, MAXIMUM_JOB_PIXELS, MAXIMUM_MEMORY_MIB, BAKE_WORKER_MAXIMUM_SECONDS } from '../src/agent-scene-capabilities.js';
import { PATH_TRACER_CAPABILITIES } from '../src/path-tracer-capabilities.js';
import { chooseDenoiser, finishWithOidn } from './agent-path-trace-denoise.mjs';
-import { chooseNativeKernel, chooseTraceBackend, createNativeTracerLocator, isNativeTimeLimitError, traceFrameNative, traceTexelsNative } from './agent-native-trace.mjs';
+import { chooseNativeInstancing, chooseTraceBackend, createNativeTracerLocator, isNativeTimeLimitError, traceFrameNative, traceTexelsNative } from './agent-native-trace.mjs';
import { createAgentAssetCatalog } from './agent-asset-catalog.mjs';
import { geometryOnlyGlb } from './agent-query-asset.mjs';
import { AGENT_ASSET_LIMITS, assertCombinedAssetBytes } from '../src/agent-asset-limits.js';
@@ -565,7 +565,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
let backendNote = trace.note;
if (trace.backend === 'native') {
try {
- const exported = await jobPage.evaluate(input => window.__agentPreview.exportNativeScene(input), { ...frameInput, options: { width, height, bounces: tracerOptions.bounces, seed: tracerOptions.seed, fireflyClamp: 20, noiseThreshold: tracerOptions.noiseThreshold, instancing: chooseNativeKernel() === 'cycles' } });
+ const exported = await jobPage.evaluate(input => window.__agentPreview.exportNativeScene(input), { ...frameInput, options: { width, height, bounces: tracerOptions.bounces, seed: tracerOptions.seed, fireflyClamp: 20, noiseThreshold: tracerOptions.noiseThreshold, instancing: chooseNativeInstancing() } });
traced = await traceFrameNative({ tracer: trace.tracer, exported, width, height, samples: tracerOptions.samples, bounces: tracerOptions.bounces,
seed: tracerOptions.seed, denoise: choice.denoise === true ? 'wavelet' : choice.denoise === false ? 'none' : choice.denoise, denoiser: choice.denoiser,
maxSeconds: tracerOptions.maxSeconds, noiseThreshold: tracerOptions.noiseThreshold });
diff --git a/tests/native-instancing-transport.test.js b/tests/native-instancing-transport.test.js
index ad784a97..f1ebeffd 100644
--- a/tests/native-instancing-transport.test.js
+++ b/tests/native-instancing-transport.test.js
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import test from 'node:test';
import { buildNativeInput } from '../packages/render-native/pack-input.mjs';
import { buildNativeInputV2, findNativeAddon, traceNative } from '../packages/render-native/index.mjs';
-import { traceFrameNative } from '../scripts/agent-native-trace.mjs';
+import { chooseNativeInstancing, traceFrameNative } from '../scripts/agent-native-trace.mjs';
import { encodeNativeInputV2 } from '../scripts/native-bake-page.js';
import { buildCopyScene } from '../bench/instancing/copies-scene.mjs';
import { createCamera } from '../src/path-tracer.js';
@@ -70,6 +70,21 @@ test('the legacy packer refuses an instanced scene and a scene without shared ge
assert.ok(flattened.indices.length > 0);
});
+test('a job instances on the cycles kernel unless JS67_NATIVE_INSTANCING=off or the legacy kernel is chosen', () => {
+ assert.equal(chooseNativeInstancing({}), true);
+ assert.equal(chooseNativeInstancing({ JS67_NATIVE_INSTANCING: 'on' }), true);
+ assert.equal(chooseNativeInstancing({ JS67_NATIVE_INSTANCING: 'off' }), false);
+ assert.equal(chooseNativeInstancing({ JS67_NATIVE_KERNEL: 'legacy' }), false);
+});
+
+test('the job report counts the bytes handed to the tracer', async () => {
+ const { input } = instancedInput('translate');
+ const exported = JSON.parse(JSON.stringify({ ...encodeNativeInputV2(input), triangleCount: input.triangleCount, triangles: input.triangleCount, instances: input.instanceCount, ignored: [] }));
+ const traced = await traceFrameNative({ tracer: recordingTracer([]), exported, width: WIDTH, height: HEIGHT, samples: 4, denoise: 'none', kernel: 'cycles' });
+ const expected = Object.values(input).reduce((total, value) => total + (ArrayBuffer.isView(value) ? value.byteLength : 0), 0);
+ assert.equal(traced.report.inputBytes, expected);
+});
+
const addonSkip = findNativeAddon() ? false : 'the native addon is not built';
test('a job frame of an instanced scene equals the direct trace of the same input', { skip: addonSkip }, async t => {