3dgs-renderer

基于 WebGPU 的独立 3D 高斯泼溅渲染库。

特性

- 纯 WebGPU 渲染（无 WebGL 回退）
- 通过 CameraAdapter 集成 Three.js 相机
- 提供独立的 PerspectiveCamera，无需依赖 Three.js
- 支持 PLY 文件加载，带 FP16 优化
- GPU 加速基数排序，实现从后到前渲染
- 球谐函数计算（0-3 阶）
- Mip-splatting 抗锯齿

安装

``bash
npm install 3dgs-renderer three gl-matrix
`

快速开始

$3

`typescript
import * as THREE from "three";
import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
import {
requestWebGPU,
PLYLoader,
PointCloud,
GaussianRenderer,
CameraAdapter,
} from "3dgs-renderer";

async function main() {
const canvas = document.getElementById("canvas") as HTMLCanvasElement;

// 初始化 WebGPU
const { device, format } = await requestWebGPU();

// 配置画布
const context = canvas.getContext("webgpu")!;
context.configure({ device, format, alphaMode: "premultiplied" });

// 加载 PLY 文件
const response = await fetch("model.ply");
const buffer = await response.arrayBuffer();
const loader = new PLYLoader();
const gaussianData = await loader.loadBuffer(buffer);

// 创建点云
const pointCloud = new PointCloud(device, gaussianData);

// 创建渲染器
const renderer = new GaussianRenderer({
device,
format,
shDegree: gaussianData.shDegree(),
});
await renderer.initialize();

// 设置 Three.js 相机
const camera = new THREE.PerspectiveCamera(
60,
canvas.width / canvas.height,
0.1,
1000
);
camera.position.set(0, 0, 5);

const controls = new OrbitControls(camera, canvas);

// WebGPU 相机适配器
const cameraAdapter = new CameraAdapter();

// 渲染循环
function render() {
requestAnimationFrame(render);
controls.update();

const viewport: [number, number] = [canvas.width, canvas.height];
cameraAdapter.update(camera, viewport);

const encoder = device.createCommandEncoder();

// 准备阶段（预处理 + 排序）
renderer.prepare(encoder, device.queue, pointCloud, {
cameraAdapter,
viewport,
});

// 渲染
const textureView = context.getCurrentTexture().createView();
const renderPass = encoder.beginRenderPass({
colorAttachments: [
{
view: textureView,
clearValue: { r: 0, g: 0, b: 0, a: 1 },
loadOp: "clear",
storeOp: "store",
},
],
});
renderer.render(renderPass, pointCloud);
renderPass.end();

device.queue.submit([encoder.finish()]);
}

render();
}

main();
`

$3

`typescript
import {
requestWebGPU,
PLYLoader,
PointCloud,
GaussianRenderer,
PerspectiveCamera,
} from "3dgs-renderer";

async function main() {
const canvas = document.getElementById("canvas") as HTMLCanvasElement;

// 初始化 WebGPU
const { device, format } = await requestWebGPU();

// 配置画布
const context = canvas.getContext("webgpu")!;
context.configure({ device, format, alphaMode: "premultiplied" });

// 加载 PLY 文件
const loader = new PLYLoader();
const gaussianData = await loader.loadUrl("model.ply");

// 创建点云
const pointCloud = new PointCloud(device, gaussianData);

// 创建渲染器
const renderer = new GaussianRenderer({
device,
format,
shDegree: gaussianData.shDegree(),
});
await renderer.initialize();

// 创建独立相机
const camera = new PerspectiveCamera(
[0, 0, 5], // 位置
[0, 0, 0], // 目标点
[0, 1, 0] // 上方向
);
camera.setAspect(canvas.width / canvas.height);

// 渲染循环
function render() {
requestAnimationFrame(render);

const viewport: [number, number] = [canvas.width, canvas.height];

const encoder = device.createCommandEncoder();

// 准备阶段（预处理 + 排序）
renderer.prepare(encoder, device.queue, pointCloud, {
camera,
viewport,
});

// 渲染
const textureView = context.getCurrentTexture().createView();
const renderPass = encoder.beginRenderPass({
colorAttachments: [
{
view: textureView,
clearValue: { r: 0, g: 0, b: 0, a: 1 },
loadOp: "clear",
storeOp: "store",
},
],
});
renderer.render(renderPass, pointCloud);
renderPass.end();

device.queue.submit([encoder.finish()]);
}

render();
}

main();
`

API 参考

$3

- GaussianRenderer - 主渲染管线
- GaussianPreprocessor - GPU 预处理（变换、球谐计算、剔除）
- PointCloud - 高斯数据的 GPU 缓冲区管理
- RadixSorter - GPU 基数排序，用于深度排序

$3

- CameraAdapter - Three.js 到 WebGPU 的相机转换
- PerspectiveCamera - 独立透视相机

$3

- PLYLoader - 加载 3DGS PLY 文件
- GaussianData - 内存中的高斯数据容器

$3

- requestWebGPU() - 初始化 WebGPU 设备
- createBuffer() - 创建 GPU 缓冲区
- f32_to_f16() / f16_to_f32() - FP16 转换

渲染模式

渲染器支持多种渲染模式：

`typescript
import { RenderMode } from "3dgs-renderer";

// 颜色模式（默认）- 基于视角的球谐颜色
pointCloud.setRenderMode(RenderMode.Color);

// 法线模式 - 可视化表面法线
pointCloud.setRenderMode(RenderMode.Normal);

// 深度模式 - 可视化深度
pointCloud.setRenderMode(RenderMode.Depth);
``

许可证

MIT