qualia_vision/biosense/magnification/
evm_snr_gate.rs1use super::temporal_bandpass::{design_bandpass_iir, temporal_bandpass_series};
4use crate::cv::error::CvError;
5
6#[derive(Debug, Clone, Copy, PartialEq)]
8pub enum EvmSnrVerdict {
9 Ok { snr: f32 },
10 Abstain { snr: f32 },
11}
12
13#[derive(Debug, Clone, Copy, PartialEq)]
15pub enum EvmRefuse {
16 ConsentDenied,
17 BufferTooSmall,
18 InvalidParameter,
19 EmptyInput,
20 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
58pub 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
73pub 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
81pub const DEFAULT_EVM_MIN_SNR: f32 = 0.08;
83
84pub 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
125pub 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
130pub 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 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 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}