rayzee 11.13.0 → 11.15.0

package/README.md

@@ -147,7 +147,7 @@ A single HTML file — no Node.js, no build step. Uses [ES module import maps](h
       "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.tsl.js",
       "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.webgpu.js",
       "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.0/examples/jsm/",
-      "oidn-web/": "https://cdn.jsdelivr.net/npm/oidn-web@0.5.0/",
+      "oidn-webgpu/": "https://cdn.jsdelivr.net/npm/oidn-webgpu@0.6.0/",
       "rayzee": "https://cdn.jsdelivr.net/npm/rayzee/dist/rayzee.es.js"
     }
   }
@@ -533,7 +533,7 @@ To pause rendering for image-viewing UI, set `engine.pauseRendering = true` and
 
 ### Renderer core (`rayzee/core`)
 
-`PathTracerApp` is built on `RayzeeRenderer`, the renderer without the viewer: a scene and camera in, path-traced samples accumulated, the image out. The denoisers, camera controls, gizmo, overlays, timeline and animation playback exist only in `PathTracerApp`; six capabilities come as add-ons — file formats beyond glTF and `.hdr`, the physical sky, scene archives, bidirectional path tracing, OpenColorIO colour and on-disk storage. Its entry point downloads about 40 % less (249 KB against 418 KB compressed). It takes the same constructor options except `container`, and renders the same pixels.
+`PathTracerApp` is built on `RayzeeRenderer`, the renderer without the viewer: a scene and camera in, path-traced samples accumulated, the image out. The denoisers, camera controls, gizmo, overlays, timeline and animation playback exist only in `PathTracerApp`; six capabilities come as add-ons — file formats beyond glTF and `.hdr`, the physical sky, scene archives, bidirectional path tracing, OpenColorIO colour and on-disk storage. Its entry point downloads about 30 % less at startup (277 KB against 404 KB compressed). It takes the same constructor options except `container`, and renders the same pixels.
 
 ```js
 import { RayzeeRenderer } from 'rayzee/core';
@@ -890,8 +890,8 @@ await engine.unloadColorConfig();
 ```
 
 - **Load and unload through `engine.loadColorConfig()` / `unloadColorConfig()`** once a scene exists: they undo an adopted working space while the config that converted the environment is still loaded.
