spz2glb - SPZ to GLB Converter

Lossless packaging of SPZ into GLB — preserves SPZ compressed stream, with dual-scenario collaboration: lightweight web usage + heavy local workloads.

Release Status

• Current stable line: v2.x (for exact version, see Releases and repository tags)
• Core positioning: lossless packaging (SPZ stream stored as-is in GLB)
• Key enhancement: WASM memory/API capabilities (reserved input, explicit release, stats, dual profile)
• Dual-end collaboration: scenario split — browser side for lightweight preview/quick checks, local CLI for heavy conversion, batch jobs, and deep verification
• Validation closure: built-in 3-layer verification (structure/lossless/decoding consistency) + cloud browser smoke

Responsibility Boundary (Fixed)

• spz2glb is responsible for only two things: SPZ→GLB format packaging and GLB delivery/distribution workflow.
• spz2glb does not own compression algorithm R&D, rendering-engine capability expansion, or generic 3D editing pipelines.
• GLB compliance and correctness are judged by the three-layer verification system (structure / lossless / decoding consistency).
• The Web path is for lightweight single-file demos by default; batch and heavy workloads belong to the CLI path.

📚 Documentation

• Wiki: https://github.com/spz-ecosystem/spz2glb/wiki
• Live Demo: GitHub Pages
  • Installation Guide
  • Quick Start
  • Usage
  • Three-Layer Verification
  • Batch Processing
  • Performance Optimization
  • Troubleshooting
  • FAQ
  • Building Guide
  • Contributing

Core Features

• Lossless Packaging: SPZ compressed stream stored as-is in GLB, 100% byte-level fidelity
• SPZ_2 Extension: Uses KHR_gaussian_splatting_compression_spz_2 standard extension
• Large-Scale Refactor (v2.0): Unified CLI/WASM core path, reduced dual-end divergence
• WASM Enhancements: Reserved input, explicit output release, memory stats, compat/perf-lite dual profile
• Dual-End Collaboration (scenario split): lightweight web interaction and fast feedback on browser side; batch, large-file, and heavy verification workflows on local CLI side
• Three-Layer Verification: Structure validation / lossless validation / decoding consistency
• Cross-Platform: Windows, Linux, macOS (x64 + ARM)
• Zero Runtime Dependencies: C++17 + WASM, no additional runtime dependencies

Comparison with splat-transform

Note: this section describes tool positioning differences, not an absolute quality ranking.

Core Difference in One Line

• spz2glb: Lossless packaging of SPZ into GLB (SPZ compressed stream stored as-is)
• splat-transform: Reads SPZ, decompresses and reconstructs full Gaussian data, then writes GLB (not lossless packaging)

Detailed Comparison

| Dimension | spz2glb (v2.0) | splat-transform (v1.10.1) | |-----------|-------------------|-----------------------------| | Core positioning | Lossless SPZ→GLB packaging (preserves SPZ compressed stream) | Data transformation/reconstruction tool (multi-format conversion & editing) | | SPZ handling | No decompression; SPZ stored as binary stream inside GLB | Read SPZ → decompress to full Gaussian data → rebuild GLB | | GLB output | Uses KHR_gaussian_splatting_compression_spz_2 extension with original SPZ stream | Uses standard KHR_gaussian_splatting extension with decompressed Gaussian attributes | | Data fidelity | 100% lossless (byte-level SPZ preservation) | Decompress-rebuild cycle involves codec conversion | | Feature scope | Focused on SPZ↔GLB conversion and verification | Supports read/transform/filter/merge/generate across PLY/SOG/SPZ/KSPLAT/SPLAT formats | | Runtime | C++17 + WASM, no runtime dependencies | TypeScript/Node.js with WebGPU dependency for SOG compression | | WASM capabilities | Reserved input, explicit release, memory stats, dual profile | Browser/Node dual-end, not centered on release-grade memory governance | | Validation | Built-in 3-layer verification (structure/lossless/decoding consistency) + cloud browser smoke | Unit tests + fixture validation |

Usage Recommendations

| Scenario | Recommended Tool | |----------|------------------| | Need to losslessly embed SPZ in GLB, preserving original compression | spz2glb | | Need GLB with directly renderable Gaussian data (not compressed stream) | splat-transform | | Need splat transformation, filtering, merging, generation | splat-transform | | Need cross-format batch processing (SOG/KSPLAT/SPLAT/etc.) | splat-transform | | Need dual-scenario collaboration (lightweight web + heavy local tasks) with release-grade validation | spz2glb |

Basic Conversion

# Convert SPZ to GLB
spz2glb model.spz model.glb

Three-Layer Verification

