### Install gsply Package - Bash/Shell

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Basic pip installation of the gsply library with optional GPU acceleration (PyTorch) and SOG format support. Full installation example includes all optional dependencies for complete feature set.

```bash
pip install gsply
```

```bash
pip install torch
```

```bash
pip install gsply[sogs]
```

```bash
pip install gsply[sogs] torch  # GPU + SOG support
```

```bash
# Editable install with development extras
pip install -e ".[dev]"

# Install documentation extras for Sphinx
pip install -e ".[docs]"
```

--------------------------------

### Install gsply from PyPI or source

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Installation instructions for gsply package from PyPI (coming soon) or directly from the GitHub repository source. Requires Python environment with pip package manager.

```bash
# From PyPI (coming soon)
pip install gsply

# From source
git clone https://github.com/OpsiClear/gsply.git
cd gsply
pip install -e .
```

--------------------------------

### Install gsply from Source

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

This snippet shows how to clone the gsply repository, set up a virtual environment, and install the library in development mode or with all dependencies. It is essential for contributing to the project.

```bash
git clone https://github.com/OpsiClear/gsply.git
cd gsply

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

# Or install all dependencies (including benchmarks)
pip install -e ".[all]"
```

--------------------------------

### Read SOG Format Files - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Load SOG format files using sogread() function which requires gsply[sogs] installation. Supports both file paths and in-memory bytes for flexible reading options.

```python
from gsply import sogread

# Read SOG format (requires gsply[sogs])
data = sogread("model.sog")  # Returns GSData (same API as plyread)

# In-memory reading from bytes
with open("model.sog", "rb") as f:
    sog_bytes = f.read()
data = sogread(sog_bytes)  # No disk I/O
```

--------------------------------

### Install Setuptools and Wheel

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

Installs or upgrades the setuptools and wheel packages using pip. This is a common fix for build issues related to missing or outdated packaging tools.

```bash
pip install --upgrade setuptools wheel
```

--------------------------------

### Verify PyPI Installation and Package Metadata

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

Commands to verify the installation of the gsply package from PyPI, check its version, and display its metadata. These are useful for post-release verification.

```bash
# Verify PyPI installation
pip install --upgrade gsply
python -c "import gsply; print(gspsply.__version__)"

# Run tests
pytest tests/ -v

# Check package metadata
pip show gsply
```

--------------------------------

### Run gsply Benchmarks

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

Instructions for running performance benchmarks to compare gsply's speed against other libraries. This requires installing benchmark-specific dependencies first.

```bash
# Install benchmark dependencies
pip install -e ".[benchmark]"

# Run benchmark with default settings
python benchmarks/benchmark.py

# Custom test file and iterations
python benchmarks/benchmark.py --config.file path/to/model.ply --config.iterations 20
```

--------------------------------

### Python Type Hinting Example

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

An example demonstrating Python 3.10+ type hinting conventions used in the gsply project. It includes the use of `from __future__ import annotations`, `typing` module types, and explicit return value type hints for functions like `plyread`.

```python
from __future__ import annotations
from pathlib import Path
import numpy as np

def plyread(file_path: str | Path) -> tuple[
    np.ndarray,  # means
    np.ndarray,  # scales
    np.ndarray,  # quats
    np.ndarray,  # opacities
    np.ndarray,  # sh0
    np.ndarray | None,  # shN
]:
    """Read Gaussian Splatting PLY file."""
    pass
```

--------------------------------

### Python Docstring Example (Google Style)

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

This example illustrates the Google-style docstrings employed in the gsply project. It showcases the structure for Args, Returns, and Raises sections, along with an example usage, as applied to the `detect_format` function.

```python
def detect_format(file_path: str | Path) -> tuple[bool, int | None]:
    """Detect PLY format type and SH degree.

    Args:
        file_path: Path to PLY file

    Returns:
        Tuple of (is_compressed, sh_degree):
        - is_compressed: True if compressed format
        - sh_degree: 0-3 for uncompressed, None for compressed

    Raises:
        FileNotFoundError: If file does not exist
        ValueError: If file is not a valid PLY

    Example:
        >>> is_compressed, sh_degree = detect_format("model.ply")
        >>> print(f"Compressed: {is_compressed}, SH: {sh_degree}")
    """
    pass
```

