SOG Reader module

SOG (Splat Ordering Grid) format reader - optimized implementation.

SOG format uses WebP images to store quantized Gaussian splatting data with codebook-based compression for scales and colors.

Returns GSData container (same as plyread) for consistent API across all formats.

Format:

  • meta.json: Metadata (bounds, codebooks, file references)

  • means_l.webp, means_u.webp: Position data (16-bit split into low/high bytes)

  • quats.webp: Quaternion data (packed smallest-three encoding)

  • scales.webp: Scale labels + codebook (256 centroids from k-means)

  • sh0.webp: Color labels + codebook (256 centroids) + opacity

  • shN_centroids.webp, shN_labels.webp: Optional higher-order SH (if present)

Can be:

  • .sog ZIP bundle (all files in one archive)

  • Folder with separate files

  • Bytes (in-memory ZIP extraction)

gsply.sog_reader.sogread(file_path)[source]

Read SOG (Splat Ordering Grid) format file.

Returns GSData container (same as plyread) for consistent API. Supports both .sog ZIP bundles and folders with separate files. Can also accept bytes directly for in-memory ZIP extraction.

Parameters:

file_path (str | Path | bytes) – Path to .sog file, folder containing SOG files, or bytes (ZIP data)

Return type:

GSData

Returns:

GSData container with Gaussian parameters (same container as plyread)

Raises:

  • ImportError – If imagecodecs is not installed

  • ValueError – If file format is invalid or missing required files

Example

>>> # From file path - returns GSData (same as plyread)
>>> data = sogread("model.sog")
>>> print(f"Loaded {len(data)} Gaussians")
>>> positions = data.means  # Same API as GSData from plyread
>>>
>>> # From bytes (in-memory)
>>> with open("model.sog", "rb") as f:
...     sog_bytes = f.read()
>>> data = sogread(sog_bytes)  # Returns GSData