mutracer README

项目的 README,来自 github.com/pissang/mutracer。合并为一个 markdown 文件:README.md。

MuTracer

npm version MIT license

MuTracer is a physically based path tracer for the web. It renders on WebGPU and falls back to WebGL 2, with OpenPBR materials, TinyBVH acceleration and denoising built in.

Try the viewer. MuTracer is a 0.x library; APIs may change between minor releases.

Rendered live in the browser. Click an image to open the scene in the viewer.

2025 Yamaha MT-09 SP V4
Yamaha MT-09 · metal and coat · VTX, CC-BY-NC-SA 4.0
Super Human
Super Human · subsurface skin · Davyd Vidiger, CC-BY 4.0
Gelatinous Cube
Gelatinous Cube · transmission · glenatron, CC-BY-NC 4.0
Crystal Lens
Crystal Lens · dispersion · Yi Shen, CC0
Blender Cover Remix
Blender Cover Remix · characters · bandinopla, CC-BY 4.0
OpenPBR material spheres
Material spheres · OpenPBR layers · procedural, CC0

Performance

LEGO Technic Bugatti Chiron rendered in MuTracer

The LEGO Technic Bugatti Chiron (VTX, CC-BY-NC-SA 4.0) is a heavy scene that path traces interactively in the viewer:

Bugatti Chiron
Rendered triangles 4.6 M (2.5 M unique, 341 geometries in 560 meshes)
Materials 35
Download 12.8 MB .glb
BVH build, 1 thread 1.7 s (built-in builder) / 1.0 s (TinyBVH WebAssembly)
BVH build, 4 workers (default) 0.50 s (built-in builder) / 0.28 s (TinyBVH WebAssembly)
1920 × 1080, 64 spp 12.1 s path tracing, 12.4 s with OIDN denoising

Measured on an Apple M4 Max: rendering in Chrome with WebGPU at the viewer's default settings (6 bounces), BVH builds on CPU threads excluding worker startup.

Install

npm install @meimu/mutracer

For the Three.js example, install three and import THREESync from @meimu/mutracer/three. TypeScript users of the adapter also need matching @types/three declarations. The MuTracer scene example uses gl-matrix for matrix math.

The package is ESM with TypeScript declarations (lib/main.js). A UMD build with a MuTracer global is at dist/mutracer.umd.js; deploy its dist/assets/ alongside it. See loading and deployment.

Quick start

With Three.js

Build or load a Three.js scene as usual and let THREESync keep MuTracer in sync with it. RenderLoop renders progressively and calls the sync each frame.

import * as THREE from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { Engine, RenderLoop } from '@meimu/mutracer';
import { THREESync } from '@meimu/mutracer/three';

const canvas = document.querySelector('canvas')!;

const scene = new THREE.Scene();
scene.add((await new GLTFLoader().loadAsync('model.glb')).scene);

const camera = new THREE.PerspectiveCamera(40, canvas.width / canvas.height, .1, 100);
camera.position.set(0, 2, 6);
const controls = new OrbitControls(camera, canvas);

const engine = new Engine({ canvas });
const sync = new THREESync(engine, { scene, camera, controls });
const loop = new RenderLoop(engine, { sync });
loop.start();

Custom Three.js materials and lights can use convertMaterial / convertLight in the same sync options; see Three.js integration.

With MuTracer scene classes

Describe meshes, materials, lights and the camera directly with MuTracer.

import { mat4 } from 'gl-matrix';
import {
  Camera, EnvironmentLight, Mesh, OpenPBRMaterial, RectLight, Engine, RenderLoop,
  Texture, createPlaneGeometry, createSphereGeometry, type Scene
} from '@meimu/mutracer';

const canvas = document.querySelector('canvas')!;

const red = new OpenPBRMaterial({ baseColor: [0.8, 0.1, 0.1], specularRoughness: 0.3 });

const ball = new Mesh(createSphereGeometry(64, 32), red);
mat4.fromTranslation(ball.transform, [0, 1, 0]);

const floor = new Mesh(createPlaneGeometry(), new OpenPBRMaterial());
mat4.fromScaling(floor.transform, [5, 1, 5]);

// Rect lights emit along their local -Z axis.
const light = new RectLight({ size: [2, 2], color: [1, 1, 1], intensity: 5 });
mat4.fromTranslation(light.transform, [0, 4, 0]);
mat4.rotateX(light.transform, light.transform, -Math.PI / 2);

// A constant grey sky as a 1x1 float environment map.
const sky = new Texture({ data: new Float32Array([0.3, 0.3, 0.3, 1]), width: 1, height: 1 });

const scene: Scene = {
  meshes: [ball, floor],
  lights: [light, new EnvironmentLight({ map: sky })]
};

const camera = new Camera({ projection: 'perspective', fov: 40, near: .1, far: 100 });
camera.position = [0, 2, 6];
camera.lookAt([0, 1, 0]);

const engine = new Engine({ canvas });
engine.on('error', error => console.error(error));
engine.scene = scene;
engine.camera = camera;
const loop = new RenderLoop(engine);
loop.start();

