D5 Gaussian Splat Library

基于 Three.js 的高性能 3D Gaussian Splatting 渲染库，支持实时渲染 3DGS 场景。

特性

• 支持 .ply 和 .splat 格式文件加载
• 基于 WASM 的高性能排序（支持 SIMD 加速）
• 支持球谐函数（Spherical Harmonics）实现视角相关颜色
• 内置 OrbitControls 相机控制
• 支持射线投射（Raycasting）进行场景交互
• GPU 加速距离计算
• 支持动态场景变换
• 场景淡入效果
• 支持多场景管理

安装

# 使用 yarn
yarn add @d5techs/d5-gaussian-splat-lib [email protected]

# 使用 npm
npm install @d5techs/d5-gaussian-splat-lib [email protected]

依赖要求

• [email protected]（peerDependency）

基础用法

1. 全托管模式

最简单的使用方式，库会自动创建渲染器、相机和控制器：

import { D5GaussianSplatLib } from "@d5techs/d5-gaussian-splat-lib";

// 创建渲染器实例
const viewer = new D5GaussianSplatLib({
  rootElement: document.getElementById("container"),
});

// 加载 3DGS 场景
await viewer.addSplatScene("path/to/model.ply");

// 启动渲染循环
viewer.start();

2. Three.js 混合开发模式

与现有 Three.js 项目集成，使用外部相机和渲染器：

import * as THREE from "three";
import { D5GaussianSplatLib } from "@d5techs/d5-gaussian-splat-lib";

// 创建 Three.js 场景
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();

// 创建 GS 渲染器，使用外部相机和渲染器
const viewer = new D5GaussianSplatLib({
  camera: camera,
  renderer: renderer,
  threeScene: scene,
  useBuiltInControls: false, // 使用自定义控制器
});

// 加载场景
await viewer.addSplatScene("path/to/model.ply", {
  position: [0, 0, 0],
  rotation: [0, 0, 0, 1],
  scale: [1, 1, 1],
});

viewer.start();

配置选项

构造函数选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | rootElement | HTMLElement | - | 渲染容器元素 | | camera | THREE.Camera | - | 外部相机（可选） | | renderer | THREE.WebGLRenderer | - | 外部渲染器（可选） | | threeScene | THREE.Scene | - | 外部场景（可选） | | useBuiltInControls | boolean | true | 是否使用内置控制器 | | initialCameraPosition | [number, number, number] | [0, 10, 15] | 初始相机位置 | | initialCameraLookAt | [number, number, number] | [0, 0, 0] | 初始相机朝向 | | sphericalHarmonicsDegree | number | 0 | 球谐函数阶数（0-3） | | antialiased | boolean | false | 是否启用抗锯齿 | | dynamicScene | boolean | false | 是否启用动态场景 | | enableSIMDInSort | boolean | true | 是否启用 SIMD 排序加速 | | sharedMemoryForWorkers | boolean | true | Worker 是否使用共享内存 | | logLevel | number | 0 | 日志级别 |

addSplatScene 选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | position | [number, number, number] | [0, 0, 0] | 场景位置 | | rotation | [number, number, number, number] | [0, 0, 0, 1] | 场景旋转（四元数） | | scale | [number, number, number] | [1, 1, 1] | 场景缩放 | | splatAlphaRemovalThreshold | number | 1 | Alpha 移除阈值 |

进度回调

const viewer = new D5GaussianSplatLib({
  rootElement: container,
  onProgress: (progress, label, status) => {
    // progress: 0-100
    // label: 进度文本
    // status: LoaderStatus.Downloading | LoaderStatus.Processing | LoaderStatus.Done
    console.log(`${label} - ${status}`);
  },
});

性能优化配置

const viewer = new D5GaussianSplatLib({
  rootElement: container,
  // 排序优化配置
  sortOptimization: {
    enabled: true,           // 是否启用排序优化
    minAngleDiff: 0.95,      // 最小角度差异阈值
    minPositionDiff: 2.0,    // 最小位置差异阈值（米）
    minTimeBetweenSorts: 100, // 最小排序间隔（毫秒）
  },
  // 中心计算配置
  centerCalculation: {
    useWeightedAverage: true, // 使用加权平均
    sampleRate: 1.0,          // 采样率
  },
});

交互功能

键盘快捷键

| 按键 | 功能 | |------|------| | F / G | 调整焦距 | | ← / → | 旋转相机 | | C | 切换网格光标 | | P | 切换点云模式 | | + / - | 调整 Splat 大小 |

鼠标交互

• 点击场景可聚焦到点击位置
• 支持 OrbitControls 标准交互（旋转、缩放、平移）

API

D5GaussianSplatLib

// 添加场景
await viewer.addSplatScene(path: string, options?: AddSplatSceneOptions): Promise<void>

// 启动渲染循环
viewer.start(): void

// 获取 SplatMesh
viewer.getSplatMesh(): SplatMesh

// 强制渲染下一帧
viewer.forceRenderNextFrame(): void

支持的文件格式

| 格式 | 扩展名 | 说明 | |------|--------|------| | PLY | .ply | 标准 PLY 格式，支持 3DGS 训练输出 | | Splat | .splat | 压缩的 Splat 格式 |

浏览器兼容性

• 需要 WebGL 2.0 支持
• 建议使用现代浏览器（Chrome 80+、Firefox 75+、Safari 15+、Edge 80+）
• 支持 SharedArrayBuffer 可获得更好性能

开发

# 安装依赖
yarn install

# 构建
yarn build

# 运行测试
yarn test

构建产物

构建后在 build 目录生成以下文件：

• d5-gaussian-splat-lib.module.js - ES Module 格式
• d5-gaussian-splat-lib.module.min.js - ES Module 压缩版
• d5-gaussian-splat-lib.umd.cjs - UMD 格式
• d5-gaussian-splat-lib.umd.min.cjs - UMD 压缩版

发布

详细发布流程请参考 publish.md

许可证

MIT