Skip to content

Render dense grid volumes with Principled Volume terms (#44) - #55

Merged
anxuanng merged 1 commit into
mainfrom
44-grid-volumes
Nov 16, 2026
Merged

anxuanng merged 1 commit into
mainfrom
44-grid-volumes

Conversation

@anxuanng

Copy link
Copy Markdown
Contributor

Part of #44. The Crucible pin bump that stops the native backend throwing for grid volumes is a separate change.

What it does

Cook renders dense grid volumes: 3D grids of density, temperature and flame (half or full floats) placed by a box, with the .67vg channel layout of Crucible's volume-grid.js (decodeGridFile reads it). Pass scene.gridVolumes.

  • Distance sampling: delta tracking for camera and path rays, ratio tracking for shadow rays, against one global majorant (the sum of the grid majorants). Per-brick majorants are the follow-up.
  • Principled Volume terms, written from the equations: density, absorption colour, scattering colour with Henyey-Greenstein anisotropy, emission per unit length (times the flame channel, or the density without one) and physical blackbody from temperature: 5.670373e-8 * 1e-6 / pi * T^4 * blackbodyIntensity times the Planck colour of luminance 1, the same table Crucible uses.
  • Bounded input with clear errors: 8 grids, 256 voxels per axis, 256 MiB of voxels, finite non-negative values within half float range.
  • No new binding. The grids sit in the texel pool behind a descriptor table, reached through two reserved words of KernelParamsV2 and kernel flag 8192; the kernel code is compiled in only for such a pack. Format notes are in FORMAT-v2.md, "Grid volumes". The new code is src/cycles/grid_volume.wgsl and grid-volume-input.mjs; integrator.wgsl gets six small hooks.

Evidence

One frame of the #1735 explosion (frame 9, 427x240, same spec for both): Cook on the left, Blender 5.3 Cycles on the right, linear data tone mapped the same way.

Cook and Cycles

Measured on an RTX 3060 (Cook) and the CPU with 8 threads (Cycles), linear RGB, image mean 0.1454:

Comparison RMSE of the mean
Cook 16384 spp vs Cycles 2048 spp, adaptive sampling off 0.00268 1.8%
Cook 2048 spp vs Cycles 2048 spp, adaptive sampling on (its default) 0.00606 4.2%
Means: Cook 0.14532, Cycles 0.14538 0.04% apart

Most of the first number is noise. The two renders' own noise is about 0.0017 together (inferred from their per-pixel noise at 16 spp scaled to those sample counts), which leaves a bias of about 0.002, 1.4% (inferred). The error sits in the fire (RMSE 0.0069 there, 0.0004 on the open floor).

Noise (standard deviation of one render, from two seeds, same frame):

seconds noise
Cycles, 16 spp, adaptive off 0.83 to 0.97 0.0156
Cook, 170 spp 0.75 0.0085
Cycles, 2048 spp with adaptive sampling (default) 2.3 0.0051
Cook, 490 spp 2.1 to 2.2 0.0050

At equal samples Cook is noisier (0.0286 against 0.0156 at 16 spp, 1.8 times). At equal time it is 1.8 times less noisy than fixed-sample Cycles and equal to Cycles with its adaptive sampling. GPU against CPU, so the time comparison says little about the algorithms.

No grids, no change: the SHA-256 of the linear output of the room fixture (160x120, 16 spp) is 7dc98f89...2862 and of a world fog scene (128x96, 32 spp, sun, albedo and anisotropy) is 276f3dc0...eda6, identical between the addon built from main and this branch.

How I checked it

  • node --test: 194 pass, none skipped (a GPU adapter with ray queries was present). New: tests/grid-volume-input.test.mjs (input validation, descriptor layout, .67vg decoding, the no-grid pack equals the old one) and tests/gpu/grid-volume.test.mjs, three closed forms: a camera ray through a box with chromatic absorption keeps exp(-sigma * length) of the background per channel; a shadow ray through a slab gives the same transmittance by ratio tracking (shadowed over open floor pixel); the emission of a box equals the numeric integral of emission * density * exp(-optical depth). The box edge is half density at a face, so the closed forms use length * (1 - 1 / (4 n)).
  • node tools/run-cargo-tests.mjs: 139 and 23 pass, with two new tests on the specialization and the module in the kernel manifest. The existing texel pool invariant test now allows the grid reader vg_word, which is not a texture sampler.
  • node tools/check-exports.mjs and release-guard against origin/main: clean.
  • Reproduce: node tools/grid-volume-parity.mjs <spec.json> <grid.67vg> <prefix> --samples N renders Cook, Crucible's scripts/cycles-volume-reference.py renders Cycles, tools/exr-to-npy.py converts the EXR in Blender, and tools/grid-volume-compare.mjs rmse|noise scores.

Not in this slice

  • A majorant per brick (the global majorant makes empty space cost null collisions).
  • An analytic light seen along a segment that crosses a grid is weighted by the whole segment's null collisions.
  • Overlapping grids with different anisotropy blend g by their scattering.
  • Single frame only; no motion blur from the velocity channels.

Grid volumes are 3D grids of density, temperature and flame placed by a box,
read from scene.gridVolumes (the .67vg layout of Crucible's volume-grid.js).
They live in the texture texel pool behind a descriptor table, found through
the two reserved words of KernelParamsV2 and kernel flag 8192, so no binding
changes and a pack without grids is unchanged bit for bit.

The kernel walks camera and path rays with delta tracking against a global
majorant and shadow rays with ratio tracking, with absorption colour,
scattering with Henyey-Greenstein anisotropy, emission per unit length and
physical blackbody from temperature.

Tools compare one Crucible explosion frame with the Cycles reference.
@anxuanng
anxuanng merged commit 6e2cd0b into main Nov 16, 2026
5 checks passed
@anxuanng
anxuanng deleted the 44-grid-volumes branch November 16, 2026 17:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant