@d5techs/3dgs-lib 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +316 -142
  2. package/dist/3dgs-lib.cjs +1442 -1976
  3. package/dist/3dgs-lib.cjs.map +1 -1
  4. package/dist/3dgs-lib.js +1443 -1977
  5. package/dist/3dgs-lib.js.map +1 -1
  6. package/dist/App.d.ts +1 -1
  7. package/dist/core/BoundingBoxRenderer.d.ts +3 -14
  8. package/dist/gs/GSSplatRenderer.d.ts +26 -176
  9. package/dist/gs/GSSplatRendererMobile.d.ts +8 -6
  10. package/dist/gs/GSSplatSorter.d.ts +41 -37
  11. package/dist/gs/IGSSplatRenderer.d.ts +10 -37
  12. package/dist/index.d.ts +9 -6
  13. package/dist/interaction/GizmoManager.d.ts +4 -41
  14. package/dist/loaders/GLBLoader.d.ts +3 -11
  15. package/dist/loaders/OBJLoader.d.ts +1 -1
  16. package/dist/mesh/Mesh.d.ts +6 -10
  17. package/dist/scene/SceneManager.d.ts +6 -6
  18. package/dist/scene/proxies/MeshGroupProxy.d.ts +20 -0
  19. package/dist/scene/proxies/SplatBoundingBoxProvider.d.ts +11 -0
  20. package/dist/scene/proxies/SplatTransformProxy.d.ts +17 -0
  21. package/dist/scene/proxies/index.d.ts +6 -0
  22. package/dist/types/geometry.d.ts +60 -0
  23. package/dist/types/index.d.ts +8 -0
  24. package/dist/types/material.d.ts +27 -0
  25. package/dist/types/splat.d.ts +25 -0
  26. package/dist/utils/device.d.ts +17 -0
  27. package/dist/utils/geometry.d.ts +26 -0
  28. package/dist/utils/index.d.ts +6 -0
  29. package/dist/utils/texture.d.ts +64 -0
  30. package/package.json +1 -1
package/README.md CHANGED
@@ -1,194 +1,205 @@
1
- # WebGPU 3D Gaussian Splatting 渲染引擎
1
+ # @d5techs/3dgs-lib
2
2
 
3
- 一个可扩展的 WebGPU 3D 渲染引擎，核心特性是支持 **3D Gaussian Splatting (3DGS)** 技术。
3
+ 可扩展的 WebGPU 3D 渲染引擎，核心特性是支持 **3D Gaussian Splatting (3DGS)** 技术。
4
4
 
5
5
  ![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue?logo=typescript)