For many copies of one geometry, use InstancedMesh with shared materials and a Float32 matrix array. THREESync converts Three.js instancing into the same batches automatically. See the instancing example.

Rendering options

Enable denoising on an individual result:

loop.final.setDenoiser({ type: 'jnlm' }); // required type; call again to change it
loop.final.setDenoiser({ type: 'oidn', model: 'standard' }); // WebGPU; custom weightsUrl also supported
// Third-party WebGPU filters: { type: 'custom', denoiser: yourCallerOwnedDenoiser }.

Borrow WebGPU output with render.getOutputTexture('hdr') or render.getOutputTexture('display'), or add a display overlay through engine.display.addPostProcess(pass). Passes also run during PNG export; see the overlay example and texture lifetime.

Batch quality or display edits use Object.assign(loop.final, settings) or Object.assign(engine.display, settings), typed with RenderSettings or DisplaySettings; see the setting defaults.

RenderLoop provides preview and final results. For custom frame control, use Engine / Render / Display directly with a fallback, or a fixed-size invisible render for export. See independent render results.

Documentation

Guide Contents
Getting started Scene model, render loop, lights, export
Scene updates Editing a rendering scene, animation, update costs
API reference Engine, Display and Render options, methods and scene types
Materials OpenPBR inputs, textures, alpha, bevel, displacement
Three.js THREESync, supported materials and lights, userData keys
Denoising JNLM and OIDN denoisers, OIDN weights hosting, denoising while converging
Sampling Patterns, dimensions and progressive budgets
BVH BVH builders, TinyBVH layouts, worker preparation
Performance Tuning checklist
llms.txt Compact usage guide for coding agents

The examples cover a procedural scene, a Three.js/glTF scene and an OpenPBR gallery with denoising and PNG export. Run them with:

npm install
npm run dev

Browser support

The first frame compiles large shaders, which can take several seconds on some platforms; refine() reports the progress through its return status.

Contributing

Pull requests are not accepted at the moment; please open an issue instead. See CONTRIBUTING.md for development setup, required checks and GPU validation.

License

MuTracer is released under the MIT License. It includes third-party code and data under MIT, Apache-2.0 and CC0 licenses; see THIRD_PARTY_NOTICES.md.

For host WebGPU integration, supply your own GPUDevice.

Render on an OffscreenCanvas in a Worker with the worker integration guide.

mutracer (pissang/mutracer)

正在搜索数据库…

这是什么?MuTracer 是一个面向网页的基于物理的路径追踪渲染器:它使用 WebGPU 渲染场景(不支持时回退到 WebGL 2),支持 OpenPBR 材质、TinyBVH 加速和内置降噪。
这是独立的渲染器,还是可以嵌入的库?它是一个 JavaScript/TypeScript 库,你需要安装它并嵌入到网页中。它以 ESM 构建版本发布,附带 TypeScript 类型声明,另外还提供 UMD 打包文件,而不是独立应用。
我要怎样把它加到网页项目里?照常创建或加载一个 Three.js 场景,让 THREESync 使 MuTracer 与其保持同步,同时由 RenderLoop 每帧渐进式渲染;也可以直接用 MuTracer 自带的场景类描述网格、材质、灯光和相机。
使用它一定要装 Three.js 吗?不需要,MuTracer 有自己的场景模型;但如果你想加载 glTF 场景,或复用 Three.js 的材质和灯光,就需要 Three.js(用于 GLTFLoader + THREESync)和 gl-matrix(用于矩阵运算)。
这个 API 现在稳定吗?不稳定。它仍处于 1.0 之前的版本阶段,因此 API 可能会在次版本之间发生变化。
它必须依赖 WebGPU 吗?没有它能运行吗?推荐使用 WebGPU;OIDN 降噪和 HDR 输出等功能则必须依赖它。但在不支持 WebGPU 的浏览器上,它会自动回退到 WebGL 2(需要 EXT_color_buffer_float 扩展)。
什么是 OpenPBR,它在这里为什么重要?OpenPBR 1.1 是 MuTracer 实现的基于物理的表面模型,涵盖 F82 金属、各向异性 GGX 高光和涂层、薄膜干涉、带吸收的色散透射以及次表面散射,开箱即可获得精确的材质效果。
它能处理很重、面数很高的场景吗?可以。它使用分箱式 SAH 在多个并行 Worker 中构建两级 BVH(可使用 TinyBVH 的移植版本或其 WebAssembly 构建器),从而能够进行交互式路径追踪;在 Apple M4 Max 上,一个 460 万三角面的 Bugatti Chiron 模型以 1920x1080、64spp 渲染,大约需要 12 秒。
是否包含降噪功能?包含。它支持在 WebGPU 上使用 Intel Open Image Denoise 进行反照率和法线引导的降噪,也提供可同时在 WebGPU 和 WebGL 2 上运行的联合非局部均值滤波器。
我可以导出最终渲染结果吗?可以。converge() 会生成一帧确定性的、方差自适应的最终画面,支持色调映射(AgX、ACES、Cineon、Reinhard、线性)、调色、泛光、景深和透明背景,这些效果在导出 PNG 时同样生效。
作者
pissang
大小
46.1 MB
星标
189
时长
1个月
提交 · 90 天