PanoGS / panogs /core /compression.py
SiddhuG01's picture
Deploy PanoGS Gradio proof of concept
42bed50
Raw History Blame Contribute Delete
6.07 kB
"""
LightGaussian: Unbounded 3D Gaussian Compression and Significance-Based Pruning.
Implements importance-based pruning and distillation techniques (Fan et al., arXiv:2311.17245)
to reduce model size, improve framerates, and remove visual floaters with minimal PSNR/SSIM loss.
"""
from dataclasses import dataclass
from pathlib import Path
from typing import Optional, Tuple, Union
import numpy as np
from panogs.core.gaussian.model import GaussianModel
from panogs.core.logging import get_logger
from panogs.io.gaussian_ply import load_gaussian_ply, save_gaussian_ply, save_gaussian_splat
@dataclass
class CompressionConfig:
"""Configuration for LightGaussian importance-based pruning and compression."""
prune_ratio: float = 0.30 # Fraction of lowest-importance Gaussians to prune (0.0 to 0.8)
min_opacity_threshold: float = 0.02 # Absolute cutoff for low-opacity floaters
volume_weight: float = 1.0 # Weight for 3D spatial volume in significance score
opacity_weight: float = 1.0 # Weight for opacity in significance score
max_scale_clamp: float = 0.5 # Max scale clamp to prune unconstrained giant sky floaters
def compute_gaussian_importance(
model: GaussianModel,
config: Optional[CompressionConfig] = None,
) -> np.ndarray:
"""
Calculate importance/significance score for each Gaussian in the model.
Significance score S_i = (opacity_i ^ opacity_weight) * (Volume_i ^ volume_weight)
Gaussians with near-zero opacity or negligible/degenerate footprint receive low scores.
Args:
model: GaussianModel instance.
config: Compression configuration.
Returns:
np.ndarray: (N,) importance score array in range [0, 1].
"""
if config is None:
config = CompressionConfig()
opacity = np.clip(model.get_opacity().ravel(), 0.0, 1.0)
scales = model.get_scaling() # (N, 3)
# 3D Gaussian Volume: proportional to s_x * s_y * s_z
volume = np.prod(np.clip(scales, 1e-6, 10.0), axis=1)
# Normalize volume to [0, 1] robustly using percentiles to avoid outlier domination
v_min, v_max = np.percentile(volume, 1.0), np.percentile(volume, 99.0)
v_norm = np.clip((volume - v_min) / max(1e-6, v_max - v_min), 1e-4, 1.0)
# Importance formula from LightGaussian:
# S_i = opacity^w_op * volume^w_vol
importance = (opacity ** config.opacity_weight) * (v_norm ** config.volume_weight)
# Penalize unconstrained giant floaters (splats with giant scale but isolated in space)
giant_mask = np.any(scales > config.max_scale_clamp, axis=1)
importance[giant_mask] *= 0.1
# Penalize sub-threshold opacities
low_alpha_mask = opacity < config.min_opacity_threshold
importance[low_alpha_mask] = 0.0
return importance.astype(np.float32)
def prune_gaussians_by_importance(
model: GaussianModel,
prune_ratio: float = 0.30,
min_opacity: float = 0.02,
) -> Tuple[GaussianModel, np.ndarray]:
"""
Prune a fraction of least significant 3D Gaussians.
Args:
model: Input GaussianModel.
prune_ratio: Percentage of Gaussians to prune (0.0 = keep all, 0.5 = keep top 50%).
min_opacity: Hard minimum opacity threshold.
Returns:
Tuple: (pruned GaussianModel, keep_mask boolean array)
"""
logger = get_logger("core.compression")
num_before = model.num_gaussians
if num_before == 0 or prune_ratio <= 0.0:
return model, np.ones(num_before, dtype=bool)
cfg = CompressionConfig(prune_ratio=prune_ratio, min_opacity_threshold=min_opacity)
scores = compute_gaussian_importance(model, cfg)
target_keep_count = max(1, int(num_before * (1.0 - prune_ratio)))
sorted_indices = np.argsort(scores)
keep_indices = sorted_indices[-target_keep_count:]
keep_mask = np.zeros(num_before, dtype=bool)
keep_mask[keep_indices] = True
pruned_model = GaussianModel(
xyz=model._xyz[keep_mask],
scaling_log=model._scaling_log[keep_mask],
rotation_quats=model._rotation_quats[keep_mask],
opacity_logits=model._opacity_logits[keep_mask],
features_dc=model._features_dc[keep_mask],
)
num_after = pruned_model.num_gaussians
pct_saved = ((num_before - num_after) / num_before) * 100
logger.info(
f"LightGaussian Pruning: {num_before:,} -> {num_after:,} splats "
f"({pct_saved:.1f}% reduction, retained {100 - pct_saved:.1f}%)."
)
return pruned_model, keep_mask
def compress_scene(
input_path: Union[str, Path],
output_path: Union[str, Path],
preset: str = "balanced",
save_splat: bool = True,
) -> GaussianModel:
"""
Compress a 3D Gaussian Splatting scene (.ply or .splat) using quality presets.
Presets:
- "crisp": 15% prune ratio, keeps maximum detail and subpixel edges.
- "balanced": 30% prune ratio, optimal quality/speed tradeoff.
- "fast": 50% prune ratio, maximizes WebGL framerates.
Args:
input_path: Path to input .ply or .splat.
output_path: Destination path for compressed model.
preset: "crisp", "balanced", or "fast".
save_splat: Also save binary WebGL .splat file.
Returns:
GaussianModel: Compressed model.
"""
logger = get_logger("core.compression")
input_path = Path(input_path)
output_path = Path(output_path)
preset_ratios = {
"crisp": 0.15,
"balanced": 0.30,
"fast": 0.50,
}
prune_ratio = preset_ratios.get(preset.lower(), 0.30)
logger.info(f"Loading scene {input_path} for compression (preset: {preset})...")
model = load_gaussian_ply(input_path)
compressed_model, _ = prune_gaussians_by_importance(model, prune_ratio=prune_ratio)
save_gaussian_ply(output_path, compressed_model)
logger.info(f"Saved compressed PLY to {output_path}")
if save_splat:
splat_out = output_path.with_suffix(".splat")
save_gaussian_splat(splat_out, compressed_model)
logger.info(f"Saved compressed SPLAT to {splat_out}")
return compressed_model