https://github.com/3dgscloud/gaussforge
A high-performance Gaussian Splatting format conversion library that supports lossless conversion between multiple mainstream formats.
https://github.com/3dgscloud/gaussforge
3dgs gaussian-processes guassian
Last synced: 5 months ago
JSON representation
A high-performance Gaussian Splatting format conversion library that supports lossless conversion between multiple mainstream formats.
- Host: GitHub
- URL: https://github.com/3dgscloud/gaussforge
- Owner: 3dgscloud
- License: apache-2.0
- Created: 2025-12-19T06:15:17.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-27T16:39:30.000Z (5 months ago)
- Last Synced: 2026-02-27T21:13:58.918Z (5 months ago)
- Topics: 3dgs, gaussian-processes, guassian
- Language: C++
- Homepage: https://www.3dgsviewers.com/
- Size: 430 KB
- Stars: 26
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GaussForge
[](https://pypi.org/project/gaussforge/)
[](https://github.com/3dgscloud/GaussForge/releases)
[](https://github.com/3dgscloud/GaussForge/commits)
A high-performance Gaussian Splatting format conversion library that supports lossless conversion between multiple mainstream formats.
## Online Viewer
Try GaussForge in your browser! Visit **[3DGS Viewer](https://www.3dgsviewers.com/)** - a free online 3D Gaussian Splatting viewer that supports multiple formats including PLY, SPZ, SPLAT, KSPLAT, and SOG. The viewer integrates GaussForge, allowing you to view and export models in all supported formats directly in your web browser. No installation required - simply upload your 3DGS model file and start viewing instantly.
## Features
- **Multi-format Support**: Supports PLY, compressed.ply, SPLAT, KSPLAT, SPZ and other formats
- **High Performance**: Written in C++17 with deep performance optimizations
- **Lossless Conversion**: Based on a unified intermediate representation (IR) to ensure data integrity
- **Easy Integration**: Provides both static library and command-line tool
- **WebAssembly Support**: WASM build available for browser and Node.js environments with TypeScript bindings
- **Python Support**: Python package available via pip with pre-built wheels for major platforms
- **Data Validation**: Built-in data validation mechanism to ensure conversion quality
- **Zero Dependencies**: Only depends on necessary third-party libraries (managed via CMake FetchContent), apart from build tools
## Supported Formats
| Format | Extension | Read | Write | Description |
|--------|-----------|------|-------|-------------|
| PLY | `.ply` | ✅ | ✅ | Standard PLY format |
| SPZ | `.spz` | ✅ | ✅ | SPZ compressed format |
| Compressed PLY | `.compressed.ply` | ✅ | ✅ | Compressed PLY format |
| SPLAT | `.splat` | ✅ | ✅ | Splat format |
| KSPLAT | `.ksplat` | ✅ | ✅ | K-Splat format |
| SOG | `.sog` | ✅ | ✅ | SOG format |
## Dependencies & Credits
GaussForge is built on top of several excellent open-source libraries:
- **[spz](https://github.com/nianticlabs/spz)**: Gaussian splat compression library (Apache-2.0)
- **[libwebp](https://github.com/webmproject/libwebp)**: WebP image encoding/decoding (BSD-3-Clause)
- **[nlohmann_json](https://github.com/nlohmann/json)**: JSON for Modern C++ (MIT)
- **[zlib](https://github.com/madler/zlib)**: Compression library (zlib License)
### Format Credits
- **SPZ Format**: Developed by **[Niantic](https://github.com/nianticlabs/spz)**.
- **KSPLAT Format**: Developed by **[mkkellogg](https://github.com/mkkellogg/GaussianSplats3D)**.
## Quick Start
### System Requirements
- CMake 3.26 or higher
- C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
- Build tools: Ninja or Make
### Building the Project
```bash
# Create build directory
mkdir build && cd build
# Configure build (Debug mode)
cmake ..
# Or configure Release mode (with optimizations enabled)
cmake -DCMAKE_BUILD_TYPE=Release ..
# Build
cmake --build .
# Run tests (optional)
ctest
```
### Installation
```bash
# In the build directory
cmake --install . --prefix /usr/local
```
## Usage
### Command-Line Tool
The project provides the `gfconvert` command-line tool for converting Gaussian splat files between different formats:
```bash
# Basic usage
./gfconvert
# Example: Convert PLY to SPZ
./gfconvert input.ply output.spz
# Example: Convert compressed.ply to standard PLY
./gfconvert input.compressed.ply output.ply
# Manually specify formats (when file extensions are non-standard)
./gfconvert input.dat output.dat --in-format ply --out-format spz
```
### Using as a Library
GaussForge can be integrated into your project as a static library:
```cpp
#include "gf/core/gauss_ir.h"
#include "gf/io/registry.h"
#include "gf/io/reader.h"
#include "gf/io/writer.h"
// Create registry (automatically registers all built-in formats)
gf::IORegistry registry;
// Get reader and writer
auto* reader = registry.ReaderForExt("ply");
auto* writer = registry.WriterForExt("spz");
// Read file
gf::ReadOptions read_opt;
auto ir = reader->Read(data, size, read_opt);
// Write file
gf::WriteOptions write_opt;
auto out_data = writer->Write(ir.value(), write_opt);
```
### WebAssembly (WASM) Support
GaussForge also provides a WebAssembly build that enables format conversion directly in web browsers and Node.js. The WASM version includes a TypeScript wrapper library for easy integration into frontend applications.
**Installation:**
```bash
npm install @gaussforge/wasm
```
**Quick Example:**
```typescript
import { createGaussForge } from '@gaussforge/wasm';
const gaussForge = await createGaussForge();
const converted = await gaussForge.convert(fileData, 'ply', 'spz');
```
For detailed WASM usage and API documentation, see the [WASM README](wasm/README.md).
### Python Package
GaussForge provides a Python package with pre-built wheels for Linux, macOS (Apple Silicon), and Windows. No compilation required - just install and use.
**Installation:**
```bash
pip install gaussforge
```
**Quick Example:**
```python
import gaussforge
# Create instance
gf = gaussforge.GaussForge()
# Get version and supported formats
print(f"Version: {gaussforge.__version__}")
print(f"Formats: {gf.get_supported_formats()}")
# Read a PLY file
with open("model.ply", "rb") as f:
data = f.read()
result = gf.read(data, "ply")
if "error" not in result:
print(f"Loaded {result['data']['numPoints']} points")
# Convert to another format
converted = gf.convert(data, "ply", "splat")
if "error" not in converted:
with open("output.splat", "wb") as f:
f.write(converted["data"])
```
**API Reference:**
- `GaussForge()` - Create a new instance
- `read(data: bytes, format: str)` - Read Gaussian data from bytes
- `write(ir: dict, format: str)` - Write Gaussian IR to bytes
- `convert(data: bytes, in_format: str, out_format: str)` - Convert between formats
- `get_model_info(data: bytes, format: str)` - Get detailed model information
- `get_supported_formats()` - Get list of supported format names
- `get_version()` - Get library version string
For more details, see the [Python README](python/README.md).
## Project Structure
```
GaussForge/
├── include/ # Header files
│ └── gf/
│ ├── core/ # Core data structures (IR, metadata, validation)
│ └── io/ # I/O interfaces and format implementations
├── src/ # Source files
│ ├── core/ # Core implementations
│ ├── io/ # I/O implementations
│ ├── cli/ # Command-line tool
│ └── wasm/ # WebAssembly bindings
├── python/ # Python package (nanobind bindings)
├── wasm/ # WASM package (npm)
└── cmakes/ # CMake configuration files
```
## Core Concepts
### Intermediate Representation (IR)
GaussForge uses a unified intermediate representation `GaussianCloudIR` to store Gaussian splat data:
- **Positions**: 3D coordinate array
- **Scales**: Logarithmic scale values
- **Rotations**: Quaternion-represented rotations
- **Alphas**: Pre-sigmoid opacity values
- **Colors**: Spherical harmonics 0th-order (DC) coefficients
- **SH Coefficients**: Higher-order spherical harmonics coefficients
- **Metadata**: Coordinate system, units, color space, and other information
### Data Validation
Basic data validation is automatically performed during conversion to ensure:
- Array size consistency
- Data range reasonableness
- Format specification compliance
## Development
### Adding New Format Support
1. Create new reader/writer header files in `include/gf/io/`
2. Implement corresponding reader/writer in `src/io/`
3. Register the new format in `src/io/registry.cpp`
### Build Options
- `CMAKE_BUILD_TYPE=Debug`: Debug mode with debug information
- `CMAKE_BUILD_TYPE=Release`: Release mode with all optimization options enabled (-O3, LTO, vectorization, etc.)
## License
This project is licensed under the [Apache License 2.0](LICENSE). See the [LICENSE](LICENSE) file for details.
## Contributing
Contributions via Issues and Pull Requests are welcome!
## Related Resources
- [3D Gaussian Splatting Paper](https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/)
- [SOG Format Specification](https://developer.playcanvas.com/user-manual/gaussian-splatting/formats/sog/)
- [SPZ Format Documentation](https://github.com/nianticlabs/spz)
## Acknowledgments
Thanks to all developers who have contributed to the standardization of Gaussian splat formats.