use rayon::prelude::*;
use thiserror::Error;
#[derive(Debug, Error)]
pub enum CompressionError {
#[error("empty input: at least one Gaussian is required")]
EmptyInput,
#[error("length mismatch for {field}: expected {expected}, got {got}")]
LengthMismatch {
field: &'static str,
expected: usize,
got: usize,
},
#[error("invalid codebook size {size}: {reason}")]
InvalidCodebookSize { size: usize, reason: &'static str },
}
#[derive(Debug, Clone)]
pub struct SceneBounds {
pub min: [f32; 3],
pub max: [f32; 3],
}
impl SceneBounds {
pub fn from_positions(positions: &[[f32; 3]]) -> Option<Self> {
if positions.is_empty() {
return None;
}
let mut mn = positions[0];
let mut mx = positions[0];
for p in positions.iter().skip(1) {
for i in 0..3 {
if p[i] < mn[i] {
mn[i] = p[i];
}
if p[i] > mx[i] {
mx[i] = p[i];
}
}
}
Some(Self { min: mn, max: mx })
}
pub fn expand(mut self, margin: f32) -> Self {
for i in 0..3 {
self.min[i] -= margin;
self.max[i] += margin;
}
self
}
pub fn contains(&self, p: &[f32; 3]) -> bool {
for ((&pv, &mn), &mx) in p.iter().zip(self.min.iter()).zip(self.max.iter()) {
if pv < mn || pv > mx {
return false;
}
}
true
}
}
fn quantize_i16(v: f32, lo: f32, hi: f32) -> i16 {
if (hi - lo).abs() < f32::EPSILON {
return 0;
}
let t = ((v - lo) / (hi - lo)).clamp(0.0, 1.0);
let scaled = t * 65535.0 - 32768.0;
scaled.round().clamp(i16::MIN as f32, i16::MAX as f32) as i16
}
fn dequantize_i16(q: i16, lo: f32, hi: f32) -> f32 {
let t = (q as f32 + 32768.0) / 65535.0;
lo + t * (hi - lo)
}
fn quantize_i8(v: f32) -> i8 {
let t = (v.clamp(-1.0, 1.0) + 1.0) / 2.0; let scaled = t * 255.0 - 128.0;
scaled.round().clamp(i8::MIN as f32, i8::MAX as f32) as i8
}
fn dequantize_i8(q: i8) -> f32 {
let t = (q as f32 + 128.0) / 255.0; t * 2.0 - 1.0
}
fn quantize_u8(v: f32, lo: f32, hi: f32) -> u8 {
if (hi - lo).abs() < f32::EPSILON {
return 128;
}
let t = ((v - lo) / (hi - lo)).clamp(0.0, 1.0);
(t * 255.0).round().clamp(0.0, 255.0) as u8
}
fn dequantize_u8(q: u8, lo: f32, hi: f32) -> f32 {
let t = q as f32 / 255.0;
lo + t * (hi - lo)
}
fn rms_error_f32(a: &[f32], b: &[f32]) -> f32 {
if a.is_empty() {
return 0.0;
}
let mse = a
.iter()
.zip(b.iter())
.map(|(x, y)| (x - y).powi(2))
.sum::<f32>()
/ a.len() as f32;
mse.sqrt()
}
#[derive(Debug, Clone)]
pub struct CompressedPositions {
pub data: Vec<[i16; 3]>,
pub bounds: SceneBounds,
}
impl CompressedPositions {
pub fn compress(positions: &[[f32; 3]], bounds: &SceneBounds) -> Self {
let data = positions
.iter()
.map(|p| {
[
quantize_i16(p[0], bounds.min[0], bounds.max[0]),
quantize_i16(p[1], bounds.min[1], bounds.max[1]),
quantize_i16(p[2], bounds.min[2], bounds.max[2]),
]
})
.collect();
Self {
data,
bounds: bounds.clone(),
}
}
pub fn decompress(&self) -> Vec<[f32; 3]> {
self.data
.iter()
.map(|q| {
[
dequantize_i16(q[0], self.bounds.min[0], self.bounds.max[0]),
dequantize_i16(q[1], self.bounds.min[1], self.bounds.max[1]),
dequantize_i16(q[2], self.bounds.min[2], self.bounds.max[2]),
]
})
.collect()
}
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn bytes(&self) -> usize {
self.data.len() * 6
}
}
#[derive(Debug, Clone)]
pub struct CompressedRotations {
pub data: Vec<[i8; 4]>,
}
impl CompressedRotations {
pub fn compress(rotations: &[[f32; 4]]) -> Self {
let data = rotations
.iter()
.map(|r| {
[
quantize_i8(r[0]),
quantize_i8(r[1]),
quantize_i8(r[2]),
quantize_i8(r[3]),
]
})
.collect();
Self { data }
}
pub fn decompress(&self) -> Vec<[f32; 4]> {
self.data
.iter()
.map(|q| {
let x = dequantize_i8(q[0]);
let y = dequantize_i8(q[1]);
let z = dequantize_i8(q[2]);
let w = dequantize_i8(q[3]);
let n = (x * x + y * y + z * z + w * w).sqrt();
if n < 1e-6 {
[0.0, 0.0, 0.0, 1.0]
} else {
[x / n, y / n, z / n, w / n]
}
})
.collect()
}
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn bytes(&self) -> usize {
self.data.len() * 4
}
}
#[derive(Debug, Clone)]
pub struct CompressedScales {
pub data: Vec<[u8; 3]>,
pub log_min: f32,
pub log_max: f32,
}
impl CompressedScales {
pub fn compress(scales: &[[f32; 3]]) -> Self {
if scales.is_empty() {
return Self {
data: Vec::new(),
log_min: 0.0,
log_max: 0.0,
};
}
let mut log_min = f32::INFINITY;
let mut log_max = f32::NEG_INFINITY;
for s in scales {
for &v in s {
if v < log_min {
log_min = v;
}
if v > log_max {
log_max = v;
}
}
}
let data = scales
.iter()
.map(|s| {
[
quantize_u8(s[0], log_min, log_max),
quantize_u8(s[1], log_min, log_max),
quantize_u8(s[2], log_min, log_max),
]
})
.collect();
Self {
data,
log_min,
log_max,
}
}
pub fn decompress(&self) -> Vec<[f32; 3]> {
self.data
.iter()
.map(|q| {
[
dequantize_u8(q[0], self.log_min, self.log_max),
dequantize_u8(q[1], self.log_min, self.log_max),
dequantize_u8(q[2], self.log_min, self.log_max),
]
})
.collect()
}
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn bytes(&self) -> usize {
self.data.len() * 3
}
}
#[derive(Debug, Clone)]
pub struct CompressedOpacities {
pub data: Vec<u8>,
pub logit_min: f32,
pub logit_max: f32,
}
impl CompressedOpacities {
pub fn compress(opacities: &[f32]) -> Self {
if opacities.is_empty() {
return Self {
data: Vec::new(),
logit_min: 0.0,
logit_max: 0.0,
};
}
let mut logit_min = f32::INFINITY;
let mut logit_max = f32::NEG_INFINITY;
for &v in opacities {
if v < logit_min {
logit_min = v;
}
if v > logit_max {
logit_max = v;
}
}
let data = opacities
.iter()
.map(|&v| quantize_u8(v, logit_min, logit_max))
.collect();
Self {
data,
logit_min,
logit_max,
}
}
pub fn decompress(&self) -> Vec<f32> {
self.data
.iter()
.map(|&q| dequantize_u8(q, self.logit_min, self.logit_max))
.collect()
}
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn bytes(&self) -> usize {
self.data.len()
}
}
#[derive(Debug, Clone)]
pub struct ShCodebook {
pub entries: Vec<Vec<f32>>,
pub sh_len: usize,
}
impl ShCodebook {
pub fn build(sh_coeffs: &[Vec<f32>], k: usize) -> Result<Self, CompressionError> {
if sh_coeffs.is_empty() {
return Err(CompressionError::EmptyInput);
}
if !(2..=256).contains(&k) || (k & (k - 1)) != 0 {
return Err(CompressionError::InvalidCodebookSize {
size: k,
reason: "must be a power of two between 2 and 256",
});
}
let sh_len = sh_coeffs[0].len();
if let Some(bad) = sh_coeffs.iter().position(|v| v.len() != sh_len) {
return Err(CompressionError::LengthMismatch {
field: "sh_coeffs (ragged: per-Gaussian SH vector lengths differ)",
expected: sh_len,
got: sh_coeffs[bad].len(),
});
}
let n = sh_coeffs.len();
let effective_k = k.min(n);
let mean = compute_mean(sh_coeffs, sh_len);
let mut codebook: Vec<Vec<f32>> = vec![mean];
while codebook.len() < effective_k {
let current_len = codebook.len();
let mut new_entries: Vec<Vec<f32>> = Vec::with_capacity(current_len * 2);
for entry in &codebook {
let (a, b) = split_entry(entry);
new_entries.push(a);
new_entries.push(b);
}
codebook = new_entries;
codebook.truncate(effective_k);
codebook = kmeans_refine(sh_coeffs, codebook, sh_len, 20);
}
Ok(Self {
entries: codebook,
sh_len,
})
}
pub fn encode(&self, sh_coeffs: &[Vec<f32>]) -> Vec<u8> {
sh_coeffs
.par_iter()
.map(|v| {
let mut best_idx = 0usize;
let mut best_dist = f32::INFINITY;
for (i, entry) in self.entries.iter().enumerate() {
let d = sq_dist(v, entry);
if d < best_dist {
best_dist = d;
best_idx = i;
}
}
(best_idx & 0xFF) as u8
})
.collect()
}
pub fn decode(&self, indices: &[u8]) -> Vec<Vec<f32>> {
indices
.iter()
.map(|&idx| {
let i = (idx as usize).min(self.entries.len().saturating_sub(1));
self.entries[i].clone()
})
.collect()
}
pub fn bytes(&self) -> usize {
self.entries.len() * self.sh_len * 4
}
}
fn compute_mean(vecs: &[Vec<f32>], sh_len: usize) -> Vec<f32> {
let mut sum = vec![0.0f32; sh_len];
for v in vecs {
for (s, &x) in sum.iter_mut().zip(v.iter()) {
*s += x;
}
}
let n = vecs.len() as f32;
sum.iter().map(|&s| s / n).collect()
}
fn split_entry(entry: &[f32]) -> (Vec<f32>, Vec<f32>) {
const EPS: f32 = 1e-4;
let a = entry.iter().map(|&x| x + EPS).collect();
let b = entry.iter().map(|&x| x - EPS).collect();
(a, b)
}
fn sq_dist(a: &[f32], b: &[f32]) -> f32 {
a.iter()
.zip(b.iter())
.map(|(&x, &y)| (x - y) * (x - y))
.sum()
}
fn assign_to_centroids(data: &[Vec<f32>], codebook: &[Vec<f32>]) -> (Vec<usize>, Vec<f32>) {
let k = codebook.len();
let per_point: Vec<(usize, f32)> = data
.par_iter()
.map(|v| {
let mut best_idx = 0usize;
let mut best_dist = f32::INFINITY;
for (i, entry) in codebook.iter().enumerate() {
let d = sq_dist(v, entry);
if d < best_dist {
best_dist = d;
best_idx = i;
}
}
(best_idx, best_dist)
})
.collect();
let mut assignments = vec![0usize; data.len()];
let mut distortions = vec![0.0f32; k];
for (idx, &(best_idx, best_dist)) in per_point.iter().enumerate() {
assignments[idx] = best_idx;
distortions[best_idx] += best_dist;
}
(assignments, distortions)
}
fn kmeans_refine(
data: &[Vec<f32>],
mut codebook: Vec<Vec<f32>>,
sh_len: usize,
max_iter: usize,
) -> Vec<Vec<f32>> {
let k = codebook.len();
if k == 0 || data.is_empty() {
return codebook;
}
const CONVERGENCE_TOL: f32 = 1e-5;
let mut prev_total_distortion: Option<f32> = None;
for _iter in 0..max_iter {
let (assignments, distortions) = assign_to_centroids(data, &codebook);
let total_distortion: f32 = distortions.iter().sum();
let mut sums: Vec<Vec<f32>> = vec![vec![0.0f32; sh_len]; k];
let mut counts: Vec<usize> = vec![0usize; k];
for (idx, &c) in assignments.iter().enumerate() {
for (s, &x) in sums[c].iter_mut().zip(data[idx].iter()) {
*s += x;
}
counts[c] += 1;
}
let mut changed = false;
let dead_centroid_indices: Vec<usize> = (0..k).filter(|&i| counts[i] == 0).collect();
for dead_idx in dead_centroid_indices {
let donor_cluster = (0..k)
.filter(|&i| counts[i] > 1) .max_by(|&a, &b| {
distortions[a]
.partial_cmp(&distortions[b])
.unwrap_or(std::cmp::Ordering::Equal)
});
if let Some(donor) = donor_cluster {
let farthest_idx = assignments
.iter()
.enumerate()
.filter(|(_, &c)| c == donor)
.max_by(|(ia, _), (ib, _)| {
sq_dist(&data[*ia], &codebook[donor])
.partial_cmp(&sq_dist(&data[*ib], &codebook[donor]))
.unwrap_or(std::cmp::Ordering::Equal)
})
.map(|(i, _)| i);
if let Some(fi) = farthest_idx {
codebook[dead_idx] = data[fi].clone();
changed = true;
}
}
}
for i in 0..k {
if counts[i] == 0 {
continue;
}
let new_centroid: Vec<f32> = sums[i].iter().map(|&s| s / counts[i] as f32).collect();
let delta = sq_dist(&new_centroid, &codebook[i]);
if delta > 1e-10 {
changed = true;
}
codebook[i] = new_centroid;
}
if !changed {
break;
}
if let Some(prev) = prev_total_distortion {
let denom = prev.max(1e-12);
if ((prev - total_distortion).abs() / denom) < CONVERGENCE_TOL {
break;
}
}
prev_total_distortion = Some(total_distortion);
}
codebook
}
#[derive(Debug, Clone)]
pub enum ShCompressed {
Raw(Vec<Vec<f32>>),
Codebook {
codebook: ShCodebook,
indices: Vec<u8>,
},
}
#[derive(Debug, Clone)]
pub struct CompressedGaussianModel {
pub positions: CompressedPositions,
pub rotations: CompressedRotations,
pub scales: CompressedScales,
pub opacities: CompressedOpacities,
pub sh_compressed: ShCompressed,
pub sh_degree: u32,
pub num_gaussians: usize,
}
impl CompressedGaussianModel {
pub fn total_bytes(&self) -> usize {
let sh_bytes = match &self.sh_compressed {
ShCompressed::Raw(raw) => raw.iter().map(|v| v.len() * 4).sum::<usize>(),
ShCompressed::Codebook { codebook, indices } => codebook.bytes() + indices.len(),
};
self.positions.bytes()
+ self.rotations.bytes()
+ self.scales.bytes()
+ self.opacities.bytes()
+ sh_bytes
}
}
#[derive(Debug)]
pub struct DecompressedArrays {
pub positions: Vec<[f32; 3]>,
pub rotations: Vec<[f32; 4]>,
pub scales: Vec<[f32; 3]>,
pub opacities: Vec<f32>,
pub sh_coeffs: Vec<Vec<f32>>,
}
#[derive(Debug, Clone)]
pub struct CompressionConfig {
pub position_margin: f32,
pub use_sh_codebook: bool,
pub sh_codebook_size: usize,
}
impl Default for CompressionConfig {
fn default() -> Self {
Self {
position_margin: 0.1,
use_sh_codebook: true,
sh_codebook_size: 256,
}
}
}
#[derive(Debug, Clone)]
pub struct CompressionStats {
pub original_bytes: usize,
pub compressed_bytes: usize,
pub compression_ratio: f32,
pub position_error_rms: f32,
pub rotation_error_rms: f32,
pub scale_error_rms: f32,
pub opacity_error_rms: f32,
pub sh_error_rms: f32,
}
impl CompressionStats {
pub fn format_summary(&self) -> String {
format!(
"Compression: {:.1}× ({} → {} bytes)\n\
RMS errors — pos: {:.6}, rot: {:.6}, scale: {:.6}, opacity: {:.6}, sh: {:.6}",
self.compression_ratio,
self.original_bytes,
self.compressed_bytes,
self.position_error_rms,
self.rotation_error_rms,
self.scale_error_rms,
self.opacity_error_rms,
self.sh_error_rms,
)
}
}
pub fn compress_gaussians(
positions: &[[f32; 3]],
rotations: &[[f32; 4]],
scales: &[[f32; 3]],
opacities: &[f32],
sh_coeffs: &[Vec<f32>],
sh_degree: u32,
config: &CompressionConfig,
) -> Result<(CompressedGaussianModel, CompressionStats), CompressionError> {
let n = positions.len();
if n == 0 {
return Err(CompressionError::EmptyInput);
}
for (name, got) in [
("rotations", rotations.len()),
("scales", scales.len()),
("opacities", opacities.len()),
] {
if got != n {
return Err(CompressionError::LengthMismatch {
field: name,
expected: n,
got,
});
}
}
if !sh_coeffs.is_empty() && sh_coeffs.len() != n {
return Err(CompressionError::LengthMismatch {
field: "sh_coeffs",
expected: n,
got: sh_coeffs.len(),
});
}
if let Some(bad) = sh_coeffs
.first()
.map(|first| first.len())
.and_then(|sh_len| sh_coeffs.iter().position(|v| v.len() != sh_len))
{
return Err(CompressionError::LengthMismatch {
field: "sh_coeffs (ragged: per-Gaussian SH vector lengths differ)",
expected: sh_coeffs[0].len(),
got: sh_coeffs[bad].len(),
});
}
if config.use_sh_codebook && !sh_coeffs.is_empty() {
let k = config.sh_codebook_size;
if !(2..=256).contains(&k) || (k & (k - 1)) != 0 {
return Err(CompressionError::InvalidCodebookSize {
size: k,
reason: "must be a power of two between 2 and 256",
});
}
}
let sh_len_per = if sh_coeffs.is_empty() {
0
} else {
sh_coeffs[0].len()
};
let original_bytes = (n * 3 + n * 4 + n * 3 + n + n * sh_len_per) * 4;
let bounds = SceneBounds::from_positions(positions)
.ok_or(CompressionError::EmptyInput)?
.expand(config.position_margin);
let comp_pos = CompressedPositions::compress(positions, &bounds);
let comp_rot = CompressedRotations::compress(rotations);
let comp_scales = CompressedScales::compress(scales);
let comp_opacities = CompressedOpacities::compress(opacities);
let sh_compressed = if sh_coeffs.is_empty() {
ShCompressed::Raw(Vec::new())
} else if config.use_sh_codebook {
match ShCodebook::build(sh_coeffs, config.sh_codebook_size) {
Ok(codebook) => {
let indices = codebook.encode(sh_coeffs);
ShCompressed::Codebook { codebook, indices }
}
Err(_) => ShCompressed::Raw(sh_coeffs.to_vec()),
}
} else {
ShCompressed::Raw(sh_coeffs.to_vec())
};
let pos_recon = comp_pos.decompress();
let rot_recon = comp_rot.decompress();
let scale_recon = comp_scales.decompress();
let opacity_recon = comp_opacities.decompress();
let pos_flat_orig: Vec<f32> = positions.iter().flat_map(|p| p.iter().copied()).collect();
let pos_flat_recon: Vec<f32> = pos_recon.iter().flat_map(|p| p.iter().copied()).collect();
let rot_flat_orig: Vec<f32> = rotations.iter().flat_map(|r| r.iter().copied()).collect();
let rot_flat_recon: Vec<f32> = rot_recon.iter().flat_map(|r| r.iter().copied()).collect();
let scale_flat_orig: Vec<f32> = scales.iter().flat_map(|s| s.iter().copied()).collect();
let scale_flat_recon: Vec<f32> = scale_recon.iter().flat_map(|s| s.iter().copied()).collect();
let position_error_rms = rms_error_f32(&pos_flat_orig, &pos_flat_recon);
let rotation_error_rms = rms_error_f32(&rot_flat_orig, &rot_flat_recon);
let scale_error_rms = rms_error_f32(&scale_flat_orig, &scale_flat_recon);
let opacity_error_rms = rms_error_f32(opacities, &opacity_recon);
let sh_error_rms = if sh_coeffs.is_empty() {
0.0
} else {
let sh_recon = match &sh_compressed {
ShCompressed::Raw(raw) => raw.clone(),
ShCompressed::Codebook { codebook, indices } => codebook.decode(indices),
};
let orig_flat: Vec<f32> = sh_coeffs.iter().flat_map(|v| v.iter().copied()).collect();
let recon_flat: Vec<f32> = sh_recon.iter().flat_map(|v| v.iter().copied()).collect();
rms_error_f32(&orig_flat, &recon_flat)
};
let model = CompressedGaussianModel {
positions: comp_pos,
rotations: comp_rot,
scales: comp_scales,
opacities: comp_opacities,
sh_compressed,
sh_degree,
num_gaussians: n,
};
let compressed_bytes = model.total_bytes();
let compression_ratio = if compressed_bytes > 0 {
original_bytes as f32 / compressed_bytes as f32
} else {
1.0
};
let stats = CompressionStats {
original_bytes,
compressed_bytes,
compression_ratio,
position_error_rms,
rotation_error_rms,
scale_error_rms,
opacity_error_rms,
sh_error_rms,
};
Ok((model, stats))
}
pub fn decompress_gaussians(
model: &CompressedGaussianModel,
) -> Result<DecompressedArrays, CompressionError> {
let positions = model.positions.decompress();
let rotations = model.rotations.decompress();
let scales = model.scales.decompress();
let opacities = model.opacities.decompress();
let sh_coeffs = match &model.sh_compressed {
ShCompressed::Raw(raw) => raw.clone(),
ShCompressed::Codebook { codebook, indices } => codebook.decode(indices),
};
let n = model.num_gaussians;
for (field, len) in [
("positions", positions.len()),
("rotations", rotations.len()),
("scales", scales.len()),
("opacities", opacities.len()),
] {
if len != n {
return Err(CompressionError::LengthMismatch {
field,
expected: n,
got: len,
});
}
}
if !sh_coeffs.is_empty() && sh_coeffs.len() != n {
return Err(CompressionError::LengthMismatch {
field: "sh_coeffs",
expected: n,
got: sh_coeffs.len(),
});
}
Ok(DecompressedArrays {
positions,
rotations,
scales,
opacities,
sh_coeffs,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_quantize_i16_roundtrip() {
let lo = -5.0f32;
let hi = 5.0f32;
for &v in &[-5.0f32, -2.5, 0.0, 2.5, 5.0] {
let q = quantize_i16(v, lo, hi);
let r = dequantize_i16(q, lo, hi);
let max_err = (hi - lo) / 65535.0 / 2.0;
assert!(
(v - r).abs() <= max_err + 1e-6,
"i16 roundtrip: orig={v}, recon={r}, max_err={max_err}"
);
}
}
#[test]
fn test_quantize_i8_roundtrip() {
for &v in &[-1.0f32, -0.5, 0.0, 0.5, 1.0] {
let q = quantize_i8(v);
let r = dequantize_i8(q);
assert!((v - r).abs() < 0.0045, "i8 roundtrip: orig={v}, recon={r}");
}
}
#[test]
fn test_quantize_u8_roundtrip() {
let lo = 0.0f32;
let hi = 1.0f32;
for &v in &[0.0f32, 0.25, 0.5, 0.75, 1.0] {
let q = quantize_u8(v, lo, hi);
let r = dequantize_u8(q, lo, hi);
let max_err = (hi - lo) / 255.0 / 2.0;
assert!(
(v - r).abs() <= max_err + 1e-6,
"u8 roundtrip: orig={v}, recon={r}"
);
}
}
#[test]
fn test_scene_bounds_from_positions() {
let positions = vec![[1.0f32, 2.0, 3.0], [-1.0, 0.0, 5.0], [0.5, -2.0, 4.0]];
let bounds = SceneBounds::from_positions(&positions).unwrap();
assert!((bounds.min[0] - (-1.0)).abs() < 1e-6);
assert!((bounds.max[0] - 1.0).abs() < 1e-6);
assert!((bounds.min[1] - (-2.0)).abs() < 1e-6);
assert!((bounds.max[1] - 2.0).abs() < 1e-6);
assert!((bounds.min[2] - 3.0).abs() < 1e-6);
assert!((bounds.max[2] - 5.0).abs() < 1e-6);
}
#[test]
fn test_scene_bounds_from_empty() {
let bounds = SceneBounds::from_positions(&[]);
assert!(bounds.is_none());
}
#[test]
fn test_compress_positions_roundtrip() {
let positions = vec![
[0.0f32, 0.0, 0.0],
[1.0, 2.0, 3.0],
[-1.0, -2.0, -3.0],
[0.5, 1.5, 2.5],
];
let bounds = SceneBounds::from_positions(&positions).unwrap().expand(0.1);
let comp = CompressedPositions::compress(&positions, &bounds);
let recon = comp.decompress();
let range = 10.0f32; let max_err = range / 65535.0 + 1e-4;
for (orig, rec) in positions.iter().zip(recon.iter()) {
for i in 0..3 {
assert!(
(orig[i] - rec[i]).abs() < max_err,
"pos roundtrip axis {i}: orig={}, recon={}",
orig[i],
rec[i]
);
}
}
}
#[test]
fn test_compress_rotations_roundtrip() {
let rotations = vec![
[0.0f32, 0.0, 0.0, 1.0],
[0.5, 0.5, 0.5, 0.5],
[-0.5, 0.5, -0.5, 0.5],
[1.0f32 / 2.0f32.sqrt(), 0.0, 0.0, 1.0f32 / 2.0f32.sqrt()],
];
let comp = CompressedRotations::compress(&rotations);
let recon = comp.decompress();
for (orig, rec) in rotations.iter().zip(recon.iter()) {
for i in 0..4 {
assert!(
(orig[i] - rec[i]).abs() < 0.01,
"rot roundtrip axis {i}: orig={}, recon={}",
orig[i],
rec[i]
);
}
}
}
#[test]
fn test_compress_rotations_decompress_is_normalized() {
let rotations = vec![
[0.0f32, 0.0, 0.0, 1.0],
[0.5, 0.5, 0.5, 0.5],
[-0.5, 0.5, -0.5, 0.5],
[1.0f32 / 2.0f32.sqrt(), 0.0, 0.0, 1.0f32 / 2.0f32.sqrt()],
[0.1, 0.2, 0.3, 0.9],
];
let comp = CompressedRotations::compress(&rotations);
let recon = comp.decompress();
for q in &recon {
let norm = (q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]).sqrt();
assert!(
(norm - 1.0).abs() < 1e-5,
"decompressed quaternion should be unit length, got |q|={norm} for {q:?}"
);
}
}
#[test]
fn test_compress_rotations_decompress_extreme_values_stay_finite_and_normalized() {
let comp = CompressedRotations {
data: vec![[i8::MIN, i8::MIN, i8::MIN, i8::MIN], [0, 0, 0, i8::MIN]],
};
let recon = comp.decompress();
for q in &recon {
let norm = (q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]).sqrt();
for &v in q {
assert!(v.is_finite(), "expected finite component, got {v}");
}
assert!(
(norm - 1.0).abs() < 1e-5,
"expected unit-length fallback/renormalization, got |q|={norm}"
);
}
}
#[test]
fn test_compress_scales_roundtrip() {
let scales = vec![[-3.0f32, -2.0, -1.0], [-0.5, 0.0, 0.5], [1.0, 2.0, 3.0]];
let comp = CompressedScales::compress(&scales);
let recon = comp.decompress();
let range = comp.log_max - comp.log_min;
let max_err = range / 255.0 + 1e-5;
for (orig, rec) in scales.iter().zip(recon.iter()) {
for i in 0..3 {
assert!(
(orig[i] - rec[i]).abs() < max_err,
"scale roundtrip axis {i}: orig={}, recon={}",
orig[i],
rec[i]
);
}
}
}
#[test]
fn test_compress_opacities_roundtrip() {
let opacities = vec![-5.0f32, -2.0, 0.0, 2.0, 5.0];
let comp = CompressedOpacities::compress(&opacities);
let recon = comp.decompress();
let range = comp.logit_max - comp.logit_min;
let max_err = range / 255.0 + 1e-5;
for (orig, rec) in opacities.iter().zip(recon.iter()) {
assert!(
(orig - rec).abs() < max_err,
"opacity roundtrip: orig={orig}, recon={rec}"
);
}
}
#[test]
fn test_sh_codebook_build_simple() {
let sh_coeffs = vec![vec![1.0f32, 0.0, 0.0], vec![0.0f32, 0.0, 1.0]];
let codebook = ShCodebook::build(&sh_coeffs, 2);
assert!(codebook.is_ok());
let cb = codebook.unwrap();
assert_eq!(cb.entries.len(), 2);
assert_eq!(cb.sh_len, 3);
}
#[test]
fn test_sh_codebook_build_rejects_ragged_vectors() {
let sh_coeffs = vec![vec![1.0f32, 0.0, 0.0], vec![0.0f32, 1.0]];
let result = ShCodebook::build(&sh_coeffs, 2);
assert!(matches!(
result,
Err(CompressionError::LengthMismatch { .. })
));
}
#[test]
fn test_sh_codebook_build_doc_range_matches_code() {
let sh_coeffs = vec![vec![1.0f32, 0.0], vec![0.0f32, 1.0]];
assert!(ShCodebook::build(&sh_coeffs, 2).is_ok());
assert!(matches!(
ShCodebook::build(&sh_coeffs, 3),
Err(CompressionError::InvalidCodebookSize { .. })
));
assert!(matches!(
ShCodebook::build(&sh_coeffs, 512),
Err(CompressionError::InvalidCodebookSize { .. })
));
}
#[test]
fn test_sh_codebook_encode_decode() {
let cluster_a = vec![1.0f32, 0.0];
let cluster_b = vec![0.0f32, 1.0];
let mut sh_coeffs: Vec<Vec<f32>> = Vec::new();
for _ in 0..4 {
sh_coeffs.push(cluster_a.clone());
}
for _ in 0..4 {
sh_coeffs.push(cluster_b.clone());
}
let codebook = ShCodebook::build(&sh_coeffs, 2).unwrap();
let indices = codebook.encode(&sh_coeffs);
let decoded = codebook.decode(&indices);
for (orig, dec) in sh_coeffs.iter().zip(decoded.iter()) {
let dist: f32 = orig
.iter()
.zip(dec.iter())
.map(|(a, b)| (a - b).powi(2))
.sum();
assert!(dist.sqrt() < 0.05, "SH decode error too large: {dist}");
}
}
#[test]
fn test_compress_gaussians_full_pipeline() {
let n = 10usize;
let positions: Vec<[f32; 3]> = (0..n)
.map(|i| [i as f32 * 0.1, i as f32 * 0.2, i as f32 * 0.3])
.collect();
let rotations: Vec<[f32; 4]> = (0..n).map(|_| [0.0, 0.0, 0.0, 1.0]).collect();
let scales: Vec<[f32; 3]> = (0..n).map(|i| [-1.0 + i as f32 * 0.1; 3]).collect();
let opacities: Vec<f32> = (0..n).map(|i| i as f32 * 0.1 - 0.5).collect();
let sh_len = 9usize;
let sh_coeffs: Vec<Vec<f32>> = (0..n).map(|_| vec![0.0f32; sh_len]).collect();
let config = CompressionConfig {
use_sh_codebook: false,
..Default::default()
};
let result = compress_gaussians(
&positions, &rotations, &scales, &opacities, &sh_coeffs, 1, &config,
);
assert!(
result.is_ok(),
"compress_gaussians failed: {:?}",
result.err()
);
let (model, stats) = result.unwrap();
assert_eq!(model.num_gaussians, n);
assert!(stats.original_bytes > 0);
assert!(stats.compressed_bytes > 0);
}
#[test]
fn test_compression_stats_ratio() {
let n = 100usize;
let positions: Vec<[f32; 3]> = (0..n).map(|i| [i as f32; 3]).collect();
let rotations: Vec<[f32; 4]> = (0..n).map(|_| [0.0, 0.0, 0.0, 1.0]).collect();
let scales: Vec<[f32; 3]> = (0..n).map(|_| [-1.0, -1.5, -2.0]).collect();
let opacities: Vec<f32> = (0..n).map(|i| i as f32 * 0.02 - 1.0).collect();
let sh_len = 27usize;
let sh_coeffs: Vec<Vec<f32>> = (0..n).map(|i| vec![(i as f32) * 0.01; sh_len]).collect();
let config = CompressionConfig {
sh_codebook_size: 64,
..Default::default()
};
let (_, stats) = compress_gaussians(
&positions, &rotations, &scales, &opacities, &sh_coeffs, 2, &config,
)
.unwrap();
assert!(
stats.compressed_bytes < stats.original_bytes,
"compressed ({}) should be smaller than original ({})",
stats.compressed_bytes,
stats.original_bytes
);
assert!(stats.compression_ratio > 1.0, "ratio should be > 1");
}
#[test]
fn test_compression_stats_format_summary() {
let stats = CompressionStats {
original_bytes: 1000,
compressed_bytes: 250,
compression_ratio: 4.0,
position_error_rms: 0.001,
rotation_error_rms: 0.005,
scale_error_rms: 0.002,
opacity_error_rms: 0.003,
sh_error_rms: 0.010,
};
let s = stats.format_summary();
assert!(s.contains("4.0"), "summary should contain ratio: {s}");
assert!(
s.contains("1000"),
"summary should contain original bytes: {s}"
);
assert!(
s.contains("250"),
"summary should contain compressed bytes: {s}"
);
}
#[test]
fn test_rms_error_helper() {
let a = vec![1.0f32, 2.0, 3.0];
let b = vec![1.1f32, 2.0, 2.9];
let rms = rms_error_f32(&a, &b);
assert!((rms - (0.02f32 / 3.0).sqrt()).abs() < 1e-5, "rms={rms}");
}
#[test]
fn test_rms_error_helper_empty() {
let rms = rms_error_f32(&[], &[]);
assert_eq!(rms, 0.0);
}
#[test]
fn test_empty_input_error() {
let result = compress_gaussians(&[], &[], &[], &[], &[], 0, &Default::default());
assert!(matches!(result, Err(CompressionError::EmptyInput)));
}
#[test]
fn test_length_mismatch_error() {
let positions = vec![[0.0f32; 3]; 3];
let rotations = vec![[0.0f32, 0.0, 0.0, 1.0]; 2]; let scales = vec![[-1.0f32; 3]; 3];
let opacities = vec![0.0f32; 3];
let result = compress_gaussians(
&positions,
&rotations,
&scales,
&opacities,
&[],
0,
&Default::default(),
);
assert!(matches!(
result,
Err(CompressionError::LengthMismatch { .. })
));
}
#[test]
fn test_length_mismatch_error_names_field() {
let positions = vec![[0.0f32; 3]; 3];
let rotations = vec![[0.0f32, 0.0, 0.0, 1.0]; 2]; let scales = vec![[-1.0f32; 3]; 3];
let opacities = vec![0.0f32; 3];
let result = compress_gaussians(
&positions,
&rotations,
&scales,
&opacities,
&[],
0,
&Default::default(),
);
match result {
Err(CompressionError::LengthMismatch { field, .. }) => {
assert_eq!(field, "rotations", "error should name the short array")
}
other => panic!("expected LengthMismatch naming 'rotations', got {other:?}"),
}
}
#[test]
fn test_compress_gaussians_rejects_ragged_sh_vectors() {
let n = 3usize;
let positions: Vec<[f32; 3]> = vec![[0.0; 3]; n];
let rotations: Vec<[f32; 4]> = vec![[0.0, 0.0, 0.0, 1.0]; n];
let scales: Vec<[f32; 3]> = vec![[-1.0; 3]; n];
let opacities: Vec<f32> = vec![0.0; n];
let sh_coeffs: Vec<Vec<f32>> = vec![vec![0.0f32; 9], vec![0.0f32; 6], vec![0.0f32; 9]];
let result = compress_gaussians(
&positions,
&rotations,
&scales,
&opacities,
&sh_coeffs,
1,
&Default::default(),
);
assert!(matches!(
result,
Err(CompressionError::LengthMismatch { .. })
));
}
#[test]
fn test_decompress_gaussians_rejects_truncated_rotations() {
let positions = CompressedPositions::compress(
&[[0.0f32; 3], [1.0, 1.0, 1.0]],
&SceneBounds {
min: [0.0; 3],
max: [1.0; 3],
},
);
let rotations = CompressedRotations::compress(&[[0.0, 0.0, 0.0, 1.0]]); let scales = CompressedScales::compress(&[[-1.0f32; 3], [-1.0; 3]]);
let opacities = CompressedOpacities::compress(&[0.0f32, 0.0]);
let model = CompressedGaussianModel {
positions,
rotations,
scales,
opacities,
sh_compressed: ShCompressed::Raw(Vec::new()),
sh_degree: 0,
num_gaussians: 2,
};
let result = decompress_gaussians(&model);
match result {
Err(CompressionError::LengthMismatch { field, .. }) => {
assert_eq!(field, "rotations")
}
other => panic!("expected LengthMismatch naming 'rotations', got {other:?}"),
}
}
#[test]
fn test_decompress_roundtrip_rms_error_small() {
let n = 50usize;
let positions: Vec<[f32; 3]> = (0..n)
.map(|i| {
let t = i as f32 / n as f32;
[t * 2.0 - 1.0, t * 3.0 - 1.5, t * 4.0 - 2.0]
})
.collect();
let rotations: Vec<[f32; 4]> = (0..n)
.map(|i| {
let t = i as f32 / n as f32;
let q = [t - 0.5, 0.3, -0.2, (1.0f32 - t * 0.1).max(0.1)];
let norm = (q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]).sqrt();
[q[0] / norm, q[1] / norm, q[2] / norm, q[3] / norm]
})
.collect();
let scales: Vec<[f32; 3]> = (0..n)
.map(|i| {
let t = i as f32 / n as f32;
[-3.0 + t * 3.0; 3]
})
.collect();
let opacities: Vec<f32> = (0..n).map(|i| (i as f32 / n as f32) * 6.0 - 3.0).collect();
let sh_len = 9usize;
let sh_coeffs: Vec<Vec<f32>> = (0..n)
.map(|i| (0..sh_len).map(|j| (i + j) as f32 * 0.01).collect())
.collect();
let config = CompressionConfig {
use_sh_codebook: false, ..Default::default()
};
let (model, stats) = compress_gaussians(
&positions, &rotations, &scales, &opacities, &sh_coeffs, 1, &config,
)
.unwrap();
let arrays = decompress_gaussians(&model).unwrap();
assert_eq!(arrays.positions.len(), n);
assert_eq!(arrays.rotations.len(), n);
assert!(
stats.position_error_rms < 0.01,
"position RMS too large: {}",
stats.position_error_rms
);
assert!(
stats.rotation_error_rms < 0.01,
"rotation RMS too large: {}",
stats.rotation_error_rms
);
assert!(
stats.scale_error_rms < 0.05,
"scale RMS too large: {}",
stats.scale_error_rms
);
assert!(
stats.opacity_error_rms < 0.05,
"opacity RMS too large: {}",
stats.opacity_error_rms
);
assert!(
stats.sh_error_rms < 1e-6,
"sh RMS should be near zero: {}",
stats.sh_error_rms
);
}
}