use thiserror::Error;
#[derive(Debug, Error)]
pub enum MipSplattingError {
#[error("Invalid pixel size: {0} (must be positive)")]
InvalidPixelSize(f32),
#[error("Invalid scale: {0} (must be positive)")]
InvalidScale(f32),
#[error("Scale count {scales} does not match position count {positions}")]
CountMismatch { scales: usize, positions: usize },
#[error("Invalid focal length: {0} (must be positive)")]
InvalidFocalLength(f32),
}
#[derive(Debug, Clone, PartialEq)]
pub enum FilterMode {
Gaussian,
Box,
}
#[derive(Debug, Clone)]
pub struct MipCamera {
pub focal_length_x: f32,
pub focal_length_y: f32,
pub image_width: u32,
pub image_height: u32,
pub near_plane: f32,
pub far_plane: f32,
}
impl MipCamera {
pub fn new(fx: f32, fy: f32, width: u32, height: u32) -> Result<Self, MipSplattingError> {
if fx <= 0.0 {
return Err(MipSplattingError::InvalidFocalLength(fx));
}
if fy <= 0.0 {
return Err(MipSplattingError::InvalidFocalLength(fy));
}
Ok(Self {
focal_length_x: fx,
focal_length_y: fy,
image_width: width,
image_height: height,
near_plane: 0.01,
far_plane: 100.0,
})
}
pub fn from_fov(fov_y_rad: f32, width: u32, height: u32) -> Result<Self, MipSplattingError> {
let half_tan = (fov_y_rad * 0.5).tan();
if half_tan <= 0.0 {
return Err(MipSplattingError::InvalidFocalLength(0.0));
}
let fy = (height as f32 * 0.5) / half_tan;
let fx = fy * (width as f32 / height as f32);
Self::new(fx, fy, width, height)
}
pub fn pixel_angular_size(&self) -> f32 {
(1.0_f32 / self.focal_length_x).atan()
}
pub fn pixel_footprint_radius(&self, depth: f32) -> f32 {
depth / self.focal_length_x
}
}
#[derive(Debug, Clone)]
pub struct MipConfig {
pub filter_mode: FilterMode,
pub filter_scale: f32,
pub clamp_to_footprint: bool,
pub max_scale_ratio: f32,
}
impl Default for MipConfig {
fn default() -> Self {
Self {
filter_mode: FilterMode::Gaussian,
filter_scale: 0.3,
clamp_to_footprint: true,
max_scale_ratio: 4.0,
}
}
}
#[derive(Debug, Clone)]
pub struct MipSplattingStats {
pub num_gaussians: usize,
pub num_clamped: usize,
pub mean_scale_ratio: f32,
pub max_scale_ratio: f32,
pub mip_level_histogram: Vec<u32>,
}
pub fn compute_filter_variance(
camera: &MipCamera,
depth: f32,
config: &MipConfig,
) -> Result<f32, MipSplattingError> {
if depth <= 0.0 {
return Err(MipSplattingError::InvalidPixelSize(depth));
}
let footprint = camera.pixel_footprint_radius(depth);
let variance = match config.filter_mode {
FilterMode::Gaussian => {
let sigma = config.filter_scale * footprint;
sigma * sigma
}
FilterMode::Box => {
let sigma = footprint / 12.0_f32.sqrt();
sigma * sigma
}
};
Ok(variance)
}
pub fn adjust_scales_for_mip(
scales_log: &[[f32; 3]],
positions_view: &[[f32; 3]],
camera: &MipCamera,
config: &MipConfig,
) -> Result<Vec<[f32; 3]>, MipSplattingError> {
if scales_log.len() != positions_view.len() {
return Err(MipSplattingError::CountMismatch {
scales: scales_log.len(),
positions: positions_view.len(),
});
}
let mut adjusted = Vec::with_capacity(scales_log.len());
for (scale_log, pos) in scales_log.iter().zip(positions_view.iter()) {
let depth = pos[2].max(camera.near_plane);
let footprint = camera.pixel_footprint_radius(depth);
let sigma_min = footprint * config.filter_scale;
let log_sigma_min = if sigma_min > 0.0 {
sigma_min.ln()
} else {
f32::NEG_INFINITY
};
let max_ratio_log = config.max_scale_ratio.ln();
let mut out = [0.0f32; 3];
for axis in 0..3 {
let original = scale_log[axis];
let mut s = if config.clamp_to_footprint {
original.max(log_sigma_min)
} else {
original
};
s = s.min(original + max_ratio_log);
out[axis] = s;
}
adjusted.push(out);
}
Ok(adjusted)
}
pub fn compute_ewa_filter(
camera: &MipCamera,
position_view: [f32; 3],
config: &MipConfig,
) -> Result<[f32; 4], MipSplattingError> {
let (x, y, z) = (position_view[0], position_view[1], position_view[2]);
if z <= 0.0 {
return Err(MipSplattingError::InvalidPixelSize(z));
}
let depth = z;
let filter_var = compute_filter_variance(camera, depth, config)?;
let fx = camera.focal_length_x;
let fy = camera.focal_length_y;
let z2 = z * z;
let j00 = fx / z;
let j02 = -fx * x / z2;
let j11 = fy / z;
let j12 = -fy * y / z2;
let jjt00 = j00 * j00 + j02 * j02;
let jjt01 = j02 * j12; let jjt11 = j11 * j11 + j12 * j12;
Ok([
filter_var * jjt00,
filter_var * jjt01,
filter_var * jjt01, filter_var * jjt11,
])
}
pub fn compute_mip_level(
depth: f32,
gaussian_scale: f32,
camera: &MipCamera,
max_mip_levels: u32,
) -> Result<u32, MipSplattingError> {
if gaussian_scale <= 0.0 {
return Err(MipSplattingError::InvalidScale(gaussian_scale));
}
let effective_depth = depth.max(camera.near_plane);
let base = camera.focal_length_x * gaussian_scale;
let ratio = effective_depth / base;
let mip_f = if ratio > 0.0 { ratio.log2() } else { 0.0 };
let mip = mip_f.floor().max(0.0) as u32;
Ok(mip.min(max_mip_levels))
}
pub fn compute_mip_levels_batch(
scales_log: &[[f32; 3]],
positions_view: &[[f32; 3]],
camera: &MipCamera,
max_mip_levels: u32,
) -> Result<Vec<u32>, MipSplattingError> {
if scales_log.len() != positions_view.len() {
return Err(MipSplattingError::CountMismatch {
scales: scales_log.len(),
positions: positions_view.len(),
});
}
let mut levels = Vec::with_capacity(scales_log.len());
for (scale_log, pos) in scales_log.iter().zip(positions_view.iter()) {
let mean_log = (scale_log[0] + scale_log[1] + scale_log[2]) / 3.0;
let gaussian_scale = mean_log.exp();
let depth = pos[2].max(camera.near_plane);
let level = compute_mip_level(depth, gaussian_scale, camera, max_mip_levels)?;
levels.push(level);
}
Ok(levels)
}
pub fn compute_mip_stats(
original_scales: &[[f32; 3]],
adjusted_scales: &[[f32; 3]],
mip_levels: &[u32],
) -> MipSplattingStats {
let num_gaussians = original_scales.len();
let mut num_clamped = 0usize;
let mut sum_ratio = 0.0f32;
let mut max_ratio = 1.0f32;
for (orig, adj) in original_scales.iter().zip(adjusted_scales.iter()) {
let mut clamped_this = false;
let mut best_ratio = 1.0f32;
for axis in 0..3 {
let orig_scale = orig[axis].exp();
let adj_scale = adj[axis].exp();
let ratio = if orig_scale > 0.0 {
adj_scale / orig_scale
} else {
1.0
};
if ratio > best_ratio {
best_ratio = ratio;
}
if adj_scale > orig_scale * (1.0 + f32::EPSILON) {
clamped_this = true;
}
}
sum_ratio += best_ratio;
if best_ratio > max_ratio {
max_ratio = best_ratio;
}
if clamped_this {
num_clamped += 1;
}
}
let mean_scale_ratio = if num_gaussians > 0 {
sum_ratio / num_gaussians as f32
} else {
1.0
};
let max_level = mip_levels.iter().copied().max().unwrap_or(0) as usize;
let mut histogram = vec![0u32; max_level + 1];
for &level in mip_levels {
let idx = level as usize;
if idx < histogram.len() {
histogram[idx] += 1;
}
}
MipSplattingStats {
num_gaussians,
num_clamped,
mean_scale_ratio,
max_scale_ratio: max_ratio,
mip_level_histogram: histogram,
}
}
#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
use super::*;
fn test_camera() -> MipCamera {
MipCamera::new(500.0, 500.0, 512, 512).unwrap()
}
fn test_config() -> MipConfig {
MipConfig::default()
}
#[test]
fn test_camera_new_valid() {
let cam = MipCamera::new(500.0, 500.0, 512, 512);
assert!(cam.is_ok());
let cam = cam.unwrap();
assert_eq!(cam.image_width, 512);
assert_eq!(cam.image_height, 512);
assert!((cam.focal_length_x - 500.0).abs() < 1e-6);
}
#[test]
fn test_camera_new_negative_fx() {
let result = MipCamera::new(-1.0, 500.0, 512, 512);
assert!(matches!(result, Err(MipSplattingError::InvalidFocalLength(v)) if v == -1.0));
}
#[test]
fn test_from_fov_60_degrees() {
let fov_y = std::f32::consts::PI / 3.0; let cam = MipCamera::from_fov(fov_y, 1024, 1024).unwrap();
assert!(
(cam.focal_length_y - 886.7).abs() < 1.0,
"fy={}",
cam.focal_length_y
);
}
#[test]
fn test_footprint_radius_depth_1() {
let cam = test_camera();
let r = cam.pixel_footprint_radius(1.0);
assert!((r - 0.002).abs() < 1e-6, "r={}", r);
}
#[test]
fn test_footprint_radius_depth_scaling() {
let cam = test_camera();
let r1 = cam.pixel_footprint_radius(1.0);
let r2 = cam.pixel_footprint_radius(2.0);
assert!((r2 / r1 - 2.0).abs() < 1e-6, "ratio={}", r2 / r1);
}
#[test]
fn test_filter_variance_gaussian_positive() {
let cam = test_camera();
let config = MipConfig {
filter_mode: FilterMode::Gaussian,
..test_config()
};
let v = compute_filter_variance(&cam, 1.0, &config).unwrap();
assert!(v > 0.0, "variance={}", v);
}
#[test]
fn test_filter_variance_box_positive_and_different() {
let cam = test_camera();
let config_g = MipConfig {
filter_mode: FilterMode::Gaussian,
..test_config()
};
let config_b = MipConfig {
filter_mode: FilterMode::Box,
..test_config()
};
let v_gauss = compute_filter_variance(&cam, 1.0, &config_g).unwrap();
let v_box = compute_filter_variance(&cam, 1.0, &config_b).unwrap();
assert!(v_box > 0.0, "box variance={}", v_box);
assert!(
(v_gauss - v_box).abs() > 1e-8,
"should differ: gauss={} box={}",
v_gauss,
v_box
);
}
#[test]
fn test_filter_variance_increases_with_depth() {
let cam = test_camera();
let config = test_config();
let v_near = compute_filter_variance(&cam, 0.1, &config).unwrap();
let v_far = compute_filter_variance(&cam, 10.0, &config).unwrap();
assert!(v_near < v_far, "near={} far={}", v_near, v_far);
}
#[test]
fn test_adjust_scales_large_no_clamping() {
let cam = test_camera();
let config = test_config();
let scales_log = vec![[2.0f32, 2.0, 2.0]];
let positions_view = vec![[0.0f32, 0.0, 1.0]];
let adjusted = adjust_scales_for_mip(&scales_log, &positions_view, &cam, &config).unwrap();
assert_eq!(adjusted.len(), 1);
for axis in 0..3 {
assert!(
(adjusted[0][axis] - scales_log[0][axis]).abs() < 1e-5,
"axis {}: orig={} adj={}",
axis,
scales_log[0][axis],
adjusted[0][axis]
);
}
}
#[test]
fn test_adjust_scales_small_gets_clamped() {
let cam = test_camera();
let config = test_config();
let scales_log = vec![[-10.0f32, -10.0, -10.0]];
let positions_view = vec![[0.0f32, 0.0, 1.0]];
let adjusted = adjust_scales_for_mip(&scales_log, &positions_view, &cam, &config).unwrap();
let any_increased = (0..3).any(|ax| adjusted[0][ax] > scales_log[0][ax] + 1e-6);
assert!(
any_increased,
"expected scale clamping, got {:?}",
adjusted[0]
);
}
#[test]
fn test_adjust_scales_count_mismatch() {
let cam = test_camera();
let config = test_config();
let scales_log = vec![[0.0f32; 3]; 3];
let positions_view = vec![[0.0f32; 3]; 5];
let result = adjust_scales_for_mip(&scales_log, &positions_view, &cam, &config);
assert!(matches!(
result,
Err(MipSplattingError::CountMismatch {
scales: 3,
positions: 5
})
));
}
#[test]
fn test_ewa_filter_off_center() {
let cam = test_camera();
let config = test_config();
let mat = compute_ewa_filter(&cam, [1.0, 1.0, 2.0], &config).unwrap();
assert!(mat[0] > 0.0, "m00 should be positive");
assert!(mat[3] > 0.0, "m11 should be positive");
assert!(
mat[1].abs() > 0.0,
"off-diagonal m01 should be non-zero for off-center"
);
}
#[test]
fn test_ewa_filter_on_axis_diagonal() {
let cam = test_camera();
let config = test_config();
let mat = compute_ewa_filter(&cam, [0.0, 0.0, 1.0], &config).unwrap();
assert!(
mat[1].abs() < 1e-10,
"m01 should be 0 on-axis, got {}",
mat[1]
);
assert!(
mat[2].abs() < 1e-10,
"m10 should be 0 on-axis, got {}",
mat[2]
);
assert!(mat[0] > 0.0, "m00 should be positive");
assert!(mat[3] > 0.0, "m11 should be positive");
}
#[test]
fn test_mip_level_large_scale_is_zero() {
let cam = test_camera();
let level = compute_mip_level(1.0, 10.0, &cam, 8).unwrap();
assert_eq!(level, 0, "expected mip 0 for large scale");
}
#[test]
fn test_mip_level_tiny_scale_clamped() {
let cam = test_camera();
let level = compute_mip_level(100.0, 0.0001, &cam, 8).unwrap();
assert_eq!(level, 8, "expected mip clamped to max=8, got {}", level);
}
#[test]
fn test_mip_levels_batch_length() {
let cam = test_camera();
let n = 7;
let scales_log: Vec<[f32; 3]> = (0..n).map(|_| [0.0f32; 3]).collect();
let positions_view: Vec<[f32; 3]> = (0..n).map(|i| [0.0, 0.0, (i + 1) as f32]).collect();
let levels = compute_mip_levels_batch(&scales_log, &positions_view, &cam, 8).unwrap();
assert_eq!(levels.len(), n);
}
#[test]
fn test_mip_stats_num_clamped() {
let orig = vec![[-5.0f32, -5.0, -5.0], [-5.0, -5.0, -5.0], [2.0, 2.0, 2.0]];
let adj = vec![[-4.0f32, -4.0, -4.0], [-3.0, -3.0, -3.0], [2.0, 2.0, 2.0]];
let mip_levels = vec![0u32, 1, 0];
let stats = compute_mip_stats(&orig, &adj, &mip_levels);
assert_eq!(
stats.num_clamped, 2,
"expected 2 clamped, got {}",
stats.num_clamped
);
}
#[test]
fn test_mip_stats_mean_ratio_at_least_one() {
let cam = test_camera();
let config = test_config();
let scales_log: Vec<[f32; 3]> = vec![[-8.0; 3], [-6.0; 3], [2.0; 3]];
let positions_view: Vec<[f32; 3]> = vec![[0.0, 0.0, 1.0]; 3];
let adjusted = adjust_scales_for_mip(&scales_log, &positions_view, &cam, &config).unwrap();
let mip_levels = vec![0u32; 3];
let stats = compute_mip_stats(&scales_log, &adjusted, &mip_levels);
assert!(
stats.mean_scale_ratio >= 1.0 - 1e-5,
"mean ratio should be ≥ 1, got {}",
stats.mean_scale_ratio
);
}
#[test]
fn test_adjust_scales_max_ratio_clamped() {
let cam = test_camera();
let config = MipConfig {
max_scale_ratio: 2.0, ..test_config()
};
let scales_log = vec![[-20.0f32, -20.0, -20.0]];
let positions_view = vec![[0.0f32, 0.0, 1.0]];
let adjusted = adjust_scales_for_mip(&scales_log, &positions_view, &cam, &config).unwrap();
let max_allowed = -20.0 + 2.0_f32.ln();
for (axis, &val) in adjusted[0].iter().enumerate().take(3) {
assert!(
val <= max_allowed + 1e-5,
"axis {}: expected ≤ {} got {}",
axis,
max_allowed,
val
);
}
}
#[test]
fn test_mip_level_zero_scale_error() {
let cam = test_camera();
let result = compute_mip_level(1.0, 0.0, &cam, 8);
assert!(matches!(result, Err(MipSplattingError::InvalidScale(v)) if v == 0.0));
}
#[test]
fn test_pixel_angular_size_matches_atan_of_inverse_focal() {
let cam = test_camera(); let expected = (1.0_f32 / 500.0).atan();
let got = cam.pixel_angular_size();
assert!(
(got - expected).abs() < 1e-8,
"expected {expected}, got {got}"
);
}
#[test]
fn test_pixel_angular_size_independent_of_image_dimensions() {
let cam_a = MipCamera::new(500.0, 500.0, 100, 100).expect("valid camera");
let cam_b = MipCamera::new(500.0, 500.0, 4000, 3000).expect("valid camera");
assert!(
(cam_a.pixel_angular_size() - cam_b.pixel_angular_size()).abs() < 1e-6,
"angular pixel size must depend only on focal length, not resolution"
);
}
#[test]
fn test_pixel_angular_size_decreases_with_focal_length() {
let narrow_fov = MipCamera::new(2000.0, 2000.0, 512, 512).expect("ok");
let wide_fov = MipCamera::new(200.0, 200.0, 512, 512).expect("ok");
assert!(narrow_fov.pixel_angular_size() < wide_fov.pixel_angular_size());
}
}