# Run all verifications (provide your own SPZ and GLB files)
spz_verify all input.spz output.glb

# Output:
# Layer 1: GLB Structure & SPZ_2 Specification Validation - PASSED (7/7)
# Layer 2: Binary Lossless Verification - PASSED (100% MD5 match)
# Layer 3: Decoding Consistency Verification - PASSED (Size match)
# [SUCCESS] All verifications PASSED!

Note: Use the actual executable path from your build output (for example build/spz2glb / build/spz_verify) or add binaries to PATH.

Batch Processing

# Batch convert all SPZ files
for file in *.spz; do
    spz2glb "$file" "${file%.spz}.glb"
done

Quick Start

Option 1: Download Pre-compiled Binaries

Download binaries for your platform from Releases:

• Windows: spz2glb-windows-x64.exe
• Linux: spz2glb-linux-x64
• macOS: spz2glb-macos-x64

Option 2: Build from Source (One-Click Build)

# 1. Clone the repository
git clone https://github.com/spz-ecosystem/spz2glb.git
cd spz2glb

# 2. One-click build (handles all dependencies automatically)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j$(nproc)

# 3. Run (use actual binary path or PATH command)
spz2glb input.spz output.glb

Platform-Specific Dependencies (install before building):

# Ubuntu/Debian
sudo apt-get install -y zlib1g-dev

# macOS
brew install zlib

# Windows
# No manual installation required, CI uses vcpkg to install automatically

Usage

Converter (spz2glb)

spz2glb <input.spz> <output.glb>

Complete Examples:

# Convert a single file
spz2glb model.spz model.glb

# Batch conversion
for file in *.spz; do
    spz2glb "$file" "${file%.spz}.glb"
done

Output Example:

[INFO] Loading SPZ: model.spz
[INFO] SPZ version: 2
[INFO] Num points: 100000
[INFO] SH degree: 3
[INFO] SPZ size (raw compressed): 15 MB
[INFO] Creating glTF Asset with KHR extensions
[INFO] Exporting GLB...
[SUCCESS] GLB exported: model.glb
[INFO] GLB size: 16 MB

Three-Layer Verification Tool (spz_verify)

Important Notes:

• Independent Tool: spz_verify is a standalone verification tool, NOT part of the production conversion pipeline
• Development/Testing Use: Designed for quality assurance, debugging, and testing workflows
• Not Required for Daily Use: Once conversion is verified, you only need spz2glb for production
• Layer 2 Performs Decompression: Layer 2 verification extracts and decompresses data to compute MD5 hashes (slower than Layer 1/3)

spz_verify <command> [options]

Commands:

# Run all three layers of verification
spz_verify all <input.spz> <output.glb>

# Run individual layer verification
spz_verify layer1 <output.glb>              # GLB structure validation (fast)
spz_verify layer2 <input.spz> <output.glb>  # Lossless binary validation (MD5, slower)
spz_verify layer3 <input.spz> <output.glb>  # Decode consistency validation (fast)

Complete Examples:

# 1. Convert file
spz2glb model.spz model.glb

# 2. Run all verifications
spz_verify all model.spz model.glb

# Or verify individually
spz_verify layer1 model.glb
spz_verify layer2 model.spz model.glb
spz_verify layer3 model.spz model.glb

Verification Output:

Layer 1: GLB Structure Validation
  ✓ Magic number: 0x46546C67 ("glTF")
  ✓ Version: 2
  ✓ extensionsUsed contains KHR_gaussian_splatting
  ✓ extensionsUsed contains KHR_gaussian_splatting_compression_spz_2
  ✓ buffers configuration correct
  ✓ Compression stream mode (attributes empty)
  [PASS] Layer 1 validation passed

Layer 2: Lossless Binary Validation
  ✓ Original SPZ MD5: abc123...
  ✓ Extracted data MD5: abc123...
  ✓ MD5 match confirmed
  [PASS] Layer 2 validation passed

Layer 3: Decode Consistency Validation
  ✓ GLB structure valid
  ✓ Extension integrity check passed
  [PASS] Layer 3 validation passed

[SUCCESS] All 3 layers validation passed!

Automated Verification Script (Recommended)

Create verify.sh or verify.bat script to automate conversion + verification:

Linux/macOS (verify.sh):

#!/bin/bash
set -e

if [ $# -ne 1 ]; then
    echo "Usage: $0 <input.spz>"
    exit 1
fi

INPUT="$1"
OUTPUT="${INPUT%.spz}.glb"
SPZ2GLB="spz2glb"
VERIFY="spz_verify"

echo "=== SPZ to GLB Conversion & Verification ==="
echo "Input:  $INPUT"
echo "Output: $OUTPU