sogpy 1.0.1__py3-none-any.whl → 1.0.2__py3-none-any.whl

SogPython/__init__.py

@@ -0,0 +1,13 @@
+"""
+SogPython - Convert Gaussian Splat PLY files to PlayCanvas SOG format.
+
+Usage:
+    from SogPython import convert_ply_to_sog
+    convert_ply_to_sog("input.ply", "output.sog")
+"""
+
+from .sog_writer import convert_ply_to_sog
+from .ply_reader import read_ply
+
+__version__ = "1.0.0"
+__all__ = ["convert_ply_to_sog", "read_ply"]

SogPython/__main__.py

@@ -0,0 +1,6 @@
+"""CLI entry point for SogPython package."""
+
+from .cli import main
+
+if __name__ == '__main__':
+    main()

SogPython/cli.py

@@ -0,0 +1,58 @@
+"""
+SogPython CLI - Convert Gaussian Splat PLY files to PlayCanvas SOG format.
+
+Usage:
+    python -m SogPython input.ply output.sog [--iterations N]
+"""
+
+import argparse
+import sys
+
+from .sog_writer import convert_ply_to_sog
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Convert Gaussian Splat PLY files to PlayCanvas SOG format.',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+    python -m SogPython input.ply output.sog
+    python -m SogPython model.ply model.sog --iterations 20
+    python -m SogPython splat.ply splat.sog --no-bundle
+        '''
+    )
+    
+    parser.add_argument('input', help='Input PLY file path')
+    parser.add_argument('output', help='Output SOG file path')
+    parser.add_argument(
+        '--iterations', '-i',
+        type=int,
+        default=10,
+        help='Number of k-means iterations (default: 10)'
+    )
+    parser.add_argument(
+        '--no-bundle',
+        action='store_true',
+        help='Write separate files instead of ZIP bundle'
+    )
+    
+    args = parser.parse_args()
+    
+    try:
+        convert_ply_to_sog(
+            args.input,
+            args.output,
+            iterations=args.iterations,
+            bundle=not args.no_bundle
+        )
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

SogPython/kmeans.py

@@ -0,0 +1,190 @@
+"""K-means clustering implementation for SOG compression using scipy."""
+
+import numpy as np
+from typing import Tuple
+from scipy.spatial import KDTree
+
+
+def kmeans(data: np.ndarray, k: int, iterations: int = 10) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    K-means clustering using scipy KDTree for efficient nearest neighbor lookup.
+    
+    Args:
+        data: Input data array (n_samples,) or (n_samples, n_features)
+        k: Number of clusters
+        iterations: Number of iterations
+        
+    Returns:
+        Tuple of (centroids, labels)
+        - centroids: (k,) or (k, n_features) array of cluster centers
+        - labels: (n_samples,) array of cluster assignments
+    """
+    data = np.asarray(data, dtype=np.float32)
+    n = len(data)
+    
+    # Handle case where we have fewer points than clusters
+    if n < k:
+        return data.copy(), np.arange(n, dtype=np.uint32)
+    
+    # Ensure 2D for consistent handling
+    is_1d = data.ndim == 1
+    if is_1d:
+        data = data.reshape(-1, 1)
+    
+    n_features = data.shape[1]
+    
+    # Initialize centroids using quantile-based method for 1D, k-means++ style for multi-D
+    if n_features == 1:
+        sorted_data = np.sort(data[:, 0])
+        centroids = np.zeros((k, 1), dtype=np.float32)
+        for i in range(k):
+            quantile = (2 * i + 1) / (2 * k)
+            idx = min(int(quantile * n), n - 1)
+            centroids[i, 0] = sorted_data[idx]
+    else:
+        # Random initialization with reproducibility
+        np.random.seed(42)
+        indices = np.random.choice(n, k, replace=False)
+        centroids = data[indices].copy()
+    
+    labels = np.zeros(n, dtype=np.uint32)
+    
+    # For very large datasets, use batch processing
+    batch_size = 50000
+    
+    for iteration in range(iterations):
+        # Build KDTree for efficient nearest neighbor lookup
+        tree = KDTree(centroids)
+        
+        # Assign labels in batches to reduce memory usage
+        for batch_start in range(0, n, batch_size):
+            batch_end = min(batch_start + batch_size, n)
+            batch = data[batch_start:batch_end]
+            _, batch_labels = tree.query(batch)
+            labels[batch_start:batch_end] = batch_labels
+        
+        # Update centroids using vectorized operations
+        new_centroids = np.zeros_like(centroids)
+        counts = np.zeros(k, dtype=np.int64)
+        
+        # Use bincount for fast aggregation
+        for j in range(n_features):
+            sums = np.bincount(labels, weights=data[:, j], minlength=k)
+            new_centroids[:, j] = sums
+        
+        counts = np.bincount(labels, minlength=k)
+        
+        # Handle empty clusters
+        empty_mask = counts == 0
+        if np.any(empty_mask):
+            # Reinitialize empty clusters
+            empty_indices = np.where(empty_mask)[0]
+            random_points = np.random.choice(n, len(empty_indices), replace=False)
+            new_centroids[empty_indices] = data[random_points]
+            counts[empty_indices] = 1
+        
+        centroids = new_centroids / counts[:, np.newaxis]
+    
+    if is_1d:
+        centroids = centroids.flatten()
+    
+    return centroids.astype(np.float32), labels
+
+
+def cluster_1d(columns: dict, column_names: list, k: int = 256, iterations: int = 10) -> Tuple[np.ndarray, dict]:
+    """
+    Cluster multiple columns as if they were independent 1D datasets.
+    
+    This matches the TypeScript cluster1d function which clusters each column
+    independently but using shared centroids.
+    
+    Args:
+        columns: Dictionary of column name -> data array
+        column_names: Names of columns to cluster
+        k: Number of clusters (default 256)
+        iterations: Number of k-means iterations
+        
+    Returns:
+        Tuple of (centroids, labels_dict)
+        - centroids: (k,) array of centroid values
+        - labels_dict: Dictionary of column name -> labels array (uint8)
+    """
+    # Stack all column data into one 1D array
+    data_list = [columns[name] for name in column_names]
+    n_rows = len(data_list[0])
+    
+    all_data = np.concatenate(data_list)
+    
+    # Run k-means on concatenated data
+    centroids, labels = kmeans(all_data, k, iterations)
+    
+    # Order centroids smallest to largest
+    order = np.argsort(centroids)
+    centroids_sorted = centroids[order]
+    
+    # Create inverse mapping for label reordering
+    inv_order = np.zeros(k, dtype=np.uint32)
+    inv_order[order] = np.arange(k, dtype=np.uint32)
+    
+    # Reorder labels and split back into columns
+    labels_reordered = inv_order[labels].astype(np.uint8)
+    
+    labels_dict = {}
+    for i, name in enumerate(column_names):
+        start = i * n_rows
+        end = (i + 1) * n_rows
+        labels_dict[name] = labels_reordered[start:end]
+    
+    return centroids_sorted, labels_dict
+
+
+def cluster_sh(columns: dict, sh_names: list, k: int, iterations: int = 10) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Cluster spherical harmonics data with a two-level approach.
+    
+    First level: cluster all SH data points into k centroids
+    Second level: quantize the centroids using 256 values
+    
+    Args:
+        columns: Dictionary of column name -> data array
+        sh_names: List of SH coefficient column names
+        k: Number of first-level clusters (palette size)
+        iterations: Number of k-means iterations
+        
+    Returns:
+        Tuple of (labels, centroids_quantized, codebook)
+        - labels: Point -> centroid index (uint16)
+        - centroids_quantized: Quantized centroid values (n_centroids, n_coeffs)
+        - codebook: 256 values for the quantization
+    """
+    n_rows = len(columns[sh_names[0]])
+    n_coeffs = len(sh_names)
+    
+    print(f"  Clustering {n_rows} points in {n_coeffs} dimensions into {k} clusters...")
+    
+    # Stack SH data: (n_rows, n_coeffs)
+    sh_data = np.column_stack([columns[name] for name in sh_names])
+    
+    # First level clustering (reduce iterations for large datasets)
+    effective_iterations = min(iterations, 3) if n_rows > 50000 else iterations
+    centroids, labels = kmeans(sh_data, k, effective_iterations)
+    labels = labels.astype(np.uint16)
+    
+    print(f"  Quantizing {k} centroids with 256-value codebook...")
+    
+    # Second level: quantize the centroids channel-wise
+    all_centroid_values = centroids.flatten()
+    codebook, _ = kmeans(all_centroid_values, 256, iterations)
+    
+    # Order codebook smallest to largest
+    order = np.argsort(codebook)
+    codebook_sorted = codebook[order].astype(np.float32)
+    
+    # Quantize centroids using broadcasting
+    # Find nearest codebook entry for each centroid value
+    diffs = np.abs(centroids.flatten()[:, np.newaxis] - codebook_sorted[np.newaxis, :])
+    quant_indices = np.argmin(diffs, axis=1)
+    
+    centroids_quantized = quant_indices.reshape(k, n_coeffs).astype(np.uint8)
+    
+    return labels, centroids_quantized, codebook_sorted

SogPython/morton_order.py

@@ -0,0 +1,97 @@
+"""Morton order (Z-order curve) sorting for spatial coherence."""
+
+import numpy as np
+from typing import Optional
+
+
+def part1by2(x: np.ndarray) -> np.ndarray:
+    """Spread bits of x by inserting two zeros between each bit."""
+    x = x.astype(np.uint32)
+    x = x & 0x000003ff
+    x = (x ^ (x << 16)) & 0xff0000ff
+    x = (x ^ (x << 8)) & 0x0300f00f
+    x = (x ^ (x << 4)) & 0x030c30c3
+    x = (x ^ (x << 2)) & 0x09249249
+    return x
+
+
+def encode_morton3(x: np.ndarray, y: np.ndarray, z: np.ndarray) -> np.ndarray:
+    """Encode 3D coordinates into Morton code."""
+    return (part1by2(z) << 2) + (part1by2(y) << 1) + part1by2(x)
+
+
+def sort_morton_order(x: np.ndarray, y: np.ndarray, z: np.ndarray, indices: Optional[np.ndarray] = None) -> np.ndarray:
+    """
+    Sort points into Morton/Z-order for better spatial coherence.
+    
+    Args:
+        x, y, z: Position coordinate arrays
+        indices: Optional array of indices to sort (if None, creates 0..n-1)
+        
+    Returns:
+        Sorted indices array
+    """
+    n = len(x)
+    if indices is None:
+        indices = np.arange(n, dtype=np.uint32)
+    else:
+        indices = indices.copy()
+    
+    _sort_morton_recursive(x, y, z, indices)
+    return indices
+
+
+def _sort_morton_recursive(x: np.ndarray, y: np.ndarray, z: np.ndarray, indices: np.ndarray) -> None:
+    """Recursively sort indices by Morton code."""
+    if len(indices) == 0:
+        return
+    
+    # Get values for current indices
+    cx = x[indices]
+    cy = y[indices]
+    cz = z[indices]
+    
+    # Calculate bounds
+    mx, Mx = cx.min(), cx.max()
+    my, My = cy.min(), cy.max()
+    mz, Mz = cz.min(), cz.max()
+    
+    xlen = Mx - mx
+    ylen = My - my
+    zlen = Mz - mz
+    
+    # Check for invalid or identical points
+    if not (np.isfinite(xlen) and np.isfinite(ylen) and np.isfinite(zlen)):
+        return
+    if xlen == 0 and ylen == 0 and zlen == 0:
+        return
+    
+    # Normalize to 0-1023 range
+    xmul = 1024 / xlen if xlen > 0 else 0
+    ymul = 1024 / ylen if ylen > 0 else 0
+    zmul = 1024 / zlen if zlen > 0 else 0
+    
+    ix = np.minimum(1023, ((cx - mx) * xmul)).astype(np.uint32)
+    iy = np.minimum(1023, ((cy - my) * ymul)).astype(np.uint32)
+    iz = np.minimum(1023, ((cz - mz) * zmul)).astype(np.uint32)
+    
+    # Compute Morton codes
+    morton = encode_morton3(ix, iy, iz)
+    
+    # Sort by Morton code
+    order = np.argsort(morton)
+    indices[:] = indices[order]
+    morton = morton[order]
+    
+    # Recursively sort large buckets (same Morton code)
+    start = 0
+    while start < len(indices):
+        end = start + 1
+        while end < len(indices) and morton[end] == morton[start]:
+            end += 1
+        
+        # Only recurse for buckets larger than 256
+        if end - start > 256:
+            _sort_morton_recursive(x, y, z, indices[start:end])
+        
+        start = end

SogPython/ply_reader.py

@@ -0,0 +1,154 @@
+"""PLY file reader for Gaussian Splat data."""
+
+import numpy as np
+from typing import Dict, List, Tuple
+
+
+def get_numpy_dtype(ply_type: str):
+    """Map PLY type names to numpy dtypes."""
+    type_map = {
+        'char': np.int8,
+        'uchar': np.uint8,
+        'short': np.int16,
+        'ushort': np.uint16,
+        'int': np.int32,
+        'uint': np.uint32,
+        'float': np.float32,
+        'double': np.float64,
+    }
+    return type_map.get(ply_type)
+
+
+def parse_ply_header(data: bytes) -> Tuple[Dict, int]:
+    """
+    Parse PLY header and return element definitions and header end position.
+    
+    Returns:
+        Tuple of (header_info, header_end_position)
+        header_info = {'comments': [...], 'elements': [{'name': ..., 'count': ..., 'properties': [...]}]}
+    """
+    # Find end of header
+    header_end = data.find(b'end_header\n')
+    if header_end == -1:
+        header_end = data.find(b'end_header\r\n')
+        end_len = 12
+    else:
+        end_len = 11
+    
+    if header_end == -1:
+        raise ValueError("Invalid PLY file: no end_header found")
+    
+    header_text = data[:header_end].decode('ascii')
+    lines = [l.strip() for l in header_text.split('\n') if l.strip()]
+    
+    # Validate PLY magic
+    if not lines[0].startswith('ply'):
+        raise ValueError("Invalid PLY file: missing 'ply' header")
+    
+    header_info = {
+        'comments': [],
+        'elements': [],
+        'format': 'binary_little_endian'
+    }
+    
+    current_element = None
+    
+    for line in lines[1:]:
+        words = line.split()
+        
+        if words[0] == 'format':
+            header_info['format'] = words[1]
+        elif words[0] == 'comment':
+            header_info['comments'].append(' '.join(words[1:]))
+        elif words[0] == 'element':
+            if len(words) != 3:
+                raise ValueError(f"Invalid element line: {line}")
+            current_element = {
+                'name': words[1],
+                'count': int(words[2]),
+                'properties': []
+            }
+            header_info['elements'].append(current_element)
+        elif words[0] == 'property':
+            if current_element is None or len(words) < 3:
+                raise ValueError(f"Invalid property line: {line}")
+            # Skip list properties (not used in splat data)
+            if words[1] == 'list':
+                continue
+            dtype = get_numpy_dtype(words[1])
+            if dtype is None:
+                raise ValueError(f"Unknown property type: {words[1]}")
+            current_element['properties'].append({
+                'name': words[2],
+                'type': words[1],
+                'dtype': dtype
+            })
+    
+    return header_info, header_end + end_len
+
+
+def read_ply(filepath: str) -> Dict[str, np.ndarray]:
+    """
+    Read a PLY file and return a dictionary of property arrays.
+    
+    Args:
+        filepath: Path to the PLY file
+        
+    Returns:
+        Dictionary mapping property names to numpy arrays
+    """
+    with open(filepath, 'rb') as f:
+        data = f.read()
+    
+    header, data_start = parse_ply_header(data)
+    
+    # Only support binary little endian format
+    if 'binary_little_endian' not in header['format']:
+        raise ValueError(f"Unsupported PLY format: {header['format']}. Only binary_little_endian is supported.")
+    
+    result = {}
+    offset = data_start
+    
+    for element in header['elements']:
+        name = element['name']
+        count = element['count']
+        properties = element['properties']
+        
+        if not properties:
+            continue
+        
+        # Build structured dtype for this element
+        dtype_list = [(p['name'], p['dtype']) for p in properties]
+        element_dtype = np.dtype(dtype_list)
+        
+        # Read element data
+        element_size = element_dtype.itemsize
+        element_data = np.frombuffer(
+            data, 
+            dtype=element_dtype, 
+            count=count, 
+            offset=offset
+        )
+        offset += element_size * count
+        
+        # Store vertex element properties directly
+        if name == 'vertex':
+            for prop in properties:
+                result[prop['name']] = element_data[prop['name']].astype(np.float32)
+    
+    return result
+
+
+def get_splat_data(ply_data: Dict[str, np.ndarray]) -> Dict[str, np.ndarray]:
+    """
+    Organize PLY data into splat data structure.
+    
+    Returns dictionary with:
+        - x, y, z: positions
+        - rot_0, rot_1, rot_2, rot_3: quaternion rotation
+        - scale_0, scale_1, scale_2: scale (log)
+        - f_dc_0, f_dc_1, f_dc_2: DC spherical harmonic (color)
+        - opacity: opacity (logit)
+        - f_rest_0 to f_rest_44: higher order SH (optional)
+    """
+    return ply_data

SogPython/sog_writer.py

@@ -0,0 +1,435 @@
+"""
+SOG (Splat Optimized Graphics) format writer.
+
+Converts Gaussian Splat PLY data to PlayCanvas SOG format using:
+- WebP lossless compression for textures
+- K-means clustering for scale and color data
+- Morton ordering for spatial coherence
+"""
+
+import json
+import math
+import zipfile
+import io
+from pathlib import Path
+from typing import Dict, Optional, List, Tuple
+
+import numpy as np
+from PIL import Image
+
+from .ply_reader import read_ply
+from .morton_order import sort_morton_order
+from .kmeans import cluster_1d, cluster_sh
+from .utils import sigmoid, log_transform
+
+
+# Spherical harmonics coefficient names
+SH_NAMES = [f"f_rest_{i}" for i in range(45)]
+
+
+def encode_webp_lossless(data: np.ndarray, width: int, height: int) -> bytes:
+    """Encode RGBA data as lossless WebP."""
+    # Ensure data is the right shape and type
+    rgba = data.reshape(height, width, 4).astype(np.uint8)
+    image = Image.fromarray(rgba, mode='RGBA')
+    
+    buffer = io.BytesIO()
+    image.save(buffer, format='WEBP', lossless=True)
+    return buffer.getvalue()
+
+
+def calc_min_max(data: Dict[str, np.ndarray], column_names: List[str], indices: np.ndarray) -> List[Tuple[float, float]]:
+    """Calculate min/max for specified columns using only indexed rows."""
+    result = []
+    for name in column_names:
+        values = data[name][indices]
+        result.append((float(values.min()), float(values.max())))
+    return result
+
+
+def write_means(data: Dict[str, np.ndarray], indices: np.ndarray, width: int, height: int) -> Tuple[bytes, bytes, Dict]:
+    """
+    Write position data as two 16-bit WebP textures (low and high bytes).
+    
+    Uses log transform on positions for better precision distribution.
+    """
+    n = len(indices)
+    channels = 4
+    
+    means_l = np.zeros(width * height * channels, dtype=np.uint8)
+    means_u = np.zeros(width * height * channels, dtype=np.uint8)
+    
+    # Calculate min/max with log transform
+    column_names = ['x', 'y', 'z']
+    min_max_raw = calc_min_max(data, column_names, indices)
+    min_max = [(log_transform(np.array([mm[0]]))[0], log_transform(np.array([mm[1]]))[0]) for mm in min_max_raw]
+    
+    x_data = data['x'][indices]
+    y_data = data['y'][indices]
+    z_data = data['z'][indices]
+    
+    for i in range(n):
+        # Apply log transform and normalize to 16-bit
+        x_log = log_transform(np.array([x_data[i]]))[0]
+        y_log = log_transform(np.array([y_data[i]]))[0]
+        z_log = log_transform(np.array([z_data[i]]))[0]
+        
+        x_range = min_max[0][1] - min_max[0][0]
+        y_range = min_max[1][1] - min_max[1][0]
+        z_range = min_max[2][1] - min_max[2][0]
+        
+        x_norm = 65535 * (x_log - min_max[0][0]) / x_range if x_range > 0 else 0
+        y_norm = 65535 * (y_log - min_max[1][0]) / y_range if y_range > 0 else 0
+        z_norm = 65535 * (z_log - min_max[2][0]) / z_range if z_range > 0 else 0
+        
+        x_int = int(max(0, min(65535, x_norm)))
+        y_int = int(max(0, min(65535, y_norm)))
+        z_int = int(max(0, min(65535, z_norm)))
+        
+        ti = i  # layout is identity
+        
+        # Low bytes
+        means_l[ti * 4] = x_int & 0xff
+        means_l[ti * 4 + 1] = y_int & 0xff
+        means_l[ti * 4 + 2] = z_int & 0xff
+        means_l[ti * 4 + 3] = 0xff
+        
+        # High bytes
+        means_u[ti * 4] = (x_int >> 8) & 0xff
+        means_u[ti * 4 + 1] = (y_int >> 8) & 0xff
+        means_u[ti * 4 + 2] = (z_int >> 8) & 0xff
+        means_u[ti * 4 + 3] = 0xff
+    
+    webp_l = encode_webp_lossless(means_l, width, height)
+    webp_u = encode_webp_lossless(means_u, width, height)
+    
+    return webp_l, webp_u, {
+        'mins': [mm[0] for mm in min_max],
+        'maxs': [mm[1] for mm in min_max]
+    }
+
+
+def write_quaternions(data: Dict[str, np.ndarray], indices: np.ndarray, width: int, height: int) -> bytes:
+    """
+    Write quaternion rotation data using smallest-three compression.
+    
+    Stores three components (excluding the largest) in range [-1, 1] scaled by sqrt(2).
+    The alpha channel encodes which component was dropped (252-255).
+    """
+    n = len(indices)
+    channels = 4
+    quats = np.zeros(width * height * channels, dtype=np.uint8)
+    
+    rot_0 = data['rot_0'][indices]
+    rot_1 = data['rot_1'][indices]
+    rot_2 = data['rot_2'][indices]
+    rot_3 = data['rot_3'][indices]
+    
+    sqrt2 = math.sqrt(2)
+    
+    for i in range(n):
+        q = [rot_0[i], rot_1[i], rot_2[i], rot_3[i]]
+        
+        # Normalize
+        length = math.sqrt(sum(c * c for c in q))
+        if length > 0:
+            q = [c / length for c in q]
+        
+        # Find largest component
+        max_comp = max(range(4), key=lambda j: abs(q[j]))
+        
+        # Ensure largest component is positive
+        if q[max_comp] < 0:
+            q = [-c for c in q]
+        
+        # Scale by sqrt(2)
+        q = [c * sqrt2 for c in q]
+        
+        # Get indices of the three smallest components
+        idx_map = {
+            0: [1, 2, 3],
+            1: [0, 2, 3],
+            2: [0, 1, 3],
+            3: [0, 1, 2]
+        }
+        idx = idx_map[max_comp]
+        
+        ti = i
+        quats[ti * 4] = int(255 * (q[idx[0]] * 0.5 + 0.5))
+        quats[ti * 4 + 1] = int(255 * (q[idx[1]] * 0.5 + 0.5))
+        quats[ti * 4 + 2] = int(255 * (q[idx[2]] * 0.5 + 0.5))
+        quats[ti * 4 + 3] = 252 + max_comp
+    
+    return encode_webp_lossless(quats, width, height)
+
+
+def write_scales(data: Dict[str, np.ndarray], indices: np.ndarray, width: int, height: int, iterations: int) -> Tuple[bytes, List[float]]:
+    """
+    Write scale data using k-means clustering to 256 values.
+    """
+    n = len(indices)
+    channels = 4
+    
+    # Cluster scale data
+    column_names = ['scale_0', 'scale_1', 'scale_2']
+    centroids, labels_dict = cluster_1d(data, column_names, 256, iterations)
+    
+    # Build output texture
+    scales_buf = np.zeros(width * height * channels, dtype=np.uint8)
+    
+    for i, idx in enumerate(indices):
+        ti = i
+        scales_buf[ti * 4] = labels_dict['scale_0'][idx]
+        scales_buf[ti * 4 + 1] = labels_dict['scale_1'][idx]
+        scales_buf[ti * 4 + 2] = labels_dict['scale_2'][idx]
+        scales_buf[ti * 4 + 3] = 255
+    
+    return encode_webp_lossless(scales_buf, width, height), centroids.tolist()
+
+
+def write_colors(data: Dict[str, np.ndarray], indices: np.ndarray, width: int, height: int, iterations: int) -> Tuple[bytes, List[float]]:
+    """
+    Write color (DC spherical harmonic) and opacity data.
+    
+    Colors are clustered to 256 values, opacity is stored as sigmoid(raw) in alpha channel.
+    """
+    n = len(indices)
+    channels = 4
+    
+    # Cluster color data
+    column_names = ['f_dc_0', 'f_dc_1', 'f_dc_2']
+    centroids, labels_dict = cluster_1d(data, column_names, 256, iterations)
+    
+    # Calculate sigmoid of opacity
+    opacity_raw = data['opacity']
+    opacity_sigmoid = sigmoid(opacity_raw)
+    opacity_u8 = np.clip(opacity_sigmoid * 255, 0, 255).astype(np.uint8)
+    
+    # Build output texture
+    sh0_buf = np.zeros(width * height * channels, dtype=np.uint8)
+    
+    for i, idx in enumerate(indices):
+        ti = i
+        sh0_buf[ti * 4] = labels_dict['f_dc_0'][idx]
+        sh0_buf[ti * 4 + 1] = labels_dict['f_dc_1'][idx]
+        sh0_buf[ti * 4 + 2] = labels_dict['f_dc_2'][idx]
+        sh0_buf[ti * 4 + 3] = opacity_u8[idx]
+    
+    return encode_webp_lossless(sh0_buf, width, height), centroids.tolist()
+
+
+def write_sh(data: Dict[str, np.ndarray], indices: np.ndarray, width: int, height: int, 
+             sh_bands: int, iterations: int) -> Optional[Dict]:
+    """
+    Write higher-order spherical harmonics data.
+    
+    Uses two-level clustering:
+    1. Cluster all SH points into palette_size centroids
+    2. Quantize centroid values using 256-value codebook
+    """
+    sh_coeffs = {1: 3, 2: 8, 3: 15}[sh_bands]
+    sh_column_names = SH_NAMES[:sh_coeffs * 3]
+    
+    # Check if all SH columns exist
+    for name in sh_column_names:
+        if name not in data:
+            return None
+    
+    n = len(indices)
+    palette_size = min(64 * 1024, max(1024, 2 ** int(math.log2(n / 1024)) * 1024))
+    
+    # Two-level clustering
+    labels, centroids_quantized, codebook = cluster_sh(data, sh_column_names, palette_size, iterations)
+    
+    # Write centroids texture
+    n_centroids = len(centroids_quantized)
+    centroid_width = 64 * sh_coeffs
+    centroid_height = int(math.ceil(n_centroids / 64))
+    
+    centroids_buf = np.zeros(centroid_width * centroid_height * 4, dtype=np.uint8)
+    
+    for i, row in enumerate(centroids_quantized):
+        for j in range(sh_coeffs):
+            # R, G, B channels for each coefficient
+            if j * 3 < len(row):
+                centroids_buf[i * sh_coeffs * 4 + j * 4 + 0] = row[j * 3] if j * 3 < len(row) else 0
+                centroids_buf[i * sh_coeffs * 4 + j * 4 + 1] = row[j * 3 + 1] if j * 3 + 1 < len(row) else 0
+                centroids_buf[i * sh_coeffs * 4 + j * 4 + 2] = row[j * 3 + 2] if j * 3 + 2 < len(row) else 0
+            centroids_buf[i * sh_coeffs * 4 + j * 4 + 3] = 0xff
+    
+    centroids_webp = encode_webp_lossless(centroids_buf, centroid_width, centroid_height)
+    
+    # Write labels texture (16-bit indices)
+    labels_buf = np.zeros(width * height * 4, dtype=np.uint8)
+    
+    for i, idx in enumerate(indices):
+        label = labels[idx]
+        ti = i
+        labels_buf[ti * 4 + 0] = label & 0xff
+        labels_buf[ti * 4 + 1] = (label >> 8) & 0xff
+        labels_buf[ti * 4 + 2] = 0
+        labels_buf[ti * 4 + 3] = 0xff
+    
+    labels_webp = encode_webp_lossless(labels_buf, width, height)
+    
+    return {
+        'count': palette_size,
+        'bands': sh_bands,
+        'codebook': codebook.tolist(),
+        'files': ['shN_centroids.webp', 'shN_labels.webp'],
+        'centroids_webp': centroids_webp,
+        'labels_webp': labels_webp
+    }
+
+
+def detect_sh_bands(data: Dict[str, np.ndarray]) -> int:
+    """Detect how many spherical harmonics bands are present in the data."""
+    # Band 1: f_rest_0 to f_rest_8 (9 coeffs)
+    # Band 2: f_rest_0 to f_rest_23 (24 coeffs)
+    # Band 3: f_rest_0 to f_rest_44 (45 coeffs)
+    
+    for name in SH_NAMES[:9]:
+        if name not in data:
+            return 0
+    # Has at least band 1
+    
+    for name in SH_NAMES[9:24]:
+        if name not in data:
+            return 1
+    # Has at least band 2
+    
+    for name in SH_NAMES[24:45]:
+        if name not in data:
+            return 2
+    
+    return 3
+
+
+def convert_ply_to_sog(input_path: str, output_path: str, iterations: int = 10, bundle: bool = True) -> None:
+    """
+    Convert a Gaussian Splat PLY file to PlayCanvas SOG format.
+    
+    Args:
+        input_path: Path to input .ply file
+        output_path: Path to output .sog file
+        iterations: Number of k-means iterations (default 10)
+        bundle: If True, create a ZIP bundle (default). If False, write separate files.
+    """
+    print(f"Reading PLY file: {input_path}")
+    data = read_ply(input_path)
+    
+    num_rows = len(data['x'])
+    print(f"Loaded {num_rows} splats")
+    
+    # Generate Morton-ordered indices
+    print("Generating Morton order...")
+    indices = sort_morton_order(data['x'], data['y'], data['z'])
+    
+    # Calculate texture dimensions (multiples of 4)
+    width = int(math.ceil(math.sqrt(num_rows) / 4)) * 4
+    height = int(math.ceil(num_rows / width / 4)) * 4
+    print(f"Texture size: {width}x{height}")
+    
+    # Prepare output
+    output_files = {}
+    
+    # Write positions
+    print("Writing positions...")
+    means_l, means_u, means_info = write_means(data, indices, width, height)
+    output_files['means_l.webp'] = means_l
+    output_files['means_u.webp'] = means_u
+    
+    # Write quaternions
+    print("Writing quaternions...")
+    quats_webp = write_quaternions(data, indices, width, height)
+    output_files['quats.webp'] = quats_webp
+    
+    # Write scales
+    print("Compressing scales...")
+    scales_webp, scales_codebook = write_scales(data, indices, width, height, iterations)
+    output_files['scales.webp'] = scales_webp
+    
+    # Write colors
+    print("Compressing colors...")
+    sh0_webp, colors_codebook = write_colors(data, indices, width, height, iterations)
+    output_files['sh0.webp'] = sh0_webp
+    
+    # Write spherical harmonics if present
+    sh_bands = detect_sh_bands(data)
+    sh_info = None
+    if sh_bands > 0:
+        print(f"Compressing spherical harmonics (bands={sh_bands})...")
+        sh_result = write_sh(data, indices, width, height, sh_bands, iterations)
+        if sh_result:
+            output_files['shN_centroids.webp'] = sh_result['centroids_webp']
+            output_files['shN_labels.webp'] = sh_result['labels_webp']
+            sh_info = {
+                'count': sh_result['count'],
+                'bands': sh_result['bands'],
+                'codebook': sh_result['codebook'],
+                'files': sh_result['files']
+            }
+    
+    # Build metadata
+    print("Finalizing...")
+    meta = {
+        'version': 2,
+        'asset': {
+            'generator': 'SogPython v1.0.0'
+        },
+        'count': num_rows,
+        'means': {
+            'mins': means_info['mins'],
+            'maxs': means_info['maxs'],
+            'files': ['means_l.webp', 'means_u.webp']
+        },
+        'scales': {
+            'codebook': scales_codebook,
+            'files': ['scales.webp']
+        },
+        'quats': {
+            'files': ['quats.webp']
+        },
+        'sh0': {
+            'codebook': colors_codebook,
+            'files': ['sh0.webp']
+        }
+    }
+    
+    if sh_info:
+        meta['shN'] = sh_info
+    
+    meta_json = json.dumps(meta, separators=(',', ':')).encode('utf-8')
+    
+    if bundle:
+        # Write as ZIP archive
+        print(f"Writing SOG bundle: {output_path}")
+        with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_STORED) as zf:
+            zf.writestr('meta.json', meta_json)
+            for filename, content in output_files.items():
+                zf.writestr(filename, content)
+    else:
+        # Write separate files
+        output_dir = Path(output_path).parent
+        output_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Write meta.json to the specified output path
+        with open(output_path, 'wb') as f:
+            f.write(meta_json)
+        
+        for filename, content in output_files.items():
+            filepath = output_dir / filename
+            with open(filepath, 'wb') as f:
+                f.write(content)
+            print(f"  Wrote: {filepath}")
+    
+    print("Done!")
+
+
+if __name__ == '__main__':
+    import sys
+    if len(sys.argv) < 3:
+        print("Usage: python -m SogPython.sog_writer input.ply output.sog")
+        sys.exit(1)
+    
+    convert_ply_to_sog(sys.argv[1], sys.argv[2])

SogPython/utils.py

@@ -0,0 +1,13 @@
+"""Math utility functions for SOG conversion."""
+
+import numpy as np
+
+
+def sigmoid(v: np.ndarray) -> np.ndarray:
+    """Apply sigmoid function element-wise."""
+    return 1.0 / (1.0 + np.exp(-v))
+
+
+def log_transform(value: np.ndarray) -> np.ndarray:
+    """Apply log transform: sign(x) * log(|x| + 1)."""
+    return np.sign(value) * np.log(np.abs(value) + 1)

{sogpy-1.0.1.dist-info → sogpy-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sogpy
-Version: 1.0.1
+Version: 1.0.2
 Summary: Convert Gaussian Splat PLY files to PlayCanvas SOG format
 Author: Sai Kiran Nunemunthala
 License: MIT

sogpy-1.0.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+SogPython/__init__.py,sha256=Ti6ObkhdwWcWeYYNCHI1HoItVwRtOtNuogWNeQmDCEs,327
+SogPython/__main__.py,sha256=XoPPTOAhqA6H8hnL3ScskAuG6KlYHG0YNuAVyd7r66s,107
+SogPython/cli.py,sha256=I-cdz24J_aD_l3BIpXEt9O0lnZZmpPUuroqlrN6369E,1505
+SogPython/kmeans.py,sha256=WMCLwoxl4wpnJJVkFiyrx9Bqn_qwEIYTDHcZhBz9eX4,6938
+SogPython/morton_order.py,sha256=VqQR0HgOcwDTEVeNQiffcUxzfwUDstvy0VCpnbFeu0I,2862
+SogPython/ply_reader.py,sha256=uCzbaeeg7gEB7q9Qga-Pq3S20a1TdEWB8B_svA_Trz0,4765
+SogPython/sog_writer.py,sha256=kzEE2w5d-ItfyDicZIhwANFwC0Dxo_1GZdgcx8ezNKE,14797
+SogPython/utils.py,sha256=8Ax_tY0Wi1et3lpUSKo5uA9OVXo0JbTqUrxZ18Qu6qc,359
+sogpy-1.0.2.dist-info/licenses/LICENSE,sha256=mpsXTefte3G1DXWr26libFtoeBCPQ-IP6jKjyGus2JY,1079
+sogpy-1.0.2.dist-info/METADATA,sha256=p7CkUV36BEXVeD0qb_C0sCIzGL3Z7X-ORi2LSkTdX_Q,2775
+sogpy-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+sogpy-1.0.2.dist-info/entry_points.txt,sha256=tyH3YLVEYtnfLxGz2wDRw0sk0PJStagzOad4OcQGc-8,45
+sogpy-1.0.2.dist-info/top_level.txt,sha256=TXTJX_Nz_uzJam-x3xH33S0JBd-MA1DiMqXtLHHdVlw,10
+sogpy-1.0.2.dist-info/RECORD,,

sogpy-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+SogPython

sogpy-1.0.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-sogpy-1.0.1.dist-info/licenses/LICENSE,sha256=mpsXTefte3G1DXWr26libFtoeBCPQ-IP6jKjyGus2JY,1079
-sogpy-1.0.1.dist-info/METADATA,sha256=6fWJB6nnIEHke0AiMD5xv0iAaj_Sd0_t7oT39daSWJY,2775
-sogpy-1.0.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-sogpy-1.0.1.dist-info/entry_points.txt,sha256=tyH3YLVEYtnfLxGz2wDRw0sk0PJStagzOad4OcQGc-8,45
-sogpy-1.0.1.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-sogpy-1.0.1.dist-info/RECORD,,

sogpy-1.0.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-