Skip to main content

qualia_vision/recipes/
self_monitor_pulse_evm.rs

1//! Recipe: consent → quality gate → optional colour-EVM on face ROI → rPPG ensemble.
2//!
3//! Returns HR + confidence with an explicit **abstain** path (does not invent a pulse).
4//! Fail closed without consent. No training.
5
6use crate::biosense::{
7    ensemble_hr, eulerian_color_magnify_consented, face_roi_center, frame_blur_score,
8    reject_low_quality, roi_mean_rgb, BiosenseConsent, ColourEvmParams, FaceRoi, HrEstimate,
9    QualityReject,
10};
11use crate::cv::buffer::{GrayView, RgbView};
12use crate::cv::color::rgb_to_gray_u8;
13
14/// Why the pulse recipe abstained (honest fail-closed).
15#[derive(Debug, Clone, Copy, PartialEq, Eq)]
16pub enum PulseAbstain {
17    NoConsent,
18    InsufficientFrames,
19    BufferTooSmall,
20    LowQuality,
21    LowConfidence,
22    EvmRefused,
23}
24
25/// Outcome of [`self_monitor_pulse_evm`]: estimate or structured abstain.
26#[derive(Debug, Clone, Copy)]
27pub struct PulseEvmResult {
28    pub bpm: f32,
29    pub confidence: f32,
30    pub snr: f32,
31    pub abstained: bool,
32    pub used_evm: bool,
33    pub reason: Option<PulseAbstain>,
34}
35
36impl PulseEvmResult {
37    fn estimate(hr: HrEstimate, used_evm: bool) -> Self {
38        Self {
39            bpm: hr.bpm,
40            confidence: hr.confidence,
41            snr: hr.snr,
42            abstained: false,
43            used_evm,
44            reason: None,
45        }
46    }
47
48    fn abstain(reason: PulseAbstain, used_evm: bool) -> Self {
49        Self {
50            bpm: 0.0,
51            confidence: 0.0,
52            snr: 0.0,
53            abstained: true,
54            used_evm,
55            reason: Some(reason),
56        }
57    }
58}
59
60/// Minimum frames for spectral HR (matches ensemble path).
61const MIN_FRAMES: usize = 32;
62/// Default ensemble confidence floor.
63const DEFAULT_MIN_CONF: f32 = 0.15;
64/// Blur variance floor (same order as `self_monitor_pulse`).
65const MIN_BLUR: f32 = 10.0;
66/// Motion energy ceiling on first pair (disabled when only one gray available).
67const MAX_MOTION: f32 = 40.0;
68
69/// Self-monitor pulse with optional Eulerian colour magnification on the face ROI.
70///
71/// * `use_evm` — when true, run consent-gated colour EVM on the ROI crop before
72///   ROI-mean extraction; on EVM refuse, **fall back** to unmagnified means
73///   (still quality-gated). Set SNR gate off via soft params when frames are short.
74/// * `min_confidence` — ensemble SNR confidence gate; below → abstain.
75pub fn self_monitor_pulse_evm(
76    consent: BiosenseConsent,
77    rgb_frames: &[u8],
78    n_frames: usize,
79    width: u32,
80    height: u32,
81    fps: f32,
82    use_evm: bool,
83    min_confidence: f32,
84) -> PulseEvmResult {
85    if !consent.may_process() {
86        return PulseEvmResult::abstain(PulseAbstain::NoConsent, false);
87    }
88    let fb = (width as usize)
89        .saturating_mul(height as usize)
90        .saturating_mul(3);
91    if n_frames < MIN_FRAMES || fb == 0 {
92        return PulseEvmResult::abstain(PulseAbstain::InsufficientFrames, false);
93    }
94    if rgb_frames.len() < n_frames.saturating_mul(fb) {
95        return PulseEvmResult::abstain(PulseAbstain::BufferTooSmall, false);
96    }
97    if fps <= 1.0 {
98        return PulseEvmResult::abstain(PulseAbstain::InsufficientFrames, false);
99    }
100
101    // Quality gate on first frame (and optional first-pair motion).
102    let mut gray0 = vec![0u8; (width * height) as usize];
103    let v0 = match RgbView::new(width, height, width * 3, &rgb_frames[..fb]) {
104        Some(v) => v,
105        None => return PulseEvmResult::abstain(PulseAbstain::BufferTooSmall, false),
106    };
107    if rgb_to_gray_u8(v0, &mut gray0).is_err() {
108        return PulseEvmResult::abstain(PulseAbstain::LowQuality, false);
109    }
110    let gv0 = match GrayView::new(width, height, width, &gray0) {
111        Some(g) => g,
112        None => return PulseEvmResult::abstain(PulseAbstain::LowQuality, false),
113    };
114    let blur = frame_blur_score(gv0);
115    if reject_low_quality(blur, 0.0, MIN_BLUR, MAX_MOTION) == QualityReject::TooBlurry {
116        return PulseEvmResult::abstain(PulseAbstain::LowQuality, false);
117    }
118
119    let roi = face_roi_center(v0);
120    let conf_gate = if min_confidence > 0.0 {
121        min_confidence
122    } else {
123        DEFAULT_MIN_CONF
124    };
125
126    let (means, used_evm) = match extract_roi_means(
127        consent, rgb_frames, n_frames, width, height, fb, roi, fps, use_evm,
128    ) {
129        Ok(v) => v,
130        Err(PulseAbstain::EvmRefused) => {
131            // Fall back without EVM if magnify path hard-failed buffer geometry.
132            match extract_roi_means(
133                consent, rgb_frames, n_frames, width, height, fb, roi, fps, false,
134            ) {
135                Ok((m, _)) => (m, false),
136                Err(r) => return PulseEvmResult::abstain(r, false),
137            }
138        }
139        Err(r) => return PulseEvmResult::abstain(r, false),
140    };
141
142    match ensemble_hr(consent, &means, n_frames, fps, conf_gate) {
143        Ok(hr) => PulseEvmResult::estimate(hr, used_evm),
144        Err(_) => PulseEvmResult::abstain(PulseAbstain::LowConfidence, used_evm),
145    }
146}
147
148fn extract_roi_means(
149    consent: BiosenseConsent,
150    rgb_frames: &[u8],
151    n_frames: usize,
152    width: u32,
153    height: u32,
154    fb: usize,
155    roi: FaceRoi,
156    fps: f32,
157    use_evm: bool,
158) -> Result<(Vec<f32>, bool), PulseAbstain> {
159    let mut means = vec![0.0f32; n_frames * 3];
160
161    if use_evm && roi.w >= 4 && roi.h >= 4 {
162        let rw = roi.w as usize;
163        let rh = roi.h as usize;
164        let crop_fb = rw * rh * 3;
165        let mut cropped = vec![0u8; n_frames * crop_fb];
166        for i in 0..n_frames {
167            let src = &rgb_frames[i * fb..(i + 1) * fb];
168            let v =
169                RgbView::new(width, height, width * 3, src).ok_or(PulseAbstain::BufferTooSmall)?;
170            crop_roi_rgb(v, roi, &mut cropped[i * crop_fb..(i + 1) * crop_fb]);
171        }
172        let mut magnified = vec![0u8; n_frames * crop_fb];
173        let params = ColourEvmParams {
174            fps,
175            f_lo_hz: 0.7,
176            f_hi_hz: 4.0,
177            alpha_chroma: 20.0,
178            alpha_luma: 0.0,
179            // Soft gate: recipe still abstains later via ensemble conf.
180            require_snr: false,
181            ..ColourEvmParams::default()
182        };
183        match eulerian_color_magnify_consented(
184            consent,
185            &cropped,
186            n_frames,
187            roi.w,
188            roi.h,
189            params,
190            &mut magnified,
191        ) {
192            Ok(_) => {
193                let full_roi = FaceRoi {
194                    x: 0,
195                    y: 0,
196                    w: roi.w,
197                    h: roi.h,
198                };
199                for i in 0..n_frames {
200                    let slice = &magnified[i * crop_fb..(i + 1) * crop_fb];
201                    let v = RgbView::new(roi.w, roi.h, roi.w * 3, slice)
202                        .ok_or(PulseAbstain::BufferTooSmall)?;
203                    let mut m = [0.0f32; 3];
204                    roi_mean_rgb(v, full_roi, &mut m);
205                    means[i * 3] = m[0];
206                    means[i * 3 + 1] = m[1];
207                    means[i * 3 + 2] = m[2];
208                }
209                return Ok((means, true));
210            }
211            Err(_) => {
212                // Caller may fall back; signal EVM path refused.
213                return Err(PulseAbstain::EvmRefused);
214            }
215        }
216    }
217
218    // Unmagnified ROI means.
219    for i in 0..n_frames {
220        let slice = &rgb_frames[i * fb..(i + 1) * fb];
221        let v =
222            RgbView::new(width, height, width * 3, slice).ok_or(PulseAbstain::BufferTooSmall)?;
223        let mut m = [0.0f32; 3];
224        roi_mean_rgb(v, roi, &mut m);
225        means[i * 3] = m[0];
226        means[i * 3 + 1] = m[1];
227        means[i * 3 + 2] = m[2];
228    }
229    Ok((means, false))
230}
231
232fn crop_roi_rgb(src: RgbView<'_>, roi: FaceRoi, out: &mut [u8]) {
233    let rw = roi.w as usize;
234    let rh = roi.h as usize;
235    debug_assert!(out.len() >= rw * rh * 3);
236    for dy in 0..rh {
237        for dx in 0..rw {
238            let x = roi.x + dx as u32;
239            let y = roi.y + dy as u32;
240            let (r, g, b) = if x < src.width && y < src.height {
241                src.pixel(x, y)
242            } else {
243                (0, 0, 0)
244            };
245            let o = (dy * rw + dx) * 3;
246            out[o] = r;
247            out[o + 1] = g;
248            out[o + 2] = b;
249        }
250    }
251}
252
253#[cfg(test)]
254mod tests {
255    use super::*;
256    use crate::biosense::BiosensePurpose;
257
258    fn grant() -> BiosenseConsent {
259        BiosenseConsent::grant_process(BiosensePurpose::WellfairSelfMonitor, 7)
260    }
261
262    /// Synthetic face-like frames: central warm patch + green pulse at `hr_bpm`.
263    fn synth_pulse_frames(n: usize, w: u32, h: u32, fps: f32, hr_bpm: f32) -> Vec<u8> {
264        let fb = (w * h * 3) as usize;
265        let mut frames = vec![40u8; n * fb];
266        let f_hr = hr_bpm / 60.0;
267        let cx0 = w / 3;
268        let cy0 = h / 6;
269        let rw = (w / 3).max(8);
270        let rh = (h / 4).max(8);
271        for t in 0..n {
272            let phase = (core::f32::consts::TAU * f_hr * t as f32 / fps).sin();
273            let g = (120.0 + 25.0 * phase).clamp(0.0, 255.0) as u8;
274            let r = (140.0 + 8.0 * phase).clamp(0.0, 255.0) as u8;
275            let b = (90.0 - 6.0 * phase).clamp(0.0, 255.0) as u8;
276            let base = t * fb;
277            for y in cy0..cy0 + rh {
278                for x in cx0..cx0 + rw {
279                    // Add spatial texture so blur score is non-zero.
280                    let tex = ((x + y + t as u32) % 7) as u8;
281                    let i = base + ((y * w + x) * 3) as usize;
282                    frames[i] = r.saturating_add(tex);
283                    frames[i + 1] = g.saturating_add(tex / 2);
284                    frames[i + 2] = b;
285                }
286            }
287            // Edge noise for laplacian variance.
288            for y in 0..h {
289                for x in 0..w {
290                    if x < 2 || y < 2 || x + 2 >= w || y + 2 >= h {
291                        continue;
292                    }
293                    if (x + y) % 11 == 0 {
294                        let i = base + ((y * w + x) * 3) as usize;
295                        frames[i] = frames[i].saturating_add(30);
296                        frames[i + 1] = frames[i + 1].saturating_add(20);
297                    }
298                }
299            }
300        }
301        frames
302    }
303
304    #[test]
305    fn no_consent_abstains() {
306        let frames = synth_pulse_frames(64, 48, 48, 30.0, 72.0);
307        let r = self_monitor_pulse_evm(
308            BiosenseConsent::denied(BiosensePurpose::WellfairSelfMonitor),
309            &frames,
310            64,
311            48,
312            48,
313            30.0,
314            false,
315            0.1,
316        );
317        assert!(r.abstained);
318        assert_eq!(r.reason, Some(PulseAbstain::NoConsent));
319    }
320
321    #[test]
322    fn short_window_abstains() {
323        let frames = synth_pulse_frames(8, 32, 32, 30.0, 60.0);
324        let r = self_monitor_pulse_evm(grant(), &frames, 8, 32, 32, 30.0, false, 0.1);
325        assert!(r.abstained);
326        assert_eq!(r.reason, Some(PulseAbstain::InsufficientFrames));
327    }
328
329    #[test]
330    fn synthetic_pulse_without_evm() {
331        let n = 150;
332        let w = 64u32;
333        let h = 64u32;
334        let fps = 30.0;
335        let frames = synth_pulse_frames(n, w, h, fps, 72.0);
336        let r = self_monitor_pulse_evm(grant(), &frames, n, w, h, fps, false, 0.05);
337        // Quality + spectral path: expect a estimate or low-confidence abstain
338        // (never invent NoConsent). Prefer estimate when SNR is good.
339        if r.abstained {
340            assert_eq!(r.reason, Some(PulseAbstain::LowConfidence));
341        } else {
342            assert!(!r.used_evm);
343            assert!((r.bpm - 72.0).abs() < 15.0, "bpm={}", r.bpm);
344            assert!(r.confidence > 0.0);
345        }
346    }
347
348    #[test]
349    fn synthetic_pulse_with_evm_flag() {
350        let n = 90;
351        let w = 48u32;
352        let h = 48u32;
353        let fps = 30.0;
354        let frames = synth_pulse_frames(n, w, h, fps, 60.0);
355        let r = self_monitor_pulse_evm(grant(), &frames, n, w, h, fps, true, 0.05);
356        // EVM path may run or fall back; must not claim consent failure.
357        assert_ne!(r.reason, Some(PulseAbstain::NoConsent));
358        if !r.abstained {
359            assert!((r.bpm - 60.0).abs() < 20.0, "bpm={}", r.bpm);
360        }
361    }
362
363    #[test]
364    fn flat_uniform_frames_quality_or_conf_abstain() {
365        // Uniform frames → low blur score → quality abstain (or conf if blur slips).
366        let n = 64;
367        let w = 32u32;
368        let h = 32u32;
369        let frames = vec![128u8; n * (w * h * 3) as usize];
370        let r = self_monitor_pulse_evm(grant(), &frames, n, w, h, 30.0, false, 0.2);
371        assert!(r.abstained);
372        assert!(matches!(
373            r.reason,
374            Some(PulseAbstain::LowQuality | PulseAbstain::LowConfidence)
375        ));
376    }
377}