# 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