GaussForge

March 1, 2026 · View on GitHub

npm

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 - 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: Gaussian splat compression library (Apache-2.0)
libwebp: WebP image encoding/decoding (BSD-3-Clause)
nlohmann_json: JSON for Modern C++ (MIT)
zlib: Compression library (zlib License)

Format Credits

SPZ Format: Developed by Niantic.
KSPLAT Format: Developed by mkkellogg.

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

# 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

# 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:

# Basic usage
./gfconvert <input_file> <output_file>

# 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:

#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:

npm install @gaussforge/wasm

Quick Example:

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.

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:

pip install gaussforge

Quick Example:

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.

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

Create new reader/writer header files in include/gf/io/
Implement corresponding reader/writer in src/io/
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.)