--------------------------------

### GSPly Training Workflow Example

Source: https://github.com/opsiclear/gsply/blob/master/docs/API_REFERENCE.md

A complete workflow demonstrating the training process using GSPly and PyTorch. Includes loading data from a PLY file, transferring it to the GPU, running a training loop with an optimizer, and saving the optimized results.

```python
import gsply
from gsply import GSTensor
import torch

# Load from disk
data = gsply.plyread("scene.ply")  # Has _base -> fast GPU transfer

# Transfer to GPU (11x faster with _base)
gstensor = GSTensor.from_gsdata(data, device='cuda', requires_grad=True)

# Training loop
optimizer = torch.optim.Adam([gstensor.means, gstensor.scales], lr=0.01)

for epoch in range(100):
    optimizer.zero_grad()

    # Unpack for rendering (cleaner API)
    means, scales, quats, opacities, sh0, shN = gstensor.unpack()
    loss = render_gaussians(means, scales, quats, opacities, sh0)

    loss.backward()
    optimizer.step()

# Save optimized results
optimized_data = gstensor.to_gsdata()
gsply.plywrite("optimized.ply", optimized_data.means, optimized_data.scales,
               optimized_data.quats, optimized_data.opacities,
               optimized_data.sh0, optimized_data.shN)
```

--------------------------------

### GPU Acceleration with PyTorch GSTensor (Functional API)

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Employs the functional API of GSTensor for GPU-accelerated tasks. This covers transferring data to the GPU, direct GPU input/output operations for compressed PLY files, and optimized mask operations. It also shows how to enable gradients for training.

```python
from gsply import GSTensor, plyread_gpu, plywrite_gpu

# Transfer to GPU (11x faster with zero-copy base tensor)
gstensor = GSTensor.from_gsdata(data, device="cuda", requires_grad=False)

# Direct GPU I/O
gstensor = plyread_gpu("model.compressed.ply", device="cuda")
plywrite_gpu("output.compressed.ply", gstensor)

# GPU-optimized mask operations (100-1000x faster than CPU)
mask = gstensor.combine_masks(mode="and")
subset = gstensor[mask]

# Enable gradients for training
gstensor_train = GSTensor.from_gsdata(data, device="cuda", requires_grad=True)
```

--------------------------------

### GPU Mask Operations for Performance

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Highlights the substantial performance gains achieved by using GPU-accelerated mask operations compared to their CPU counterparts. This section demonstrates the speed difference for combining masks, showing orders of magnitude improvement.

```python
# CPU: ~1.43ms for 100K Gaussians, 5 layers
mask = data.combine_masks(mode="and")

# GPU: ~0.001ms for 100K Gaussians, 5 layers (1000x faster!)
gstensor = GSTensor.from_gsdata(data, device="cuda")
mask = gstensor.combine_masks(mode="and")
```

--------------------------------

### GSPly Inference Workflow Example

Source: https://github.com/opsiclear/gsply/blob/master/docs/API_REFERENCE.md

An example workflow for performing inference with GSPly. It covers loading a scene, transferring it to the GPU in inference mode, filtering Gaussians based on an opacity threshold, rendering the filtered scene, and saving the result.

```python
import gsply
from gsply import GSTensor
import torch

# Load scene
data = gsply.plyread("scene.ply")

# Transfer to GPU (inference mode, no gradients)
gstensor = GSTensor.from_gsdata(data, device='cuda', requires_grad=False)

# Filter Gaussians by opacity threshold
high_opacity_mask = gstensor.opacities > 0.5
filtered = gstensor[high_opacity_mask]

# Render filtered scene with unpacking
with torch.no_grad():
    means, scales, quats, opacities, sh0, shN = filtered.unpack()
    rendered = render_gaussians(means, scales, quats, opacities, sh0)

# Save filtered version
filtered_data = filtered.to_gsdata()
gsply.plywrite("filtered.ply", filtered_data.means, filtered_data.scales,
               filtered_data.quats, filtered_data.opacities,
               filtered_data.sh0, filtered_data.shN)
```

