mod io;
mod render;
mod spz;
pub use io::SplatError;
pub use threers_splat_sort::DepthSort;
pub use render::{
splat_material, splat_object, splat_sh_degree, SplatOptions, SplatSorter,
DEFAULT_MAX_STORAGE_BYTES, SPLATS_PER_INSTANCE,
};
use crate::math::{Box3, Vector3};
pub const SH_C0: f32 = 0.282_094_8;
pub fn sh_rest_coefficients(degree: u32) -> usize {
let k = (degree.min(3) + 1) as usize;
k * k - 1
}
#[derive(Debug, Clone, Default, PartialEq)]
pub struct GaussianSplats {
pub positions: Vec<[f32; 3]>,
pub scales: Vec<[f32; 3]>,
pub rotations: Vec<[f32; 4]>,
pub opacities: Vec<f32>,
pub colors: Vec<[f32; 3]>,
pub sh_degree: u32,
pub sh: Vec<f32>,
pub antialiased: bool,
}
impl GaussianSplats {
pub fn len(&self) -> usize {
self.positions.len()
}
pub fn is_empty(&self) -> bool {
self.positions.is_empty()
}
pub fn push(
&mut self,
position: Vector3,
scale: [f32; 3],
rotation: [f32; 4],
opacity: f32,
color: [f32; 3],
) {
self.positions.push([position.x, position.y, position.z]);
self.scales.push(scale);
self.rotations.push(normalize_quat(rotation));
self.opacities.push(opacity);
self.colors.push(color);
let rest = sh_rest_coefficients(self.sh_degree) * 3;
self.sh.extend(std::iter::repeat_n(0.0, rest));
}
pub fn validate(&self) -> Result<(), SplatError> {
let n = self.len();
let lens = [
("scales", self.scales.len()),
("rotations", self.rotations.len()),
("opacities", self.opacities.len()),
("colors", self.colors.len()),
];
if self.sh_degree > 3 {
return Err(SplatError::new(format!(
"spherical-harmonic degree {} is past 3",
self.sh_degree
)));
}
let sh_expected = n * sh_rest_coefficients(self.sh_degree) * 3;
if self.sh.len() != sh_expected {
return Err(SplatError::new(format!(
"sh has {} floats, but {n} splats at degree {} need {sh_expected}",
self.sh.len(),
self.sh_degree
)));
}
for (name, len) in lens {
if len != n {
return Err(SplatError::new(format!(
"{name} has {len} entries for {n} positions"
)));
}
}
Ok(())
}
pub fn covariance(&self, i: usize) -> [f32; 6] {
covariance(self.scales[i], self.rotations[i])
}
pub fn bounding_box(&self) -> Box3 {
let mut b = Box3::empty();
for p in &self.positions {
b.expand_by_point(Vector3::new(p[0], p[1], p[2]));
}
b
}
pub fn truncate_sh(&mut self, degree: u32) {
if degree >= self.sh_degree {
return;
}
let from = sh_rest_coefficients(self.sh_degree) * 3;
let to = sh_rest_coefficients(degree) * 3;
self.sh = self
.sh
.chunks_exact(from)
.flat_map(|c| c[..to].iter().copied())
.collect();
self.sh_degree = degree;
}
pub fn framing(&self) -> (Vector3, f32) {
let finite = || self.positions.iter().filter(|p| p.iter().all(|v| v.is_finite()));
if finite().next().is_none() {
return (Vector3::ZERO, 1.0);
}
let at = |v: &mut Vec<f32>, f: f32| {
let k = ((v.len() - 1) as f32 * f) as usize;
*v.select_nth_unstable_by(k, f32::total_cmp).1
};
let median_on = |k: usize| at(&mut finite().map(|p| p[k]).collect(), 0.5);
let c = Vector3::new(median_on(0), median_on(1), median_on(2));
let mut d: Vec<f32> = finite()
.map(|p| (Vector3::new(p[0], p[1], p[2]) - c).length())
.collect();
let (median, p90) = (at(&mut d, 0.5), at(&mut d, 0.9));
let distance = if p90 < 4.0 * median {
2.0 * p90
} else {
1.2 * median
};
(c, distance.max(1e-3))
}
pub fn color_towards(&self, i: usize, dir: Vector3) -> [f32; 3] {
let n = sh_rest_coefficients(self.sh_degree);
let rest = &self.sh[i * n * 3..][..n * 3];
let c = eval_sh(self.colors[i], self.sh_degree, rest, dir.normalize());
c.map(|v| v.max(0.0))
}
}
pub fn covariance(s: [f32; 3], q: [f32; 4]) -> [f32; 6] {
let [x, y, z, w] = normalize_quat(q);
let r = [
[
1.0 - 2.0 * (y * y + z * z),
2.0 * (x * y - w * z),
2.0 * (x * z + w * y),
],
[
2.0 * (x * y + w * z),
1.0 - 2.0 * (x * x + z * z),
2.0 * (y * z - w * x),
],
[
2.0 * (x * z - w * y),
2.0 * (y * z + w * x),
1.0 - 2.0 * (x * x + y * y),
],
];
let m = |i: usize, j: usize| r[i][j] * s[j];
let e = |a: usize, b: usize| (0..3).map(|k| m(a, k) * m(b, k)).sum::<f32>();
[e(0, 0), e(0, 1), e(0, 2), e(1, 1), e(1, 2), e(2, 2)]
}
pub(crate) fn normalize_quat(q: [f32; 4]) -> [f32; 4] {
let len = q.iter().map(|v| v * v).sum::<f32>().sqrt();
if len > 0.0 && len.is_finite() {
q.map(|v| v / len)
} else {
[0.0, 0.0, 0.0, 1.0]
}
}
const SH_C1: f32 = 0.488_602_5;
const SH_C2: [f32; 5] = [1.092_548_4, -1.092_548_4, 0.315_391_57, -1.092_548_4, 0.546_274_2];
const SH_C3: [f32; 7] = [
-0.590_043_6,
2.890_611_4,
-0.457_045_8,
0.373_176_33,
-0.457_045_8,
1.445_305_7,
-0.590_043_6,
];
fn eval_sh(base: [f32; 3], degree: u32, rest: &[f32], d: Vector3) -> [f32; 3] {
let (x, y, z) = (d.x, d.y, d.z);
let mut basis = Vec::with_capacity(15);
if degree >= 1 {
basis.extend([-SH_C1 * y, SH_C1 * z, -SH_C1 * x]);
}
if degree >= 2 {
let (xx, yy, zz) = (x * x, y * y, z * z);
basis.extend([
SH_C2[0] * x * y,
SH_C2[1] * y * z,
SH_C2[2] * (2.0 * zz - xx - yy),
SH_C2[3] * x * z,
SH_C2[4] * (xx - yy),
]);
}
if degree >= 3 {
let (xx, yy, zz) = (x * x, y * y, z * z);
basis.extend([
SH_C3[0] * y * (3.0 * xx - yy),
SH_C3[1] * x * y * z,
SH_C3[2] * y * (4.0 * zz - xx - yy),
SH_C3[3] * z * (2.0 * zz - 3.0 * xx - 3.0 * yy),
SH_C3[4] * x * (4.0 * zz - xx - yy),
SH_C3[5] * z * (xx - yy),
SH_C3[6] * x * (xx - 3.0 * yy),
]);
}
let mut c = base;
for (k, b) in basis.iter().enumerate() {
for ch in 0..3 {
c[ch] += b * rest[k * 3 + ch];
}
}
c
}