@meimu/mutracer 0.0.0-stage → 0.1.1

package/docs/denoising.md

@@ -0,0 +1,301 @@
+# Denoising
+
+MuTracer has two built-in denoisers. Both filter the complete composed image using
+albedo and normal guides.
+
+- **JNLM**: a built-in joint non-local means filter, on WebGPU and
+  WebGL 2. It needs no weight download.
+- **OIDN**: [Intel Open Image Denoise](https://www.openimagedenoise.org/)
+  networks, run through [`oidn-web`](https://www.npmjs.com/package/oidn-web),
+  WebGPU only. They take longer and need weights, but are cleaner at one or
+  two samples per pixel, for example for denoising while the camera moves.
+
+```ts
+const engine = new Engine({canvas});
+const final = new Render(engine, {denoiser: {type: 'jnlm'}});
+final.setDenoiser({type: 'oidn', model: 'standard'});
+final.setDenoiser(null); // disable
+```
+
+`type` is required: use `jnlm` or `oidn`. `render.denoiser` returns a frozen
+copy of the configuration; call `setDenoiser` again to change it. Unknown types,
+foreign fields and invalid JNLM settings throw synchronously, preserving the
+active network and output. Equal implementation settings share the network;
+changing only `schedule` preserves active inference, and passing an identical
+configuration does nothing.
+Each render has its own configuration and scheduling. Converge waits for its
+configured filter; intermediate progressive inference reports converging and
+final inference reports denoising. Engine caches equal network configurations
+and weights, releasing the network after its last render lease is released.
+
+`setDenoiser` returns a promise that resolves when the filter is ready, which
+for OIDN means its weights have loaded, and rejects when loading fails. A
+configuration replaced before it finishes loading resolves without an error;
+an identical configuration returns the current promise. Await it when you need
+the filter before rendering:
+
+```ts
+try {
+  await final.setDenoiser({type: 'oidn', model: 'standard'});
+} catch (error) {
+  final.setDenoiser({type: 'jnlm'}); // weights unavailable; fall back to JNLM
+}
+```
+
+OIDN is loaded lazily. On WebGL its configuration warns, leaves this render
+unfiltered and resolves; JNLM works on both backends. Loading failures of a
+`denoiser` constructor option, and of reloads after device recovery, report
+through engine error events, as do inference failures. Replaced/disposed
+network prewarm results are discarded.
+
+## Options
+
+| `JNLMDenoiserOptions` | Description |
+| --- | --- |
+| `type` | Required: `'jnlm'` |
+| `schedule` | `'converged'` (default), `'progressive'`, or `'every-sample'` |
+| `strength` | JNLM filter strength. Default `1` |
+| `searchRadius` | JNLM search radius, integer `1–16`. Default `5` (11 × 11 window) |
+| `patchRadius` | JNLM color comparison patch radius, integer `0–3`. Default `1` (3 × 3 patch) |
+| `albedoBandwidth` | JNLM relative albedo tolerance, `0.0001–10`. Default `0.4` |
+| `normalBandwidth` | JNLM encoded normal tolerance, `0.0001–10`. Default `0.05` |
+| `iterations` | JNLM filter passes, integer `1–4`. Default `2` |
+
+| `OIDNDenoiserOptions` | Description |
+| --- | --- |
+| `type` | Required: `'oidn'` |
+| `model` | OIDN network: `'standard'` (default), `'small'` or `'cleanAuxLarge'` |
+| `weightsBaseUrl` | Directory containing the OIDN `.tza` files |
+| `schedule` | `'converged'` (default), `'progressive'`, or `'every-sample'` |
+| `maxTileSize` | Maximum OIDN tile size; chosen by oidn-web by default |
+| `signal` | `AbortSignal` for the OIDN weight download; default undefined |
+| `weightsUrl` | Explicit custom network; mutually exclusive with model/base directory |
+| `aux`, `hdr`, `hdrTransfer` | Custom network metadata only; defaults true, true, `'pu'` |
+| `auxiliaryModelUrls` | Both prefilter URLs; defaults to packaged cleanAuxLarge filters, otherwise none |
+| `engine`, `precision`, `dynamicTile` | Defaults `'auto'`, `'auto'`, true; see custom networks below |
+
+## OIDN models
+
+| `model` | Weights | Use |
+| --- | --- | --- |
+| `'standard'` (default) | `rt_hdr_alb_nrm.tza` (1.8 MB) | Balanced quality and speed; bundled with mutracer |
+| `'small'` | `rt_hdr_alb_nrm_small.tza` (0.6 MB) | Fastest; previews while converging; bundled with mutracer |
+| `'cleanAuxLarge'` | `rt_hdr_calb_cnrm_large.tza` + `rt_alb_large.tza` + `rt_nrm_large.tza` (22 MB) | Highest quality; prefilters guides; from oidn-weights@2.3.0-1 |
+
+## Hosting the weights
+
+Standard and small load from your application's own build assets by default.
+Vite and webpack 5 copy the package's static weight URLs into the output.
+In Vite development add `optimizeDeps: { exclude: ['@meimu/mutracer'] }` to avoid
+prebundling asset URLs; otherwise MuTracer warns once and falls back to
+jsDelivr's copy for the installed MuTracer version. The standalone `dist/`
+library bundles use that CDN copy directly.
+
+The large beauty network and auxiliary prefilters default to
+`https://cdn.jsdelivr.net/npm/oidn-weights@2.3.0-1/`. To self-host all networks,
+install `oidn-weights@2.3.0-1` and copy `node_modules/oidn-weights/*.tza` to a
+static directory. If you only use standard/small, copying the two files from
+`node_modules/@meimu/mutracer/oidn/weights/` is sufficient:
+
+```ts
+final.setDenoiser({type: 'oidn', weightsBaseUrl: '/assets/oidn/weights/'});
+```
+
+Explicit URLs never fall back to the CDN. Every download is checked for the
+TZA file signature. The weights use Apache-2.0 (`oidn/weights/LICENSE.txt`).
+
+## Scheduling
+
+```ts
+final.setDenoiser({type: 'oidn', model: 'standard', schedule: 'progressive'});
+preview.setDenoiser({type: 'oidn', model: 'small', schedule: 'every-sample'});
+```
+
+Converged filters the final sample budget. Progressive filters sample 1,
+then 4, 8, 16, … and the final budget, with a ten-second limit between
+updates. Every-sample filters every complete sample of its render. Coalescing
+continuous scene/camera edits is application loop policy; the engine accepts
+edits only when update is called. See [progressive rendering](./progressive-rendering.md).
+
+## Tuning JNLM
+
+`strength` (default `1`) scales the color tolerance. Higher values remove
+more noise at low sample counts and more detail at high ones.
+
+```ts
+final.setDenoiser({type: 'jnlm', strength: 1.5});    // filter more
+```
+
+JNLM settings are available through `DenoiserOptions`. Omitted settings use
+the exported `DEFAULT_JNLM_OPTIONS`; `JNLMOptions` is the corresponding type.
+`setDenoiser` applies a fresh configuration to the existing sample
+accumulation, so include the settings you want to retain on each call.
+
+```ts
+import { DEFAULT_JNLM_OPTIONS } from '@meimu/mutracer';
+
+final.setDenoiser({
+  type: 'jnlm',
+  ...DEFAULT_JNLM_OPTIONS,
+  strength: 1.2,
+  searchRadius: 7,
+  albedoBandwidth: 0.3
+});
+```
+
+Larger search windows cost more but find more matching neighbors. Smaller
+patches preserve small color details. Lower albedo and normal tolerances
+reject more neighbors, protecting detail while retaining more noise. Extra
+passes remove broader noise patches and can soften detail. Invalid parameters
+reject before replacing the active filter. These settings work on both WebGPU
+and WebGL 2; OIDN rejects JNLM fields.
+
+## Custom OIDN networks
+
+Load an explicit network file through the same built-in OIDN path:
+
+```ts
+final.setDenoiser({
+  type: 'oidn', weightsUrl: '/assets/custom.tza',
+  aux: true, hdr: true, hdrTransfer: 'pu',
+  engine: 'wgsl', precision: 'auto', dynamicTile: true
+});
+```
+
+`weightsUrl` is mutually exclusive with `model` and `weightsBaseUrl`. The
+custom network metadata defaults to `aux: true`, `hdr: true`,
+`hdrTransfer: 'pu'`; those fields require `weightsUrl`. Explicit downloads
+never fall back to a CDN. `auxiliaryModelUrls: {albedo, normal}` optionally
+loads prefilters for either source; cleanAuxLarge supplies its packaged filters
+by default. Override both auxiliary URLs together.
+
+Execution settings are available for every OIDN configuration. `engine`
+defaults to `'auto'`; `'wgsl'` selects native GPU inference and `'webnn'` the
+experimental WebNN path. `precision` defaults to `'auto'` (FP16 when
+shader-f16 is available), with `'fp32'` and `'fp16'` overrides. `dynamicTile`
+defaults to `true`; use `false` for fixed tiles or an object with
+`minTileSize` (256), `initialTileSize` (432), `targetTileTimeMs` (16) and
+`adjustmentStep` (16). Tile sizes are clamped/aligned by oidn-web.
+
+All implementation settings participate in the network cache key; `schedule`
+and download `signal` do not. Renders with different signals share a pending
+load; its initial request's signal controls that download. Loading failures
+reject the returned promise and can be retried by calling `setDenoiser(null)`
+and then the configuration again. Nested tile/URL settings are copied and frozen too.
+
+`@meimu/mutracer/oidn` contains only weight constants and the
+`resolveOIDNModelUrl` / `resolveOIDNAuxiliaryModelUrls` URL helpers. Loading
+functions and network handles are internal; configure them through Render.
+OIDN option types are exported from the main entry.
+
+## Custom denoisers
+
+Provide a caller-owned `Denoiser` on WebGPU. Built-in JNLM and OIDN retain
+their specialized paths. This identity filter illustrates the buffer contract:
+
+```ts
+import type {Denoiser} from '@meimu/mutracer';
+
+const copy: Denoiser = {
+  async denoise({device, width, height, color, output}, {signal}) {
+    if (signal.aborted) return;
+    const encoder = device.createCommandEncoder();
+    encoder.copyBufferToBuffer(color, 0, output, 0, width * height * 16);
+    device.queue.submit([encoder.finish()]);
+  }
+};
+final.setDenoiser({type: 'custom', denoiser: copy, schedule: 'converged'});
+```
+
+The required `type` and `denoiser` choose this branch; `schedule` defaults to
+`converged`. Optional `prepare({device, width, height})` runs before the first
+inference and whenever the instance's last prepared device or dimensions
+change. It can preallocate resources. A shared instance switching between
+render sizes is prepared again. `DenoiseInput` contains these buffers:
+
+| Buffer | Data |
+| --- | --- |
+| `color` | Native resolved linear HDR ray color; before exposure, grading, tone mapping, vignette, bloom and display background/catcher composition |
+| `albedo` | Linear RGB albedo averaged over complete samples; alpha is primary-hit coverage |
+| `normal` | Resolved world-space normal averaged and encoded as `normal*.5+.5`, without renormalization; alpha 1 for valid surface data, otherwise zero RGBA |
+| `output` | Write all linear HDR RGB; output alpha is ignored and the input path coverage is preserved |
+
+All four are tightly packed RGBA float32, top row first, exactly
+`width * height * 16` bytes, with STORAGE, COPY_SRC and COPY_DST usages.
+Dimensions describe the actual internal image (WebGPU rounds up to 16).
+Input buffers are read-only. Buffers are borrowed until the promise settles;
+do not retain or destroy them. Resolve after submitting every output write;
+MuTracer copies the result, waits for GPU work, then releases its queue lease.
+Custom `readPixels('denoised')` returns the filtered native HDR ray color,
+with input path coverage. Display settings then follow the ordinary compose
+path: flat backgrounds retain their display-space treatment and catcher
+layers are combined after tone mapping. An identity filter preserves the
+unfiltered display, including bloom and partially transparent catchers.
+
+The resolved ray color uses native hit-count normalization; fully blank
+pixels use sample-count normalization. Flat primary misses can contribute
+background radiance, but this buffer has not yet undergone display background
+or catcher composition. `readPixels('hdr')` separately restores a per-sample
+average for mixed flat-background pixels, so do not assume it equals the
+custom input at those edges.
+
+Render and Engine never dispose the supplied instance. Its object identity
+selects it; identical assignment and schedule-only edits preserve running
+inference. One engine serializes preparation and denoising across all renders,
+so an instance can share resources between them. Sharing across separate
+engines needs caller-managed coordination.
+
+The context signal aborts on committed input changes, restart, replacement,
+Render/Engine disposal or cancellation of convergence. Results resolving after
+abort are discarded. The queue still waits for that promise to settle before
+lending shared buffers again, so respond promptly to abort. Current preparation
+and inference failures report through `engine.on('error', ...)`; stale jobs do
+not report obsolete failures. WebGL warns once per render and leaves it
+unfiltered.
+
+A recovered engine may provide a new `input.device`. Rebuild device-owned
+resources when it changes; `prepare` is called again. Dispose caller-owned
+resources yourself after outstanding work has settled.
+
+## Implementation notes
+
+### Custom HDR layers
+
+Custom filters operate on the resolved beauty RGB. With a shadow catcher, the
+filtered correction is carried over to the foreground and background layers;
+coverage and shadow masks are not filtered.
+
+### How JNLM works
+
+The weights follow Rousselle, Manzi and Zwicker, *Robust Denoising using
+Feature and Color Information* (2013). Each pixel starts with a weighted mean of
+its 11 × 11 neighborhood. A neighbor's weight is the smaller of:
+
+- a color weight: the distance between the two pixels' 3 × 3 patches,
+  normalized by their estimated variance, so differences explained by noise
+  are ignored;
+- a feature weight: the albedo, coverage and normal differences, which keep
+  texture and geometric edges.
+
+Albedo differences are measured relative to each channel's local brightness,
+with a small floor near black. This protects low-contrast dark textures as
+well as brighter ones. Coverage and encoded normals use absolute differences.
+
+The mean is corrected by a local linear fit between each RGB channel and its
+albedo channel, using the same weights. This preserves subtle texture while
+averaging lighting noise. A small regularizer stabilizes nearly constant
+guides, and the fitted response is bounded between zero and multiplicative
+albedo modulation. Constant albedo keeps the weighted mean; unrelated albedo
+does not automatically get transferred into the image. Alpha and the
+luminance matching guide retain their weighted-mean estimates.
+
+A second pass filters the result again with every other pixel (à-trous),
+which removes the blotches a single pass leaves at the scale of its window.
+
+The variance comes from per-pixel luminance moments that the path tracer
+accumulates alongside the color. Weights are computed in linear radiance and
+applied to the composed image, including its alpha, so shadow catchers and
+transparent backgrounds are filtered too. Pixels that show the background
+directly are left as rendered.
+
+While-converging intermediate denoise batches report `'converging'`. Only denoising the final image at `maxSamples` reports `'denoising'`; `'finished'` means that final image is ready.

package/docs/getting-started.md

@@ -0,0 +1,308 @@
+# Getting started
+
+## Concepts
+
+MuTracer renders a plain **scene description** with a **camera**:
+
+```ts
+interface Scene {
+  meshes: Mesh[];          // geometry + one OpenPBRMaterial per group
+  lights: SceneLight[];    // analytic lights, environment and ambient light
+  background?: ColorRGBA | Texture | GroundedSkyboxBackground;
+}
+```
+
+- `Mesh(geometry, material)` places a `Geometry` in the world with
+  `mesh.transform` (a column-major `mat4`, compatible with `gl-matrix`).
+- `Geometry` holds indexed or non-indexed triangle attributes. Use the helpers
+  `createPlaneGeometry`, `createCubeGeometry`, `createSphereGeometry` or build
+  one from arrays (see below).
+- Materials are `OpenPBRMaterial` instances. See [materials](./materials.md).
+- Units are arbitrary but consistent; light intensities are in radiometric
+  units relative to them.
+
+`Engine` commits scene and camera changes, `Render` accumulates samples, and
+`Display` presents an image. See [independent render results](./progressive-rendering.md).
+
+## A minimal render loop
+
+```ts
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { Engine, RenderLoop, THREESync } from '@meimu/mutracer';
+const engine = new Engine({canvas});
+engine.scene = scene;
+const camera = new THREE.PerspectiveCamera(40, 1, .1, 100);
+camera.position.set(0, 2, 6);
+const controls = new OrbitControls(camera, canvas);
+controls.target.set(0, 1, 0);
+const sync = new THREESync(engine, {camera, controls});
+const loop = new RenderLoop(engine, {sync, final: {maxSamples: 1024, bounces: 5}});
+function resize() {
+  const ratio = Math.min(devicePixelRatio, 2);
+  engine.display.setSize(canvas.clientWidth * ratio, canvas.clientHeight * ratio);
+  camera.aspect = canvas.clientWidth / canvas.clientHeight;
+  camera.updateProjectionMatrix();
+}
+window.addEventListener('resize', resize);
+resize(); loop.start();
+```
+
+RenderLoop synchronizes sources, commits changes and presents preview or final.
+Subscribe to `loop.on('status', ...)` for UI and `engine.on('progress', ...)`
+for preparation progress. Engine chooses WebGPU with WebGL 2 fallback.
+Preparation is automatic; see [BVH](./bvh.md) for optional CPU preparation.
+
+For custom frame control, use `loop.tick()` in your own animation frame instead
+of `start()`. For explicit rendering without the built-in policy, use
+[Engine / Render / Display directly](./progressive-rendering.md#explicit-frame-control).
+
+## Geometry from arrays
+
+```ts
+import { Geometry, GeometryAttribute } from '@meimu/mutracer';
+
+const geometry = new Geometry({
+  position: new GeometryAttribute(new Float32Array(positions), 3),
+  indices: new GeometryAttribute(new Uint32Array(indices), 1),
+  uv: new GeometryAttribute(new Float32Array(uvs), 2) // optional
+});
+```
+
+Only `position` is required. Omitting `indices` generates sequential indices; omitting `normal` generates smooth area-weighted normals. Read `geometry.vertexCount` and `geometry.triangleCount` for counts.
+
+For several materials on one geometry, pass an array of materials to `Mesh`
+and set `geometry.materialIndex` to an `Int32Array` attribute with `itemSize: 1` and one raw index
+into `mesh.materials` per vertex.
+
+Place nodes by assigning `node.position = [x, y, z]` and calling `node.lookAt(target, up?)`. `position` reads a copy; assign it back to move the node.
+
+## Cameras
+
+```ts
+const camera = new Camera({ projection: 'perspective', fov: 45, near: 0.1, far: 100 });
+camera.position = [0, 2, 6]; camera.lookAt([0, 0, 0]);
+```
+
+`camera.aspect` defaults to undefined, so rendering uses the canvas width/height.
+Explicitly set it to lock a perspective aspect ratio. `copy(source)` and `clone()`
+copy camera settings; `getProjectionMatrix(targetAspect = 1)` includes zoom.
+
+For orbit/pan/zoom, use Three.js OrbitControls with THREESync as above.
+`fromTHREECamera` remains available for one-shot camera conversion.
+
+### Depth of field
+
+Depth of field uses a thin lens described in photographic terms:
+
+```ts
+camera.fStop = 2.8;          // f-number; 0 (default) disables depth of field
+camera.focusDistance = 6;    // lens to focus plane, along the view direction
+camera.sensorHeight = 24;    // mm; with fov it sets the focal length
+camera.metersPerUnit = 1;    // scene unit length in metres (glTF: 1)
+```
+
+The focal length is `0.5 * sensorHeight * zoom / tan(fov / 2)` in millimetres
+(convert `fov` from degrees to radians). The aperture radius is
+`focalLength / (2 * fStop)` in millimetres, then divided by
+`1000 * metersPerUnit` to obtain scene units. A narrower field of view or a
+lower f-number blurs more, as on a real camera.
+
+`metersPerUnit` converts the lens size to scene units. When a scene is modelled
+in centimetres set it to `0.01`. For a miniature look, treat the scene as
+smaller than it is (`0.1` turns a 2 m object into a 20 cm one). Orthographic
+cameras have no depth of field.
+
+## Lights
+
+| Class | Constructor | Notes |
+| --- | --- | --- |
+| `RectLight` | `{ size?, color?, intensity?, texture?, spread? }` | One-sided, emits along local -Z |
+| `SphereLight` | `{ radius?, color?, intensity? }` | Spherical emitter; radius 0 is a point |
+| `SpotLight` | `{ color?, intensity?, radius?, innerAngle?, outerAngle?, iesProfile? }` | Cone, optional IES emission |
+| `DirectionalLight` | `{ color?, intensity? }` | Emits along local -Z |
+| `AmbientLight` | `{ color?, intensity? }` | Uniform environment radiance |
+| `EnvironmentLight` | `{ map }` | Equirectangular HDR illumination |
+
+Place analytic lights with `light.position = [x, y, z]` and `light.lookAt(target)`.
+Their transform scale is ignored; `size` and `radius` set emitter dimensions.
+Local +X is the IES azimuth reference; rotate the transform around local Z to
+orient a profile. Invalid mutable values are clamped and reported once without
+failing the render (through `error` events when attached).
+
+Load `.hdr` environments with `await loadRGBE(url)`, which resolves to a
+float `Texture`. Emissive materials (`emissionLuminance > 0`) also act as
+lights.
+
+## Backgrounds
+
+- omitted: camera rays show the environment light;
+- `[r, g, b, a]`: a linear color. `[0, 0, 0, 0]` gives a transparent canvas;
+  combine with `shadowCatcher` materials to composite over a web page;
+- a `Texture`: an equirectangular background independent of the lighting;
+- `{ type: 'GroundedSkybox', map, height, radius }`: projects the environment
+  onto a ground plane.
+
+## Updating the scene
+
+Keep the same scene and edit it in place. `engine.update()` detects property
+assignments, scene membership, transforms, materials, lights and backgrounds.
+In-place edits to array or image contents need a notification:
+
+```ts
+texture.markUpdated();                // texture pixels or UV-array elements
+
+geometry.markVerticesUpdated();       // vertex attributes only
+geometry.markUpdated();               // indices, materialIndex or other geometry data
+instancedMesh.markTransformsUpdated(); // instance matrix elements
+instancedMesh.markColorsUpdated();     // instance color elements
+instancedMesh.markUpdated();           // both instance matrices and colors
+```
+
+See [scene updates](./updates.md) for vertex animation and update costs. RenderLoop calls its syncs automatically. With explicit frame control, call `sync.update()` before engine.update;
+see [Three.js](./threejs.md).
+
+## Exporting an image
+
+For a final-quality still, use a render's deterministic convergence:
+
+```ts
+await loop.converge({samples: 1024, sampleSequenceOffset: 0});
+const blob = await engine.display.toBlob(loop.final);
+const hdr = await loop.final.readPixels('hdr');
+```
+
+Readback returns RGBA Float32Array values, top row first. A separate fixed-size
+Render can export another resolution or a copied camera override without
+changing the canvas. See [exporting](./progressive-rendering.md#reading-and-exporting).
+
+Call `loop.dispose()`, `sync.dispose()`, `controls.dispose()` and `engine.dispose()`
+when finished. See [ownership](./progressive-rendering.md#options-and-ownership).
+
+## Using your own GPUDevice
+
+```ts
+import { Engine, getRecommendedDeviceDescriptor } from '@meimu/mutracer';
+const adapter = await navigator.gpu.requestAdapter();
+if (!adapter) throw new Error('WebGPU unavailable');
+const device = await adapter.requestDevice(getRecommendedDeviceDescriptor(adapter));
+const engine = new Engine({ canvas, device });
+await engine.init();
+```
+
+The caller owns the device and releases it after all engines using it have been
+disposed. Supplying a device selects WebGPU; `backend: 'webgl'` is rejected.
+See [device requirements](./api.md#device-requirements) for limits and OIDN.
+
+## Running in a worker
+
+Transfer the display canvas once from the main thread:
+
+```ts
+const worker = new Worker(new URL('./render.worker.ts', import.meta.url), {type: 'module'});
+const offscreen = canvas.transferControlToOffscreen();
+worker.postMessage({canvas: offscreen, width: 800, height: 600}, [offscreen]);
+```
+
+In `render.worker.ts`, construct the scene and camera in the worker:
+
+```ts
+import {Engine, RenderLoop, Camera, Mesh, OpenPBRMaterial,
+  AmbientLight, createSphereGeometry} from '@meimu/mutracer';
+self.onmessage = ({data}) => {
+  const engine = new Engine({canvas: data.canvas});
+  engine.display.setSize(data.width, data.height);
+  engine.scene = {
+    meshes: [new Mesh(createSphereGeometry(), new OpenPBRMaterial())],
+    lights: [new AmbientLight({intensity: 1})],
+  };
+  engine.camera = new Camera({projection: 'perspective'});
+  engine.camera.position = [0, 0, 4]; engine.camera.lookAt([0, 0, 0]);
+  const loop = new RenderLoop(engine);
+  loop.start();
+  self.onmessage = ({data}) => {
+    if (data.type === 'stop') loop.stop();
+    if (data.type === 'start') loop.start();
+    if (data.type === 'resize') engine.display.setSize(data.width, data.height);
+    if (data.type === 'dispose') {loop.dispose(); engine.dispose();}
+  };
+};
+```
+
+Engine accepts HTMLCanvasElement or OffscreenCanvas. Without `document`, the
+omitted canvas defaults to a new OffscreenCanvas. Texture accepts ImageBitmap
+and OffscreenCanvas as well as HTML images/canvases and raw pixels. Export with
+`await engine.display.toBlob(render)` as on the main thread; offscreen displays
+use `convertToBlob`. Worker-created caller-owned GPUDevice instances use the
+same [host integration](#using-your-own-gpudevice) options.
+
+Workers have no page visibility event, so the loop keeps running until stopped.
+Forward visibility decisions from the main thread using stop/start messages.
+Without requestAnimationFrame, the loop uses a 16 ms timer. THREESync can
+synchronize a Three.js scene and camera in the worker; DOM-based controls
+remain on the main thread and their interaction/camera changes must be forwarded.
+
+BVH preparation creates nested workers when Worker is available. If startup or
+transport fails, it falls back to building in the calling thread (the render
+worker here). Asset URLs stay relative to the library/module, as on the main
+thread. Browser support for OffscreenCanvas and each GPU backend is required.
+
+## Loading and deployment
+
+With npm, import the public API as usual:
+
+```ts
+import { Engine, Render } from '@meimu/mutracer';
+
+const engine = new Engine({canvas});
+const render = new Render(engine);
+render.setDenoiser({type: 'oidn'});
+```
+
+MuTracer initializes OIDN and loads its model weights automatically when a
+render first prepares its OIDN denoiser on WebGPU. With code splitting enabled,
+its runtime code is also fetched only at that point; importing the package,
+initializing an engine, or using JNLM does not fetch it. Selecting
+`engine.bvhBuilder = 'tinybvh'` loads its WASM when a BVH is first built; the
+calling thread and BVH workers use the same asset URL. No separate runtime
+imports or asset-loading calls are needed. See [denoising](./denoising.md#hosting-the-weights)
+for model hosting.
+
+For the standalone UMD build, copy the entire `dist/` directory to your hosting
+location, keeping this layout:
+
+```text
+mutracer.umd.js
+assets/
+  bvh.worker.js
+```
+
+For example, after copying it to `/vendor/mutracer/`, load
+`/vendor/mutracer/mutracer.umd.js` in a script tag to use the `MuTracer` global.
+The BVH worker URL resolves relative to the library script.
+
+Standalone asset names are stable. Deploy the script and assets together; use
+a versioned directory or package-version URL when caching them for a long time.
+Application bundlers may give their own output assets hashed names.
+
+## Bundler notes
+
+The npm ESM entry preserves the dynamic import of the OIDN module. Vite and
+webpack builds with code splitting enabled emit it and its dependencies as an
+async chunk, fetched on first use. Configuring a single-file build or inlining
+dynamic imports can include that code in the main bundle instead; initialization
+is still deferred, but its download is no longer deferred.
+
+Vite development prebundles dependencies and can relocate asset URLs. Exclude
+MuTracer so the bundled OIDN standard/small weights and the optional TinyBVH
+wasm load from the package:
+
+```ts
+export default defineConfig({
+  optimizeDeps: { exclude: ['@meimu/mutracer'] }
+});
+```
+
+Vite production builds and webpack 5 copy these assets without extra
+configuration. With bundlers that do not support asset URLs, self-host the
+OIDN weights with `weightsBaseUrl` (see [denoising](./denoising.md#hosting-the-weights)).