--------------------------------

### Create and Apply Mask Layers - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Add named mask layers to GSData objects and combine them using boolean logic (AND/OR). Masks persist through slicing, concatenation, and CPU-GPU transfers.

```python
# Add named mask layers
data.add_mask_layer("high_opacity", data.opacities > 0.25)
data.add_mask_layer("foreground", data.means[:, 2] < 0.0)

# Combine with AND logic (both conditions must pass)
filtered = data.apply_masks(mode="and")

# Or combine with OR logic (either condition passes)
visible = data.apply_masks(mode="or", layers=["high_opacity", "foreground"])

# Combine specific layers programmatically
combined_mask = data.combine_masks(mode="and", layers=["high_opacity", "foreground"])
```

--------------------------------

### GPU Acceleration with PyTorch GSTensor (Object-Oriented API)

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Utilizes the recommended object-oriented API of GSTensor for GPU-accelerated operations. This includes direct GPU loading, saving with GPU compression, and format conversions like denormalization and SH to RGB. Requires PyTorch and CUDA enabled GPU.

```python
from gsply import GSTensor

# Direct GPU loading (auto-detects format)
gstensor = GSTensor.load("model.ply", device="cuda")

# Save with GPU compression
gstensor.save("output.compressed.ply")  # GPU compression (default)

# GPU format conversion
gstensor.denormalize()  # GPU-accelerated (uses torch.exp, torch.sigmoid)
gstensor.to_rgb()  # GPU-accelerated SH → RGB conversion
```

--------------------------------

### Save Gaussian Splats with GSData - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Save GSData objects to PLY files with automatic optimization. Supports both uncompressed and compressed formats with GPU acceleration via GSTensor.

```python
from gsply import GSData, GSTensor

# Save uncompressed (auto-optimized)
data.save("output.ply")

# Save compressed format
data.save("output.ply", compressed=True)

# GPU acceleration
gstensor = GSTensor.load("model.ply", device='cuda')
gstensor.save("output.compressed.ply")  # GPU compression (default)
```

--------------------------------

### Read Gaussian Splats with plyread - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Functional API for reading PLY files with auto-detection of compressed or uncompressed formats. Returns GSData object with the same API as object-oriented approach.

```python
from gsply import plyread

# Auto-detects format (compressed or uncompressed)
data = plyread("scene.ply")
```

--------------------------------

### GSPly Compressed PLY Reading Example

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Demonstrates how to read a compressed PLY file using the GSPly library. The `plyread` function automatically detects the compressed format and returns the decompressed Gaussian attributes (means, scales, quaternions, opacities, and SH coefficients). The output data is in the same format as uncompressed PLY data.

```python
import gsply

# Automatically detects compressed format
means, scales, quats, opacities, sh0, shN = gsply.plyread("scene.ply")

print(f"Loaded {means.shape[0]} Gaussians")
# Output: Loaded 50375 Gaussians

# Data is already decompressed and ready to use
# Same format as uncompressed PLY
```

--------------------------------

### Initialize GSData Container and Add Masks

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/api/gsdata.md

This example demonstrates how to initialize a GSData container by reading from a PLY file and subsequently adding named mask layers based on Gaussian properties. It also shows how to filter the data using these masks.

```python
>>> data = plyread("scene.ply")
>>> print(f"Loaded {len(data)} Gaussians")
>>> # Add named mask layers
>>> data.add_mask_layer("high_opacity", data.opacities > 0.5)
>>> data.add_mask_layer("foreground", data.means[:, 2] < 0)
>>> # Combine and apply
>>> filtered = data.apply_masks(mode="and")
```

--------------------------------

### Convert SH to RGB and Back

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Demonstrates converting Spherical Harmonics (SH) data to RGB colors for manipulation and then back to SH format for compatibility with PLY files. This process is essential for applications that require visual representation or specific file format adherence.

```python
data.to_rgb()  # sh0 now contains RGB colors [0, 1]
data.sh0 *= 1.5  # Make brighter (RGB space)
data.to_sh()  # Convert back to SH format for PLY compatibility
```

--------------------------------

### Package Verification Checklist

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

