3dgs-renderer

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

特性

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

安装

npm install 3dgs-renderer three gl-matrix

快速开始

配合 Three.js 使用

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();

独立使用（无需 Three.js）

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 参考

核心类

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

相机

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

输入/输出

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

工具函数

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

渲染模式

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

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

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

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

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

许可证

MIT