@d5techs/3dgs-lib 1.0.1 → 1.1.1

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 (38) hide show
  1. package/README.md +311 -136
  2. package/dist/3dgs-lib.cjs +4215 -2150
  3. package/dist/3dgs-lib.cjs.map +1 -1
  4. package/dist/3dgs-lib.js +4216 -2151
  5. package/dist/3dgs-lib.js.map +1 -1
  6. package/dist/App.d.ts +28 -7
  7. package/dist/core/BoundingBoxRenderer.d.ts +2 -15
  8. package/dist/core/OrbitControls.d.ts +21 -41
  9. package/dist/core/gizmo/{TransformGizmoV2.d.ts → TransformGizmo.d.ts} +2 -2
  10. package/dist/core/{ViewportGizmo.d.ts → gizmo/ViewportGizmo.d.ts} +2 -2
  11. package/dist/core/gizmo/index.d.ts +3 -2
  12. package/dist/core/index.d.ts +7 -0
  13. package/dist/gs/GSSplatRenderer.d.ts +68 -172
  14. package/dist/gs/GSSplatRendererMobile.d.ts +9 -6
  15. package/dist/gs/GSSplatSorter.d.ts +44 -37
  16. package/dist/gs/IGSSplatRenderer.d.ts +39 -37
  17. package/dist/gs/SOGLoader.d.ts +25 -0
  18. package/dist/index.d.ts +17 -13
  19. package/dist/interaction/GizmoManager.d.ts +9 -46
  20. package/dist/interaction/HotspotManager.d.ts +142 -0
  21. package/dist/loaders/GLBLoader.d.ts +3 -11
  22. package/dist/loaders/OBJLoader.d.ts +1 -1
  23. package/dist/mesh/Mesh.d.ts +8 -16
  24. package/dist/mesh/MeshRenderer.d.ts +30 -14
  25. package/dist/scene/SceneManager.d.ts +12 -6
  26. package/dist/scene/proxies/MeshGroupProxy.d.ts +20 -0
  27. package/dist/scene/proxies/SplatBoundingBoxProvider.d.ts +11 -0
  28. package/dist/scene/proxies/SplatTransformProxy.d.ts +17 -0
  29. package/dist/scene/proxies/index.d.ts +6 -0
  30. package/dist/types/geometry.d.ts +60 -0
  31. package/dist/types/index.d.ts +8 -0
  32. package/dist/types/material.d.ts +27 -0
  33. package/dist/types/splat.d.ts +25 -0
  34. package/dist/utils/device.d.ts +17 -0
  35. package/dist/utils/geometry.d.ts +26 -0
  36. package/dist/utils/index.d.ts +6 -0
  37. package/dist/utils/texture.d.ts +64 -0
  38. package/package.json +4 -1
package/README.md CHANGED
@@ -5,189 +5,201 @@
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
13
+
14
+ - PLY / Splat 文件加载与解析
15
+ - GPU 加速排序（基于 Radix Sort Compute Shader）
16
+ - 球谐函数 (SH) 多级支持：L0 / L1 / L2 / L3
17
+ - 桌面端/移动端自适应渲染器
18
+ - Normalized Gaussian 抗锯齿
19
+ - ClipCorner 优化减少 overdraw
20
+
21
+ ### 传统 3D 模型
22
+
23
+ - GLB/GLTF 模型加载（支持 PBR 材质和纹理）
24
+ - OBJ/MTL 模型加载（支持材质和纹理）
25
+ - 自动计算 Bounding Box
26
+
27
+ ### 交互系统
28
+
29
+ - 轨道控制器 (OrbitControls) - 支持鼠标和触摸
30
+ - 变换 Gizmo - 平移/旋转/缩放三种模式
31
+ - 视口坐标轴指示器
32
+ - 选中对象包围盒显示
33
+
34
+ ### 场景管理
35
+
36
+ - 多对象管理
37
+ - 材质颜色编辑
38
+ - 自动 Frame Model 功能
39
+ - Splat 变换（位置/旋转/缩放）
40
+
41
+ ---
37
42
 
38
43
  ## 系统要求
39
44
 
40
45
  ### 浏览器支持
41
46
 
42
- | 浏览器 | 最低版本 |
43
- |--------|----------|
44
- | Chrome | 113+ |
45
- | Edge | 113+ |
46
- | Safari | 17+ |
47
- | Firefox | 实验性支持 |
47
+ | 浏览器 | 最低版本 | 备注 |
48
+ |--------|----------|------|
49
+ | Chrome | 113+ | 推荐 |
50
+ | Edge | 113+ | 推荐 |
51
+ | Safari | 17+ | macOS/iOS |
52
+ | Firefox | Nightly | 实验性支持 |
48
53
 
