3D engine that AI agents drive
Thin-lens depth of field from a camera's fStop to the cycles kernel (#896)
Nguyen Xuan Anbe928dafd447
diff --git a/bench/cycles-parity/render-cycles.py b/bench/cycles-parity/render-cycles.pyindex 9e38ee60..6f6f1eac 100644--- a/bench/cycles-parity/render-cycles.py+++ b/bench/cycles-parity/render-cycles.py@@ -54,7 +54,7 @@ def parse_cli_arguments():raise ValueError("Pass script arguments after '--': <sceneJsonPath> <outputPrefix> [options].")argument_list = sys.argv[sys.argv.index("--") + 1:]if len(argument_list) < 2 or argument_list[0].startswith("--") or argument_list[1].startswith("--"):- raise ValueError("Usage: blender -b --factory-startup --python bench/cycles-parity/render-cycles.py -- <sceneJsonPath> <outputPrefix> [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--keep-exr] [--part-ids] [--grey-diffuse] [--z-depth] [--depth-samples 64] [--denoise none|oidn-gpu|oidn-cpu]")+ raise ValueError("Usage: blender -b --factory-startup --python bench/cycles-parity/render-cycles.py -- <sceneJsonPath> <outputPrefix> [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--keep-exr] [--part-ids] [--grey-diffuse] [--z-depth] [--depth-samples 64] [--denoise none|oidn-gpu|oidn-cpu] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]")return {"scene_json_path": os.path.abspath(argument_list[0]),"output_prefix": os.path.abspath(argument_list[1]),@@ -76,6 +76,37 @@ def parse_cli_arguments():"z_depth": "--z-depth" in argument_list,"depth_samples": int(read_flag_value(argument_list, "--depth-samples", str(DEFAULT_DEPTH_SAMPLES))),"denoise": read_flag_value(argument_list, "--denoise", "none"),+ "f_stop": float(read_flag_value(argument_list, "--f-stop", "0")) if "--f-stop" in argument_list else None,+ "focus_distance": float(read_flag_value(argument_list, "--focus-distance", "0")) if "--focus-distance" in argument_list else None,+ "aperture_blades": int(read_flag_value(argument_list, "--aperture-blades", "0")),+ "aperture_rotation": float(read_flag_value(argument_list, "--aperture-rotation", "0")),+ "sensor_width": float(read_flag_value(argument_list, "--sensor-width", "36")),+ }+++def resolve_lens_options(options, camera_entry):+ """Depth-of-field settings from --f-stop and its companions, or None for a pinhole (the default).++ Without --focus-distance the focus is the eye-to-target distance, as in createCamera.+ """+ if options["f_stop"] is None:+ stray_flags = [name for name in ("--focus-distance", "--aperture-blades", "--aperture-rotation", "--sensor-width") if name in sys.argv]+ if stray_flags:+ raise ValueError(f"Option {stray_flags[0]} needs --f-stop: pass the f-stop that turns on depth of field, such as --f-stop 2.8.")+ return None+ if options["f_stop"] <= 0:+ raise ValueError(f"--f-stop must be above 0, got {options['f_stop']}.")+ if options["aperture_blades"] != 0 and not 3 <= options["aperture_blades"] <= 64:+ raise ValueError(f"--aperture-blades must be 0 (a round aperture) or from 3 to 64, got {options['aperture_blades']}.")+ focus_distance = options["focus_distance"]+ if focus_distance is None:+ focus_distance = math.dist(camera_entry["eye"], camera_entry["target"])+ return {+ "f_stop": options["f_stop"],+ "focus_distance": focus_distance,+ "aperture_blades": options["aperture_blades"],+ "aperture_rotation": options["aperture_rotation"],+ "sensor_width": options["sensor_width"],}@@ -418,9 +449,26 @@ def build_scene_lights(scene, environment_entry):add_area_light(scene, light_index, area_entry)-def build_camera_object(scene, camera_entry):+def configure_depth_of_field(camera_data, lens_options, aspect):+ """Thin-lens depth of field, matching createCamera in src/path-tracer.js (the same flags go to trace-native.mjs).++ The sensor is sensor-width / aspect tall, so the focal length Cycles derives from the vertical field of view is the one+ the native side computes; the aperture radius is then focal length / (2 * f-stop) in metres.+ """+ camera_data.sensor_height = lens_options["sensor_width"] / aspect+ camera_data.dof.use_dof = True+ camera_data.dof.aperture_fstop = lens_options["f_stop"]+ camera_data.dof.focus_distance = lens_options["focus_distance"]+ if lens_options["aperture_blades"] > 0:+ camera_data.dof.aperture_blades = lens_options["aperture_blades"]+ camera_data.dof.aperture_rotation = math.radians(lens_options["aperture_rotation"])+++def build_camera_object(scene, camera_entry, lens_options=None, aspect=16.0 / 9.0):camera_data = bpy.data.cameras.new("Camera")camera_data.sensor_fit = "VERTICAL"+ if lens_options is not None:+ configure_depth_of_field(camera_data, lens_options, aspect)camera_data.angle_y = math.radians(camera_entry["fov"])camera_data.clip_start = camera_entry["near"]camera_data.clip_end = camera_entry["far"]@@ -653,7 +701,8 @@ def main():build_scene_objects(scene, description)build_world_shader(scene, description["world"], repository_root)build_scene_lights(scene, description["environment"])- build_camera_object(scene, description["camera"])+ lens_options = resolve_lens_options(options, description["camera"])+ build_camera_object(scene, description["camera"], lens_options, options["width"] / options["height"])configure_linear_exr_output(scene, options["width"], options["height"])if options["part_ids"]:render_part_identifier_map(scene, options["output_prefix"], options["width"], options["height"])@@ -679,6 +728,11 @@ def main():print("DEPTH_PASS_FAILED " + depth_error)report = {"greyDiffuse": options["grey_diffuse"],+ "thinLens": None if lens_options is None else {+ **lens_options,+ "blenderLensMillimetres": scene.camera.data.lens,+ "blenderApertureRadius": scene.camera.data.lens / 1000.0 / (2.0 * lens_options["f_stop"]),+ },"depthNpyPath": depth_npy_path,"depthError": depth_error,"depthSamples": options["depth_samples"] if options["z_depth"] else None,diff --git a/bench/cycles-parity/trace-native.mjs b/bench/cycles-parity/trace-native.mjsindex ba8bd61d..8881515d 100644--- a/bench/cycles-parity/trace-native.mjs+++ b/bench/cycles-parity/trace-native.mjs@@ -114,7 +114,7 @@ function parseLightSamplingOption(argumentList) {function parseTraceArguments(argumentList) {if (argumentList.length < 2 || argumentList[0].startsWith('--') || argumentList[1].startsWith('--')) {- throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda] [--grey-diffuse] [--write-depth]');+ throw new RangeError('Usage: node bench/cycles-parity/trace-native.mjs <sceneJsonPath> <outputPrefix> [--kernel legacy|cycles] [--samples 256] [--bounces 8] [--transparent-bounces 8] [--seed 1] [--width 960] [--height 540] [--sampler white|sobol-burley] [--light-sampling auto|tree|uniform] [--path-regeneration | --no-path-regeneration] [--env-compensation 0..1] [--filter-type box|gaussian|blackman-harris] [--filter-width 1.0] [--clamp-direct 0] [--clamp-indirect 0] [--firefly-clamp 1e9] [--noise-threshold 0] [--denoise none|wavelet|atrous] [--oidn-devices cpu,cuda] [--grey-diffuse] [--write-depth] [--f-stop 2.8 [--focus-distance m] [--aperture-blades 0|3..64] [--aperture-rotation degrees] [--sensor-width 36]]');}return {sceneJsonPath: resolve(argumentList[0]),@@ -151,9 +151,39 @@ function parseTraceArguments(argumentList) {maxSeconds: parseNumberOption(argumentList, '--max-seconds', 1800, 1),greyDiffuse: argumentList.includes('--grey-diffuse'),writeDepth: argumentList.includes('--write-depth'),+ lens: parseLensOptions(argumentList),};}+/**+ * Thin-lens fields for the scene camera, in the names `createCamera` reads (render-cycles.py takes the same flags). Empty+ * without --f-stop: the scene camera stays a pinhole. --aperture-rotation is in degrees.+ */+function parseLensOptions(argumentList) {+ const lensFlags = ['--focus-distance', '--aperture-blades', '--aperture-rotation', '--sensor-width'];+ if (!argumentList.includes('--f-stop')) {+ const strayFlag = lensFlags.find((flagName) => argumentList.includes(flagName));+ if (strayFlag) {+ throw new RangeError(`Option ${strayFlag} needs --f-stop: pass the f-stop that turns on depth of field, such as --f-stop 2.8.`);+ }+ return {};+ }+ const lens = { fStop: parseNumberOption(argumentList, '--f-stop', 2.8, 0.01) };+ if (argumentList.includes('--focus-distance')) {+ lens.focusDistance = parseNumberOption(argumentList, '--focus-distance', 1, 0.001);+ }+ if (argumentList.includes('--aperture-blades')) {+ lens.apertureBlades = parseIntegerOption(argumentList, '--aperture-blades', 0, 0);+ }+ if (argumentList.includes('--aperture-rotation')) {+ lens.apertureRotation = parseNumberOption(argumentList, '--aperture-rotation', 0, -3600);+ }+ if (argumentList.includes('--sensor-width')) {+ lens.sensorWidth = parseNumberOption(argumentList, '--sensor-width', 36, 0.1);+ }+ return lens;+}+function packSceneForKernel(traceScene, camera, options) {if (options.kernel === 'cycles' && typeof renderNative.buildNativeInputV2 === 'function') {return renderNative.buildNativeInputV2(traceScene, camera, options, packModule);@@ -242,6 +272,9 @@ async function runOidnComparison(traced, linearRgb, options, outputPrefix) {async function runCli() {setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);const options = parseTraceArguments(process.argv.slice(2));+ if (options.lens.fStop !== undefined && options.kernel !== 'cycles') {+ throw new RangeError('Option --f-stop (depth of field) needs --kernel cycles: the legacy kernel draws a pinhole.');+ }if (!renderNative.findNativeAddon()) {throw new Error('The render-native addon is missing. Build packages/render-native before running trace-native.mjs.');}@@ -252,7 +285,7 @@ async function runCli() {const buildStarted = performance.now();const traceSource = await reconstructTraceSceneSource(description);const traceScene = buildTraceSceneWithManyLights(traceSource.parts, traceSource.environment);- const camera = createCamera(traceSource.camera, options.width, options.height);+ const camera = createCamera({ ...traceSource.camera, ...options.lens }, options.width, options.height);const samplesPerDispatch = options.samplesPerDispatch !== undefined? options.samplesPerDispatch: (options.noiseThreshold > 0 ? 8 : undefined);@@ -305,6 +338,9 @@ async function runCli() {}const report = {greyDiffuse: options.greyDiffuse,+ thinLens: camera.apertureRadius > 0+ ? { apertureRadius: camera.apertureRadius, focalDistance: camera.focalDistance, apertureBlades: camera.apertureBlades, apertureRotation: camera.apertureRotation }+ : null,depthNpyPath,depthConvention: depthNpyPath ? 'ray-distance' : null,cameraVerticalFovDegrees: traceSource.camera.fov,diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex 7a73d5a8..3e3b1dec 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -2,6 +2,7 @@// native kernel (`FORMAT-v2.md` and `src/cycles/abi.wgsl`). Pure typed arrays with zero Node-only imports.import { buildLightTree } from './light-tree-v2.mjs';+import { THIN_LENS_FLOAT_INDEXES } from './pack-input.mjs';export const FORMAT_V2_MAGIC = 0x36375054;export const FORMAT_V2_VERSION = 2;@@ -1693,6 +1694,45 @@ export function validatePackOptions(options, callerName, requireDimensionsAndSam}}+export const MAX_APERTURE_BLADES = 64;++/** The thin lens a v1 params block carries (see THIN_LENS_FLOAT_INDEXES in pack-input.mjs); nothing for a pinhole, so its bytes stay as they were. */+function readV1ThinLens(paramF32) {+ if (!(paramF32[THIN_LENS_FLOAT_INDEXES.apertureRadius] > 0)) {+ return {};+ }+ return Object.fromEntries(Object.entries(THIN_LENS_FLOAT_INDEXES).map(([fieldName, floatIndex]) => [fieldName, paramF32[floatIndex]]));+}+const DEFAULT_FOCAL_DISTANCE = 10;++function requireThinLensNumber(value, name, callerName, isValid, expectation) {+ if (typeof value !== 'number' || !Number.isFinite(value) || !isValid(value)) {+ throw new RangeError(`${callerName}: camera \`${name}\` must be ${expectation}, got ${JSON.stringify(value)}.`);+ }+}++/**+ * The thin lens of a camera, from the camera object (as `createCamera` returns it for a camera with an `fStop`) or from the+ * same names in `options`: `apertureRadius` (scene units, 0 is a pinhole), `focalDistance` (along the view axis),+ * `apertureBlades` (0 for a round aperture, else 3 to 64) and `apertureRotation` (radians). A pinhole keeps the defaults+ * the params block always held, so its bytes do not change. Throws a RangeError that says what to pass.+ */+export function resolveThinLensParameters(camera, options, callerName) {+ const apertureRadius = camera?.apertureRadius ?? options.apertureRadius ?? 0;+ requireThinLensNumber(apertureRadius, 'apertureRadius', callerName, value => value >= 0,+ 'a number of scene units, 0 or more (0 is a pinhole; fStop 2.8 on a 50 mm lens is 0.00893)');+ const focalDistance = camera?.focalDistance ?? options.focalDistance ?? DEFAULT_FOCAL_DISTANCE;+ requireThinLensNumber(focalDistance, 'focalDistance', callerName, value => value > 0,+ 'a distance along the view axis above 0, such as the eye-to-target distance');+ const apertureBlades = camera?.apertureBlades ?? options.apertureBlades ?? 0;+ requireThinLensNumber(apertureBlades, 'apertureBlades', callerName,+ value => Number.isInteger(value) && (value === 0 || (value >= 3 && value <= MAX_APERTURE_BLADES)),+ `0 for a round aperture or a whole number from 3 to ${MAX_APERTURE_BLADES}`);+ const apertureRotation = camera?.apertureRotation ?? options.apertureRotation ?? 0;+ requireThinLensNumber(apertureRotation, 'apertureRotation', callerName, () => true, 'a finite number of radians');+ return { apertureRadius, focalDistance, apertureBlades, apertureRotation };+}+function effectiveCyclesClamp(value) {if (value === undefined || value === null) {return 0.0;@@ -1826,6 +1866,7 @@ function packKernelParamsV2({const cameraNear = Math.max(0, Number(options.near ?? camera?.near ?? 0));const cameraFar = Math.max(cameraNear + 1e-3, Number(options.far ?? camera?.far ?? farDistance ?? 1e30));const lensShift = camera?.lensShift ?? options.lensShift ?? [0, 0];+ const thinLens = resolveThinLensParameters(camera, options, 'buildNativeInputV2');u32[0] = FORMAT_V2_MAGIC;u32[1] = FORMAT_V2_VERSION;@@ -1875,17 +1916,17 @@ function packKernelParamsV2({f32[36] = scaledRight[0];f32[37] = scaledRight[1];f32[38] = scaledRight[2];- f32[39] = Math.max(0, Number(camera?.apertureRadius ?? options.apertureRadius ?? 0));+ f32[39] = thinLens.apertureRadius;f32[40] = scaledUp[0];f32[41] = scaledUp[1];f32[42] = scaledUp[2];- f32[43] = Math.max(1e-4, Number(camera?.focalDistance ?? options.focalDistance ?? 10));+ f32[43] = thinLens.focalDistance;f32[44] = Number(lensShift[0] ?? 0);f32[45] = Number(lensShift[1] ?? 0);- u32[46] = Math.max(0, Math.round(Number(camera?.apertureBlades ?? options.apertureBlades ?? 0))) >>> 0;- f32[47] = Number(camera?.apertureRotation ?? options.apertureRotation ?? 0);+ u32[46] = thinLens.apertureBlades >>> 0;+ f32[47] = thinLens.apertureRotation;u32[48] = packedEnvironment.envWidth >>> 0;u32[49] = packedEnvironment.envHeight >>> 0;@@ -2785,6 +2826,7 @@ export function upgradeNativeInputV1ToV2(v1Input, options = {}) {above: [paramF32[12], paramF32[13], paramF32[14]],halfWidth: paramF32[32],halfHeight: paramF32[33],+ ...readV1ThinLens(paramF32),};const packedTextures = textureCollector.finish();diff --git a/packages/render-native/pack-input.mjs b/packages/render-native/pack-input.mjsindex 33b9c46e..e1c01023 100644--- a/packages/render-native/pack-input.mjs+++ b/packages/render-native/pack-input.mjs@@ -3,6 +3,20 @@const PARAMETER_BYTES = 16 * 16;const SUN_CONE_COSINE = Math.cos(Math.PI / 360);+// A thin lens rides in the unused fourth float of the four camera vectors: aperture radius (eye), focus distance (forward),+// aperture blades (right) and aperture rotation in radians (above). The legacy kernel reads only xyz of those vectors, so it+// draws a pinhole as before; the "cycles" kernel gets them when the input is upgraded to FORMAT-v2. A pinhole leaves all four 0.+export const THIN_LENS_FLOAT_INDEXES =Object.freeze({ apertureRadius: 3, focalDistance: 7, apertureBlades: 11, apertureRotation: 15 });++function writeThinLens(floats, camera) {+ if (!(camera.apertureRadius > 0)) {+ return;+ }+ for (const [fieldName, floatIndex] of Object.entries(THIN_LENS_FLOAT_INDEXES)) {+ floats[floatIndex] = Number(camera[fieldName] ?? 0);+ }+}+function writeParameters(scene, camera, options, lightCount, atlasWidth, subsurfaceOffset) {const buffer = new ArrayBuffer(PARAMETER_BYTES);const floats = new Float32Array(buffer);@@ -14,6 +28,7 @@ function writeParameters(scene, camera, options, lightCount, atlasWidth, subsurffloats.set([...camera.forward, 0], 4);floats.set([...camera.right, 0], 8);floats.set([...camera.above, 0], 12);+ writeThinLens(floats, camera);floats.set([...(sun?.direction ?? [0, 1, 0]), 0], 16);floats.set([...(sun?.color ?? [0, 0, 0]), SUN_CONE_COSINE], 20);floats.set([environment?.width ?? 1, environment?.height ?? 1, environment?.intensity ?? 1, environment?.total ?? 1], 24);diff --git a/src/camera.js b/src/camera.jsindex c5483038..c1d9a23c 100644--- a/src/camera.js+++ b/src/camera.js@@ -61,6 +61,53 @@ export function cameraFieldOfView(frame, aspect) {return fov;}+export const MAX_APERTURE_BLADES = 64;++function requirePositiveFinite(value, name) {+ if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {+ throw new RangeError(`Camera ${name} must be a positive finite number, got ${JSON.stringify(value)}.`);+ }+}++/** Focal length in millimetres: `focalLength` as given, or the one that gives `fov` on a sensor `sensorWidth` wide across the image. */+export function cameraFocalLength(frame, aspect) {+ if (frame.focalLength !== undefined) {+ requirePositiveFinite(frame.focalLength, 'focalLength');+ return frame.focalLength;+ }+ const sensorWidth = frame.sensorWidth ?? 36;+ requirePositiveFinite(sensorWidth, 'sensorWidth');+ const fieldOfView = cameraFieldOfView(frame, aspect);+ return sensorWidth / aspect / (2 * Math.tan(fieldOfView * Math.PI / 360));+}++/**+ * The thin lens a camera with an `fStop` describes, for the native path tracer (Cycles' camera model): the aperture radius in+ * scene units (focalLength / (2 * fStop), millimetres to metres), the focus distance along the view axis (`focusDistance`, by+ * default the distance from eye to target), and the optional polygonal blades (`apertureBlades`, 0 or 3 to 64) turned by+ * `apertureRotation` degrees. Returns null for a camera without `fStop`: a pinhole.+ */+export function resolveThinLens(frame, { aspect, eye, target }) {+ if (frame.fStop === undefined) return null;+ requirePositiveFinite(frame.fStop, 'fStop');+ const focusDistance = frame.focusDistance ?? Math.hypot(target[0] - eye[0], target[1] - eye[1], target[2] - eye[2]);+ requirePositiveFinite(focusDistance, 'focusDistance');+ const blades = frame.apertureBlades ?? 0;+ if (!Number.isInteger(blades) || blades < 0 || blades === 1 || blades === 2 || blades > MAX_APERTURE_BLADES) {+ throw new RangeError(`Camera apertureBlades must be 0 (a round aperture) or a whole number from 3 to ${MAX_APERTURE_BLADES}, got ${JSON.stringify(frame.apertureBlades)}.`);+ }+ const rotationDegrees = frame.apertureRotation ?? 0;+ if (typeof rotationDegrees !== 'number' || !Number.isFinite(rotationDegrees)) {+ throw new RangeError(`Camera apertureRotation must be a finite number of degrees, got ${JSON.stringify(frame.apertureRotation)}.`);+ }+ return {+ apertureRadius: cameraFocalLength(frame, aspect) / 1000 / (2 * frame.fStop),+ focalDistance: focusDistance,+ apertureBlades: blades,+ apertureRotation: rotationDegrees * Math.PI / 180,+ };+}+const viewDirections = { front: [0, 0, 1], right: [1, 0, 0], top: [0, 1, 0], perspective: [0.58, 0.34, 0.74] };export function cameraView(name = 'front', { target = [0, 1.5, 0], height = 3.8, distance = 8 } = {}) {diff --git a/src/path-tracer.js b/src/path-tracer.jsindex 3f7307d4..703e7bea 100644--- a/src/path-tracer.js+++ b/src/path-tracer.js@@ -1,4 +1,4 @@-import { cameraFieldOfView } from './camera.js';+import { cameraFieldOfView, resolveThinLens } from './camera.js';import { fresnelSchlick } from './material-layers.js';import { pointLightFalloff } from './ray-query.js';import { profileGain } from './light-profile.js';@@ -155,7 +155,11 @@ export function createCamera(camera, width, height) {for (let axis = 0; axis < 3; axis++) right[axis] /= rightLength;const above = [right[1] * forward[2] - right[2] * forward[1], right[2] * forward[0] - right[0] * forward[2], right[0] * forward[1] - right[1] * forward[0]];const halfHeight = Math.tan(fov * Math.PI / 360);- return { eye, forward, right, above, halfHeight, halfWidth: halfHeight * width / height };+ const view = { eye, forward, right, above, halfHeight, halfWidth: halfHeight * width / height };+ // A camera with an fStop adds its thin lens (apertureRadius, focalDistance, apertureBlades, apertureRotation). Only the+ // native "cycles" kernel draws it; every other tracer ignores the extra fields, and a pinhole view is unchanged.+ const thinLens = resolveThinLens(camera, { aspect: width / height, eye, target });+ return thinLens ? { ...view, ...thinLens } : view;}// ---- Random numbers ----diff --git a/tests/cook-dof-parity.test.js b/tests/cook-dof-parity.test.jsnew file mode 100644index 00000000..23d95d8e--- /dev/null+++ b/tests/cook-dof-parity.test.js@@ -0,0 +1,207 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import {+ buildNativeInputV2,+ findNativeAddon,+ traceNative,+ upgradeNativeInputV1ToV2,+} from '../packages/render-native/index.mjs';+import { buildNativeInput } from '../packages/render-native/pack-input.mjs';+import { resolveThinLensParameters } from '../packages/render-native/pack-input-v2.mjs';+import { cameraFocalLength, resolveThinLens } from '../src/camera.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';++const skipWithoutAddon = findNativeAddon() === null ? 'the native addon is not built' : false;++// Word indexes in the 320-byte KernelParamsV2 block (abi.wgsl): aperture_radius, focal_distance, aperture_blades, aperture_rotation.+const APERTURE_RADIUS_WORD = 39;+const FOCAL_DISTANCE_WORD = 43;+const APERTURE_BLADES_WORD = 46;+const APERTURE_ROTATION_WORD = 47;+const LENS_WORDS = [APERTURE_RADIUS_WORD, FOCAL_DISTANCE_WORD, APERTURE_BLADES_WORD, APERTURE_ROTATION_WORD];++const PINHOLE_SPEC = { eye: [0, 0, 4], target: [0, 0, 0], fov: 45 };+const LENS_OF_50_MM = { ...PINHOLE_SPEC, focalLength: 50, fStop: 2.8 };+// The pinhole camera with an f-stop added: same view, so the params block differs only in the lens words.+const LENS_ON_PINHOLE = { ...PINHOLE_SPEC, fStop: 2.8 };++function cardGeometry(left, right) {+ return {+ positions: new Float32Array([left, -1.5, 0, right, -1.5, 0, right, 1.5, 0, left, 1.5, 0]),+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]),+ uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),+ colors: new Float32Array(12).fill(1),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ };+}++// An emissive card whose right edge crosses the middle of the image, in front of nothing.+function buildEdgeScene() {+ return buildTraceScene([{ name: 'card', geometry: cardGeometry(-1.5, 0), material: { color: [1, 1, 1], emission: 4 } }], {});+}++function kernelWords(input) {+ const { buffer, byteOffset, byteLength } = input.kernelParams;+ return new Uint32Array(buffer.slice(byteOffset, byteOffset + byteLength));+}++function floatOfWord(word) {+ return new Float32Array(new Uint32Array([word]).buffer)[0];+}++function differingWords(first, second) {+ return [...first.keys()].filter((index) => first[index] !== second[index]);+}++function packWithCamera(spec, size = 16) {+ const camera = createCamera(spec, size, size);+ return buildNativeInputV2(buildEdgeScene(), camera, { width: size, height: size, samples: 1 });+}++test('the aperture radius is focal length over twice the f-stop, in metres', () => {+ const lens = resolveThinLens(LENS_OF_50_MM, { aspect: 1, eye: [0, 0, 4], target: [0, 0, 0] });+ assert.ok(Math.abs(lens.apertureRadius - 0.05 / (2 * 2.8)) < 1e-12);+ assert.equal(lens.focalDistance, 4, 'focus defaults to the eye-to-target distance');+ assert.equal(lens.apertureBlades, 0);+ assert.equal(lens.apertureRotation, 0);+});++test('a camera given only a field of view uses the focal length that field gives on the sensor', () => {+ const aspect = 16 / 9;+ const focalLength = cameraFocalLength({ fov: 50 }, aspect);+ assert.ok(Math.abs(focalLength - 36 / aspect / (2 * Math.tan(25 * Math.PI / 180))) < 1e-9);+ const wideSensor = cameraFocalLength({ fov: 50, sensorWidth: 72 }, aspect);+ assert.ok(Math.abs(wideSensor - 2 * focalLength) < 1e-9, 'twice the sensor, twice the focal length');+ assert.equal(cameraFocalLength({ fov: 50, focalLength: 85 }, aspect), 85, 'an explicit focal length wins');+});++test('focus distance, blades and rotation come through; rotation turns from degrees to radians', () => {+ const lens = resolveThinLens(+ { ...LENS_OF_50_MM, focusDistance: 2.5, apertureBlades: 6, apertureRotation: 30 },+ { aspect: 1, eye: [0, 0, 4], target: [0, 0, 0] },+ );+ assert.equal(lens.focalDistance, 2.5);+ assert.equal(lens.apertureBlades, 6);+ assert.ok(Math.abs(lens.apertureRotation - Math.PI / 6) < 1e-12);+});++test('a camera without an fStop is a pinhole: no lens fields, no change to the view', () => {+ assert.equal(resolveThinLens(PINHOLE_SPEC, { aspect: 1, eye: [0, 0, 4], target: [0, 0, 0] }), null);+ const view = createCamera(PINHOLE_SPEC, 16, 16);+ assert.deepEqual(Object.keys(view).sort(), ['above', 'eye', 'forward', 'halfHeight', 'halfWidth', 'right']);+});++test('a lens that cannot be built says what to pass', () => {+ const frame = { eye: [0, 0, 4], target: [0, 0, 0] };+ const make = (extra) => () => resolveThinLens({ ...LENS_OF_50_MM, ...extra }, { aspect: 1, ...frame });+ assert.throws(make({ fStop: 0 }), /fStop must be a positive finite number/);+ assert.throws(make({ focusDistance: -1 }), /focusDistance must be a positive finite number/);+ assert.throws(make({ apertureBlades: 2 }), /apertureBlades must be 0 .* 3 to 64/);+ assert.throws(make({ apertureBlades: 4.5 }), /apertureBlades must be 0/);+ assert.throws(make({ apertureBlades: 65 }), /apertureBlades must be 0/);+ assert.throws(make({ apertureRotation: Number.NaN }), /apertureRotation must be a finite number of degrees/);+ assert.throws(make({ focalLength: -5 }), /focalLength must be a positive finite number/);+});++test('with depth of field off, the lens words of the params block hold the values they always held', () => {+ const words = kernelWords(packWithCamera(PINHOLE_SPEC));+ assert.equal(words[APERTURE_RADIUS_WORD], 0);+ assert.equal(floatOfWord(words[FOCAL_DISTANCE_WORD]), 10);+ assert.equal(words[APERTURE_BLADES_WORD], 0);+ assert.equal(words[APERTURE_ROTATION_WORD], 0);+});++test('depth of field changes only its own words of the params block', () => {+ const pinhole = kernelWords(packWithCamera(PINHOLE_SPEC));+ const round = kernelWords(packWithCamera({ ...LENS_ON_PINHOLE, focusDistance: 3 }));+ assert.deepEqual(differingWords(pinhole, round), [APERTURE_RADIUS_WORD, FOCAL_DISTANCE_WORD]);+ assert.equal(floatOfWord(round[APERTURE_RADIUS_WORD]), Math.fround(cameraFocalLength(PINHOLE_SPEC, 1) / 1000 / 5.6));+ assert.equal(floatOfWord(round[FOCAL_DISTANCE_WORD]), 3);++ const hexagon = kernelWords(packWithCamera({ ...LENS_ON_PINHOLE, apertureBlades: 6, apertureRotation: 90 }));+ assert.deepEqual(differingWords(pinhole, hexagon), LENS_WORDS);+ assert.equal(hexagon[APERTURE_BLADES_WORD], 6);+ assert.equal(floatOfWord(hexagon[APERTURE_ROTATION_WORD]), Math.fround(Math.PI / 2));+});++test('a v1 input carries the lens in the free fourth floats and upgrades to the same v2 words', () => {+ const scene = buildEdgeScene();+ const options = { width: 16, height: 16, samples: 1 };+ const lensCamera = createCamera({ ...LENS_ON_PINHOLE, focusDistance: 3, apertureBlades: 5, apertureRotation: 12 }, 16, 16);+ const v1 = buildNativeInput(scene, lensCamera, options, pack);+ const floats = new Float32Array(v1.parameters.buffer, v1.parameters.byteOffset, 64);+ assert.deepEqual([floats[3], floats[7], floats[11], floats[15]],+ [lensCamera.apertureRadius, lensCamera.focalDistance, lensCamera.apertureBlades, lensCamera.apertureRotation].map(Math.fround));++ const direct = kernelWords(buildNativeInputV2(scene, lensCamera, options));+ const upgraded = kernelWords(upgradeNativeInputV1ToV2(v1, options));+ for (const wordIndex of LENS_WORDS) {+ assert.equal(upgraded[wordIndex], direct[wordIndex], `word ${wordIndex}`);+ }+});++test('a pinhole v1 input keeps its camera vectors at 0 in the fourth float and upgrades to the default lens words', () => {+ const options = { width: 16, height: 16, samples: 1 };+ const v1 = buildNativeInput(buildEdgeScene(), createCamera(PINHOLE_SPEC, 16, 16), options, pack);+ const floats = new Float32Array(v1.parameters.buffer, v1.parameters.byteOffset, 64);+ assert.deepEqual([floats[3], floats[7], floats[11], floats[15]], [0, 0, 0, 0]);+ const upgraded = kernelWords(upgradeNativeInputV1ToV2(v1, options));+ const direct = kernelWords(packWithCamera(PINHOLE_SPEC));+ for (const wordIndex of LENS_WORDS) {+ assert.equal(upgraded[wordIndex], direct[wordIndex], `word ${wordIndex}`);+ }+});++test('the packer rejects lens values the kernel cannot use, naming the field and what to pass', () => {+ const caller = 'buildNativeInputV2';+ assert.throws(() => resolveThinLensParameters({ apertureRadius: -1 }, {}, caller), /buildNativeInputV2: camera `apertureRadius` must be a number of scene units, 0 or more/);+ assert.throws(() => resolveThinLensParameters({ apertureRadius: Number.NaN }, {}, caller), /apertureRadius/);+ assert.throws(() => resolveThinLensParameters({ apertureRadius: 0.01, focalDistance: 0 }, {}, caller), /`focalDistance` must be a distance along the view axis above 0/);+ assert.throws(() => resolveThinLensParameters({}, { apertureBlades: 2 }, caller), /`apertureBlades` must be 0 for a round aperture or a whole number from 3 to 64/);+ assert.throws(() => resolveThinLensParameters({}, { apertureRotation: Infinity }, caller), /`apertureRotation` must be a finite number of radians/);+ assert.deepEqual(resolveThinLensParameters({}, {}, caller), { apertureRadius: 0, focalDistance: 10, apertureBlades: 0, apertureRotation: 0 });+});++// Pixels along the middle row whose value lies between 5 and 95 percent of the row's brightest: the width of the edge.+function edgeWidth(rgba, width, height) {+ const row = Math.floor(height / 2);+ const values = Array.from({ length: width }, (_, column) => rgba[(row * width + column) * 4]);+ const brightest = Math.max(...values);+ assert.ok(brightest > 0.5, 'the card is visible');+ return values.filter((value) => value > 0.05 * brightest && value < 0.95 * brightest).length;+}++test('the cycles kernel blurs an edge off the focus plane and keeps it sharp on it', { skip: skipWithoutAddon }, () => {+ const size = { width: 64, height: 32 };+ const traceOptions = { ...size, samples: 96, bounces: 1, seed: 5, kernel: 'cycles' };+ // 200 mm at f/2 is a 5 cm aperture radius; the card edge is 4 m away.+ const lensSpec = { eye: [0, 0, 4], target: [0, 0, 0], focalLength: 200, fStop: 2 };+ const traceWith = (spec) => {+ const camera = createCamera(spec, size.width, size.height);+ return traceNative(buildNativeInputV2(buildEdgeScene(), camera, traceOptions), traceOptions);+ };+ const pinhole = traceWith({ eye: lensSpec.eye, target: lensSpec.target, focalLength: 200 });+ const onFocus = traceWith(lensSpec);+ const nearFocus = traceWith({ ...lensSpec, focusDistance: 1.5 });+ const hexagon = traceWith({ ...lensSpec, focusDistance: 1.5, apertureBlades: 6 });++ const pinholeEdge = edgeWidth(pinhole.rgba, size.width, size.height);+ const onFocusEdge = edgeWidth(onFocus.rgba, size.width, size.height);+ const nearFocusEdge = edgeWidth(nearFocus.rgba, size.width, size.height);+ assert.ok(pinholeEdge <= 3, `pinhole edge is ${pinholeEdge} pixels wide`);+ assert.ok(onFocusEdge <= 3, `an edge on the focus plane is ${onFocusEdge} pixels wide`);+ assert.ok(nearFocusEdge >= onFocusEdge + 5, `an edge 2.5 m behind the focus is ${nearFocusEdge} pixels wide`);+ assert.ok(edgeWidth(hexagon.rgba, size.width, size.height) >= onFocusEdge + 5, 'a hexagonal aperture blurs it too');+ assert.ok(nearFocus.rgba.every(Number.isFinite));+});++test('the cycles kernel draws the same bytes for a pinhole whether or not the camera names a lens of aperture 0', { skip: skipWithoutAddon }, () => {+ const traceOptions = { width: 16, height: 16, samples: 8, bounces: 1, seed: 3, kernel: 'cycles', samplesPerDispatch: 8 };+ const camera = createCamera(PINHOLE_SPEC, 16, 16);+ const plain = traceNative(buildNativeInputV2(buildEdgeScene(), camera, traceOptions), traceOptions);+ const explicit = traceNative(buildNativeInputV2(buildEdgeScene(), { ...camera, apertureRadius: 0, focalDistance: 7 }, traceOptions), traceOptions);+ assert.ok(Buffer.from(plain.rgba.buffer, plain.rgba.byteOffset, plain.rgba.byteLength)+ .equals(Buffer.from(explicit.rgba.buffer, explicit.rgba.byteOffset, explicit.rgba.byteLength)));+});