Skip to content

armgit / 67.js

Public Imported from GitHub
0

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