49
- ### 其他要求
54
+ ### 运行环境
50
55
 
51
- - 需要在 **HTTPS** 或 **localhost** 环境下运行
52
- - Node.js 18+（用于开发构建）
56
+ - **HTTPS** 或 **localhost**（WebGPU 安全要求）
57
+ - Node.js 18+（仅开发构建需要）
58
+
59
+ ---
53
60
 
54
61
  ## 快速开始
55
62
 
56
63
  ### 安装
57
64
 
58
65
  ```bash
59
- # 使用 yarn
66
+ # yarn
60
67
  yarn add @d5techs/3dgs-lib
61
68
 
62
- # 或使用 npm
69
+ # npm
63
70
  npm install @d5techs/3dgs-lib
64
- ```
65
-
66
- ### 开发
67
71
 
68
- ```bash
69
- # 启动开发服务器
70
- yarn dev
71
-
72
- # 构建库
73
- yarn build:lib
74
-
75
- # 构建 Demo
76
- yarn build:demo
72
+ # pnpm
73
+ pnpm add @d5techs/3dgs-lib
77
74
  ```
78
75
 
79
- ## 基本用法
76
+ ### 基本用法
80
77
 
81
78
  ```typescript
82
79
  import { App } from '@d5techs/3dgs-lib';
83
80
 
84
- // 创建应用
81
+ // 1. 创建应用
85
82
  const canvas = document.getElementById('canvas') as HTMLCanvasElement;
86
83
  const app = new App(canvas);
87
84
 
88
- // 初始化
85
+ // 2. 初始化（异步）
89
86
  await app.init();
90
87
 
91
- // 加载 3D Gaussian Splatting 模型
88
+ // 3. 加载模型
89
+ // 3DGS 模型
92
90
  await app.addPLY('model.ply', (progress, stage) => {
93
91
  console.log(`${stage}: ${progress.toFixed(1)}%`);
94
92
  });
95
93
 
96
- // 或加载传统 3D 模型
94
+ // 或传统 3D 模型
97
95
  await app.addGLB('model.glb');
98
96
  await app.addOBJ('model.obj');
99
97
 
100
- // 自动调整相机
98
+ // 4. 自动调整相机视角
101
99
  app.frameCurrentModel();
102
100
 
103
- // 启动渲染
101
+ // 5. 启动渲染循环
104
102
  app.start();
105
103
  ```
106
104
 
107
- ## 项目结构
108
-
109
- ```
110
- @d5techs/3dgs-lib/
111
- ├── src/ # 引擎源代码
112
- │ ├── index.ts # 库入口
113
- │ ├── App.ts # 统一调度入口
114
- │ ├── core/ # 核心模块
115
- │ │ ├── Renderer.ts # WebGPU 渲染器
116
- │ │ ├── Camera.ts # 相机
117
- │ │ ├── OrbitControls.ts # 轨道控制器
118
- │ │ ├── ViewportGizmo.ts # 视口 Gizmo
119
- │ │ ├── BoundingBoxRenderer.ts # 包围盒渲染
120
- │ │ ├── gizmo/ # 变换 Gizmo
121
- │ │ └── math/ # 数学工具
122
- │ ├── gs/ # 3D Gaussian Splatting
123
- │ │ ├── GSSplatRenderer.ts # 桌面端渲染器
124
- │ │ ├── GSSplatRendererMobile.ts # 移动端渲染器
125
- │ │ ├── GSSplatSorter.ts # GPU 排序器
126
- │ │ ├── PLYLoader.ts # PLY 加载器
127
- │ │ ├── SplatLoader.ts # Splat 加载器
128
- │ │ └── *.wgsl # WGSL 着色器
129
- │ ├── mesh/ # 网格渲染
130
- │ ├── loaders/ # 模型加载器
131
- │ ├── scene/ # 场景管理
132
- │ └── interaction/ # 交互管理
133
- ├── demo/ # Demo 应用
134
- ├── USAGE_GUIDE.md # 使用手册
135
- └── 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>
136
121
  ```
137
122
 
123
+ ---
124
+
138
125
  ## 核心 API
139
126
 
140
127
  ### App 类
141
128
 
