use thiserror::Error;
#[derive(Debug, Error)]
pub enum TaaError {
#[error("No history frame available")]
NoHistory,
#[error(
"Dimension mismatch: current frame has {current} pixels, history has {history} pixels"
)]
DimensionMismatch {
current: usize,
history: usize,
},
#[error("Invalid motion field: expected {expected_pixels} pixels, got {got}")]
InvalidMotionField {
expected_pixels: usize,
got: usize,
},
#[error("Zero dimension: width and height must be > 0")]
ZeroDimension,
#[error("Invalid channels: must be > 0")]
InvalidChannels,
}
#[derive(Debug, Clone, Copy, Default)]
pub struct MotionVector {
pub dx: f32,
pub dy: f32,
}
impl MotionVector {
pub fn magnitude(&self) -> f32 {
(self.dx * self.dx + self.dy * self.dy).sqrt()
}
pub fn is_static(&self, threshold: f32) -> bool {
self.magnitude() < threshold
}
}
pub struct MotionVectorField {
pub vectors: Vec<MotionVector>,
pub width: usize,
pub height: usize,
}
impl MotionVectorField {
pub fn new(width: usize, height: usize) -> Self {
Self {
vectors: vec![MotionVector::default(); width * height],
width,
height,
}
}
pub fn zero_motion(width: usize, height: usize) -> Self {
Self::new(width, height)
}
pub fn get(&self, x: usize, y: usize) -> Option<&MotionVector> {
if x >= self.width || y >= self.height {
return None;
}
self.vectors.get(y * self.width + x)
}
pub fn set(&mut self, x: usize, y: usize, mv: MotionVector) -> bool {
if x >= self.width || y >= self.height {
return false;
}
let idx = y * self.width + x;
if let Some(slot) = self.vectors.get_mut(idx) {
*slot = mv;
true
} else {
false
}
}
pub fn mean_magnitude(&self) -> f32 {
if self.vectors.is_empty() {
return 0.0;
}
let sum: f32 = self.vectors.iter().map(|mv| mv.magnitude()).sum();
sum / self.vectors.len() as f32
}
pub fn max_magnitude(&self) -> f32 {
self.vectors
.iter()
.map(|mv| mv.magnitude())
.fold(0.0_f32, f32::max)
}
}
#[derive(Debug, Clone)]
pub struct TaaConfig {
pub current_weight: f32,
pub disocclusion_threshold: f32,
pub enable_neighborhood_clamp: bool,
pub disocclusion_blend: f32,
pub convergence_frames: usize,
}
impl Default for TaaConfig {
fn default() -> Self {
Self {
current_weight: 0.1,
disocclusion_threshold: 0.1,
enable_neighborhood_clamp: true,
disocclusion_blend: 0.5,
convergence_frames: 8,
}
}
}
#[derive(Clone, Copy)]
struct FrameView<'a> {
image: &'a [f32],
width: usize,
height: usize,
channels: usize,
}
fn sample_bilinear_into(view: FrameView<'_>, x: f32, y: f32, out: &mut [f32]) {
let FrameView {
image,
width,
height,
channels,
} = view;
let x0f = x.clamp(0.0, (width.saturating_sub(1)) as f32);
let y0f = y.clamp(0.0, (height.saturating_sub(1)) as f32);
let x0 = x0f.floor() as usize;
let y0 = y0f.floor() as usize;
let x1 = (x0 + 1).min(width.saturating_sub(1));
let y1 = (y0 + 1).min(height.saturating_sub(1));
let fx = x0f - x0f.floor();
let fy = y0f - y0f.floor();
for c in 0..channels {
let p00 = image
.get((y0 * width + x0) * channels + c)
.copied()
.unwrap_or(0.0);
let p10 = image
.get((y0 * width + x1) * channels + c)
.copied()
.unwrap_or(0.0);
let p01 = image
.get((y1 * width + x0) * channels + c)
.copied()
.unwrap_or(0.0);
let p11 = image
.get((y1 * width + x1) * channels + c)
.copied()
.unwrap_or(0.0);
let value = (1.0 - fy) * ((1.0 - fx) * p00 + fx * p10) + fy * ((1.0 - fx) * p01 + fx * p11);
if let Some(slot) = out.get_mut(c) {
*slot = value;
}
}
}
fn neighborhood_minmax_into(
view: FrameView<'_>,
px: usize,
py: usize,
min_out: &mut [f32],
max_out: &mut [f32],
) {
let FrameView {
image,
width,
height,
channels,
} = view;
for v in min_out.iter_mut().take(channels) {
*v = f32::INFINITY;
}
for v in max_out.iter_mut().take(channels) {
*v = f32::NEG_INFINITY;
}
let y_start = py.saturating_sub(1);
let y_end = (py + 2).min(height);
let x_start = px.saturating_sub(1);
let x_end = (px + 2).min(width);
for ny in y_start..y_end {
for nx in x_start..x_end {
let base = (ny * width + nx) * channels;
for c in 0..channels {
let v = image.get(base + c).copied().unwrap_or(0.0);
if let Some(min_slot) = min_out.get_mut(c) {
if v < *min_slot {
*min_slot = v;
}
}
if let Some(max_slot) = max_out.get_mut(c) {
if v > *max_slot {
*max_slot = v;
}
}
}
}
}
for c in 0..channels {
if min_out.get(c).copied() == Some(f32::INFINITY) {
if let Some(slot) = min_out.get_mut(c) {
*slot = 0.0;
}
if let Some(slot) = max_out.get_mut(c) {
*slot = 0.0;
}
}
}
}
pub struct TemporalAccumulator {
config: TaaConfig,
history: Option<Vec<f32>>,
pub width: usize,
pub height: usize,
pub channels: usize,
pub frame_count: usize,
last_disocclusion_fraction: f32,
}
impl TemporalAccumulator {
pub fn new(width: usize, height: usize, channels: usize, config: TaaConfig) -> Self {
Self {
config,
history: None,
width,
height,
channels,
frame_count: 0,
last_disocclusion_fraction: 0.0,
}
}
pub fn has_history(&self) -> bool {
self.history.is_some()
}
pub fn is_converged(&self) -> bool {
self.frame_count >= self.config.convergence_frames
}
pub fn config(&self) -> &TaaConfig {
&self.config
}
pub fn reset(&mut self) {
self.history = None;
self.frame_count = 0;
self.last_disocclusion_fraction = 0.0;
}
pub fn accumulate(
&mut self,
current_frame: &[f32],
motion_vectors: &MotionVectorField,
) -> Result<Vec<f32>, TaaError> {
if self.width == 0 || self.height == 0 {
return Err(TaaError::ZeroDimension);
}
if self.channels == 0 {
return Err(TaaError::InvalidChannels);
}
let expected_frame = self.width * self.height * self.channels;
if current_frame.len() != expected_frame {
return Err(TaaError::DimensionMismatch {
current: current_frame.len(),
history: expected_frame,
});
}
let expected_pixels = self.width * self.height;
if motion_vectors.vectors.len() != expected_pixels
|| motion_vectors.width != self.width
|| motion_vectors.height != self.height
{
return Err(TaaError::InvalidMotionField {
expected_pixels,
got: motion_vectors.vectors.len(),
});
}
if self.history.is_none() {
self.history = Some(current_frame.to_vec());
self.frame_count = 1;
return Ok(current_frame.to_vec());
}
let history = match self.history.as_deref() {
Some(h) => h,
None => return Err(TaaError::NoHistory),
};
let w = self.width;
let h = self.height;
let ch = self.channels;
let mut blended = vec![0.0_f32; expected_frame];
let mut warped = vec![0.0_f32; ch];
let mut n_min = vec![0.0_f32; ch];
let mut n_max = vec![0.0_f32; ch];
let mut disoccluded_count = 0usize;
let history_view = FrameView {
image: history,
width: w,
height: h,
channels: ch,
};
let current_view = FrameView {
image: current_frame,
width: w,
height: h,
channels: ch,
};
for py in 0..h {
for px in 0..w {
let mv = motion_vectors.get(px, py).copied().unwrap_or_default();
let src_x = px as f32 - mv.dx;
let src_y = py as f32 - mv.dy;
sample_bilinear_into(history_view, src_x, src_y, &mut warped);
if self.config.enable_neighborhood_clamp {
neighborhood_minmax_into(current_view, px, py, &mut n_min, &mut n_max);
for c in 0..ch {
warped[c] = warped[c].clamp(n_min[c], n_max[c]);
}
}
let base_cur = (py * w + px) * ch;
let mut color_dist = 0.0_f32;
for (c, &warped_val) in warped.iter().enumerate().take(ch) {
let cur_val = current_frame.get(base_cur + c).copied().unwrap_or(0.0);
let diff = (cur_val - warped_val).abs();
if diff > color_dist {
color_dist = diff;
}
}
let is_disoccluded = color_dist > self.config.disocclusion_threshold;
if is_disoccluded {
disoccluded_count += 1;
}
let weight = if is_disoccluded {
self.config.disocclusion_blend
} else {
self.config.current_weight
};
let base_out = base_cur;
for c in 0..ch {
let cur_val = current_frame.get(base_cur + c).copied().unwrap_or(0.0);
blended[base_out + c] = weight * cur_val + (1.0 - weight) * warped[c];
}
}
}
self.last_disocclusion_fraction = disoccluded_count as f32 / (w * h) as f32;
self.history = Some(blended.clone());
self.frame_count += 1;
Ok(blended)
}
pub fn history(&self) -> Result<&[f32], TaaError> {
match self.history.as_deref() {
Some(h) => Ok(h),
None => Err(TaaError::NoHistory),
}
}
}
#[derive(Debug, Clone, Default)]
pub struct TemporalStats {
pub frame_count: usize,
pub mean_motion_magnitude: f32,
pub mean_disocclusion_fraction: f32,
pub convergence_estimate: f32,
}
impl TemporalStats {
pub fn compute(accumulator: &TemporalAccumulator, motion_field: &MotionVectorField) -> Self {
let frame_count = accumulator.frame_count;
let convergence_frames = accumulator.config().convergence_frames;
let convergence_estimate = if convergence_frames == 0 {
1.0
} else {
(frame_count as f32 / convergence_frames as f32).min(1.0)
};
let mean_motion_magnitude = motion_field.mean_magnitude();
let mean_disocclusion_fraction = accumulator.last_disocclusion_fraction;
Self {
frame_count,
mean_motion_magnitude,
mean_disocclusion_fraction,
convergence_estimate,
}
}
pub fn format_summary(&self) -> String {
format!(
"frames={} convergence={:.1}% mean_motion={:.2}px disocclusion={:.1}%",
self.frame_count,
self.convergence_estimate * 100.0,
self.mean_motion_magnitude,
self.mean_disocclusion_fraction * 100.0,
)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn make_frame(w: usize, h: usize, ch: usize, val: f32) -> Vec<f32> {
vec![val; w * h * ch]
}
fn zero_field(w: usize, h: usize) -> MotionVectorField {
MotionVectorField::zero_motion(w, h)
}
#[test]
fn test_motion_vector_magnitude() {
let mv = MotionVector { dx: 3.0, dy: 4.0 };
let mag = mv.magnitude();
assert!((mag - 5.0).abs() < 1e-5, "expected 5.0, got {mag}");
}
#[test]
fn test_motion_vector_is_static() {
let mv_static = MotionVector { dx: 0.05, dy: 0.0 };
let mv_moving = MotionVector { dx: 1.0, dy: 0.0 };
assert!(mv_static.is_static(0.1), "should be static");
assert!(!mv_moving.is_static(0.1), "should not be static");
}
#[test]
fn test_motion_field_new_zeros() {
let field = MotionVectorField::new(4, 4);
assert_eq!(field.vectors.len(), 16);
for mv in &field.vectors {
assert_eq!(mv.dx, 0.0);
assert_eq!(mv.dy, 0.0);
}
}
#[test]
fn test_motion_field_set_get() {
let mut field = MotionVectorField::new(5, 5);
let mv = MotionVector { dx: 2.5, dy: -1.0 };
let ok = field.set(2, 3, mv);
assert!(ok, "set should succeed");
if let Some(got) = field.get(2, 3) {
assert!((got.dx - 2.5).abs() < 1e-6);
assert!((got.dy - (-1.0)).abs() < 1e-6);
} else {
panic!("expected Some, got None");
}
assert!(!field.set(10, 10, mv), "OOB set should return false");
assert!(field.get(10, 10).is_none(), "OOB get should return None");
}
#[test]
fn test_accumulator_first_frame_returns_current() {
let mut acc = TemporalAccumulator::new(2, 2, 3, TaaConfig::default());
let frame = make_frame(2, 2, 3, 0.8);
let field = zero_field(2, 2);
let result = acc.accumulate(&frame, &field);
match result {
Ok(out) => {
assert_eq!(out.len(), frame.len());
for (a, b) in out.iter().zip(frame.iter()) {
assert!((a - b).abs() < 1e-6, "first frame should equal input");
}
}
Err(e) => panic!("unexpected error: {e:?}"),
}
assert!(acc.has_history());
assert_eq!(acc.frame_count, 1);
}
#[test]
fn test_accumulator_second_frame_blends() {
let cfg = TaaConfig {
current_weight: 0.5,
enable_neighborhood_clamp: false,
..TaaConfig::default()
};
let mut acc = TemporalAccumulator::new(2, 2, 1, cfg);
let field = zero_field(2, 2);
let frame0 = make_frame(2, 2, 1, 0.0);
let _ = acc.accumulate(&frame0, &field);
let frame1 = make_frame(2, 2, 1, 1.0);
let result = acc.accumulate(&frame1, &field);
match result {
Ok(out) => {
for &v in &out {
assert!((v - 0.5).abs() < 1e-5, "expected 0.5, got {v}");
}
}
Err(e) => panic!("unexpected error: {e:?}"),
}
}
#[test]
fn test_accumulator_uniform_image_stable() {
let cfg = TaaConfig {
enable_neighborhood_clamp: false,
..TaaConfig::default()
};
let mut acc = TemporalAccumulator::new(4, 4, 3, cfg);
let field = zero_field(4, 4);
let frame = make_frame(4, 4, 3, 0.5);
let _ = acc.accumulate(&frame, &field);
let result = acc.accumulate(&frame, &field);
match result {
Ok(out) => {
for &v in &out {
assert!((v - 0.5).abs() < 1e-5, "uniform stable, got {v}");
}
}
Err(e) => panic!("unexpected error: {e:?}"),
}
}
#[test]
fn test_accumulator_convergence_after_n_frames() {
let cfg = TaaConfig {
convergence_frames: 3,
..TaaConfig::default()
};
let mut acc = TemporalAccumulator::new(2, 2, 1, cfg);
let field = zero_field(2, 2);
let frame = make_frame(2, 2, 1, 0.5);
assert!(!acc.is_converged());
let _ = acc.accumulate(&frame, &field);
let _ = acc.accumulate(&frame, &field);
assert!(!acc.is_converged());
let _ = acc.accumulate(&frame, &field);
assert!(acc.is_converged(), "should converge after 3 frames");
}
#[test]
fn test_accumulator_reset() {
let mut acc = TemporalAccumulator::new(2, 2, 3, TaaConfig::default());
let field = zero_field(2, 2);
let frame = make_frame(2, 2, 3, 0.3);
let _ = acc.accumulate(&frame, &field);
assert!(acc.has_history());
acc.reset();
assert!(!acc.has_history());
assert_eq!(acc.frame_count, 0);
}
#[test]
fn test_accumulator_disocclusion_large_change() {
let cfg = TaaConfig {
current_weight: 0.1,
disocclusion_threshold: 0.05,
disocclusion_blend: 0.9,
enable_neighborhood_clamp: false,
..TaaConfig::default()
};
let mut acc = TemporalAccumulator::new(1, 1, 1, cfg);
let field = zero_field(1, 1);
let _ = acc.accumulate(&[0.0], &field);
let result = acc.accumulate(&[1.0], &field);
match result {
Ok(out) => {
assert!(!out.is_empty());
assert!((out[0] - 0.9).abs() < 1e-5, "expected 0.9, got {}", out[0]);
}
Err(e) => panic!("unexpected error: {e:?}"),
}
}
#[test]
fn test_disocclusion_fraction_reflects_current_vs_history_not_brightness() {
let w = 4;
let h = 4;
let ch = 3;
let cfg = TaaConfig {
disocclusion_threshold: 0.1,
enable_neighborhood_clamp: false,
..TaaConfig::default()
};
let mut acc = TemporalAccumulator::new(w, h, ch, cfg);
let field = zero_field(w, h);
let bright = make_frame(w, h, ch, 0.9);
acc.accumulate(&bright, &field)
.expect("bootstrap accumulate");
acc.accumulate(&bright, &field).expect("second accumulate");
let stats = TemporalStats::compute(&acc, &field);
assert!(
stats.mean_disocclusion_fraction < 0.01,
"a static bright scene must not register as disoccluded, got {}",
stats.mean_disocclusion_fraction
);
let changed = make_frame(w, h, ch, 0.0);
acc.accumulate(&changed, &field).expect("third accumulate");
let stats = TemporalStats::compute(&acc, &field);
assert!(
stats.mean_disocclusion_fraction > 0.9,
"a drastic frame-to-frame change must register as disoccluded, got {}",
stats.mean_disocclusion_fraction
);
}
#[test]
fn test_neighborhood_clamp_edge_pixel() {
let image: Vec<f32> = (0..9).map(|i| i as f32 * 0.1).collect(); let mut mn = vec![0.0_f32; 1];
let mut mx = vec![0.0_f32; 1];
let view = FrameView {
image: &image,
width: 3,
height: 3,
channels: 1,
};
neighborhood_minmax_into(view, 0, 0, &mut mn, &mut mx);
assert!(mn[0] <= mx[0]);
}
#[test]
fn test_bilinear_sample_integer_coords() {
let image: Vec<f32> = (0..9).map(|i| i as f32).collect(); let mut v = vec![0.0_f32; 1];
let view = FrameView {
image: &image,
width: 3,
height: 3,
channels: 1,
};
sample_bilinear_into(view, 1.0, 1.0, &mut v);
assert_eq!(v.len(), 1);
assert!((v[0] - 4.0).abs() < 1e-5, "expected 4.0, got {}", v[0]);
}
#[test]
fn test_sample_bilinear_into_ignores_short_output_buffer() {
let image: Vec<f32> = (0..9).map(|i| i as f32).collect(); let mut v = vec![-1.0_f32; 1]; let view = FrameView {
image: &image,
width: 1,
height: 3,
channels: 3,
};
sample_bilinear_into(view, 0.0, 1.0, &mut v);
assert!((v[0] - 3.0).abs() < 1e-5, "expected 3.0, got {}", v[0]);
}
#[test]
fn test_temporal_stats_convergence() {
let cfg = TaaConfig {
convergence_frames: 10,
..TaaConfig::default()
};
let mut acc = TemporalAccumulator::new(2, 2, 3, cfg);
let field = zero_field(2, 2);
let frame = make_frame(2, 2, 3, 0.5);
let _ = acc.accumulate(&frame, &field);
let _ = acc.accumulate(&frame, &field);
let stats = TemporalStats::compute(&acc, &field);
assert_eq!(stats.frame_count, 2);
assert!((stats.convergence_estimate - 0.2).abs() < 1e-5);
let summary = stats.format_summary();
assert!(summary.contains("frames=2"));
}
#[test]
fn test_taa_config_default() {
let cfg = TaaConfig::default();
assert!((cfg.current_weight - 0.1).abs() < 1e-6);
assert!((cfg.disocclusion_threshold - 0.1).abs() < 1e-6);
assert!(cfg.enable_neighborhood_clamp);
assert!((cfg.disocclusion_blend - 0.5).abs() < 1e-6);
assert_eq!(cfg.convergence_frames, 8);
}
#[test]
fn test_dimension_mismatch_error() {
let mut acc = TemporalAccumulator::new(4, 4, 3, TaaConfig::default());
let field = zero_field(4, 4);
let bad_frame = make_frame(2, 2, 3, 0.5); let result = acc.accumulate(&bad_frame, &field);
match result {
Err(TaaError::DimensionMismatch {
current,
history: _,
}) => {
assert_eq!(current, 12);
}
other => panic!("expected DimensionMismatch, got {other:?}"),
}
}
#[test]
fn test_no_history_error() {
let acc = TemporalAccumulator::new(2, 2, 3, TaaConfig::default());
match acc.history() {
Err(TaaError::NoHistory) => {}
other => panic!("expected NoHistory, got {other:?}"),
}
}
}