6
6
  ![WebGPU](https://img.shields.io/badge/WebGPU-Supported-green)
7
7
  ![Vite](https://img.shields.io/badge/Vite-5.0-purple?logo=vite)
8
+ ![License](https://img.shields.io/badge/License-MIT-yellow)
8
9
 
9
10
  ## 功能特性
10
11
 
11
- - **WebGPU 高性能渲染** - 利用现代 GPU API 实现高效渲染
12
- - **3D Gaussian Splatting 支持**
13
- - PLY / Splat 文件加载
14
- - GPU 加速排序（基于 Radix Sort）
15
- - 球谐函数 (SH) 多级支持：L0 / L1 / L2 / L3
16
- - 移动端自动优化
17
- - **多格式模型加载**
18
- - GLB/GLTF 模型
19
- - OBJ/MTL 模型（支持材质和纹理）
20
- - **完整交互系统**
21
- - 轨道控制器 (OrbitControls)
22
- - 变换 Gizmo（平移/旋转/缩放）
23
- - 视口坐标轴指示器
24
- - 选中对象包围盒显示
25
- - **场景管理**
26
- - 多对象管理
27
- - 材质颜色编辑
28
- - 自动 Frame Model 功能
29
- - **移动端支持**
30
- - 触摸手势控制
31
- - 自动性能优化
32
- - 响应式 UI
33
-
34
- ## 文档
35
-
36
- 📖 **[完整使用手册](./USAGE_GUIDE.md)** - 详细的 API 文档和使用示例
12
+ ### 3D Gaussian Splatting
37
13
 
38
- ## 系统要求
14
+ - PLY / Splat 文件加载与解析
15
+ - GPU 加速排序（基于 Radix Sort Compute Shader）
16
+ - 球谐函数 (SH) 多级支持：L0 / L1 / L2 / L3
17
+ - 桌面端/移动端自适应渲染器
18
+ - Normalized Gaussian 抗锯齿
19
+ - ClipCorner 优化减少 overdraw
39
20
 
40
- ### 浏览器支持
21
+ ### 传统 3D 模型
41
22
 
42
- | 浏览器 | 最低版本 |
43
- |--------|----------|
44
- | Chrome | 113+ |
45
- | Edge | 113+ |
46
- | Safari | 17+ |
47
- | Firefox | 实验性支持 |
23
+ - GLB/GLTF 模型加载（支持 PBR 材质和纹理）
24
+ - OBJ/MTL 模型加载（支持材质和纹理）
25
+ - 自动计算 Bounding Box
48
26
 
49
- ### 其他要求
27
+ ### 交互系统
50
28
 
51
- - 需要在 **HTTPS** 或 **localhost** 环境下运行
52
- - Node.js 18+（用于开发构建）
29
+ - 轨道控制器 (OrbitControls) - 支持鼠标和触摸
30
+ - 变换 Gizmo - 平移/旋转/缩放三种模式
31
+ - 视口坐标轴指示器
32
+ - 选中对象包围盒显示
53
33
 
54
- ## 快速开始
34
+ ### 场景管理
55
35
 
56
- ### 安装
36
+ - 多对象管理
37
+ - 材质颜色编辑
38
+ - 自动 Frame Model 功能
39
+ - Splat 变换（位置/旋转/缩放）
57
40
 
58
- ```bash
59
- yarn install
60
- ```
41
+ ---
61
42
 
62
- ### 启动开发服务器
43
+ ## 系统要求
63
44
 
64
- ```bash
65
- yarn dev
66
- ```
45
+ ### 浏览器支持
46
+
47
+ | 浏览器 | 最低版本 | 备注 |
48
+ |--------|----------|------|
49
+ | Chrome | 113+ | 推荐 |
50
+ | Edge | 113+ | 推荐 |
51
+ | Safari | 17+ | macOS/iOS |
52
+ | Firefox | Nightly | 实验性支持 |
53
+
54
+ ### 运行环境
67
55
 
68
- 访问 `https://localhost:3000` 查看 Demo。
56
+ - **HTTPS** 或 **localhost**（WebGPU 安全要求）
57
+ - Node.js 18+（仅开发构建需要）
69
58
 
70
- ### 构建
59
+ ---
60
+
61
+ ## 快速开始
62
+
63
+ ### 安装
71
64
 
72
65
  ```bash
73
- # 构建 Demo
74
- yarn build:demo
66
+ # yarn
67
+ yarn add @d5techs/3dgs-lib
75
68
 
76
- # 构建库（类型检查）
77
- yarn build:lib
69
+ # npm
70
+ npm install @d5techs/3dgs-lib
71
+
72
+ # pnpm
73
+ pnpm add @d5techs/3dgs-lib
78
74
  ```
79
75
 
80
- ## 基本用法
76
+ ### 基本用法
81
77
 
82
78
  ```typescript
83
- import { App } from 'webgpu-3dgs';
79
+ import { App } from '@d5techs/3dgs-lib';
84
80
 
85
- // 创建应用
81
+ // 1. 创建应用
86
82
  const canvas = document.getElementById('canvas') as HTMLCanvasElement;
87
83
  const app = new App(canvas);
88
84
 
89
- // 初始化
85
+ // 2. 初始化（异步）
90
86
  await app.init();
91
87
 
92
- // 加载 3D Gaussian Splatting 模型
88
+ // 3. 加载模型
89
+ // 3DGS 模型
93
90
  await app.addPLY('model.ply', (progress, stage) => {
94
91
  console.log(`${stage}: ${progress.toFixed(1)}%`);
95
92
  });
96
93
 
97
- // 或加载传统 3D 模型
94
+ // 或传统 3D 模型
98
95
  await app.addGLB('model.glb');
99
96
  await app.addOBJ('model.obj');
100
97
 
101
- // 自动调整相机
98
+ // 4. 自动调整相机视角
102
99
  app.frameCurrentModel();
103
100
 
104
- // 启动渲染
101
+ // 5. 启动渲染循环
105
102
  app.start();
106
103
  ```
107
104
 
108
- ## 项目结构
109
-
110
- ```
111
- webgpu-3dgs/
112
- ├── src/ # 引擎源代码
113
- │ ├── index.ts # 库入口
114
- │ ├── App.ts # 统一调度入口
115
- │ ├── core/ # 核心模块
116
- │ │ ├── Renderer.ts # WebGPU 渲染器
117
- │ │ ├── Camera.ts # 相机
118
- │ │ ├── OrbitControls.ts # 轨道控制器
119
- │ │ ├── ViewportGizmo.ts # 视口 Gizmo
120
- │ │ ├── BoundingBoxRenderer.ts # 包围盒渲染
121
- │ │ ├── gizmo/ # 变换 Gizmo
122
- │ │ └── math/ # 数学工具
123
- │ ├── gs/ # 3D Gaussian Splatting
124
- │ │ ├── GSSplatRenderer.ts # 桌面端渲染器
125
- │ │ ├── GSSplatRendererMobile.ts # 移动端渲染器
126
- │ │ ├── GSSplatSorter.ts # GPU 排序器
127
- │ │ ├── PLYLoader.ts # PLY 加载器
128
- │ │ ├── SplatLoader.ts # Splat 加载器
129
- │ │ └── *.wgsl # WGSL 着色器
130
- │ ├── mesh/ # 网格渲染
131
- │ ├── loaders/ # 模型加载器
132
- │ ├── scene/ # 场景管理
133
- │ └── interaction/ # 交互管理
134
- ├── demo/ # Demo 应用
135
- ├── USAGE_GUIDE.md # 使用手册
136
- └── package.json
105
+ ### HTML 设置
106
+
107
+ ```html
108
+ <!DOCTYPE html>
109
+ <html>
110
+ <head>
111
+ <style>
112
+ body { margin: 0; overflow: hidden; }
113
+ canvas { width: 100vw; height: 100vh; display: block; }
114
+ </style>
115
+ </head>
116
+ <body>
117
+ <canvas id="canvas"></canvas>
118
+ <script type="module" src="./main.ts"></script>
119
+ </body>
120
+ </html>
137
121
  ```
138
122
 
123
+ ---
124
+
139
125
  ## 核心 API
140
126
 
141
127
  ### App 类
142
128
 
129
+ 主入口类，提供完整的应用生命周期管理。
130
+
143
131
  ```typescript
144
- // 初始化
145
- await app.init();
146
- app.start();
147
- app.stop();
148
- app.destroy();
132
+ const app = new App(canvas);
133
+
134
+ // 生命周期
135
+ await app.init(); // 初始化 WebGPU
136
+ app.start(); // 开始渲染循环
137
+ app.stop(); // 停止渲染循环
138
+ app.destroy(); // 销毁所有资源
149
139
 
150
140
  // 模型加载
151
- await app.addPLY(url, onProgress?);
152
- await app.addSplat(url, onProgress?);
153
- await app.addGLB(url);
154
- await app.addOBJ(url);
141
+ await app.addPLY(url, onProgress?); // 加载 PLY (3DGS)
142
+ await app.addSplat(url, onProgress?); // 加载 Splat (3DGS)
143
+ await app.addGLB(url); // 加载 GLB
144
+ await app.addOBJ(url); // 加载 OBJ
145
+
146
+ // 场景查询
147
+ app.getMeshCount(); // Mesh 数量
148
+ app.getSplatCount(); // Splat 数量
149
+ app.getSplatBoundingBox(); // Splat 包围盒
150
+
151
+ // 场景操作
152
+ app.clearMeshes(); // 清空所有 Mesh
153
+ app.clearSplats(); // 清空 Splat
154
+
155
+ // Splat 变换
156
+ app.setSplatPosition(x, y, z);
157
+ app.setSplatRotation(x, y, z); // 弧度
158
+ app.setSplatScale(x, y, z);
159
+
160
+ // SH 模式 (球谐函数级别)
161
+ app.setSHMode(0); // L0 - 仅 DC 颜色
162
+ app.setSHMode(1); // L1 - DC + 一阶 SH
163
+ app.setSHMode(2); // L2 - DC + 一二阶 SH
164
+ app.setSHMode(3); // L3 - 完整 SH
155
165
 
156
- // 场景管理
157
- app.getMeshCount();
158
- app.getSplatCount();
159
- app.clearMeshes();
160
- app.clearSplats();
166
+ // 相机控制
167
+ app.frameCurrentModel(animate?); // 自动调整视角
168
+ app.getCamera(); // 获取相机实例
169
+ app.getControls(); // 获取控制器实例
170
+
171
+ // Gizmo 控制
172
+ app.setGizmoMode('translate'); // 平移模式
173
+ app.setGizmoMode('rotate'); // 旋转模式
174
+ app.setGizmoMode('scale'); // 缩放模式
175
+ app.setGizmoTarget(object); // 设置操作目标
176
+
177
+ // 子系统访问
178
+ app.getRenderer(); // WebGPU 渲染器
179
+ app.getMeshRenderer(); // Mesh 渲染器
180
+ app.getGSRenderer(); // 3DGS 渲染器
181
+ ```
161
182
 
162
- // SH 模式 (0-3)
163
- app.setSHMode(mode);
164
- app.getSHMode();
183
+ ### 进度回调
165
184
 
166
- // 相机控制
167
- app.frameCurrentModel(animate?);
168
- app.getCamera();
169
- app.getControls();
185
+ ```typescript
186
+ type ProgressCallback = (
187
+ progress: number, // 0-100
188
+ stage: 'download' | 'parse' | 'upload'
189
+ ) => void;
170
190
 
171
- // Gizmo
172
- app.setGizmoMode(mode);
173
- app.setGizmoTarget(object);
191
+ await app.addPLY('model.ply', (progress, stage) => {
192
+ if (stage === 'download') {
193
+ console.log(`下载中: ${progress.toFixed(1)}%`);
194
+ } else if (stage === 'parse') {
195
+ console.log(`解析中: ${progress.toFixed(1)}%`);
196
+ } else {
197
+ console.log(`上传 GPU: ${progress.toFixed(1)}%`);
198
+ }
199
+ });
174
200
  ```
175
201
 
176
- ### 导出类
177
-
178
- | 类名 | 说明 |
179
- |------|------|
180
- | `App` | 统一调度入口 |
181
- | `Renderer` | WebGPU 渲染器 |
182
- | `Camera` | 透视相机 |
183
- | `OrbitControls` | 轨道控制器 |
184
- | `Mesh` | 网格数据结构 |
185
- | `MeshRenderer` | 网格渲染器 |
186
- | `GSSplatRenderer` | 3DGS 渲染器 |
187
- | `GLBLoader` | GLB 加载器 |
188
- | `OBJLoader` | OBJ 加载器 |
189
- | `TransformGizmoV2` | 变换 Gizmo |
190
- | `ViewportGizmo` | 视口 Gizmo |
191
- | `SceneManager` | 场景管理器 |
202
+ ---
192
203
 
193
204
  ## 交互控制
194
205
 
@@ -200,7 +211,7 @@ app.setGizmoTarget(object);
200
211
  | 右键拖拽 | 平移视角 |
201
212
  | 滚轮 | 缩放 |
202
213
 
203
- ### 触摸
214
+ ### 触摸（移动端）
204
215
 
205
216
  | 操作 | 功能 |
206
217
  |------|------|
@@ -208,29 +219,192 @@ app.setGizmoTarget(object);
208
219
  | 双指捏合 | 缩放 |
209
220
  | 双指拖拽 | 平移视角 |
210
221
 
211
- ### 键盘
222
+ ### 键盘快捷键
212
223
 
213
224
  | 按键 | 功能 |
214
225
  |------|------|
215
- | W | 平移模式 |
216
- | E | 旋转模式 |
217
- | R | 缩放模式 |
226
+ | W | 切换到平移模式 |
227
+ | E | 切换到旋转模式 |
228
+ | R | 切换到缩放模式 |
229
+
230
+ ---
231
+
232
+ ## 项目架构
233
+
234
+ ```
235
+ @d5techs/3dgs-lib/
236
+ ├── src/
237
+ │ ├── index.ts # 库入口，导出所有公共 API
238
+ │ ├── App.ts # 统一调度入口
239
+ │ │
240
+ │ ├── types/ # 统一类型定义
241
+ │ │ ├── geometry.ts # BoundingBox, Vec3Tuple, Transform
242
+ │ │ ├── material.ts # MaterialData
243
+ │ │ └── splat.ts # SHMode, RendererCapabilities
244
+ │ │
245
+ │ ├── utils/ # 公共工具函数
246
+ │ │ ├── device.ts # 设备检测 (isMobileDevice)
247
+ │ │ ├── geometry.ts # 几何计算 (computeBoundingBox)
248
+ │ │ └── texture.ts # 纹理加载工具
249
+ │ │
250
+ │ ├── core/ # 核心渲染模块
251
+ │ │ ├── Renderer.ts # WebGPU 渲染器
252
+ │ │ ├── Camera.ts # 透视相机
253
+ │ │ ├── OrbitControls.ts # 轨道控制器
254
+ │ │ ├── ViewportGizmo.ts # 视口坐标轴
255
+ │ │ ├── BoundingBoxRenderer.ts
256
+ │ │ ├── gizmo/ # 变换 Gizmo 组件
257
+ │ │ └── math/ # 数学库 (Vec3, Mat4, Quat, Ray)
258
+ │ │
259
+ │ ├── gs/ # 3D Gaussian Splatting
260
+ │ │ ├── IGSSplatRenderer.ts # 渲染器接口
261
+ │ │ ├── GSSplatRenderer.ts # 桌面端渲染器
262
+ │ │ ├── GSSplatRendererMobile.ts # 移动端渲染器
263
+ │ │ ├── GSSplatSorter.ts # GPU 排序器
264
+ │ │ ├── PLYLoader.ts # PLY 加载器
265
+ │ │ └── SplatLoader.ts # Splat 加载器
266
+ │ │
267
+ │ ├── mesh/ # 网格渲染
268
+ │ │ ├── Mesh.ts # 网格数据结构
269
+ │ │ └── MeshRenderer.ts # 网格渲染器
270
+ │ │
271
+ │ ├── loaders/ # 模型加载器
272
+ │ │ ├── GLBLoader.ts # GLB/GLTF 加载
273
+ │ │ ├── OBJLoader.ts # OBJ 加载
274
+ │ │ ├── OBJParser.ts # OBJ 解析
275
+ │ │ └── MTLParser.ts # MTL 材质解析
276
+ │ │
277
+ │ ├── scene/ # 场景管理
278
+ │ │ ├── SceneManager.ts # 场景管理器
279
+ │ │ └── proxies/ # 变换代理类
280
+ │ │
281
+ │ └── interaction/ # 交互管理
282
+ │ └── GizmoManager.ts # Gizmo 管理器
283
+ │
284
+ ├── demo/ # Demo 应用
285
+ │ ├── index.html
286
+ │ └── main.ts
287
+ │
288
+ └── dist/ # 构建输出
289
+ ├── 3dgs-lib.js # ESM
290
+ ├── 3dgs-lib.cjs # CommonJS
291
+ └── index.d.ts # 类型声明
292
+ ```
293
+
294
+ ---
295
+
296
+ ## 高级用法
297
+
298
+ ### 自定义渲染器颜色
299
+
300
+ ```typescript
301
+ const renderer = app.getRenderer();
302
+ renderer.setClearColor(0.1, 0.1, 0.1); // RGB
303
+ renderer.setClearColorHex('#1a1a2e'); // Hex
304
+ ```
305
+
306
+ ### 访问底层相机
307
+
308
+ ```typescript
309
+ const camera = app.getCamera();
310
+ camera.fov = 60; // 视场角
311
+ camera.near = 0.1; // 近裁剪面
312
+ camera.far = 1000; // 远裁剪面
313
+ camera.setPosition(0, 5, 10); // 相机位置
314
+ camera.lookAt(0, 0, 0); // 看向目标
315
+ ```
316
+
317
+ ### 配置轨道控制器
318
+
319
+ ```typescript
320
+ const controls = app.getControls();
321
+ controls.minDistance = 1; // 最小距离
322
+ controls.maxDistance = 100; // 最大距离
323
+ controls.enableDamping = true; // 启用阻尼
324
+ controls.dampingFactor = 0.1; // 阻尼系数
325
+ ```
326
+
327
+ ### 使用 Gizmo 变换对象
328
+
329
+ ```typescript
330
+ import { GizmoMode } from '@d5techs/3dgs-lib';
331
+
332
+ // 获取 Splat 变换代理
333
+ const proxy = app.getSplatTransformProxy();
334
+ if (proxy) {
335
+ app.setGizmoTarget(proxy);
336
+ app.setGizmoMode(GizmoMode.Translate);
337
+
338
+ // 设置包围盒显示
339
+ const bbProvider = app.createSplatBoundingBoxProvider();
340
+ app.setSelectionBoundingBoxProvider(bbProvider);
341
+ }
342
+ ```
343
+
344
+ ### 检测 WebGPU 支持
345
+
346
+ ```typescript
347
+ import { isWebGPUSupported } from '@d5techs/3dgs-lib';
348
+
349
+ if (!isWebGPUSupported()) {
350
+ alert('您的浏览器不支持 WebGPU');
351
+ }
352
+ ```
353
+
354
+ ---
355
+
356
+ ## 开发
357
+
358
+ ```bash
359
+ # 安装依赖
360
+ yarn install
361
+
362
+ # 启动开发服务器
363
+ yarn dev
364
+
365
+ # 构建库
366
+ yarn build:lib
367
+
368
+ # 构建 Demo
369
+ yarn build:demo
370
+
371
+ # 运行测试
372
+ yarn test
373
+ ```
374
+
375
+ ---
218
376
 
219
377
  ## 技术细节
220
378
 
221
- ### 3D Gaussian Splatting
379
+ ### 3D Gaussian Splatting 渲染管线
222
380
 
223
- - **排序**: GPU Radix Sort (Compute Shader)
224
- - **渲染**: 基于 Quad 的 2D 高斯椭圆投影
225
- - **协方差**: 3D → 2D 屏幕空间投影
226
- - **球谐函数**: 0-3 阶 SH 系数，视角相关颜色
381
+ 1. **数据加载**: PLY/Splat → CPU 解析 → GPU Buffer
382
+ 2. **视锥剔除**: Compute Shader 剔除不可见 Splat
383
+ 3. **深度排序**: GPU Radix Sort 按深度排序
384
+ 4. **渲染**: 实例化渲染 Quad，2D 高斯椭圆投影
227
385
 
228
- ### 着色器
386
+ ### 着色器技术
229
387
 
230
388
  - WGSL (WebGPU Shading Language)
389
+ - Normalized Gaussian 消除边缘雾化
231
390
  - 多 SH 级别优化变体
232
391
  - GPU 排序 Compute Shader
233
392
 
393
+ ### 内存优化
394
+
395
+ - 桌面端: 256 bytes/splat（完整 SH）
396
+ - 移动端: ~52 bytes/splat（纹理压缩）
397
+
398
+ ---
399
+
234
400
  ## 许可证
235
401
 
236
402
  MIT License
403
+
404
+ ---
405
+
406
+ ## 相关链接
407
+
408
+ - [3D Gaussian Splatting 论文](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/)
409
+ - [WebGPU 规范](https://www.w3.org/TR/webgpu/)
410
+ - [WGSL 规范](https://www.w3.org/TR/WGSL/)