129
+ 主入口类，提供完整的应用生命周期管理。
130
+
142
131
  ```typescript
143
- // 初始化
144
- await app.init();
145
- app.start();
146
- app.stop();
147
- app.destroy();
132
+ const app = new App(canvas);
133
+
134
+ // 生命周期
135
+ await app.init(); // 初始化 WebGPU
136
+ app.start(); // 开始渲染循环
137
+ app.stop(); // 停止渲染循环
138
+ app.destroy(); // 销毁所有资源
148
139
 
149
140
  // 模型加载
150
- await app.addPLY(url, onProgress?);
151
- await app.addSplat(url, onProgress?);
152
- await app.addGLB(url);
153
- 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
154
165
 
155
- // 场景管理
156
- app.getMeshCount();
157
- app.getSplatCount();
158
- app.clearMeshes();
159
- 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
+ ```
160
182
 
161
- // SH 模式 (0-3)
162
- app.setSHMode(mode);
163
- app.getSHMode();
183
+ ### 进度回调
164
184
 
165
- // 相机控制
166
- app.frameCurrentModel(animate?);
167
- app.getCamera();
168
- app.getControls();
185
+ ```typescript
186
+ type ProgressCallback = (
187
+ progress: number, // 0-100
188
+ stage: 'download' | 'parse' | 'upload'
189
+ ) => void;
169
190
 
170
- // Gizmo
171
- app.setGizmoMode(mode);
172
- 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
+ });
173
200
  ```
174
201
 
175
- ### 导出类
176
-
177
- | 类名 | 说明 |
178
- |------|------|
179
- | `App` | 统一调度入口 |
180
- | `Renderer` | WebGPU 渲染器 |
181
- | `Camera` | 透视相机 |
182
- | `OrbitControls` | 轨道控制器 |
183
- | `Mesh` | 网格数据结构 |
184
- | `MeshRenderer` | 网格渲染器 |
185
- | `GSSplatRenderer` | 3DGS 渲染器 |
186
- | `GLBLoader` | GLB 加载器 |
187
- | `OBJLoader` | OBJ 加载器 |
188
- | `TransformGizmoV2` | 变换 Gizmo |
189
- | `ViewportGizmo` | 视口 Gizmo |
190
- | `SceneManager` | 场景管理器 |
202
+ ---
191
203
 
192
204
  ## 交互控制
193
205
 
@@ -199,7 +211,7 @@ app.setGizmoTarget(object);
199
211
  | 右键拖拽 | 平移视角 |
200
212
  | 滚轮 | 缩放 |
201
213
 
202
- ### 触摸
214
+ ### 触摸（移动端）
203
215
 
204
216
  | 操作 | 功能 |
205
217
  |------|------|
@@ -207,29 +219,192 @@ app.setGizmoTarget(object);
207
219
  | 双指捏合 | 缩放 |
208
220
  | 双指拖拽 | 平移视角 |
209
221
 
210
- ### 键盘
222
+ ### 键盘快捷键
211
223
 
212
224
  | 按键 | 功能 |
213
225
  |------|------|
214
- | W | 平移模式 |
215
- | E | 旋转模式 |
216
- | 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
+ ---
217
376
 
218
377
  ## 技术细节
219
378
 
220
- ### 3D Gaussian Splatting
379
+ ### 3D Gaussian Splatting 渲染管线
221
380
 
222
- - **排序**: GPU Radix Sort (Compute Shader)
223
- - **渲染**: 基于 Quad 的 2D 高斯椭圆投影
224
- - **协方差**: 3D → 2D 屏幕空间投影
225
- - **球谐函数**: 0-3 阶 SH 系数，视角相关颜色
381
+ 1. **数据加载**: PLY/Splat → CPU 解析 → GPU Buffer
382
+ 2. **视锥剔除**: Compute Shader 剔除不可见 Splat
383
+ 3. **深度排序**: GPU Radix Sort 按深度排序
384
+ 4. **渲染**: 实例化渲染 Quad，2D 高斯椭圆投影
226
385
 
227
- ### 着色器
386
+ ### 着色器技术
228
387
 
229
388
  - WGSL (WebGPU Shading Language)
389
+ - Normalized Gaussian 消除边缘雾化
230
390
  - 多 SH 级别优化变体
231
391
  - GPU 排序 Compute Shader
232
392
 
393
+ ### 内存优化
394
+
395
+ - 桌面端: 256 bytes/splat（完整 SH）
396
+ - 移动端: ~52 bytes/splat（纹理压缩）
397
+
398
+ ---
399
+
233
400
  ## 许可证
234
401
 
235
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/)