-- A view is baked to a log2 shaper and a 65³ table, interpolated tetrahedrally; the same table drives the canvas, the GPU and CPU readbacks and the menu (`listViewTransforms()`, `onRegistryChange()`). An OCIO view returns display-encoded colour, so the engine switches the output pass to linear while one is active.
-- **Baked views.** `await engine.color.saveBakedView(id)` writes a view's table to a file (157 KB gzip for 65³), and `await engine.color.loadBakedView(bytes, { expect })` registers it with no runtime and no config — show the look on the first frame, load the config later. When that config loads, a baked view whose files match the fingerprint it was baked from is kept as is: no rebake, no new id, no restart.
+- A view is baked to a log2 shaper and a 65³ table, interpolated tetrahedrally — where that measures poorly, on linear Rec.709's axes and at 97³, whichever is closer (`entry.error` says what it cost); the same table drives the canvas, the GPU and CPU readbacks and the menu (`listViewTransforms()`, `onRegistryChange()`). An OCIO view returns display-encoded colour, so the engine switches the output pass to linear while one is active.
+- **Baked views.** `await engine.color.saveBakedView(id)` writes a view's table to a file (157 KB gzip for 65³, 426 KB for 97³), and `await engine.color.loadBakedView(bytes, { expect })` registers it with no runtime and no config — show the look on the first frame, load the config later. When that config loads, a baked view whose files match the fingerprint it was baked from is kept as is: no rebake, no new id, no restart.
 - `renderToBuffer({ colorSpace })` takes `'srgb'` (display bytes through the active view), `'linear'` (the working-space accumulation) or a config colour space; `source: 'display'` reads what the viewport shows, denoised, instead of the raw accumulation.
 - Degradations (a view that cannot bake, a display the canvas cannot show) are recorded as warnings in the [degradation contract](#degradation-contract).
 
@@ -1081,8 +1081,10 @@ surface** — pin a version and branch on the strings; they are never renamed or
 | `emissive.instances_collapsed` | an emissive instanced mesh was too large to expand, so its copies light the scene as one |
 | `refit.shared_geometry` | a deform was asked for on a mesh that shares its triangles, and was skipped |
 | `denoiser.unavailable` | a requested denoise or upscale produced nothing — the denoiser was not built, OIDN was off while accumulating, or the pass needs a canvas in a document |
+| `denoiser.non_finite_input` | the render handed OIDN NaN or infinite pixels (`detail.color` / `albedo` / `normal`: how many), which were treated as zero — a warning, recorded again only after a clean frame |
 | `output.source_fallback` | `renderToBuffer( { source: 'display' } )` found no denoised picture and returned the raw accumulation |
 | `output.tonemap_fallback` | `renderToBuffer`'s `'srgb'` bytes were tone-mapped on the CPU, not the GPU — the picture is the same within a level, only slower (a warning: strict does not throw) |
+| `output.pass_unavailable` | `exportImage` was asked for an EXR layer it cannot write, such as `albedo` or `normal` with no denoiser on (`detail.pass`); the file is written without it |
 | `light.placeholder_skipped` | a `RectAreaLightPlaceholder` node lacked `userData.name` or `userData.type: 'RectAreaLight'`, so no light was made for it |
 | `capability.missing` | a feature was asked for whose add-on is not installed on the core (procedural sky, an unregistered integrator, a colour config, storage) — names the add-on |
 | `color.config_load_failed` / `viewTransform.bake_failed` / `viewTransform.display_mismatch` | a colour config failed to load (the previous one stays), a view could not be rebaked, or a view targets a display the canvas cannot show (a saved buffer is still right) — warnings |
@@ -1111,7 +1113,7 @@ setting as `{ value, source, routed }`, and `routed: false` means stored but rea
 
 ### Output Methods
 
-Canvas output, screenshots, and scene statistics — accessed as direct methods on the engine.
+Canvas output, screenshots, saved files and scene statistics — accessed as direct methods on the engine.
 
 ```js
 engine.getCanvas()                    // Get the canvas with the final rendered image
@@ -1135,6 +1137,61 @@ a.click();
 URL.revokeObjectURL(url);
 ```
 
+#### Saving a file
+
+`exportImage()` writes the render as a file and returns `{ blob, extension, mimeType, width, height, colorSpace, … }`.
+It works on the core too, and headless.
+
+| `format` | What the file holds |
+|---|---|
+| `'png'` (`bitDepth: 8` or `16`), `'jpeg'`, `'webp'` | the picture the canvas shows: exposure, view and denoising applied; at 8 bits, JPEG and WebP, the AI upscaler's picture while one shows (`upscaled: false` skips it) |
+| `'heic'`, `'avif'` | the same picture, written by the browser's video encoder |
+| `'exr'` (`precision: 'half'` or `'float'`), `'hdr'` (Radiance) | the light itself, before exposure and view, in the working space or `colorSpace`; with `asShown: true`, the light the screen gives off for the picture, so any viewer shows it as the screen does |
+
+```js
+const { blob, extension } = await engine.exportImage({ format: 'png', bitDepth: 16 });
+const exr = await engine.exportImage({ format: 'exr', passes: ['albedo', 'normal', 'depth'] });
+const photo = await engine.exportImage({ format: 'jpeg', gainMap: true });   // an HDR photo
+engine.exportInfo();   // what can be written now: { width, height, upscaled, hdr, layers: { albedo, normal, depth } }
+```
+
+- **HDR photos.** `gainMap: true` on `'jpeg'`, `'heic'` or `'avif'` adds a gain map — a second, small picture that
+  says how much brighter each part of the HDR version is (ISO 21496-1; Ultra HDR in a JPEG). Photo viewers that read gain
+  maps show the file in HDR, others the normal picture. It needs the screen showing HDR
+  (`engine.color.setHdrOutput(true)` on an HDR display; `exportInfo().hdr`).
+- **EXR layers.** `albedo` and `normal` are the denoisers' guide images, so they exist only while a denoiser is on;
+  `depth` is measured when asked for. A layer that cannot be written records `output.pass_unavailable`.
+- **Where each works.** JPEG, WebP, HEIC and AVIF need a browser (its canvas or video encoder); PNG, EXR and HDR work in
+  Node too. `canEncodeStill('heic')` from `rayzee/encoders` says whether this browser can write HEIC or AVIF.
+- Render details (samples, size, view, settings, versions) go into the file, except a WebP, unless `metadata: false`.
+  An EXR's also say how its picture was shown (the exposure, auto exposure's included, local exposure and a held
+  backdrop). The file writers download on the first export, not at startup.
+- **Showing a saved EXR again.** `await engine.createPictureView(canvas)` (the viewer, `PathTracerApp`) gives a
+  picture view on a canvas of your own; `await view.show(exrBlob)` draws the raw EXR exactly as an HDR screen showed it,
+  through the same view, exposure and local exposure, and returns `{ shown, reason }` (`reason`: the screen shows no HDR,
+  the file has no such details, its colour config is not the one loaded, or a later `show()` took over). It reads the
+  file's header first and decodes the pixels only of a file it shows. `view.setGrade(fn)` adds your own edit after
+  the view, a TSL function of the shown colour; `view.redraw()` after its uniforms change; `view.dispose()`.
+
+The writers are also a module of their own, `rayzee/encoders`, for pixels a host already has. It is part of the
+package, not an add-on: nothing to install, and importing it loads nothing else (9 KB compressed).
+
+```js
+import { encodePNG, encodeEXR, encodeHDR, IMAGE_FORMATS } from 'rayzee/encoders';
+
+const png = await encodePNG({ data, width, height });   // RGBA, Uint8Array (8 bits) or Uint16Array (16), top row first
+const hdr = await encodeHDR({ data: floats, width, height });   // RGBA Float32Array
+const exr = await encodeEXR({ width, height, channels: [
+  { name: 'R', data: floats, stride: 4, offset: 0 },
+  { name: 'G', data: floats, stride: 4, offset: 1 },
+  { name: 'B', data: floats, stride: 4, offset: 2 },
+] });
+```
+
+Chrome on macOS takes about 5 seconds to start its first hardware video encoder after the browser launches, and about
+2 ms after that. HEIC and MP4 both use it. `prepareStill('heic')` starts it ahead of time without encoding anything,
+for example when an export menu opens.
+
 ---
 
 ### Render Resolution Reserve
