Skip to main content

qualia_vision/biosense/face_mesh/
mod.rs

1//! MediaPipe Face Mesh layout adapters for pure-landmark PAD.
2//!
3//! Packs full-mesh flat buffers into the eight-slot `LandmarkFrame()` used by
4//! challenge-response PAD. **Never uses model Z** — only \(x,y\).
5//!
6//! No ONNX / MediaPipe runtime here (that is Track S2). Buffer → geometry only.
7
8pub mod evaluate_pad_from_mediapipe_trace;
9pub mod landmarks_from_normalized;
10pub mod mediapipe_index;
11pub mod pack_landmark_frame;
12
13pub use evaluate_pad_from_mediapipe_trace::{
14    evaluate_pad_from_mediapipe_trace, MAX_MEDIAPIPE_PAD_FRAMES,
15};
16pub use landmarks_from_normalized::landmarks_from_normalized;
17pub use mediapipe_index::{
18    mediapipe_index_for_pad, pad_id_for_mediapipe_index, MEDIAPIPE_FACE_MESH_COUNT,
19    PAD_LANDMARK_IDS, PAD_MEDIAPIPE_INDICES,
20};
21pub use pack_landmark_frame::{pack_landmark_frame, LandmarkBufferLayout};
22
23#[cfg(test)]
24mod trace_tests {
25    use super::*;
26    use crate::biosense::consent::{BiosenseConsent, BiosensePurpose};
27    use crate::biosense::liveness::camera_stream_integrity::CameraStreamAttestation;
28    use crate::biosense::liveness::challenge_kind::ChallengeKind;
29    use crate::biosense::liveness::challenge_pad::{PadReason, PadThresholds};
30    use crate::biosense::liveness::landmark_types::{Landmark2, LandmarkFrame, PadLandmarkId};
31    use crate::biosense::liveness::non_rigid_z::DEFAULT_MIN_NONRIGID_SCORE;
32    use crate::biosense::liveness::profile_asymmetry_ratio::{
33        synthetic_3d_par_frame, synthetic_flat_par_frame,
34    };
35
36    fn consent() -> BiosenseConsent {
37        BiosenseConsent::grant_security_template(1)
38    }
39
40    /// Scatter a PAD frame into a full MediaPipe xy flat buffer (other indices 0).
41    fn frame_to_mp_xy(frame: &LandmarkFrame) -> Vec<f32> {
42        let mut buf = vec![0.0f32; MEDIAPIPE_FACE_MESH_COUNT * 2];
43        for id in PAD_LANDMARK_IDS {
44            if let Some(p) = frame.get(id) {
45                let i = id.mediapipe_index() as usize;
46                buf[i * 2] = p.x;
47                buf[i * 2 + 1] = p.y;
48            }
49        }
50        buf
51    }
52
53    /// Same as xy but with a large fake Z so tests prove Z is ignored.
54    fn frame_to_mp_xyz_with_poison_z(frame: &LandmarkFrame) -> Vec<f32> {
55        let mut buf = vec![0.0f32; MEDIAPIPE_FACE_MESH_COUNT * 3];
56        for id in PAD_LANDMARK_IDS {
57            if let Some(p) = frame.get(id) {
58                let i = id.mediapipe_index() as usize;
59                buf[i * 3] = p.x;
60                buf[i * 3 + 1] = p.y;
61                buf[i * 3 + 2] = 1.0e6; // poison Z — must not affect PAD
62            }
63        }
64        buf
65    }
66
67    fn yaw_mp_trace(live3d: bool) -> (Vec<u32>, Vec<Vec<f32>>) {
68        let mut times = Vec::new();
69        let mut flats = Vec::new();
70        for i in 0..12 {
71            let t = 40 + i as u32 * 80;
72            let yaw = i as f32 * 4.0; // 0 → 44°
73            let (mut f, _) = if live3d {
74                synthetic_3d_par_frame(yaw, t)
75            } else {
76                synthetic_flat_par_frame(yaw, t)
77            };
78            f.t_ms = t;
79            if live3d {
80                let j = ((i as f32) * 2.1).sin() * 0.45;
81                if let Some(n) = f.get(PadLandmarkId::NoseTip) {
82                    f.set(
83                        PadLandmarkId::NoseTip,
84                        Landmark2::new(n.x + j, n.y + j * 0.3),
85                    );
86                }
87            }
88            times.push(t);
89            flats.push(frame_to_mp_xy(&f));
90        }
91        (times, flats)
92    }
93
94    #[test]
95    fn pack_roundtrip_preserves_par_slots() {
96        let (f, _) = synthetic_3d_par_frame(20.0, 100);
97        let flat = frame_to_mp_xy(&f);
98        let packed = pack_landmark_frame(100, &flat, LandmarkBufferLayout::XyInterleaved).unwrap();
99        for id in [
100            PadLandmarkId::NoseTip,
101            PadLandmarkId::LeftCheek,
102            PadLandmarkId::RightCheek,
103            PadLandmarkId::LeftEyeOuter,
104            PadLandmarkId::RightEyeOuter,
105            PadLandmarkId::Chin,
106        ] {
107            let a = f.get(id).unwrap();
108            let b = packed.get(id).unwrap();
109            assert!(
110                (a.x - b.x).abs() < 1e-5 && (a.y - b.y).abs() < 1e-5,
111                "{:?}",
112                id
113            );
114        }
115    }
116
117    #[test]
118    fn flat_par_via_mediapipe_trace_fails() {
119        let (times, flats) = yaw_mp_trace(false);
120        let refs: Vec<&[f32]> = flats.iter().map(|v| v.as_slice()).collect();
121        let mut thr = PadThresholds::default();
122        thr.require_jitter = false;
123        thr.min_nonrigid_score = DEFAULT_MIN_NONRIGID_SCORE;
124        thr.action.yaw_deg = 15.0;
125        let r = evaluate_pad_from_mediapipe_trace(
126            consent(),
127            ChallengeKind::YawLeft,
128            LandmarkBufferLayout::XyInterleaved,
129            &times,
130            &refs,
131            &[],
132            CameraStreamAttestation::default(),
133            &thr,
134            None,
135        )
136        .unwrap();
137        assert!(!r.passed);
138        assert!(
139            matches!(
140                r.reason,
141                PadReason::FlatSurface | PadReason::WrongAction | PadReason::StaticMesh
142            ),
143            "got {:?}",
144            r.reason
145        );
146    }
147
148    #[test]
149    fn live3d_par_via_mediapipe_xyz_not_flat() {
150        let (times, flats_xy) = yaw_mp_trace(true);
151        // Rebuild as xyz with poison Z to prove Z is unused.
152        let flats_xyz: Vec<Vec<f32>> = flats_xy
153            .iter()
154            .map(|xy| {
155                // Re-pack through LandmarkFrame then poison-z layout.
156                let f = pack_landmark_frame(0, xy, LandmarkBufferLayout::XyInterleaved).unwrap();
157                frame_to_mp_xyz_with_poison_z(&f)
158            })
159            .collect();
160        let refs: Vec<&[f32]> = flats_xyz.iter().map(|v| v.as_slice()).collect();
161        let mut thr = PadThresholds::default();
162        thr.jitter.min_rms = 0.00005;
163        thr.min_nonrigid_score = DEFAULT_MIN_NONRIGID_SCORE;
164        thr.action.yaw_deg = 18.0;
165        let r = evaluate_pad_from_mediapipe_trace(
166            consent(),
167            ChallengeKind::YawLeft,
168            LandmarkBufferLayout::XyzInterleaved,
169            &times,
170            &refs,
171            &[],
172            CameraStreamAttestation::default(),
173            &thr,
174            None,
175        )
176        .unwrap();
177        assert_ne!(
178            r.reason,
179            PadReason::FlatSurface,
180            "poison Z must not fake 3D"
181        );
182        // Live synthetic may pass or hit soft gates; must not be flat-mask reject.
183        assert!(
184            r.passed
185                || matches!(
186                    r.reason,
187                    PadReason::WrongAction
188                        | PadReason::StaticMesh
189                        | PadReason::JitterAnomaly
190                        | PadReason::TimeToStartExceeded
191                        | PadReason::TimeToCompleteExceeded
192                        | PadReason::PoseUnavailable
193                ),
194            "unexpected {:?}",
195            r.reason
196        );
197    }
198
199    #[test]
200    fn no_consent_fails() {
201        let (times, flats) = yaw_mp_trace(true);
202        let refs: Vec<&[f32]> = flats.iter().map(|v| v.as_slice()).collect();
203        let r = evaluate_pad_from_mediapipe_trace(
204            BiosenseConsent::denied(BiosensePurpose::Security),
205            ChallengeKind::YawLeft,
206            LandmarkBufferLayout::XyInterleaved,
207            &times,
208            &refs,
209            &[],
210            CameraStreamAttestation::default(),
211            &PadThresholds::default(),
212            None,
213        )
214        .unwrap();
215        assert!(!r.passed);
216        assert_eq!(r.reason, PadReason::NoConsent);
217    }
218
219    #[test]
220    fn normalized_trace_scales_before_pad() {
221        // One frontal frame in normalized coords → pack + denorm; nose near center.
222        let mut buf = vec![0.0f32; MEDIAPIPE_FACE_MESH_COUNT * 2];
223        let set = |buf: &mut [f32], id: PadLandmarkId, x: f32, y: f32| {
224            let i = id.mediapipe_index() as usize;
225            buf[i * 2] = x;
226            buf[i * 2 + 1] = y;
227        };
228        set(&mut buf, PadLandmarkId::NoseTip, 0.5, 0.5);
229        set(&mut buf, PadLandmarkId::Chin, 0.5, 0.8);
230        set(&mut buf, PadLandmarkId::LeftEyeOuter, 0.35, 0.4);
231        set(&mut buf, PadLandmarkId::RightEyeOuter, 0.65, 0.4);
232        set(&mut buf, PadLandmarkId::LeftCheek, 0.25, 0.55);
233        set(&mut buf, PadLandmarkId::RightCheek, 0.75, 0.55);
234        let f = pack_landmark_frame(0, &buf, LandmarkBufferLayout::XyInterleaved).unwrap();
235        let px = landmarks_from_normalized(f, 200.0, 100.0);
236        let n = px.get(PadLandmarkId::NoseTip).unwrap();
237        assert!((n.x - 100.0).abs() < 1e-3);
238        assert!((n.y - 50.0).abs() < 1e-3);
239    }
240}