Reader module¶

Reading functions for Gaussian splatting PLY files.

This module provides ultra-fast reading of Gaussian splatting PLY files in both uncompressed and compressed formats.

API Examples:

>>> from gsply import plyread
>>> data = plyread("scene.ply")
>>> print(f"Loaded {data.means.shape[0]} Gaussians with SH degree {data.shN.shape[1]}")

>>> # Or use format-specific readers
>>> from gsply.reader import read_uncompressed
>>> data = read_uncompressed("scene.ply")
>>> if data is not None:
...     print(f"Loaded {data.means.shape[0]} Gaussians")

Performance:

Read uncompressed: 1-3ms for 50K Gaussians (17-50M Gaussians/sec)
Read compressed: 3-16ms for 50K Gaussians (3-16M Gaussians/sec)

gsply.reader.plyread(file_path)[source]¶

Read Gaussian splatting PLY file (auto-detect format).

Automatically detects and reads both compressed and uncompressed formats. Uses formats.detect_format() for fast format detection.

All reads use zero-copy optimization for maximum performance.

Parameters:: file_path (str | Path) – Path to PLY file
Return type:: GSData
Returns:: GSData container with Gaussian parameters
Raises:: ValueError – If file format is not recognized or invalid

Performance:

Uncompressed: ~6ms for 400K Gaussians, SH0 (70M Gaussians/sec)
Compressed: ~9ms for 400K Gaussians, SH0 (47M Gaussians/sec)
Peak: 78M Gaussians/sec for 1M Gaussians, SH0

Example

>>> data = plyread("scene.ply")
>>> print(f"Loaded {data.means.shape[0]} Gaussians")
>>> positions = data.means
>>> colors = data.sh0
>>>
>>> # Unpack for standard GS workflows
>>> means, scales, quats, opacities, sh0, shN = data.unpack()

gsply.reader.read_uncompressed(file_path)[source]¶

Read uncompressed Gaussian splatting PLY file with zero-copy optimization.

Uses zero-copy views into a single base array for maximum performance. The returned arrays share memory with a base array that is kept alive via the GSData container’s reference counting.

Note: This function does NOT use JIT compilation - it’s already optimally implemented with NumPy zero-copy views. JIT is only used for compressed format.

Parameters:: file_path (str | Path) – Path to PLY file
Return type:: GSData | None
Returns:: GSData container with zero-copy array views, or None if format is incompatible. The base array is kept alive to ensure views remain valid.

Performance:

SH degree 0 (14 props): ~6ms for 400K Gaussians (70M Gaussians/sec)
SH degree 3 (59 props): ~3ms for 50K Gaussians (17M Gaussians/sec)
Peak: 78M Gaussians/sec for 1M Gaussians, SH0

Example

>>> data = read_uncompressed("scene.ply")
>>> if data is not None:
...     print(f"Loaded {data.means.shape[0]} Gaussians")
...     positions = data.means
...     colors = data.sh0

gsply.reader.read_compressed(file_path)[source]¶

Read compressed Gaussian splatting PLY file (PlayCanvas format).

Format uses chunk-based quantization with 256 Gaussians per chunk. Achieves 14.5x compression (16 bytes/splat vs 232 bytes/splat).

Uses Numba JIT compilation for fast parallel decompression (6x faster than pure NumPy).

Parameters:: file_path (str | Path) – Path to compressed PLY file
Return type:: GSData | None
Returns:: GSData container with decompressed Gaussian parameters, or None if format is incompatible. The base field is None (no shared array).

Performance:

With JIT: ~9ms for 400K Gaussians, SH0 (47M Gaussians/sec)
With JIT: ~118ms for 400K Gaussians, SH3 (3.4M Gaussians/sec)

Example

>>> result = read_compressed("scene.ply_compressed")
>>> if result is not None:
...     print(f"Loaded {result.means.shape[0]} compressed Gaussians")
...     positions = result.means

gsply.reader.decompress_from_bytes(compressed_bytes)[source]¶

Decompress Gaussian splatting data from bytes (PlayCanvas format).

Reads compressed PLY data from bytes without disk I/O. Symmetric with compress_to_bytes() - use for network transfer, streaming, etc.

Uses optimized header parsing (bytes.find) matching read_compressed() performance.

Parameters:: compressed_bytes (bytes) – Complete compressed PLY file as bytes
Return type:: GSData
Returns:: GSData container with decompressed Gaussian parameters

Example

>>> from gsply import compress_to_bytes, decompress_from_bytes
>>> # Compress
>>> data = plyread("model.ply")
>>> compressed = compress_to_bytes(data)
>>>
>>> # Decompress (no disk I/O!)
>>> data_restored = decompress_from_bytes(compressed)
>>> assert data_restored.means.shape == data.means.shape