@@ -1183,7 +1240,7 @@ engine.vram.getReport();   // formatted one-line summary string
 
 `denoiser` is what the engine allocates for OIDN — its three float inputs, its half-float output and
 the motion history. `canvas` is one image per presented surface (a browser may keep one or two more)
-plus the buffer three.js's output pass tone-maps through. Not counted: oidn-web's own network weights
+plus the buffer three.js's output pass tone-maps through. Not counted: oidn-webgpu's own network weights
 and activations, which it reports by count, not by size; and the neural passes, which run on a
 `GPUDevice` of their own.
 
@@ -1257,10 +1314,10 @@ const blob = await engine.screenshot();
 engine.setDeterministicMode(false);         // restore the previous configuration
 ```
 
-The RNG is already pure — `hash(pixel, rayIndex, frame)`, no clock, no `Math.random()` in any shader. What varies run to run is *which* uniforms and dispatch grids are live on frame k, so `setDeterministicMode` disables adaptive sampling, per-pixel freeze, the readback-driven per-bounce early exit and dynamic dispatch sizing, interaction mode, auto-focus, and auto-exposure, and pins the sampler's seed axis to the accumulation frame. It also forces `renderLimitMode` to `'frames'` — a wall-clock render limit retires at a run-dependent sample count. It leaves the rAF loop stopped; `renderFrames` is the drive.
+The RNG is already pure — `hash(pixel, rayIndex, frame)`, no clock, no `Math.random()` in any shader. What varies run to run is *which* uniforms and dispatch grids are live on frame k, so `setDeterministicMode` disables adaptive sampling, per-pixel freeze, the readback-driven per-bounce early exit and GPU-sized dispatch, interaction mode, auto-focus, and auto-exposure, and pins the sampler's seed axis to the accumulation frame. It also forces `renderLimitMode` to `'frames'` — a wall-clock render limit retires at a run-dependent sample count. It leaves the rAF loop stopped; `renderFrames` is the drive.
 
 - `engine.isDeterministic` — whether output is currently bit-reproducible.
-- `setDeterministicMode(true, { pinDispatch: false })` keeps the two readback-driven dispatch heuristics active. Output is then *not* reproducible; this exists so performance measurements reflect shipping behaviour rather than a configuration production never runs.
+- `setDeterministicMode(true, { pinDispatch: false })` keeps the two dispatch heuristics active (GPU-sized dispatch and the readback-driven early exit). Output is then *not* reproducible; this exists so performance measurements reflect shipping behaviour rather than a configuration production never runs.
 - `renderFrames` raises `maxSamples` if needed, and throws if something retires the render early.
 
 #### Production renders, reproducibly
@@ -1279,8 +1336,9 @@ It renders without `requestAnimationFrame` until the sample ceiling, convergence
 whichever comes first — then runs the final OIDN denoise once, and fires `RENDER_COMPLETE` as the
 loop does. Adaptive sampling decides from counts read back from the GPU; normally each is applied
 whenever it lands, so the frame that retires depends on how fast frames are submitted. For its
-duration `renderUntilComplete` runs those readbacks in **lockstep**: one issued at frame N is applied
-at frame N + 4 exactly, and the render waits if it has not landed; every reset also starts from seed
+duration `renderUntilComplete` runs those readbacks in **lockstep**: the first, issued at frame 1, is
+applied at frame 2, then one issued at frame N (a multiple of 4) at frame N + 4 exactly, and the
+render waits if one has not landed; every reset also starts from seed
 0 and from nothing the previous render measured. It turns interaction mode off meanwhile (a
 wall-clock mode for camera drags), and keeps submissions at most 2 × `drainEvery` frames ahead of
 the GPU. A time limit is wall-clock by nature, so that one stop is not reproducible. Auto exposure, if you turn it
@@ -1290,7 +1348,7 @@ on, lands on a metering of the finished image before the closing denoise.
 
 #### Batch rendering
 
-The supported entry point for a render farm is `rayzee/src/Headless.js`, exported from the package.
+The supported entry point for a render farm is `rayzee/src/viewer/Headless.js`, exported from the package.
 Its defaults are a batch renderer's — `strict`, deterministic, storage off —
 so a degraded render throws instead of shipping:
 
@@ -1311,6 +1369,9 @@ try {
 `denoise: true` turns OIDN on before accumulating (it reads the albedo and normal buffers, which
 are written only while it is on), runs **one** final denoise with `app.runFinalDenoise()`, and reads
 it back with `renderToBuffer( { source: 'display' } )`. Driving it yourself is the same three calls.
+`denoise: { quality: 'high', tileSize: 2048 }` also picks the model (the default is `'fast'`) and the tile cap: with no
+live view to keep smooth, a larger cap is faster for more GPU memory — 1920×1080 as one tile instead of four took 27 %
+less time on an M5 Pro. A tile never grows past what the GPU can dispatch (~2000² with its border), whatever the cap.
 `renderToBuffer` reports the picture it read as `source`, and records `output.source_fallback` when
 `'display'` was asked for, a denoiser is in use, and nothing had published — so a strict host cannot
 ship a noisy image by mistake. Its `'srgb'` bytes are tone-mapped on the GPU — 9 ms at 4096×2160,
@@ -1328,7 +1389,8 @@ here, or `engine.settings` before loading the model.
 
 **Provenance.** `engine.getProvenance()` — also `frame.provenance` from `captureHeadless` — is plain
 JSON naming what produced the image: engine and three.js versions, the adapter, every live setting with its source, the colour pipeline, the render size and
-samples, and whether it ran headless, strict, deterministic or lockstepped. `mode.lockstep` says
+samples, whether it ran headless, strict, deterministic or lockstepped, and the denoisers (`denoise.live`, and
+`denoise.final`: the OIDN tier, weights file, precision and tile). `mode.lockstep` says
 whether the current image was traced in lockstep, so it stays true after `renderUntilComplete` turns
 lockstep back off. Store it beside each render and "what made this?" has an answer without rendering
 again.
@@ -1368,7 +1430,7 @@ app.dispose();
 - **No canvas means headless.** `new PathTracerApp(null)` — or `{ headless: true }` — makes its own
   canvas (a WebGPU context over a plain texture), runs no render loop (drive it with `renderFrames` or
   `renderUntilComplete`), and builds neither the overlay renderer nor the transform gizmo.
-- **`configurePlatform({ Worker, decodeImage })`** is where a host without a browser supplies what one
+- **`configurePlatform({ Worker, decodeImage, readFile })`** is where a host without a browser supplies what one
   would. `nodePlatform()` from `rayzee/node` fills it: `NodeWorker`, the Web Worker API over
   `worker_threads`, runs the engine's inlined workers; `decodeImage(bytes, mimeType)` is yours — PNG,
   JPEG or WebP to RGBA8, straight alpha, top row first — since the engine carries no decoder. It decodes
@@ -1389,6 +1451,10 @@ app.dispose();
   packs in a worker, reading images decoded by `decodeImage` in place (they are kept in shared
   memory): on the main thread it held up the BVH workers, and a 1.9M-triangle, 91-texture model
   loaded in 4.1–4.9 s. It now loads in 2.1 s, against Chrome's 2.9 s on the same machine.
+- **Offline: OIDN weights from disk.** Node's `fetch` cannot open `file:` URLs, so `nodePlatform()` also hands
+  the engine a file reader, and what it downloads itself — the OIDN weights, IES profiles — can come from a folder:
+  `configureAssets({ oidnWeightsBaseUrl: 'file:///opt/rayzee/oidn/' })`, holding the `.tza` files the tiers
+  name (`rt_hdr_alb_nrm_small`, `rt_hdr_calb_cnrm_small`, `rt_hdr_calb_cnrm`, `rt_hdr_calb_cnrm_large`).
 - `nodePlatform()` also defines `ProgressEvent`, which three.js's `FileLoader` constructs while
   streaming; that is the only global it sets. three.js's own Draco and KTX2 loaders call the global
   `Worker`; the engine lends them `NodeWorker` for the length of each glTF parse, so a Draco or KTX2
@@ -1412,7 +1478,7 @@ WebGPU timestamp queries are the only true GPU metric here — `pipeline.getStat
 
 `getKernelGPUTimings()` attributes each compute pass of the last resolved frame back to a wavefront kernel name. Durations are **summed per kernel across the frame**, so `extend` reports its whole per-frame cost over every bounce iteration, not one bounce. `unattributed` collects passes belonging to no registered kernel (other stages, denoisers), so `sum(kernels) + unattributed` reconciles with `total`.
 
