Skip to main content

qualia_vision/biosense/magnification/
evm_snr_gate.rs

1//! SNR / band-energy gate for EVM — abstain rather than invent magnification.
2
3use super::temporal_bandpass::{design_bandpass_iir, temporal_bandpass_series};
4use crate::cv::error::CvError;
5
6/// Scalar energy gate verdict (band vs residual).
7#[derive(Debug, Clone, Copy, PartialEq)]
8pub enum EvmSnrVerdict {
9    Ok { snr: f32 },
10    Abstain { snr: f32 },
11}
12
13/// Why EVM processing was refused (structured, for Result paths).
14#[derive(Debug, Clone, Copy, PartialEq)]
15pub enum EvmRefuse {
16    ConsentDenied,
17    BufferTooSmall,
18    InvalidParameter,
19    EmptyInput,
20    /// Band residual energy too weak / junk relative to full signal.
21    SnrTooLow {
22        snr: f32,
23        threshold: f32,
24    },
25    InsufficientFrames {
26        got: usize,
27        need: usize,
28    },
29}
30
31impl From<CvError> for EvmRefuse {
32    fn from(e: CvError) -> Self {
33        match e {
34            CvError::BufferTooSmall => Self::BufferTooSmall,
35            CvError::EmptyInput => Self::EmptyInput,
36            CvError::InvalidParameter | CvError::DimensionMismatch => Self::InvalidParameter,
37        }
38    }
39}
40
41impl core::fmt::Display for EvmRefuse {
42    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
43        match self {
44            Self::ConsentDenied => write!(f, "biosense consent denied"),
45            Self::BufferTooSmall => write!(f, "output or scratch buffer too small"),
46            Self::InvalidParameter => write!(f, "invalid EVM parameter"),
47            Self::EmptyInput => write!(f, "empty input"),
48            Self::SnrTooLow { snr, threshold } => {
49                write!(f, "band SNR {snr:.3} below threshold {threshold:.3}")
50            }
51            Self::InsufficientFrames { got, need } => {
52                write!(f, "need at least {need} frames, got {got}")
53            }
54        }
55    }
56}
57
58/// Compare band energy to residual (out-of-band proxy).
59pub fn evm_snr_gate_energies(
60    band_energy: f32,
61    residual_energy: f32,
62    min_snr: f32,
63) -> EvmSnrVerdict {
64    let res = residual_energy.max(1e-12);
65    let snr = band_energy.max(0.0) / res;
66    if snr >= min_snr {
67        EvmSnrVerdict::Ok { snr }
68    } else {
69        EvmSnrVerdict::Abstain { snr }
70    }
71}
72
73/// Mean square of a slice.
74pub fn energy_ms(x: &[f32]) -> f32 {
75    if x.is_empty() {
76        return 0.0;
77    }
78    x.iter().map(|v| v * v).sum::<f32>() / x.len() as f32
79}
80
81/// Default minimum band SNR (fraction of total demeaned RMS in-band).
82pub const DEFAULT_EVM_MIN_SNR: f32 = 0.08;
83
84/// Estimate SNR as band residual RMS / total demeaned RMS (after IIR band-pass).
85///
86/// `scratch` ≥ `trace.len()`.
87pub fn band_energy_snr(
88    trace: &[f32],
89    fps: f32,
90    f_lo_hz: f32,
91    f_hi_hz: f32,
92    scratch: &mut [f32],
93) -> Result<f32, EvmRefuse> {
94    if trace.len() < 8 {
95        return Err(EvmRefuse::InsufficientFrames {
96            got: trace.len(),
97            need: 8,
98        });
99    }
100    if scratch.len() < trace.len() {
101        return Err(EvmRefuse::BufferTooSmall);
102    }
103    let bp = design_bandpass_iir(fps, f_lo_hz, f_hi_hz)?;
104    temporal_bandpass_series(trace, &bp, scratch)?;
105    let n = trace.len();
106    let mean: f32 = trace.iter().sum::<f32>() / n as f32;
107    let mut total_e = 0.0f32;
108    let mut band_e = 0.0f32;
109    let skip = ((fps * 0.5) as usize).min(n / 4).max(1);
110    let count = (n - skip).max(1) as f32;
111    for i in skip..n {
112        let d = trace[i] - mean;
113        total_e += d * d;
114        let b = scratch[i];
115        band_e += b * b;
116    }
117    let total_rms = (total_e / count).sqrt();
118    let band_rms = (band_e / count).sqrt();
119    if total_rms < 1e-8 {
120        return Ok(0.0);
121    }
122    Ok(band_rms / total_rms)
123}
124
125/// Gate on a precomputed energy pair (compat thin name used by early stubs).
126pub fn evm_snr_gate(band_energy: f32, residual_energy: f32, min_snr: f32) -> EvmSnrVerdict {
127    evm_snr_gate_energies(band_energy, residual_energy, min_snr)
128}
129
130/// Gate on a temporal trace: `Ok(snr)` if usable; else `Err(SnrTooLow|…)`.
131pub fn evm_snr_gate_trace(
132    trace: &[f32],
133    fps: f32,
134    f_lo_hz: f32,
135    f_hi_hz: f32,
136    min_snr: f32,
137    scratch: &mut [f32],
138) -> Result<f32, EvmRefuse> {
139    let snr = band_energy_snr(trace, fps, f_lo_hz, f_hi_hz, scratch)?;
140    if snr < min_snr {
141        return Err(EvmRefuse::SnrTooLow {
142            snr,
143            threshold: min_snr,
144        });
145    }
146    Ok(snr)
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152
153    #[test]
154    fn abstain_low() {
155        assert!(matches!(
156            evm_snr_gate(0.1, 10.0, 1.0),
157            EvmSnrVerdict::Abstain { .. }
158        ));
159    }
160
161    #[test]
162    fn ok_high() {
163        assert!(matches!(
164            evm_snr_gate(10.0, 1.0, 2.0),
165            EvmSnrVerdict::Ok { .. }
166        ));
167    }
168
169    #[test]
170    fn abstains_on_junk_noise() {
171        let fps = 30.0f32;
172        let n = 120;
173        // Pure DC: no temporal structure → band SNR ≈ 0 after demean.
174        let t = vec![42.0f32; n];
175        let mut scratch = vec![0.0f32; n];
176        let r = evm_snr_gate_trace(&t, fps, 0.7, 4.0, 0.08, &mut scratch);
177        assert!(
178            matches!(r, Err(EvmRefuse::SnrTooLow { .. })),
179            "expected abstain, got {r:?}"
180        );
181        // Out-of-band high tone only (well above 4 Hz) should also be weak in-band.
182        let mut hi = vec![0.0f32; n];
183        for i in 0..n {
184            let tt = i as f32 / fps;
185            hi[i] = 5.0 * (core::f32::consts::TAU * 12.0 * tt).sin();
186        }
187        let r2 = evm_snr_gate_trace(&hi, fps, 0.7, 4.0, 0.85, &mut scratch);
188        assert!(
189            matches!(r2, Err(EvmRefuse::SnrTooLow { .. })),
190            "expected high-tone abstain, got {r2:?}"
191        );
192    }
193
194    #[test]
195    fn accepts_in_band_sinusoid() {
196        let fps = 30.0f32;
197        let n = 180;
198        let mut t = vec![0.0f32; n];
199        for i in 0..n {
200            let tt = i as f32 / fps;
201            t[i] = 10.0 + 2.0 * (core::f32::consts::TAU * 1.2 * tt).sin();
202        }
203        let mut scratch = vec![0.0f32; n];
204        let snr = evm_snr_gate_trace(&t, fps, 0.7, 4.0, 0.15, &mut scratch).unwrap();
205        assert!(snr > 0.15, "snr={snr}");
206    }
207}