npm package: 3dgs-renderer-test
Description: A standalone 3D Gaussian Splatting renderer library using WebGPU
Latest version: 0.0.1

# 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
```

## 快速开始

### 配合 Three.js 使用

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

### 独立使用（无需 Three.js）

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

### 核心类

- `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 转换

## 渲染模式

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

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

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

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

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

## 许可证

MIT