use nalgebra as na;
use oxigaf_flame::Mesh;
use crate::gaussian::GaussianModel;
use crate::RenderError;
const BINDING_BWD_WORKGROUP_SIZE: u32 = 256;
const FRAME_EPSILON: f32 = 1e-10;
#[derive(Debug)]
pub struct BindingResult {
pub positions: Vec<[f32; 3]>,
pub face_frames: Vec<FaceFrame>,
}
#[derive(Debug, Clone, Copy)]
pub struct FaceFrame {
pub tangent: na::Vector3<f32>,
pub bitangent: na::Vector3<f32>,
pub normal: na::Vector3<f32>,
}
impl FaceFrame {
#[must_use]
pub fn axis_aligned() -> Self {
Self {
tangent: na::Vector3::x(),
bitangent: na::Vector3::y(),
normal: na::Vector3::z(),
}
}
#[must_use]
pub fn from_normal_and_tangent(
normal: na::Vector3<f32>,
tangent_hint: na::Vector3<f32>,
) -> Self {
let normal_len = normal.norm();
if !normal_len.is_finite() || normal_len <= FRAME_EPSILON {
return Self::axis_aligned();
}
let unit_normal = normal / normal_len;
let mut tangent = tangent_hint - unit_normal * unit_normal.dot(&tangent_hint);
let mut tangent_len = tangent.norm();
if !tangent_len.is_finite() || tangent_len <= FRAME_EPSILON {
let nx = unit_normal.x.abs();
let ny = unit_normal.y.abs();
let nz = unit_normal.z.abs();
let axis = if nx <= ny && nx <= nz {
na::Vector3::x()
} else if ny <= nz {
na::Vector3::y()
} else {
na::Vector3::z()
};
tangent = axis - unit_normal * unit_normal.dot(&axis);
tangent_len = tangent.norm();
}
if !tangent_len.is_finite() || tangent_len <= FRAME_EPSILON {
return Self::axis_aligned();
}
let tangent = tangent / tangent_len;
let bitangent = unit_normal.cross(&tangent);
Self {
tangent,
bitangent,
normal: unit_normal,
}
}
}
fn lookup_vertex(
mesh: &Mesh,
vertex_id: u32,
gaussian_index: usize,
) -> Result<&na::Point3<f32>, RenderError> {
mesh.vertices
.get(vertex_id as usize)
.ok_or_else(|| RenderError::InvalidGaussian {
index: gaussian_index,
reason: format!(
"bound face references vertex {vertex_id}, but the mesh has {} vertices",
mesh.vertices.len()
),
})
}
pub fn apply_binding(model: &GaussianModel, mesh: &Mesh) -> Result<BindingResult, RenderError> {
let n = model.len();
if model.face_indices.len() != n {
return Err(RenderError::MismatchedBufferSizes {
expected: n,
actual: model.face_indices.len(),
});
}
if model.barycentric.len() != n {
return Err(RenderError::MismatchedBufferSizes {
expected: n,
actual: model.barycentric.len(),
});
}
if model.local_offsets.len() != n {
return Err(RenderError::MismatchedBufferSizes {
expected: n,
actual: model.local_offsets.len(),
});
}
if n == 0 {
return Ok(BindingResult {
positions: Vec::new(),
face_frames: Vec::new(),
});
}
if mesh.faces.is_empty() || mesh.vertices.is_empty() {
return Err(RenderError::ValidationError(format!(
"FLAME binding requires a non-empty mesh, got {} faces and {} vertices",
mesh.faces.len(),
mesh.vertices.len()
)));
}
let mut positions = Vec::with_capacity(n);
let mut face_frames = Vec::with_capacity(n);
for i in 0..n {
let face_idx = model.face_indices[i] as usize;
let bary = model.barycentric[i];
let offset = model.local_offsets[i];
let face = mesh
.faces
.get(face_idx)
.ok_or_else(|| RenderError::InvalidGaussian {
index: i,
reason: format!(
"bound face index {face_idx} out of range (mesh has {} faces)",
mesh.faces.len()
),
})?;
let v0 = lookup_vertex(mesh, face[0], i)?;
let v1 = lookup_vertex(mesh, face[1], i)?;
let v2 = lookup_vertex(mesh, face[2], i)?;
let base_pos = v0.coords * bary[0] + v1.coords * bary[1] + v2.coords * bary[2];
let edge0 = v1 - v0;
let edge1 = v2 - v0;
let frame = FaceFrame::from_normal_and_tangent(edge0.cross(&edge1), edge0);
let world_offset =
frame.tangent * offset[0] + frame.bitangent * offset[1] + frame.normal * offset[2];
let pos = base_pos + world_offset;
positions.push([pos.x, pos.y, pos.z]);
face_frames.push(frame);
}
Ok(BindingResult {
positions,
face_frames,
})
}
#[must_use]
pub fn build_vertex_frames(mesh: &Mesh) -> Vec<FaceFrame> {
let num_vertices = mesh.vertices.len();
let mut accum_normal = vec![na::Vector3::<f32>::zeros(); num_vertices];
let mut accum_tangent = vec![na::Vector3::<f32>::zeros(); num_vertices];
for face in &mesh.faces {
let i0 = face[0] as usize;
let i1 = face[1] as usize;
let i2 = face[2] as usize;
let (Some(v0), Some(v1), Some(v2)) = (
mesh.vertices.get(i0),
mesh.vertices.get(i1),
mesh.vertices.get(i2),
) else {
continue;
};
let edge0 = v1 - v0;
let edge1 = v2 - v0;
let face_normal = edge0.cross(&edge1);
for &vid in &[i0, i1, i2] {
if let Some(slot) = accum_normal.get_mut(vid) {
*slot += face_normal;
}
if let Some(slot) = accum_tangent.get_mut(vid) {
*slot += edge0;
}
}
}
let use_mesh_normals = mesh.normals.len() == num_vertices;
(0..num_vertices)
.map(|i| {
let mut normal = accum_normal[i];
if use_mesh_normals {
if let Some(mesh_normal) = mesh.normals.get(i) {
let len = mesh_normal.norm();
if len.is_finite() && len > FRAME_EPSILON {
normal = *mesh_normal;
}
}
}
FaceFrame::from_normal_and_tangent(normal, accum_tangent[i])
})
.collect()
}
#[must_use]
pub fn build_face_frames(mesh: &Mesh) -> Vec<FaceFrame> {
mesh.faces
.iter()
.map(|face| {
let (Some(v0), Some(v1), Some(v2)) = (
mesh.vertices.get(face[0] as usize),
mesh.vertices.get(face[1] as usize),
mesh.vertices.get(face[2] as usize),
) else {
return FaceFrame::axis_aligned();
};
let edge0 = v1 - v0;
let edge1 = v2 - v0;
FaceFrame::from_normal_and_tangent(edge0.cross(&edge1), edge0)
})
.collect()
}
pub fn position_regularization(
current_positions: &[[f32; 3]],
binding_positions: &[[f32; 3]],
) -> f32 {
current_positions
.iter()
.zip(binding_positions.iter())
.map(|(cur, bind)| {
let dx = cur[0] - bind[0];
let dy = cur[1] - bind[1];
let dz = cur[2] - bind[2];
dx * dx + dy * dy + dz * dz
})
.sum()
}
pub fn scale_regularization(scales: &[[f32; 3]], max_scale: f32) -> f32 {
scales
.iter()
.map(|s| {
let excess_x = (s[0].exp() - max_scale).max(0.0);
let excess_y = (s[1].exp() - max_scale).max(0.0);
let excess_z = (s[2].exp() - max_scale).max(0.0);
excess_x * excess_x + excess_y * excess_y + excess_z * excess_z
})
.sum()
}
pub fn frame_to_quaternion(frame: &FaceFrame) -> [f32; 4] {
let rot = na::Matrix3::from_columns(&[frame.tangent, frame.bitangent, frame.normal]);
let uq = na::UnitQuaternion::from_rotation_matrix(&na::Rotation3::from_matrix_unchecked(rot));
let q = uq.quaternion();
[q.i, q.j, q.k, q.w]
}
pub fn offset_gradients_cpu(
position_grads: &[[f32; 3]],
vertex_ids: &[u32],
vertex_frames: &[FaceFrame],
) -> Result<Vec<[f32; 3]>, RenderError> {
if vertex_ids.len() != position_grads.len() {
return Err(RenderError::MismatchedBufferSizes {
expected: position_grads.len(),
actual: vertex_ids.len(),
});
}
let mut out = Vec::with_capacity(position_grads.len());
for (i, (&vid, grad)) in vertex_ids.iter().zip(position_grads.iter()).enumerate() {
let frame =
vertex_frames
.get(vid as usize)
.ok_or_else(|| RenderError::InvalidGaussian {
index: i,
reason: format!(
"bound vertex id {vid} out of range ({} vertex frames)",
vertex_frames.len()
),
})?;
if frame.normal.norm() <= 1e-4 {
out.push([0.0, 0.0, 0.0]);
continue;
}
let g = na::Vector3::new(grad[0], grad[1], grad[2]);
out.push([
g.dot(&frame.tangent),
g.dot(&frame.bitangent),
g.dot(&frame.normal),
]);
}
Ok(out)
}
pub struct FlameBindingBuffers {
pub binding_info: wgpu::Buffer,
pub tbn_frames: wgpu::Buffer,
pub position_grads: wgpu::Buffer,
pub offset_grads: wgpu::Buffer,
pub uniforms: wgpu::Buffer,
pub bind_group: wgpu::BindGroup,
num_gaussians: usize,
num_vertices: usize,
}
impl FlameBindingBuffers {
pub fn new(
device: &wgpu::Device,
bind_group_layout: &wgpu::BindGroupLayout,
num_gaussians: usize,
num_vertices: usize,
) -> Self {
use wgpu::util::DeviceExt;
let gaussian_slots = num_gaussians.max(1) as u64;
let vertex_slots = num_vertices.max(1) as u64;
let binding_info = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("flame_binding_info"),
size: gaussian_slots * 16, usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let tbn_frames = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("flame_tbn_frames"),
size: vertex_slots * 48, usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let position_grads = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("flame_position_grads"),
size: gaussian_slots * 16, usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let offset_grads = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("flame_offset_grads"),
size: gaussian_slots * 16,
usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
mapped_at_creation: false,
});
let num_gaussians_u32 = u32::try_from(num_gaussians).unwrap_or(u32::MAX);
let uniforms_data = [num_gaussians_u32, 0, 0, 0]; let uniforms = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
label: Some("flame_binding_uniforms"),
contents: bytemuck::cast_slice(&uniforms_data),
usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
});
let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("flame_binding_bwd_bind_group"),
layout: bind_group_layout,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: uniforms.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 1,
resource: binding_info.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 2,
resource: tbn_frames.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 3,
resource: position_grads.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 4,
resource: offset_grads.as_entire_binding(),
},
],
});
Self {
binding_info,
tbn_frames,
position_grads,
offset_grads,
uniforms,
bind_group,
num_gaussians,
num_vertices,
}
}
#[inline]
#[must_use]
pub fn num_gaussians(&self) -> usize {
self.num_gaussians
}
#[inline]
#[must_use]
pub fn num_vertices(&self) -> usize {
self.num_vertices
}
pub fn update_binding_info(
&self,
queue: &wgpu::Queue,
vertex_ids: &[u32],
) -> Result<(), RenderError> {
if vertex_ids.len() != self.num_gaussians {
return Err(RenderError::MismatchedBufferSizes {
expected: self.num_gaussians,
actual: vertex_ids.len(),
});
}
let mut data = Vec::with_capacity(self.num_gaussians * 4);
for (i, &vid) in vertex_ids.iter().enumerate() {
if vid as usize >= self.num_vertices {
return Err(RenderError::InvalidGaussian {
index: i,
reason: format!(
"bound vertex id {vid} out of range (mesh has {} vertices)",
self.num_vertices
),
});
}
data.extend_from_slice(&[vid, 0, 0, 0]);
}
if !data.is_empty() {
queue.write_buffer(&self.binding_info, 0, bytemuck::cast_slice(&data));
}
Ok(())
}
pub fn update_tbn_frames(
&self,
queue: &wgpu::Queue,
vertex_frames: &[FaceFrame],
) -> Result<(), RenderError> {
if vertex_frames.len() != self.num_vertices {
return Err(RenderError::MismatchedBufferSizes {
expected: self.num_vertices,
actual: vertex_frames.len(),
});
}
let mut data = Vec::with_capacity(vertex_frames.len() * 12);
for frame in vertex_frames {
data.extend_from_slice(&[frame.tangent.x, frame.tangent.y, frame.tangent.z, 0.0]);
data.extend_from_slice(&[frame.bitangent.x, frame.bitangent.y, frame.bitangent.z, 0.0]);
data.extend_from_slice(&[frame.normal.x, frame.normal.y, frame.normal.z, 0.0]);
}
if !data.is_empty() {
queue.write_buffer(&self.tbn_frames, 0, bytemuck::cast_slice(&data));
}
Ok(())
}
pub fn update_position_gradients(
&self,
queue: &wgpu::Queue,
gradients: &[[f32; 3]],
) -> Result<(), RenderError> {
if gradients.len() != self.num_gaussians {
return Err(RenderError::MismatchedBufferSizes {
expected: self.num_gaussians,
actual: gradients.len(),
});
}
let mut data = Vec::with_capacity(self.num_gaussians * 4);
for grad in gradients {
data.extend_from_slice(&[grad[0], grad[1], grad[2], 0.0]);
}
if !data.is_empty() {
queue.write_buffer(&self.position_grads, 0, bytemuck::cast_slice(&data));
}
Ok(())
}
pub fn copy_position_gradients_from(
&self,
encoder: &mut wgpu::CommandEncoder,
src: &wgpu::Buffer,
) -> Result<(), RenderError> {
let required = (self.num_gaussians as u64) * 16;
if required == 0 {
return Ok(());
}
if src.size() < required {
return Err(RenderError::BufferOverflow {
buffer_name: "flame_position_grads".to_string(),
max_size: src.size(),
requested: required,
});
}
encoder.copy_buffer_to_buffer(src, 0, &self.position_grads, 0, required);
Ok(())
}
pub fn record_backward(
&self,
encoder: &mut wgpu::CommandEncoder,
pipeline: &wgpu::ComputePipeline,
) {
self.record_backward_with_timestamps(encoder, pipeline, None);
}
pub fn record_backward_with_timestamps(
&self,
encoder: &mut wgpu::CommandEncoder,
pipeline: &wgpu::ComputePipeline,
timestamp_writes: Option<wgpu::ComputePassTimestampWrites<'_>>,
) {
if self.num_gaussians == 0 {
return;
}
let n = u32::try_from(self.num_gaussians).unwrap_or(u32::MAX);
let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
label: Some("flame_binding_bwd"),
timestamp_writes,
});
pass.set_pipeline(pipeline);
pass.set_bind_group(0, &self.bind_group, &[]);
pass.dispatch_workgroups(n.div_ceil(BINDING_BWD_WORKGROUP_SIZE), 1, 1);
}
pub fn read_offset_gradients(
&self,
device: &wgpu::Device,
queue: &wgpu::Queue,
) -> Result<Vec<[f32; 3]>, RenderError> {
if self.num_gaussians == 0 {
return Ok(Vec::new());
}
let byte_size = (self.num_gaussians as u64) * 16;
let staging = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("flame_offset_grads_staging"),
size: byte_size,
usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
label: Some("flame_offset_grads_readback"),
});
encoder.copy_buffer_to_buffer(&self.offset_grads, 0, &staging, 0, byte_size);
queue.submit(std::iter::once(encoder.finish()));
let slice = staging.slice(..);
let (tx, rx) = std::sync::mpsc::channel();
slice.map_async(wgpu::MapMode::Read, move |result| {
tx.send(result).ok();
});
let _ = device.poll(wgpu::PollType::Wait {
submission_index: None,
timeout: None,
});
rx.recv()
.map_err(|e| RenderError::BufferMapFailed {
buffer_name: "flame_offset_grads".to_string(),
error: format!("Channel recv failed: {e}"),
})?
.map_err(|e| RenderError::BufferMapFailed {
buffer_name: "flame_offset_grads".to_string(),
error: e.to_string(),
})?;
let data = slice
.get_mapped_range()
.map_err(|e| RenderError::BufferMapFailed {
buffer_name: "flame_offset_grads".to_string(),
error: format!("Mapped range failed: {e}"),
})?;
let floats: &[f32] = bytemuck::cast_slice(&data);
let grads: Vec<[f32; 3]> = floats
.chunks_exact(4)
.take(self.num_gaussians)
.map(|c| [c[0], c[1], c[2]])
.collect();
drop(data);
staging.unmap();
Ok(grads)
}
pub fn backward(
&self,
device: &wgpu::Device,
queue: &wgpu::Queue,
pipeline: &wgpu::ComputePipeline,
) -> Result<Vec<[f32; 3]>, RenderError> {
let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
label: Some("flame_binding_backward"),
});
self.record_backward(&mut encoder, pipeline);
queue.submit(std::iter::once(encoder.finish()));
let _ = device.poll(wgpu::PollType::Wait {
submission_index: None,
timeout: None,
});
self.read_offset_gradients(device, queue)
}
pub fn bind_group(&self) -> &wgpu::BindGroup {
&self.bind_group
}
}
#[cfg(test)]
mod tests {
use super::*;
fn unit_triangle_mesh() -> Mesh {
Mesh::new(
vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
na::Point3::new(0.0, 1.0, 0.0),
],
vec![[0, 1, 2]],
)
}
fn model_with_gaussians(n: usize) -> GaussianModel {
GaussianModel {
gaussians: vec![
crate::gaussian::GaussianAttributes {
position: [0.0, 0.0, 0.0],
_pad0: 0.0,
rotation: [0.0, 0.0, 0.0, 1.0],
scale: [0.0, 0.0, 0.0],
opacity: 0.0,
};
n
],
sh_coeffs: vec![0.0; n * 3],
sh_degree: 0,
face_indices: Vec::new(),
barycentric: Vec::new(),
local_offsets: Vec::new(),
is_rigid: Vec::new(),
}
}
#[test]
fn test_position_reg_zero_for_matching() {
let positions = vec![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
let binding = vec![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
assert!((position_regularization(&positions, &binding)).abs() < 1e-10);
}
#[test]
fn test_scale_reg_zero_under_max() {
let scales = vec![[0.0, 0.0, 0.0]];
assert!((scale_regularization(&scales, 2.0)).abs() < 1e-10);
}
#[test]
fn test_apply_binding_missing_arrays_is_error_not_panic() {
let model = model_with_gaussians(3); let mesh = unit_triangle_mesh();
let err = apply_binding(&model, &mesh).expect_err("must reject empty binding arrays");
assert!(matches!(
err,
RenderError::MismatchedBufferSizes {
expected: 3,
actual: 0
}
));
}
#[test]
fn test_apply_binding_empty_mesh_is_error_not_panic() {
let mut model = model_with_gaussians(1);
model.face_indices = vec![0];
model.barycentric = vec![[1.0, 0.0, 0.0]];
model.local_offsets = vec![[0.0, 0.0, 0.0]];
let empty_mesh = Mesh::new(Vec::new(), Vec::new());
let err = apply_binding(&model, &empty_mesh).expect_err("must reject an empty mesh");
assert!(matches!(err, RenderError::ValidationError(_)));
}
#[test]
fn test_apply_binding_out_of_range_face_is_error_not_clamped() {
let mut model = model_with_gaussians(1);
model.face_indices = vec![7]; model.barycentric = vec![[1.0, 0.0, 0.0]];
model.local_offsets = vec![[0.0, 0.0, 0.0]];
let mesh = unit_triangle_mesh();
let err = apply_binding(&model, &mesh).expect_err("must reject out-of-range face index");
assert!(matches!(err, RenderError::InvalidGaussian { index: 0, .. }));
}
#[test]
fn test_apply_binding_out_of_range_vertex_is_error() {
let mut model = model_with_gaussians(1);
model.face_indices = vec![0];
model.barycentric = vec![[1.0, 0.0, 0.0]];
model.local_offsets = vec![[0.0, 0.0, 0.0]];
let mesh = Mesh {
vertices: vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
],
normals: vec![na::Vector3::zeros(); 2],
faces: vec![[0, 1, 9]],
uv_coords: Vec::new(),
};
let err = apply_binding(&model, &mesh).expect_err("must reject out-of-range vertex index");
assert!(matches!(err, RenderError::InvalidGaussian { index: 0, .. }));
}
#[test]
fn test_apply_binding_empty_model_is_ok() {
let model = model_with_gaussians(0);
let mesh = unit_triangle_mesh();
let result = apply_binding(&model, &mesh).expect("empty model binds trivially");
assert!(result.positions.is_empty());
assert!(result.face_frames.is_empty());
}
#[test]
fn test_apply_binding_offset_applied_in_face_frame() {
let mut model = model_with_gaussians(1);
model.face_indices = vec![0];
model.barycentric = vec![[1.0, 0.0, 0.0]]; model.local_offsets = vec![[0.0, 0.0, 2.0]]; let mesh = unit_triangle_mesh();
let result = apply_binding(&model, &mesh).expect("binding");
let p = result.positions[0];
assert!((p[0]).abs() < 1e-6, "x = {}", p[0]);
assert!((p[1]).abs() < 1e-6, "y = {}", p[1]);
assert!((p[2] - 2.0).abs() < 1e-6, "z = {}", p[2]);
assert_eq!(result.face_frames.len(), 1);
}
#[test]
fn test_build_vertex_frames_length_matches_vertex_count() {
let mesh = unit_triangle_mesh();
let frames = build_vertex_frames(&mesh);
assert_eq!(frames.len(), mesh.vertices.len());
for frame in &frames {
assert!((frame.normal.z - 1.0).abs() < 1e-5, "{:?}", frame.normal);
assert!(frame.tangent.dot(&frame.normal).abs() < 1e-5);
assert!((frame.tangent.norm() - 1.0).abs() < 1e-5);
assert!((frame.bitangent.norm() - 1.0).abs() < 1e-5);
}
}
#[test]
fn test_build_face_frames_matches_apply_binding_frames() {
let mesh = unit_triangle_mesh();
let face_frames = build_face_frames(&mesh);
assert_eq!(face_frames.len(), mesh.faces.len());
let mut model = model_with_gaussians(1);
model.face_indices = vec![0];
model.barycentric = vec![[0.5, 0.25, 0.25]];
model.local_offsets = vec![[0.1, 0.2, 0.3]];
let result = apply_binding(&model, &mesh).expect("binding");
let forward = result.face_frames[0];
let table = face_frames[0];
assert!((forward.tangent - table.tangent).norm() < 1e-6);
assert!((forward.bitangent - table.bitangent).norm() < 1e-6);
assert!((forward.normal - table.normal).norm() < 1e-6);
}
#[test]
fn test_build_face_frames_bad_face_gets_fallback() {
let mesh = Mesh {
vertices: vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
],
normals: vec![na::Vector3::zeros(); 2],
faces: vec![[0, 1, 5]],
uv_coords: Vec::new(),
};
let frames = build_face_frames(&mesh);
assert_eq!(frames.len(), 1);
assert!((frames[0].normal.z - 1.0).abs() < 1e-6);
}
#[test]
fn test_build_vertex_frames_independent_of_gaussian_count() {
let mesh = Mesh::new(
vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
na::Point3::new(0.0, 1.0, 0.0),
na::Point3::new(1.0, 1.0, 0.0),
],
vec![[0, 1, 2], [1, 3, 2]],
);
assert_eq!(build_vertex_frames(&mesh).len(), 4);
}
#[test]
fn test_build_vertex_frames_isolated_vertex_gets_fallback() {
let mesh = Mesh::new(
vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
na::Point3::new(0.0, 1.0, 0.0),
na::Point3::new(5.0, 5.0, 5.0),
],
vec![[0, 1, 2]],
);
let frames = build_vertex_frames(&mesh);
assert_eq!(frames.len(), 4);
let isolated = frames[3];
assert!((isolated.tangent.norm() - 1.0).abs() < 1e-5);
assert!((isolated.normal.norm() - 1.0).abs() < 1e-5);
assert!(isolated.tangent.dot(&isolated.normal).abs() < 1e-5);
}
#[test]
fn test_build_vertex_frames_skips_faces_with_bad_indices() {
let mesh = Mesh {
vertices: vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
na::Point3::new(0.0, 1.0, 0.0),
],
normals: vec![na::Vector3::zeros(); 3],
faces: vec![[0, 1, 2], [0, 1, 42]],
uv_coords: Vec::new(),
};
let frames = build_vertex_frames(&mesh);
assert_eq!(frames.len(), 3);
assert!((frames[0].normal.z - 1.0).abs() < 1e-5);
}
#[test]
fn test_offset_gradients_cpu_projects_onto_vertex_frame() {
let mesh = unit_triangle_mesh();
let frames = build_vertex_frames(&mesh);
let vertex_ids = vec![2u32, 0u32];
let grads = vec![[0.0, 0.0, 1.0], [0.0, 0.0, -3.0]];
let out = offset_gradients_cpu(&grads, &vertex_ids, &frames).expect("projection");
assert_eq!(out.len(), 2);
assert!((out[0][2] - 1.0).abs() < 1e-5, "{:?}", out[0]);
assert!(out[0][0].abs() < 1e-5 && out[0][1].abs() < 1e-5);
assert!((out[1][2] + 3.0).abs() < 1e-5, "{:?}", out[1]);
}
#[test]
fn test_offset_gradients_cpu_rejects_length_mismatch() {
let frames = build_vertex_frames(&unit_triangle_mesh());
let err = offset_gradients_cpu(&[[1.0, 0.0, 0.0]], &[], &frames)
.expect_err("length mismatch must error");
assert!(matches!(err, RenderError::MismatchedBufferSizes { .. }));
}
#[test]
fn test_offset_gradients_cpu_rejects_out_of_range_vertex() {
let frames = build_vertex_frames(&unit_triangle_mesh());
let err = offset_gradients_cpu(&[[1.0, 0.0, 0.0]], &[99], &frames)
.expect_err("out-of-range vertex id must error");
assert!(matches!(err, RenderError::InvalidGaussian { index: 0, .. }));
}
#[test]
fn test_offset_gradients_are_the_adjoint_of_apply_binding() {
let mesh = Mesh::new(
vec![
na::Point3::new(0.1, -0.2, 0.3),
na::Point3::new(1.3, 0.4, -0.2),
na::Point3::new(-0.4, 1.1, 0.7),
],
vec![[0, 1, 2]],
);
let frames = build_face_frames(&mesh);
let mut model = model_with_gaussians(1);
model.face_indices = vec![0];
model.barycentric = vec![[0.25, 0.35, 0.4]];
model.local_offsets = vec![[0.13, -0.07, 0.21]];
let grad_pos = [0.7_f32, -1.3, 0.45];
let analytic = offset_gradients_cpu(&[grad_pos], &model.face_indices, &frames)
.expect("projection onto the bound face frame");
let loss = |offset: [f32; 3]| -> f32 {
let mut probe = model.clone();
probe.local_offsets = vec![offset];
let p = apply_binding(&probe, &mesh).expect("binding").positions[0];
grad_pos[0] * p[0] + grad_pos[1] * p[1] + grad_pos[2] * p[2]
};
let h = 1e-3_f32;
for axis in 0..3 {
let mut plus = model.local_offsets[0];
let mut minus = model.local_offsets[0];
plus[axis] += h;
minus[axis] -= h;
let numeric = (loss(plus) - loss(minus)) / (2.0 * h);
assert!(
(analytic[0][axis] - numeric).abs() < 1e-3,
"axis {axis}: analytic {} vs numeric {numeric}",
analytic[0][axis]
);
}
assert!(
analytic[0].iter().any(|v| v.abs() > 1e-3),
"{:?}",
analytic[0]
);
}
#[test]
fn test_face_and_vertex_frame_tables_are_not_interchangeable() {
let mesh = Mesh::new(
vec![
na::Point3::new(0.0, 0.0, 0.0),
na::Point3::new(1.0, 0.0, 0.0),
na::Point3::new(0.0, 1.0, 0.0),
na::Point3::new(1.0, 1.0, 1.0),
],
vec![[0, 1, 2], [1, 3, 2]],
);
let face_frames = build_face_frames(&mesh);
let vertex_frames = build_vertex_frames(&mesh);
assert_eq!(face_frames.len(), 2);
assert_eq!(vertex_frames.len(), 4);
let grads = vec![[0.0_f32, 0.0, 1.0]];
let by_face = offset_gradients_cpu(&grads, &[1], &face_frames).expect("face projection");
let by_vertex =
offset_gradients_cpu(&grads, &[1], &vertex_frames).expect("vertex projection");
let delta: f32 = (0..3)
.map(|i| (by_face[0][i] - by_vertex[0][i]).abs())
.sum();
assert!(
delta > 1e-4,
"the two frame tables must not be silently interchangeable: {by_face:?} vs {by_vertex:?}"
);
}
#[test]
fn test_frame_from_degenerate_normal_falls_back() {
let frame = FaceFrame::from_normal_and_tangent(na::Vector3::zeros(), na::Vector3::x());
assert!((frame.normal.z - 1.0).abs() < 1e-6);
assert!((frame.tangent.x - 1.0).abs() < 1e-6);
}
#[test]
fn test_frame_from_parallel_tangent_hint_stays_orthonormal() {
let frame = FaceFrame::from_normal_and_tangent(
na::Vector3::new(0.0, 0.0, 2.0),
na::Vector3::new(0.0, 0.0, 5.0),
);
assert!((frame.normal.z - 1.0).abs() < 1e-6);
assert!((frame.tangent.norm() - 1.0).abs() < 1e-6);
assert!(frame.tangent.dot(&frame.normal).abs() < 1e-6);
assert!((frame.bitangent.norm() - 1.0).abs() < 1e-6);
}
}