3D engine that AI agents drive
Offset the polygon aperture by half a corner step to match Cycles; add the comparison picture and results (#896)
Nguyen Xuan An59e67c492f06
diff --git a/docs/cook-depth-of-field-comparison.jpg b/docs/cook-depth-of-field-comparison.jpgnew file mode 100644index 00000000..ba756b75Binary files /dev/null and b/docs/cook-depth-of-field-comparison.jpg differdiff --git a/docs/cycles-parity.md b/docs/cycles-parity.mdindex 2f522794..a27d2bdc 100644--- a/docs/cycles-parity.md+++ b/docs/cycles-parity.md@@ -891,18 +891,23 @@ Not covered: the Classroom scene (instancing, 854 instances, depth of field, whiA camera with an `fStop` is a thin lens in the `cycles` kernel, with Cycles' model: aperture radius `focal length / 1000 / (2 * f-stop)` metres, a disk or a regular polygon of `apertureBlades` corners, and a focus distance measured along the view axis. The kernel already held the lens maths (`camera.wgsl`, a port of Cycles' `camera.h`); this slice connects it: `createCamera` turns `fStop`, `focalLength` or `fov` with `sensorWidth`, `focusDistance`, `apertureBlades` and `apertureRotation` (degrees, Blender's sense) into the aperture fields of the params block. Layout and options: [FORMAT-v2.md](../packages/render-native/FORMAT-v2.md) and the [render-native README](../packages/render-native/README.md#depth-of-field-cycles-kernel). The kernel and the legacy kernel are unchanged. Motion blur is not in Cook; it is a known gap and out of scope for #896.-Depth of field off: the packed params bytes and the random numbers drawn do not change. The lens sample (`lens_uv`) is drawn for every sample whether or not the aperture is above 0, and a pinhole camera writes the same lens words as before (`0`, `10`, `0`, `0`). Measured on an RTX 4090: 128-sample images of `lit-interior` and `glass` (480 x 270, fixed 32 samples per dispatch, seed 3), with this tree and with the base commit's JavaScript on the same addon, have identical SHA-256 for the `cycles` and the `legacy` kernel (4 of 4), and two runs of this tree agree. An earlier run on an L4 gave the same hashes.+Depth of field off: the packed params bytes and the random numbers drawn do not change. The lens sample (`lens_uv`) is drawn for every sample whether or not the aperture is above 0, and a pinhole camera writes the same lens words as before (`0`, `10`, `0`, `0`). Measured on an RTX 4090: 128-sample images of `lit-interior` and `glass` (480 x 270, fixed 32 samples per dispatch, seed 3), with this tree merged with origin/main and with origin/main's JavaScript on the same addon, have identical SHA-256 for the `cycles` and the `legacy` kernel (4 of 4), and two runs of this tree agree. Earlier runs, before the merge, on an L4 and on the 4090 gave the same hashes. The native node suite on the 4090: 194 tests, 191 pass, 0 fail, 3 skipped, with both GPU depth of field tests running.-Cycles comparison (`dof-depth` scene in `bench/reference/scenes.js`: objects 2 m, 6 m and 15 m from the camera and a grid of small lamps 15 m away; 960 x 540, f/1.0 on a 150 mm wide sensor, a 116 mm lens, focus on the ball 6 m away; the near spheres blur by about 28 pixels, the lamps by about 9; Blender 5.3.0 Cycles OptiX and Cook on one RTX 4090; seed 1, 8 bounces, box filter; `trace-native.mjs` and `render-cycles.py` take the same `--f-stop`, `--focus-distance`, `--aperture-blades`, `--aperture-rotation` (degrees) and `--sensor-width`) `[measured]`:+Cycles comparison (`dof-depth` scene in `bench/reference/scenes.js`: objects 2 m, 6 m and 15 m from the camera and a grid of small lamps 15 m away; 960 x 540, f/1.0 on a 150 mm wide sensor, a 116 mm lens, focus on the ball 6 m away; the near spheres blur by about 28 pixels, the lamps by about 9; Blender 5.3.0 Cycles OptiX and Cook on one RTX 4090; seed 1, 8 bounces, box filter; `trace-native.mjs` and `render-cycles.py` take the same `--f-stop`, `--focus-distance`, `--aperture-blades`, `--aperture-rotation` (degrees) and `--sensor-width`; Cook goes through `createCamera`) `[measured]`:-| Aperture | Cook 4096 spp against Cycles 4096 spp | mean ratio (R / G / B) | relMSE (eps 0.01) | tiles within 5 % |-| --- | --- | --- | ---: | ---: |-| disk | `--f-stop 1 --focus-distance 6` | 0.9996 / 0.9996 / 0.9996 | 3.4e-5 | 45 of 45 |-| hexagon, rotation 15, default focus | same | 0.9995 / 0.9996 / 0.9996 | 3.8e-4 (see below) | 44 of 44 |+| Aperture, Cook 4096 spp against Cycles 4096 spp | mean ratio (R / G / B) | relMSE (eps 0.01) | Cycles seed 2 against seed 1 | tiles within 5 % |+| --- | --- | ---: | ---: | ---: |+| disk, focus 6 m | 0.9996 / 0.9996 / 0.9996 | 3.4e-5 | 3.4e-5 | 45 of 45 |+| hexagon, rotation 15, default focus, with the sign flip of commit `272003cd` | 0.9997 / 0.9997 / 0.9998 | 3.3e-5 | 3.0e-5 | 44 of 44 |+| pentagon, rotation 40, default focus, with the sign flip of commit `272003cd` | 0.9994 / 0.9994 / 0.9995 | 9.2e-4 | 3.2e-5 | 44 of 44 |-Of 64 tiles, 19 (disk) and 20 (hexagon) are too dark to count. For the disk the relMSE equals Cycles' own seed 1 against seed 2 (3.4e-5): Cook sits at Cycles' noise floor. At 256 spp Cook scores 3.0e-4 and Cycles 2.6e-4 against the 4096 reference. The blur is large enough to tell the lens from a pinhole: Cook without a lens against the Cycles disk image scores 7.8e-3 (230 times worse), with 35 of 45 tiles within 5 percent and a tile ratio as low as 0.44. The hexagon score of 3.8e-4 came from a sign difference in the aperture rotation: the kernel turns the polygon the other way from Blender, so Cook at `-15` matched Cycles at `15` (whole-image relMSE 3.3e-5, lamp regions 0.004 against 0.055 for Cook at 15 and 0.03 for Cook at 0 or 30). `createCamera` now flips the sign, so `apertureRotation: 15` means the same as Blender's 15 degrees; the render with the flipped sign was not repeated after that change. Pictures: `artifacts/cook-parity/dof-896-comparison-rtx4090.png` (rows disk and hexagon; Cook and Cycles at 256 spp, Cook and Cycles at 4096, difference times 4) and `dof-896-hexagon-bokeh-crops.png`.+Of 64 tiles, 19 (disk) and 20 (hexagon, pentagon) are too dark to count. For the disk and the hexagon the relMSE is at Cycles' own noise floor. A Cook pinhole against the Cycles disk image scores 7.8e-3 (230 times worse), with 35 of 45 tiles within 5 percent and a tile ratio as low as 0.44, so the scene does tell a lens from a pinhole.-Not covered: anamorphic bokeh (slice D2), lens shift and orthographic cameras (`createCamera` refuses both), the depth pass of a lens camera (not compared), and a re-render of the hexagon after the rotation sign flip.+The polygon is where the two renderers disagree, and a hexagon alone could not show how: its 60 degree symmetry lets a sign flip and a half-step offset look the same. The pentagon at 40 degrees separates them. Against Cycles the kernel's polygon sits half a corner step away, not mirrored: on the hexagon, Cook at 45 degrees matched Cycles at 15 (lamp-region relMSE 0.004, Cycles' own seed noise is 0.004) while Cook at 0 or 30 scored 0.029 and at 15 scored 0.055; on the pentagon neither the flipped sign (-40, equal to 32 modulo 72: 0.138) nor 40 (0.164) matched, and both orderings fit a target near 76 degrees, which is 40 plus half the 72 degree step. So `createCamera` adds half a corner step (`180 / blades` degrees) to the rotation, and the sign flip of `272003cd` was wrong for polygons other than a hexagon. That last change was derived from the measurements above and has not been rendered. Pictures: `docs/cook-depth-of-field-comparison.jpg` (rows disk and hexagon with the sign flip; Cook and Cycles at 256 spp, Cook and Cycles at 4096, difference times 4).++Bundle size (`node scripts/measure-size.mjs`, growth against origin/main, gzip bytes): `entry:path-tracer` 29,509 to 29,857 (+348, allowed 590), `entry:path-tracer-progressive` 38,118 to 38,468 (+350), `entry:path-tracer-realtime` 42,565 to 42,906 (+341), `entry:core` 90,098 to 90,103 (+5, allowed 64), `scene:lit-box` unchanged at 58,841. No bundle grew past its allowance, so there is no size note.++Not covered: anamorphic bokeh (slice D2), lens shift and orthographic cameras (`createCamera` refuses both), and the depth pass of a lens camera (not compared).## Progressive film and scene updates (#896, slice S2)diff --git a/src/camera.js b/src/camera.jsindex ef837786..5a532738 100644--- a/src/camera.js+++ b/src/camera.js@@ -82,11 +82,14 @@ export function cameraFocalLength(frame, aspect) {}/**- * The kernel's aperture rotation in radians for a Blender-style rotation in degrees. The kernel turns the polygon the other way- * round, which a hexagon at 15 degrees showed against Cycles (Cook at -15 matched Cycles at 15, Cook at 0 and 30 did not).+ * The kernel's aperture rotation in radians for a Blender-style rotation in degrees. Against Cycles the kernel's polygon sits half+ * a corner step away: a hexagon at 15 degrees matched Cook at 45 (and Cook at 0 and 30 were equally far off), and a pentagon at 40+ * degrees matched Cook at about 76 and not at 40 or -40, so the half step is added, not the sign flipped. A round aperture has no+ * corners and no offset.*/-function kernelApertureRotation(rotationDegrees) {- return rotationDegrees === 0 ? 0 : -rotationDegrees * Math.PI / 180;+function kernelApertureRotation(rotationDegrees, blades) {+ const rotation = rotationDegrees * Math.PI / 180;+ return blades >= 3 ? rotation + Math.PI / blades : rotation;}/**@@ -112,7 +115,7 @@ export function resolveThinLens(frame, { aspect, eye, target }) {apertureRadius: cameraFocalLength(frame, aspect) / 1000 / (2 * frame.fStop),focalDistance: focusDistance,apertureBlades: blades,- apertureRotation: kernelApertureRotation(rotationDegrees),+ apertureRotation: kernelApertureRotation(rotationDegrees, blades),};}diff --git a/tests/cook-dof-parity.test.js b/tests/cook-dof-parity.test.jsindex da71888c..7d7df841 100644--- a/tests/cook-dof-parity.test.js+++ b/tests/cook-dof-parity.test.js@@ -84,8 +84,8 @@ test('focus distance, blades and rotation come through; rotation turns from degr);assert.equal(lens.focalDistance, 2.5);assert.equal(lens.apertureBlades, 6);- assert.ok(Math.abs(lens.apertureRotation + Math.PI / 6) < 1e-12, 'the kernel turns the other way round from Blender, so the sign flips');- assert.equal(resolveThinLens({ ...LENS_OF_50_MM, apertureRotation: 0 }, { aspect: 1, eye: [0, 0, 4], target: [0, 0, 0] }).apertureRotation, 0, 'no negative zero for no rotation');+ assert.ok(Math.abs(lens.apertureRotation - Math.PI / 3) < 1e-12, 'a hexagon at 30 degrees is the kernel at 30 degrees plus half a corner step (30)');+ assert.equal(resolveThinLens({ ...LENS_OF_50_MM, apertureRotation: 0 }, { aspect: 1, eye: [0, 0, 4], target: [0, 0, 0] }).apertureRotation, 0, 'a round aperture has no offset');});test('a camera without an fStop is a pinhole: no lens fields, no change to the view', () => {@@ -124,7 +124,7 @@ test('depth of field changes only its own words of the params block', () => {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));+ assert.equal(floatOfWord(hexagon[APERTURE_ROTATION_WORD]), Math.fround(Math.PI / 2 + Math.PI / 6));});test('a v1 input carries the lens in the free fourth floats and upgrades to the same v2 words', () => {