211 lines
5.5 KiB
Markdown
Executable File
211 lines
5.5 KiB
Markdown
Executable File
# GaussForge — 高性能 3DGS 格式转换库
|
||
|
||
> 来源: https://github.com/3dgscloud/GaussForge
|
||
> 在线查看: https://www.3dgsviewers.com/
|
||
> 研究日期: 2026-05-06
|
||
> 协议: Apache-2.0
|
||
|
||
## 项目概览
|
||
|
||
- **名称**: GaussForge
|
||
- **作者**: 3dgscloud
|
||
- **定位**: 高性能 3D Gaussian Splatting 格式转换库
|
||
- **核心特点**: 无损转换、多格式支持、C++17 编写
|
||
- **Python**: `pip install gaussforge`
|
||
- **npm**: `npm install @gaussforge/wasm`
|
||
|
||
## 解决的核心问题
|
||
|
||
3D 高斯泼溅领域存在**多种互不兼容的格式**：
|
||
- PLY（标准格式，文件大）
|
||
- SPZ（Niantic 压缩格式）
|
||
- SPLAT / KSPLAT（Web 渲染格式）
|
||
- SOG（PlayCanvas 超压缩格式）
|
||
- compressed.ply（压缩 PLY）
|
||
|
||
GaussForge 提供**无损转换**，统一这些格式。
|
||
|
||
## 支持的格式
|
||
|
||
| 格式 | 扩展名 | 读 | 写 | 说明 |
|
||
|------|--------|----|----|------|
|
||
| **PLY** | .ply | ✅ | ✅ | 标准 PLY 格式 |
|
||
| **SPZ** | .spz | ✅ | ✅ | Niantic 压缩格式 |
|
||
| **Compressed PLY** | .compressed.ply | ✅ | ✅ | 压缩 PLY |
|
||
| **SPLAT** | .splat | ✅ | ✅ | Splat 格式 |
|
||
| **KSPLAT** | .ksplat | ✅ | ✅ | K-Splat 格式 |
|
||
| **SOG** | .sog | ✅ | ✅ | PlayCanvas SOG 格式 |
|
||
|
||
## 核心技术架构
|
||
|
||
### 统一中间表示（IR）
|
||
|
||
```
|
||
任意格式 → GaussianCloudIR → 任意格式
|
||
```
|
||
|
||
所有格式转换都通过统一的中间表示 `GaussianCloudIR`：
|
||
|
||
| 数据字段 | 说明 |
|
||
|----------|------|
|
||
| **Positions** | 3D 坐标数组 |
|
||
| **Scales** | 对数尺度值 |
|
||
| **Rotations** | 四元数表示的旋转 |
|
||
| **Alphas** | 预 sigmoid 不透明度 |
|
||
| **Colors** | 球谐函数 0 阶（DC）系数 |
|
||
| **SH Coefficients** | 高阶球谐系数 |
|
||
| **Metadata** | 坐标系、单位、颜色空间 |
|
||
|
||
### 数据验证机制
|
||
|
||
- 数组大小一致性检查
|
||
- 数据范围合理性验证
|
||
- 格式规范合规性检查
|
||
|
||
## 三种使用方式
|
||
|
||
### 1. CLI 命令行工具
|
||
|
||
```bash
|
||
# PLY 转 SPZ
|
||
./gfconvert input.ply output.spz
|
||
|
||
# 压缩 PLY 转标准 PLY
|
||
./gfconvert input.compressed.ply output.ply
|
||
|
||
# 手动指定格式
|
||
./gfconvert input.dat output.dat --in-format ply --out-format spz
|
||
```
|
||
|
||
### 2. Python SDK
|
||
|
||
```bash
|
||
pip install gaussforge
|
||
```
|
||
|
||
```python
|
||
import gaussforge
|
||
|
||
gf = gaussforge.GaussForge()
|
||
|
||
# 读取 PLY
|
||
with open("model.ply", "rb") as f:
|
||
data = f.read()
|
||
|
||
result = gf.read(data, "ply")
|
||
print(f"Loaded {result['data']['numPoints']} points")
|
||
|
||
# 格式转换
|
||
converted = gf.convert(data, "ply", "splat")
|
||
with open("output.splat", "wb") as f:
|
||
f.write(converted["data"])
|
||
```
|
||
|
||
### 3. WebAssembly（浏览器/Node.js）
|
||
|
||
```bash
|
||
npm install @gaussforge/wasm
|
||
```
|
||
|
||
```typescript
|
||
import { createGaussForge } from '@gaussforge/wasm';
|
||
|
||
const gaussForge = await createGaussForge();
|
||
const converted = await gaussForge.convert(fileData, 'ply', 'spz');
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| **核心** | C++17 |
|
||
| **构建** | CMake 3.26+ |
|
||
| **编译器** | GCC 7+ / Clang 5+ / MSVC 2017+ |
|
||
| **Python 绑定** | nanobind |
|
||
| **WASM 绑定** | Emscripten + TypeScript |
|
||
| **依赖** | spz (Niantic) / libwebp / nlohmann_json / zlib |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
GaussForge/
|
||
├── include/gf/
|
||
│ ├── core/ # 核心数据结构（IR、元数据、验证）
|
||
│ └── io/ # I/O 接口和格式实现
|
||
├── src/
|
||
│ ├── core/ # 核心实现
|
||
│ ├── io/ # I/O 实现
|
||
│ ├── cli/ # 命令行工具
|
||
│ └── wasm/ # WebAssembly 绑定
|
||
├── python/ # Python 包（nanobind 绑定）
|
||
├── wasm/ # WASM 包（npm）
|
||
└── cmakes/ # CMake 配置
|
||
```
|
||
|
||
## 与 SuperSplat 的关系
|
||
|
||
| 维度 | SuperSplat | GaussForge |
|
||
|------|------------|------------|
|
||
| **定位** | 可视化编辑器 | 格式转换库 |
|
||
| **运行方式** | 浏览器 | CLI / Python / WASM |
|
||
| **功能** | 编辑/优化/发布 | 格式转换/验证 |
|
||
| **语言** | TypeScript | C++17 |
|
||
| **互补性** | 编辑前需要转换格式 | 转换后可用 SuperSplat 编辑 |
|
||
|
||
**工作流**：`原始数据 → GaussForge 转换 → SuperSplat 编辑 → 发布`
|
||
|
||
## 在线工具
|
||
|
||
**3DGS Viewer**: https://www.3dgsviewers.com/
|
||
- 集成 GaussForge 的在线 3DGS 查看器
|
||
- 支持上传 PLY/SPZ/SPLAT/KSPLAT/SOG 格式
|
||
- 可直接在浏览器中查看和导出所有格式
|
||
- 无需安装
|
||
|
||
## 应用场景
|
||
|
||
### 1. 3DGS 开发/研究
|
||
- 不同工具输出不同格式，需要统一转换
|
||
- 训练输出 PLY → 转 SPZ/SOG 用于生产
|
||
|
||
### 2. Web 应用
|
||
- WASM 版本支持浏览器端格式转换
|
||
- 用户上传任意格式，自动转换后渲染
|
||
|
||
### 3. 自动化管线
|
||
- Python SDK 集成到 CI/CD 流程
|
||
- 批量转换和验证
|
||
|
||
### 4. 跨平台协作
|
||
- 不同团队使用不同格式
|
||
- GaussForge 作为"翻译层"
|
||
|
||
## 如何添加新格式
|
||
|
||
1. 在 `include/gf/io/` 创建新的 reader/writer 头文件
|
||
2. 在 `src/io/` 实现对应读写逻辑
|
||
3. 在 `src/io/registry.cpp` 注册新格式
|
||
|
||
## 项目评价
|
||
|
||
**优点**：
|
||
- ✅ 6 种主流格式全覆盖
|
||
- ✅ 无损转换（统一 IR）
|
||
- ✅ 三种使用方式（CLI / Python / WASM）
|
||
- ✅ C++17 高性能实现
|
||
- ✅ 数据验证机制
|
||
- ✅ 零多余依赖
|
||
- ✅ Apache-2.0 开源协议
|
||
|
||
**局限**：
|
||
- 🔧 纯转换工具，不包含编辑功能
|
||
- 🔧 不涉及 3DGS 训练/生成
|
||
- 🔧 需要配合其他工具使用（编辑器/渲染器）
|
||
|
||
## 相关链接
|
||
|
||
- GitHub: https://github.com/3dgscloud/GaussForge
|
||
- 在线查看器: https://www.3dgsviewers.com/
|
||
- Python PyPI: https://pypi.org/project/gaussforge/
|
||
- npm WASM: https://www.npmjs.com/package/@gaussforge/wasm
|