A step-by-step process to verify the gsply package before submitting a pull request. This includes building the package, testing its installation in a clean environment, and running import checks.

```bash
# 1. Build the package
python -m build

# 2. Test installation in clean environment
python -m venv test_env
source test_env/bin/activate  # Windows: test_env\Scripts\activate
pip install dist/gsply-0.1.0-py3-none-any.whl

# 3. Test import
python -c "import gsply; print(f'gsply v{gsply.__version__}')"

# 4. Run tests
pytest tests/ -v

# 5. Deactivate and clean up
deactivate
rm -rf test_env
```

--------------------------------

### GSPLY Write and Read Operations (Python)

Source: https://github.com/opsiclear/gsply/blob/master/benchmarks/QUICK_REFERENCE.md

Demonstrates how to perform read and write operations using the gsply library in Python. It shows examples for achieving maximum speed and space efficiency.

```python
import gsply

# Example for Maximum Speed (Fastest Read)
data = gsply.plyread("model.ply")  # Expected throughput: 70-78 M/s

# Example for Maximum Speed (Fastest Write for 100K+ Gaussians)
gsply.plywrite("out.ply", *data, compressed=True)  # Expected throughput: 26-29 M/s

# Example for Space Efficiency
gsply.plywrite("model.ply", *data, compressed=True)
# This saves the file as "model.compressed.ply"
# Expected file size reduction: 71-74%
# Expected throughput: 4-60 M/s
```

--------------------------------

### Pytest Example for PLY File Reading and Writing

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

Demonstrates how to use the plyread and plywrite functions from the gsply library within pytest. Includes tests for reading SH degree 0 format and a roundtrip consistency check.

```python
import pytest
import numpy as np
from gsply import plyread, plywrite

def test_read_sh0_format():
    """Test reading SH degree 0 format."""
    means, scales, quats, opacities, sh0, shN = plyread("test_sh0.ply")

    assert means.shape[0] > 0
    assert means.shape[1] == 3
    assert shN is None  # SH0 has no higher-order coefficients

def test_write_and_read_roundtrip():
    """Test write-read consistency."""
    # Create test data
    means = np.random.randn(100, 3)
    scales = np.random.randn(100, 3)
    quats = np.random.randn(100, 4)
    opacities = np.random.randn(100)
    sh0 = np.random.randn(100, 3)

    # Write and read
    plywrite("temp.ply", means, scales, quats, opacities, sh0)
    means2, scales2, quats2, opacities2, sh02, shN2 = plyread("temp.ply")

    # Verify
    np.testing.assert_allclose(means, means2, rtol=1e-6)
```

--------------------------------

### Loading Animation Frames with gsply

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Loads multiple animation frames from PLY files for playback. This snippet demonstrates efficient batch reading of sequential frames using a list comprehension.

```python
# Loading 100 frames for playback
frames = [gsply.plyread(f"frame_{i:05d}.ply") for i in range(100)]
```

--------------------------------

### Batch Processing Pipeline with gsply

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Implements a read-process-write pipeline for batch processing a list of PLY files. It reads data, applies a processing function, and writes the results to output files.

```python
# Read, process, write pipeline
for file in ply_files:
    data = gsply.plyread(file)
    processed = process(data)
    gsply.plywrite(output_file, *processed)
```

--------------------------------

### Convert Between PLY and Linear Format - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Convert Gaussian splat data between PLY format (log-scales, logit-opacities) and linear format for computation/visualization. Includes normalize() and denormalize() methods.

```python
from gsply import GSData
import numpy as np

# Load PLY file (contains log-scales and logit-opacities)
data = GSData.load("scene.ply")

# Convert to linear format for computation/visualization
data.denormalize()  # Converts log-scales → linear, logit-opacities → linear
print(f"Linear opacity range: [{data.opacities.min():.3f}, {data.opacities.max():.3f}]")

# Modify in linear space
data.opacities = np.clip(data.opacities * 1.2, 0, 1)

# Convert back to PLY format before saving
data.normalize()  # Converts linear → log-scales, linear → logit-opacities
data.save("modified.ply")
```

--------------------------------

### Manual PyPI Publishing with Twine

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