-Neither method can see the OIDN denoise — `oidn-web` submits on its own command encoders, outside
+Neither method can see the OIDN denoise — `oidn-webgpu` submits on its own command encoders, outside
 the stages three.js times. It carries its own profiler instead:
 
 ```js
@@ -1616,6 +1682,12 @@ import { acquireSharedStorage } from 'rayzee/addons/storage';
 // Headless rendering (see Deterministic & Headless Rendering)
 import { renderHeadless, openHeadless, captureHeadless } from 'rayzee';
 
+// File writers behind exportImage(), for pixels a host already has (see Saving a file)
+import {
+  IMAGE_FORMATS, encodePNG, encodeEXR, encodeHDR, encodeWithCanvas, encodeGainMapJPEG,
+  encodeStill, canEncodeStill, prepareStill,
+} from 'rayzee/encoders';
+
 // Platform services for hosts without a browser (see Running in Node)
 import { configurePlatform, getPlatform } from 'rayzee';
 import { nodePlatform, NodeWorker } from 'rayzee/node';
@@ -1726,7 +1798,7 @@ import { setBindingAudit, getBindingAuditFindings, clearBindingAuditFindings } f
 
 | Package | Purpose | Install needed? |
 |---|---|---|
-| `oidn-web` | Intel Open Image Denoise for high-quality final renders | Yes — `npm install oidn-web` (**>=0.5.0**) |
+| `oidn-webgpu` | Intel Open Image Denoise for high-quality final renders | Yes — `npm install oidn-webgpu` (**>=0.6.0**; it was `oidn-web` up to 0.5.0) |
 | `onnxruntime-web` | AI-powered upscaling | No — loaded from CDN at runtime |
 | `@bb-studio/ocio` | OpenColorIO runtime for [Colour Management](#colour-management) (~6 MB WebAssembly) | Only to load colour configs — `npm install @bb-studio/ocio`, then pass it as `ocioRuntimeFactory` |
 
@@ -1742,7 +1814,7 @@ accumulating, so a preview shows a clean picture as it refines instead of only a
 1. **Install the package**
 
    ```bash
