Skip to main content

qualia_vision/biosense/liveness/
action_threshold.rs

1//! Map challenges to geometric / expression thresholds.
2//!
3//! Head turns use rigid yaw (degrees). Expressions use Euclidean landmark
4//! ratios normalized by interocular distance so camera distance cancels.
5
6use super::challenge_kind::ChallengeKind;
7use super::landmark_types::{LandmarkFrame, MeshBlendProxies, PadLandmarkId};
8use super::rigid_head_pose::HeadPose;
9
10/// Default yaw gate for "look left/right" challenges (degrees).
11pub const DEFAULT_YAW_THRESHOLD_DEG: f32 = 25.0;
12/// Mouth open / smile mouth height ratio (mouth gap / interocular).
13pub const DEFAULT_MOUTH_OPEN_RATIO: f32 = 0.22;
14/// Smile blendshape proxy peak when blendshapes available.
15pub const DEFAULT_SMILE_BLEND: f32 = 0.35;
16/// Blink blendshape peak.
17pub const DEFAULT_BLINK_PEAK: f32 = 0.40;
18
19#[derive(Debug, Clone, Copy)]
20pub struct ActionThresholds {
21    pub yaw_deg: f32,
22    pub mouth_open_ratio: f32,
23    pub smile_blend: f32,
24    pub blink_peak: f32,
25}
26
27impl Default for ActionThresholds {
28    fn default() -> Self {
29        Self {
30            yaw_deg: DEFAULT_YAW_THRESHOLD_DEG,
31            mouth_open_ratio: DEFAULT_MOUTH_OPEN_RATIO,
32            smile_blend: DEFAULT_SMILE_BLEND,
33            blink_peak: DEFAULT_BLINK_PEAK,
34        }
35    }
36}
37
38/// Mouth aperture normalized by interocular (None if landmarks missing).
39pub fn mouth_open_ratio(frame: &LandmarkFrame) -> Option<f32> {
40    let upper = frame.get(PadLandmarkId::UpperLip)?;
41    let lower = frame.get(PadLandmarkId::LowerLip)?;
42    let iod = frame.interocular()?;
43    Some(upper.dist(lower) / iod)
44}
45
46/// Whether the action criterion is met for this frame's pose + optional proxies.
47pub fn action_met_at_frame(
48    challenge: ChallengeKind,
49    pose: HeadPose,
50    pose0: HeadPose,
51    frame: &LandmarkFrame,
52    blend: Option<MeshBlendProxies>,
53    thr: &ActionThresholds,
54) -> bool {
55    match challenge {
56        ChallengeKind::YawLeft => (pose.yaw_deg - pose0.yaw_deg) >= thr.yaw_deg,
57        ChallengeKind::YawRight => (pose0.yaw_deg - pose.yaw_deg) >= thr.yaw_deg,
58        ChallengeKind::Smile => {
59            let geo = mouth_open_ratio(frame).map(|r| r >= thr.mouth_open_ratio * 0.85);
60            let bl = blend.map(|b| b.smile >= thr.smile_blend);
61            matches!((geo, bl), (Some(true), _) | (_, Some(true)))
62        }
63        ChallengeKind::BlinkTwice => {
64            // Per-frame blink peak; event counting is done by the orchestrator.
65            blend.map(|b| b.blink >= thr.blink_peak).unwrap_or(false)
66        }
67        ChallengeKind::OpenMouth => mouth_open_ratio(frame)
68            .map(|r| r >= thr.mouth_open_ratio)
69            .unwrap_or(false),
70        ChallengeKind::PitchUp => (pose0.pitch_deg - pose.pitch_deg) >= thr.yaw_deg * 0.7,
71        ChallengeKind::PitchDown => (pose.pitch_deg - pose0.pitch_deg) >= thr.yaw_deg * 0.7,
72    }
73}
74
75/// Onset: motion in the challenge direction exceeds a fraction of the threshold.
76pub fn action_onset_at_frame(
77    challenge: ChallengeKind,
78    pose: HeadPose,
79    pose0: HeadPose,
80    thr: &ActionThresholds,
81) -> bool {
82    let frac = 0.15;
83    match challenge {
84        ChallengeKind::YawLeft => (pose.yaw_deg - pose0.yaw_deg) >= thr.yaw_deg * frac,
85        ChallengeKind::YawRight => (pose0.yaw_deg - pose.yaw_deg) >= thr.yaw_deg * frac,
86        ChallengeKind::PitchUp => (pose0.pitch_deg - pose.pitch_deg) >= thr.yaw_deg * frac * 0.7,
87        ChallengeKind::PitchDown => (pose.pitch_deg - pose0.pitch_deg) >= thr.yaw_deg * frac * 0.7,
88        ChallengeKind::Smile | ChallengeKind::OpenMouth | ChallengeKind::BlinkTwice => {
89            // Expression onset handled via blend/geometry deltas in orchestrator.
90            false
91        }
92    }
93}
94
95#[cfg(test)]
96mod tests {
97    use super::*;
98    use crate::biosense::liveness::landmark_types::{Landmark2, LandmarkFrame, PadLandmarkId};
99
100    #[test]
101    fn yaw_left_threshold() {
102        let pose0 = HeadPose {
103            yaw_deg: 0.0,
104            ..Default::default()
105        };
106        let pose = HeadPose {
107            yaw_deg: 30.0,
108            ..Default::default()
109        };
110        let f = LandmarkFrame::empty(0);
111        assert!(action_met_at_frame(
112            ChallengeKind::YawLeft,
113            pose,
114            pose0,
115            &f,
116            None,
117            &ActionThresholds::default()
118        ));
119    }
120
121    #[test]
122    fn mouth_ratio_normalized() {
123        let mut f = LandmarkFrame::empty(0);
124        f.set(PadLandmarkId::LeftEyeOuter, Landmark2::new(0.0, 0.0));
125        f.set(PadLandmarkId::RightEyeOuter, Landmark2::new(100.0, 0.0));
126        f.set(PadLandmarkId::UpperLip, Landmark2::new(50.0, 40.0));
127        f.set(PadLandmarkId::LowerLip, Landmark2::new(50.0, 70.0));
128        let r = mouth_open_ratio(&f).unwrap();
129        assert!((r - 0.30).abs() < 1e-4);
130    }
131}