These bash commands outline the manual steps for publishing a Python package to PyPI using 'twine'. It covers installing 'twine', building the package distributions (wheel and source), uploading to TestPyPI for verification, and finally uploading to the production PyPI. This method is a fallback if automated publishing fails or is not configured.

```bash
# Install twine
pip install twine

# Build distributions
python -m build

# Upload to Test PyPI (recommended first)
python -m twine upload --repository testpypi dist/*

# Test installation from Test PyPI
pip install --index-url https://test.pypi.org/simple/ gsply

# Upload to Production PyPI
python -m twine upload dist/*
```

--------------------------------

### Pre-commit and Testing Commands (Shell)

Source: https://github.com/opsiclear/gsply/blob/master/AGENTS.md

Commands for running pre-commit hooks, the full test suite, and type checking, essential for maintaining code quality and ensuring stability before creating a pull request.

```shell
pre-commit run --all-files
pytest
# Optional type checking:
mypy src/
pre-commit run --hook-stage manual mypy --all-files
```

--------------------------------

### Write Data with plywrite Function - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Functional API for writing PLY files with automatic format detection and optimization. Supports both compressed and uncompressed formats with zero-copy writes when possible.

```python
from gsply import plywrite

# Write uncompressed (auto-optimized)
plywrite("output.ply", data)

# Write compressed format
plywrite("output.ply", data, compressed=True)

# Or use file extension to indicate compression
plywrite("output.compressed.ply", data)
```

--------------------------------

### Quaternion Clamping Example (Python)

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Demonstrates quaternions that fall within and outside the representable range for the smallest-three encoding. Values exceeding [-0.707, 0.707] will be clamped, potentially causing rotation errors.

```python
# This quaternion will have clamping errors:
q = [0.95, 0.05, 0.1, 0.2]  # Component 0 exceeds 0.707

# Well-behaved quaternions work fine:
q = [0.5, 0.5, 0.5, 0.5]  # All components within range
```

--------------------------------

### Contiguity Optimization for Array Operations

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Optimizes array operations by converting data to a contiguous layout, which can significantly speed up subsequent operations. This is recommended for workloads involving numerous array manipulations. The conversion has a one-time cost.

```python
# Check if arrays are contiguous
if not data.is_contiguous():
    # Convert (one-time cost, but 2-45x faster per operation)
    data.make_contiguous(inplace=True)

# Now array operations are much faster
result = data.means.sum() + data.means.max()  # Up to 45x faster!
```

--------------------------------

### Publishing to PyPI Commands

Source: https://github.com/opsiclear/gsply/blob/master/AGENTS.md

Commands for publishing the GSPly package to PyPI, including testing on Test PyPI and then uploading to the production PyPI.

```bash
# Test PyPI
twine upload --repository testpypi dist/*

# Production PyPI
twine upload dist/*
```

--------------------------------

### In-Memory Compression and Decompression - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Compress and decompress Gaussian splat data to/from bytes without disk I/O. Ideal for network transport, streaming, or custom storage backends with 71-74% size reduction.

```python
from gsply import compress_to_bytes, decompress_from_bytes

# Compress to bytes (no disk I/O)
payload = compress_to_bytes(data)

# Decompress from bytes
round_trip = decompress_from_bytes(payload)
assert round_trip.means.shape == data.means.shape
```

--------------------------------

### Bulk Concatenation for Merging Datasets

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Efficiently merges multiple datasets using bulk concatenation, which performs a single allocation and is significantly faster than repeated pairwise operations. This method is ideal for combining several datasets into one.

```python
# Fast: Single allocation (5.74x faster)
combined = GSData.concatenate([data1, data2, data3, ...])

# Slower: Repeated pairwise operations
result = data1
for d in [data2, data3, ...]:
    result = result.add(d)  # Creates intermediate allocations
```

--------------------------------

### GSPly Data Writing and Consolidation Workflow (Python)

Source: https://github.com/opsiclear/gsply/blob/master/benchmarks/BASE_CONSTRUCTION_ANALYSIS.md

Demonstrates recommended usage patterns for reading and writing GSPly data, emphasizing the performance benefits of the consolidate() method for manual consolidation before multiple writes. It also shows automatic optimization when reading directly from a file.

