API reference

Handwritten from source (packages/denoiser/src/{types,denoiser,index}.ts). Every default below is verified against the shipped implementation, not the type comments alone.

import { Denoiser } from 'denoiser';

Construction is async-only — the constructor is private. Denoiser.create() loads the default (color-only) model and creates the shared GPUDevice before resolving, so denoiser.device is available immediately after await. The default runtime is AutoRuntime: WebNN fp16 for base/large models when WebNN is available, the hand-written WGSL runtime otherwise. It never loads onnxruntime-web.

static async create(options?: DenoiserCreateOptions): Promise<Denoiser>

async denoise(color: ImgInput, options?: DenoiseImageOptions): Promise<ImageData | undefined>

Denoises an image-like input on the CPU-array path. Returns undefined only if abort() was called before the run resolved.

async denoiseToFloat(color: ImgInput, options?: DenoiseImageOptions): Promise<Float32Array | undefined>

Same as denoise(), but returns normalized [0,1] RGBA floats (ImageData bytes ÷ 255) instead of ImageData. Same options, same undefined-on-abort behavior. Internally calls denoise(), so it pays the same 8-bit quantization — use denoiseTextures if you need real float/HDR fidelity.

async denoiseTextures(options: DenoiseTexturesOptions): Promise<GPUTexture | undefined>

Zero-copy: float GPUTextures in, GPUTexture out, no CPU round-trip. Returns undefined only if abort() was called before the run resolved.

Returns your output texture if one was given; otherwise an engine-owned rgba8unorm texture valid only until the next call / a size change / dispose()/destroyDevice() — copy or sample it before calling again.

abort(): void

Marks the in-flight run so it resolves undefined instead of a result. Does not cancel GPU work already submitted — the work still completes, its result is just dropped. Typical use: drop a stale in-progress denoise when the camera/scene changed mid-run.

dispose(): void

Frees per-image GPU buffers and all but the default (first-created) model session/geometry. Keeps the shared device alive. Safe to call between unrelated workloads.

destroyDevice(): void

Full teardown: releases every session, including the last one — which destroys the shared GPUDevice. Anything else built on denoiser.device (a three.js renderer, canvas contexts, your own pipelines) dies with it. Only call this when the entire WebGPU stack is going away.

on(event: DenoiserEvent, callback: (value: unknown) => void): () => void

DenoiserEvent is 'progress' | 'executed'. Returns an unsubscribe function.

onProgress (and the 'progress' event) receive a 0–1 fraction. In tiled mode it's called once per batch of tiles as they complete (incremental progress). In whole-frame mode there is exactly one implicit batch, so it's called exactly once, near the end of the run, with 1 — not incrementally. Don't rely on it for a smooth progress bar on small/whole-frame images; it's meaningful for large tiled runs.

Returned by denoiser.stats — per-stage wall-clock timings (ms) from the most recently completed run:

Both extend Error with name set to match, so err.name or instanceof both work.

See Troubleshooting for the exact wording of each thrown/warned message and how to fix the underlying cause.

These are exported from the package (import { ... } from 'denoiser/ort', no longer from the root entry) but sit below Denoiser — most integrations never need them directly. Documented here for completeness; treat their shapes as more likely to change than the Denoiser surface above.

From denoiser/ort (no longer exported from the root denoiser entry; needs the optional onnxruntime-web peer dependency). Singleton .onnx model loader/cache the ORT runtime uses internally.

From denoiser/ort. The WebGPU/ONNX inference core of the ORT runtime (session management, tiling/geometry planning, WGSL pre/post). Denoiser covers everything most integrations need — reach for DenoiseEngine directly only if you're bypassing the high-level model-selection logic.

TextureInputs ({ color: GPUTexture; albedo?: GPUTexture; normal?: GPUTexture }) and TextureDenoiseOptions (DenoiseOptions + inputFlipY? + auxInputFlipY?

Denoiser and TiledEngine do all tiling, transfer functions and WGSL pre/post themselves; a NetworkRuntime only executes the U-Net. The default is AutoRuntime (WebNN fp16 for base/large models when available, hand-written WGSL otherwise; never ORT). Other runtimes (ORT, HF kernels, WebNN, WGSL) plug in through the same interface:

import { Denoiser } from 'denoiser';
import { OrtRuntime } from 'denoiser/ort'; // needs `npm i onnxruntime-web`

const denoiser = await Denoiser.create({
  runtime: new OrtRuntime({ weightsUrl: '/models' }), // or any NetworkRuntime
});

Entry points (one package, shared chunks, a single copy of the core):

The classes from denoiser and denoiser/core are the same. The interface is new in this release and may change, so pin your version if you implement it. See Choosing a runtime for measured speed and quality.

All runtimes except ORT read the upstream OIDN .tza weights. AutoRuntime (the default) delegates to WebnnRuntime and WgslRuntime.

tzaUrl defaults to DEFAULT_TZA_URL. device makes the runtime adopt your GPUDevice; without it, the runtime creates one with the adapter's maximum limits and features. OrtRuntime cannot adopt a device: it creates its own.

import { parseTZA, DEFAULT_TZA_URL } from 'denoiser/core';

const buf = await (await fetch(`${DEFAULT_TZA_URL}/rt_hdr_small.tza`)).arrayBuffer();
const tensors = parseTZA(buf); // TensorMap = Map<string, { data: Float32Array; shape: number[] }>

These exist for runtimes that read OIDN weights directly. You only need them if you write your own NetworkRuntime.

Exported from denoiser and denoiser/core; the FidelityFX implementations come from denoiser/ffx. See Real-time (temporal) denoising for the frame contract, conventions and measured results.

interface TemporalDenoiser<Inputs extends object = object> {
  readonly name: string;
  readonly device: GPUDevice;
  configure(config: TemporalConfig): void;
  dispatch(inputs: Inputs, guides: FrameGuides, camera: FrameCamera): GPUTexture;
  resetHistory(): void;
  readonly gpuTimings?: ReadonlyMap<string, number>;
  dispose(): void;
}

DiffuseInputs and BeautyInputs are defined for future denoisers; nothing implements them yet.

import { FfxShadowDenoiser, FfxReflectionDenoiser } from 'denoiser/ffx';

new FfxShadowDenoiser(device: GPUDevice, options?: FfxShadowDenoiserOptions);       // TemporalDenoiser<ShadowInputs>,   name 'ffx-shadows'
new FfxReflectionDenoiser(device: GPUDevice, options?: FfxReflectionDenoiserOptions); // TemporalDenoiser<SpecularInputs>, name 'ffx-reflections'

FfxReflectionDenoiser requires guides.roughness. The shadow dispatch returns an rgba16float texture whose .r is the denoised visibility.

function determineModel(selector: ModelSelector): { name: string; channels: number }

Resolves an OIDN model filename + channel count from a { filterType, quality, hdr, useColor, useAlbedo, useNormal, cleanAux, dirtyAux } selector (ModelSelector) — e.g. { filterType: 'rt', quality: 'fast', hdr: true, useColor: true, useAlbedo: true, useNormal: true, cleanAux: true, dirtyAux: false } → { name: 'rt_hdr_calb_cnrm_small', channels: 9 }. Denoiser calls this internally on every call to pick which model to run; exported for anyone building their own model-selection logic on DenoiseEngine directly.