-   npm install oidn-web
+   npm install oidn-webgpu
    ```
 
 2. **Enable in your app**
@@ -1857,7 +1929,7 @@ Two constraints shape that table, and neither is optional:
   (`> 120 ms`).** A tier a machine can afford is kept — at 512² that is every tier. The verdict
   survives a camera move, because the device does not get faster between them; it is re-taken when
   the tier or the resolution changes. Past it, each render swaps twice (to the cheap model when the
-  view moves, back for the finished image). A swap costs 10-20 ms on oidn-web 0.4.0, and each model's
+  view moves, back for the finished image). A swap costs 10–50 ms on oidn-webgpu 0.6.0 (the large model the most), and each model's
   weights are downloaded once and kept, so a swap never goes back to the network.
 
 #### What paces the refreshes
@@ -1917,8 +1989,9 @@ Denoise cost scales with frame area, and the tile tracks the frame so that a fra
 tile pays no overlap padding — at 1024x1024 that is roughly 1.8x faster than tiling it. A cap
 (default 1024) bounds the one-time activation allocation, so larger frames tile and stay
 memory-bounded. Raise or lower it with
-`engine.denoisingManager.denoiser.updateConfiguration({ tileSize: 2048 })`; the effective tile is
-`min( max( width, height ), tileSize )`.
+`engine.denoisingManager.denoiser.updateConfiguration({ tileSize: 2048 })`: a frame no larger in area than
+`tileSize`² is one tile, a larger one is split into tiles of at most `tileSize`, and no tile grows past what the GPU
+can dispatch (about 2000² with its border and overlap) — past that the denoise would silently do nothing.
 
 > **Note:** The neural network model is downloaded on first use. Subsequent runs use the browser cache. OIDN also works with `configureForMode('production')`, which enables it automatically alongside high-quality render settings.
 
@@ -1947,13 +2020,13 @@ engine.addEventListener(EngineEvents.UPSCALING_END,      () => console.log('Upsc
 ## Troubleshooting
 
 **OIDN: `Cannot find module './tza'` (webpack)**
-The `oidn-web` package uses dynamic imports that webpack cannot resolve. This does not affect Vite or other ESM-native bundlers. Add `oidn-web` to your webpack externals:
+The `oidn-webgpu` package uses dynamic imports that webpack cannot resolve. This does not affect Vite or other ESM-native bundlers. Add the engine's import of it to your webpack externals:
 
 ```js
 // webpack.config.js
 module.exports = {
   externals: {
-    'oidn-web': 'oidn-web'
+    'oidn-webgpu/dist/oidn.js': 'oidn-webgpu/dist/oidn.js'
   }
 };
 ```
@@ -1964,7 +2037,7 @@ Then load it via a script tag or import map instead:
 <script type="importmap">
 {
   "imports": {
-    "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.4.0/dist/oidn.js"
+    "oidn-webgpu/dist/oidn.js": "https://cdn.jsdelivr.net/npm/oidn-webgpu@0.6.0/dist/oidn.js"
   }
 }
 </script>

package/dist/{ActiveColor-YvuQq44O.js → ActiveColor-DakLCifA.js}

@@ -1,4 +1,4 @@
-//#region src/Color/ActiveColor.js
+//#region src/color/ActiveColor.js
 var e = "Linear Rec.709 (sRGB)", t = null;
 function n() {
 	return t;