```python
import gsply
from gsply import GSData

# Option A: From file (automatic zero-copy)
data = gsply.plyread("input.ply")
gsply.plywrite("output.ply", data)  # Already optimized!

# Option B: From scratch (manual consolidation for best performance)
data = GSData(means=means, scales=scales, ...)
data = data.consolidate()  # One-time cost, 2.4x faster writes
gsply.plywrite("output1.ply", data)  # Fast!
gsply.plywrite("output2.ply", data)  # Fast!
gsply.plywrite("output3.ply", data)  # Fast!
```

--------------------------------

### Load Gaussian Splats with GSData - Python

Source: https://github.com/opsiclear/gsply/blob/master/docs/source/usage.md

Load Gaussian splat data from PLY files using the object-oriented GSData API which auto-detects compressed or uncompressed formats. Returns NumPy arrays with zero-copy views for efficient memory usage.

```python
from gsply import GSData

# Auto-detects format (compressed or uncompressed)
data = GSData.load("scene.ply")

print(f"Loaded {len(data):,} Gaussians")
print(f"SH degree: {data.get_sh_degree()}")
print(f"Contiguous: {data.is_contiguous()}")
```

--------------------------------

### Build gsply Package

Source: https://github.com/opsiclear/gsply/blob/master/docs/CONTRIBUTING.md

Commands to clean previous builds and create the gsply wheel and source distribution using the `build` package. It also shows how to use convenience build scripts for different operating systems.

```bash
# Clean previous builds
rm -rf build/ dist/ *.egg-info

# Build wheel and source distribution
python -m build

# Or use convenience scripts
./build.sh          # Unix/Linux/Mac
.\build.ps1         # Windows PowerShell
```

--------------------------------

### Hybrid Consolidation Approach with Control Options

Source: https://github.com/opsiclear/gsply/blob/master/benchmarks/BASE_CONSTRUCTION_ANALYSIS.md

Provides both manual and automatic consolidation options with explicit control flags. Allows users to manually consolidate for explicit control, use automatic optimization with optimize=True, or disable optimization when needed.

```python
# Manual (explicit control)
data = data.consolidate()
plywrite("output.ply", data)

# Automatic (convenience)
plywrite("output.ply", data, optimize=True)  # Auto-consolidate

# Or make it default
plywrite("output.ply", data)  # Auto-consolidate by default
plywrite("output.ply", data, optimize=False)  # Skip consolidation
```

--------------------------------

### Visual Analogy: Python Loop vs. Vectorized Processing

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

This visual analogy illustrates the difference in processing efficiency between a traditional Python loop and a vectorized approach. The Python loop processes Gaussians one by one, incurring significant overhead, while the vectorized method processes all Gaussians in a single operation, drastically reducing the total processing time.

```text
Python Loop (Original):
Processing Gaussians:
[G1] -> [process] -> done
[G2] -> [process] -> done
[G3] -> [process] -> done
...
[G50375] -> [process] -> done

Time: ~40ms (one at a time)

Vectorized (Current):
Processing Gaussians:
[G1, G2, G3, ..., G50375] -> [process all] -> done

Time: ~5ms (all at once)
```

--------------------------------

### Access and convert Gaussian Splatting data formats

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Documentation for accessing numpy arrays representing Gaussian Splatting parameters (means, scales, quaternions, opacities, spherical harmonics) and converting between PLY format (log-space scales, logit-space opacities) and linear formats using normalization and color/SH conversion utilities.

```python
# All arrays are returned as numpy arrays with shapes:
# means: (N, 3) - Gaussian centers (x, y, z)
# scales: (N, 3) - Log-space scales (PLY format) or linear scales
# quats: (N, 4) - Rotations as quaternions (w, x, y, z)
# opacities: (N,) - Logit-space opacities (PLY format) or linear opacities
# sh0: (N, 3) - DC spherical harmonic coefficients (SH format) or RGB colors
# shN: (N, K, 3) or None - Higher-order SH coefficients (K=0 for degree 0)

# Format Conversion:
# PLY files store scales in log-space and opacities in logit-space
data.normalize()    # Convert linear → PLY format before saving
data.denormalize()  # Convert PLY → linear format after loading
data.to_rgb()       # Convert SH to RGB colors
data.to_sh()        # Convert RGB to SH format
```

