Skip to main content

qualia_vision/biosense/magnification/
eulerian_motion_magnify.rs

1//! Eulerian motion magnification — multi-scale spatial (Laplacian) × temporal band × α.
2//!
3//! Wu et al. style: Laplacian pyramid per frame, IIR band-pass along time per level,
4//! amplify, reconstruct, add residual to original gray sequence.
5
6use super::evm_snr_gate::{evm_snr_gate_trace, EvmRefuse, DEFAULT_EVM_MIN_SNR};
7use super::gaussian_pyramid_build::{
8    gaussian_pyramid_build, gaussian_pyramid_scratch_elems, PyramidLevelMeta, MAX_PYRAMID_LEVELS,
9};
10use super::laplacian_pyramid_build::laplacian_pyramid_build;
11use super::pyramid_reconstruct::pyramid_reconstruct;
12use super::temporal_bandpass::{bandpass_step, design_bandpass_iir};
13use crate::cv::error::CvError;
14
15/// Motion EVM parameters.
16#[derive(Debug, Clone, Copy)]
17pub struct MotionEvmParams {
18    pub fps: f32,
19    pub f_lo_hz: f32,
20    pub f_hi_hz: f32,
21    pub alpha: f32,
22    /// Pyramid depth (1..=MAX_PYRAMID_LEVELS).
23    pub levels: usize,
24    pub min_snr: f32,
25    pub require_snr: bool,
26}
27
28impl Default for MotionEvmParams {
29    fn default() -> Self {
30        Self {
31            fps: 30.0,
32            f_lo_hz: 0.4,
33            f_hi_hz: 3.0,
34            alpha: 20.0,
35            levels: 4,
36            min_snr: DEFAULT_EVM_MIN_SNR,
37            require_snr: true,
38        }
39    }
40}
41
42/// Compatibility API: gray packed `n*w*h`, default band @ 30 fps, SNR gate off.
43pub fn eulerian_motion_magnify(
44    frames: &[u8],
45    n_frames: usize,
46    width: u32,
47    height: u32,
48    alpha: f32,
49    out: &mut [u8],
50) -> Result<(), CvError> {
51    eulerian_motion_magnify_ex(
52        frames,
53        n_frames,
54        width,
55        height,
56        MotionEvmParams {
57            alpha,
58            require_snr: false,
59            ..MotionEvmParams::default()
60        },
61        out,
62    )
63    .map(|_| ())
64    .map_err(|e| match e {
65        EvmRefuse::BufferTooSmall => CvError::BufferTooSmall,
66        EvmRefuse::EmptyInput => CvError::EmptyInput,
67        _ => CvError::InvalidParameter,
68    })
69}
70
71/// Multi-scale motion EVM. Returns band SNR of global mean gray (0 if gate off).
72pub fn eulerian_motion_magnify_ex(
73    frames: &[u8],
74    n_frames: usize,
75    width: u32,
76    height: u32,
77    params: MotionEvmParams,
78    out: &mut [u8],
79) -> Result<f32, EvmRefuse> {
80    let w = width as usize;
81    let h = height as usize;
82    let px = w * h;
83    if n_frames < 8 || width < 2 || height < 2 {
84        return Err(EvmRefuse::InsufficientFrames {
85            got: n_frames,
86            need: 8,
87        });
88    }
89    if frames.len() < n_frames * px || out.len() < n_frames * px {
90        return Err(EvmRefuse::BufferTooSmall);
91    }
92
93    let levels = params.levels.clamp(1, MAX_PYRAMID_LEVELS);
94    let bp = design_bandpass_iir(params.fps, params.f_lo_hz, params.f_hi_hz)?;
95    let gain = params.alpha.clamp(0.0, 100.0);
96
97    // SNR on global mean
98    let mut mean_series = vec![0.0f32; n_frames];
99    for t in 0..n_frames {
100        let base = t * px;
101        let mut s = 0.0f32;
102        for p in 0..px {
103            s += frames[base + p] as f32;
104        }
105        mean_series[t] = s / px as f32;
106    }
107    let mut snr = 0.0f32;
108    if params.require_snr {
109        let mut scratch = vec![0.0f32; n_frames];
110        snr = evm_snr_gate_trace(
111            &mean_series,
112            params.fps,
113            params.f_lo_hz,
114            params.f_hi_hz,
115            params.min_snr,
116            &mut scratch,
117        )?;
118    }
119
120    // Tier-2 cold: pyramid scratch for one frame + per-level temporal state
121    let pyr_elems = gaussian_pyramid_scratch_elems(width, height, levels);
122    let mut g_pack = vec![0.0f32; pyr_elems];
123    let mut lap_pack = vec![0.0f32; pyr_elems];
124    let mut expand = vec![0.0f32; px];
125    let mut recon = vec![0.0f32; px];
126    let mut work = vec![0.0f32; px];
127    let mut src_f = vec![0.0f32; px];
128    let mut meta = [PyramidLevelMeta::default(); MAX_PYRAMID_LEVELS];
129
130    // Temporal IIR state per pyramid element (lo/hi)
131    let mut state_lo = vec![0.0f32; pyr_elems];
132    let mut state_hi = vec![0.0f32; pyr_elems];
133    let mut state_init = false;
134
135    // Accumulate amplified band into recon buffer history — process frame-by-frame:
136    // For each frame: build Lap pyramid, band-pass step each coeff, reconstruct band image,
137    // out = original + alpha * band.
138    for t in 0..n_frames {
139        let base = t * px;
140        for p in 0..px {
141            src_f[p] = frames[base + p] as f32;
142        }
143        let n_lev = gaussian_pyramid_build(&src_f, width, height, levels, &mut g_pack, &mut meta)?;
144        laplacian_pyramid_build(&g_pack, &meta, n_lev, &mut lap_pack, &mut expand)?;
145
146        if !state_init {
147            state_lo[..pyr_elems].copy_from_slice(&lap_pack[..pyr_elems]);
148            state_hi[..pyr_elems].copy_from_slice(&lap_pack[..pyr_elems]);
149            state_init = true;
150        }
151
152        // In-place band-pass step on laplacian coefficients
153        let total: usize = (0..n_lev).map(|i| meta[i].len).sum();
154        for k in 0..total {
155            let x = lap_pack[k];
156            lap_pack[k] = bandpass_step(x, &bp, &mut state_lo[k], &mut state_hi[k]);
157        }
158
159        pyramid_reconstruct(&lap_pack, &meta, n_lev, &mut recon, &mut work)?;
160
161        for p in 0..px {
162            let v = src_f[p] + gain * recon[p];
163            out[base + p] = v.clamp(0.0, 255.0) as u8;
164        }
165    }
166
167    Ok(snr)
168}
169
170#[cfg(test)]
171mod tests {
172    use super::*;
173
174    #[test]
175    fn motion_runs_multiscale() {
176        let n = 40usize;
177        let w = 16u32;
178        let h = 16u32;
179        let px = (w * h) as usize;
180        let mut frames = vec![80u8; n * px];
181        // Vertical edge that shifts slightly over time (sub-pixel motion proxy)
182        for t in 0..n {
183            let shift = ((core::f32::consts::TAU * 0.8 * t as f32 / 30.0).sin() * 1.5) as i32;
184            for y in 0..h as usize {
185                for x in 0..w as usize {
186                    let edge = if (x as i32) > 8 + shift { 160u8 } else { 40u8 };
187                    frames[t * px + y * w as usize + x] = edge;
188                }
189            }
190        }
191        let mut out = vec![0u8; n * px];
192        eulerian_motion_magnify_ex(
193            &frames,
194            n,
195            w,
196            h,
197            MotionEvmParams {
198                require_snr: false,
199                alpha: 10.0,
200                levels: 3,
201                ..Default::default()
202            },
203            &mut out,
204        )
205        .unwrap();
206        // Mid frames should not be identical to input everywhere
207        let mid = n / 2;
208        let mut same = 0usize;
209        for p in 0..px {
210            if frames[mid * px + p] == out[mid * px + p] {
211                same += 1;
212            }
213        }
214        assert!(same < px, "expected some pixels to change under motion mag");
215    }
216
217    #[test]
218    fn legacy_api_ok() {
219        let n = 16;
220        let w = 8u32;
221        let h = 8u32;
222        let px = 64;
223        let f = vec![100u8; n * px];
224        let mut o = vec![0u8; n * px];
225        eulerian_motion_magnify(&f, n, w, h, 5.0, &mut o).unwrap();
226    }
227}