--------------------------------

### Manual GSData Consolidation for Optimized Writing

Source: https://github.com/opsiclear/gsply/blob/master/benchmarks/BASE_CONSTRUCTION_ANALYSIS.md

Creates GSData from individual arrays, consolidates for faster writes, and performs zero-copy write operation. This approach gives users explicit control over memory trade-offs while achieving 2.4x performance improvement over direct writes.

```python
# Create data from individual arrays
data = GSData(means=means, scales=scales, quats=quats, ...)

# Consolidate for faster writes (recommended!)
data = data.consolidate()

# Write with zero-copy (2.4x faster)
plywrite("output.ply", data)
```

--------------------------------

### Read SOG Format Files with Compressed Textures

Source: https://context7.com/opsiclear/gsply/llms.txt

Reads SOG (Splat Octree Graph) format files, which support compressed textures. This requires installing the `sogs` extra dependency (`pip install gsply[sogs]`), which includes `imagecodecs` for WebP decoding. Loaded SOG data is automatically decompressed into the GSData format.

```python
import gsply

# SOG format requires optional dependencies
# Install with: pip install gsply[sogs]
# This installs imagecodecs for WebP decoding

# Read SOG file (includes compressed textures)
data = gsply.sogread("model.sog")
print(f"Loaded {len(data)} Gaussians")

# SOG files are automatically decompressed to GSData format
positions = data.means
colors = data.sh0
scales = data.scales

# All standard GSData operations work
data.denormalize()
data.save("converted.ply")
```

--------------------------------

### Load and save PLY files with Object-Oriented API

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Demonstrates the recommended object-oriented API for reading PLY files (auto-detects format), accessing Gaussian Splatting data fields like positions, colors and scales, and saving files in both uncompressed and compressed formats with optional GPU acceleration.

```python
from gsply import GSData, GSTensor

# Read PLY file (auto-detects format)
data = GSData.load("model.ply")

# Access fields
positions = data.means    # (N, 3) xyz coordinates
colors = data.sh0         # (N, 3) RGB colors
scales = data.scales      # (N, 3) scale parameters

# Save PLY file
data.save("output.ply")  # Uncompressed
data.save("output.ply", compressed=True)  # Compressed (71-74% smaller)

# GPU acceleration (optional)
gstensor = GSTensor.load("model.ply", device='cuda')
gstensor.save("output.compressed.ply")  # GPU compression
```

--------------------------------

### Numba JIT Compilation for Performance (Python)

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Applies Numba's Just-In-Time (JIT) compilation to critical Python functions, such as `_unpack_and_dequantize_vectorized`, to achieve substantial speedups, particularly for the compressed PLY format. Requires the `numba` dependency and is most beneficial for users working heavily with compressed data.

```python
from numba import jit

@jit(nopython=True, fastmath=True)
def _unpack_and_dequantize_vectorized(packed_data, chunk_indices, min_vals, max_vals):
    # Vectorized unpacking with JIT compilation
    # 10-20x faster than pure Python
```

--------------------------------

### PLY Write Function Examples

Source: https://github.com/opsiclear/gsply/blob/master/AGENTS.md

Demonstrates two ways to call the 'plywrite' function: one accepting individual arrays and another accepting an unpacked GSData object.

```python
# Pattern 1: Individual arrays
plywrite("out.ply", means, scales, quats, opacities, sh0, shN)

# Pattern 2: Unpacked GSData
plywrite("out.ply", *data.unpack())
```

--------------------------------

### Real-time Compressed Streaming with gsply

Source: https://github.com/opsiclear/gsply/blob/master/docs/GUIDE.md

Enables real-time decompression and rendering of compressed Gaussian Splatting data. This loop continuously fetches compressed frames, decompresses them using gsply, and renders the resulting Gaussian splats.

```python
# Real-time decompression and rendering
while streaming:
    compressed_frame = fetch_next_frame()
    gaussians = gsply.plyread(compressed_frame)
    render(gaussians)  # 60+ FPS target
```