Skip to main content

qualia_vision/biosense/liveness/
profile_asymmetry_ratio.rs

1//! Profile Asymmetry Ratio (PAR) — geometric lock against 2D rigid planes.
2//!
3//! # Critical trap: never trust model Z
4//!
5//! MediaPipe (and similar) *infer* depth from a monocular 2D image using
6//! statistical priors. A flat iPad showing a face will yield a "perfect"
7//! hallucinated mesh Z. Validating on model Z lets the attack pass.
8//!
9//! This module uses **only raw image-space \(x\) coordinates** of three
10//! landmarks (MediaPipe Face Mesh indices):
11//!
12//! | Role | Slot | MediaPipe index |
13//! |------|------|-----------------|
14//! | Nose tip \(N\) | [`PadLandmarkId::NoseTip`] | **1** |
15//! | Left edge \(L\) | [`PadLandmarkId::LeftCheek`] | **234** |
16//! | Right edge \(R\) | [`PadLandmarkId::RightCheek`] | **454** |
17//!
18//! ## Math
19//!
20//! \[
21//! d_L = \lvert x_N - x_L\rvert,\quad
22//! d_R = \lvert x_R - x_N\rvert,\quad
23//! PAR = d_L / d_R
24//! \]
25//!
26//! At frontal \(t_0\): \(PAR \approx 1\). At peak yaw \(t_1\): a true 3D head
27//! produces a large \(|PAR(t_1)/PAR(t_0) - 1|\) (occlusion spike). A flat mask
28//! scales both sides by \(\cos\theta\), so \(\Delta PAR \approx 0\).
29//!
30//! Require \(|\Delta yaw| \ge 25^\circ\) so the spike is unambiguous. Baseline
31//! PAR at \(t_0\) is normalized before the delta (human faces are asymmetric).
32
33use super::landmark_types::{LandmarkFrame, PadLandmarkId};
34use super::rigid_head_pose::HeadPose;
35
36/// Default \(\tau\): minimum baseline-normalized \(|\Delta PAR|\) for live 3D.
37/// Empirical; calibrate in MANIFEST for production yaw policy.
38pub const DEFAULT_PAR_TAU: f32 = 0.6;
39
40/// Minimum absolute yaw span (degrees) between frontal and peak for a valid test.
41pub const MIN_YAW_SPAN_DEG: f32 = 25.0;
42
43/// Minimum frames with valid N/L/R \(x\).
44pub const MIN_PAR_SAMPLES: usize = 4;
45
46/// Floor on \(d_R\) (and \(d_L\)) in image units to avoid division blow-up.
47const MIN_HORIZ_PX: f32 = 1e-3;
48
49#[derive(Debug, Clone, Copy, PartialEq)]
50pub enum ParVerdict {
51    /// \(\Delta PAR\) exceeds \(\tau\) under sufficient yaw — live 3D occlusion.
52    Live3d {
53        delta_par: f32,
54        par_t0: f32,
55        par_t1: f32,
56        yaw_span_deg: f32,
57    },
58    /// \(\Delta PAR\) too small — consistent with planar cosine compression.
59    FlatSurface {
60        delta_par: f32,
61        par_t0: f32,
62        par_t1: f32,
63        yaw_span_deg: f32,
64    },
65    InsufficientYaw {
66        yaw_span_deg: f32,
67    },
68    InsufficientSamples,
69    MissingLandmarks,
70}
71
72/// Horizontal distances and PAR from **\(x\) only** (y and model Z ignored).
73#[derive(Debug, Clone, Copy, PartialEq)]
74pub struct ParSample {
75    pub d_l: f32,
76    pub d_r: f32,
77    pub par: f32,
78}
79
80/// \(d_L = |x_N - x_L|\), \(d_R = |x_R - x_N|\), \(PAR = d_L / d_R\).
81///
82/// Returns `None` if nose / left / right edge missing or degenerate.
83pub fn profile_asymmetry_ratio(frame: &LandmarkFrame) -> Option<ParSample> {
84    let n = frame.get(PadLandmarkId::NoseTip)?;
85    let l = frame.get(PadLandmarkId::LeftCheek)?;
86    let r = frame.get(PadLandmarkId::RightCheek)?;
87    // Explicitly use .x only — never any z field (Landmark2 has none by design).
88    let d_l = (n.x - l.x).abs();
89    let d_r = (r.x - n.x).abs();
90    if d_l < MIN_HORIZ_PX || d_r < MIN_HORIZ_PX {
91        return None;
92    }
93    Some(ParSample {
94        d_l,
95        d_r,
96        par: d_l / d_r,
97    })
98}
99
100/// Baseline-normalized absolute delta: \(|PAR(t_1)/PAR(t_0) - 1|\).
101#[inline]
102pub fn normalized_par_delta(par_t0: f32, par_t1: f32) -> Option<f32> {
103    if !par_t0.is_finite() || !par_t1.is_finite() || par_t0.abs() < 1e-6 {
104        return None;
105    }
106    Some((par_t1 / par_t0 - 1.0).abs())
107}
108
109/// Evaluate PAR geometric lock over a landmark + pose trajectory.
110///
111/// * \(t_0\) — first valid PAR sample (challenge start / frontal).
112/// * \(t_1\) — sample at peak \(|yaw - yaw_{t0}|\) (must reach ≥ [`MIN_YAW_SPAN_DEG`]).
113/// * `tau` — minimum normalized \(\Delta PAR\) (default [`DEFAULT_PAR_TAU`] = 0.6).
114///
115/// `poses[i]` aligns with `frames[i]`. Pose yaw is used only to pick \(t_1\) and
116/// enforce span — never as a substitute for PAR, and never from model Z.
117pub fn evaluate_profile_asymmetry(
118    frames: &[LandmarkFrame],
119    poses: &[HeadPose],
120    tau: f32,
121) -> ParVerdict {
122    if frames.len() != poses.len() || frames.is_empty() {
123        return ParVerdict::InsufficientSamples;
124    }
125
126    // t0: first frame with valid PAR (frontal baseline).
127    let mut i0 = None;
128    for i in 0..frames.len() {
129        if profile_asymmetry_ratio(&frames[i]).is_some() {
130            i0 = Some(i);
131            break;
132        }
133    }
134    let Some(i0) = i0 else {
135        return ParVerdict::MissingLandmarks;
136    };
137    let par0 = match profile_asymmetry_ratio(&frames[i0]) {
138        Some(s) => s.par,
139        None => return ParVerdict::MissingLandmarks,
140    };
141    let yaw0 = poses[i0].yaw_deg;
142
143    // t1: peak |Δyaw| among samples with valid PAR.
144    let mut i1 = i0;
145    let mut best_abs = 0.0f32;
146    let mut valid = 0usize;
147    for i in 0..frames.len() {
148        if profile_asymmetry_ratio(&frames[i]).is_none() {
149            continue;
150        }
151        valid += 1;
152        let ad = (poses[i].yaw_deg - yaw0).abs();
153        if ad >= best_abs {
154            best_abs = ad;
155            i1 = i;
156        }
157    }
158
159    if valid < MIN_PAR_SAMPLES {
160        return ParVerdict::InsufficientSamples;
161    }
162
163    let yaw_span_deg = (poses[i1].yaw_deg - yaw0).abs();
164    if yaw_span_deg < MIN_YAW_SPAN_DEG {
165        return ParVerdict::InsufficientYaw { yaw_span_deg };
166    }
167
168    let par1 = match profile_asymmetry_ratio(&frames[i1]) {
169        Some(s) => s.par,
170        None => return ParVerdict::MissingLandmarks,
171    };
172
173    let Some(delta_par) = normalized_par_delta(par0, par1) else {
174        return ParVerdict::MissingLandmarks;
175    };
176
177    if delta_par > tau {
178        ParVerdict::Live3d {
179            delta_par,
180            par_t0: par0,
181            par_t1: par1,
182            yaw_span_deg,
183        }
184    } else {
185        ParVerdict::FlatSurface {
186            delta_par,
187            par_t0: par0,
188            par_t1: par1,
189            yaw_span_deg,
190        }
191    }
192}
193
194// ── Synthetic geometry for unit tests (image x only) ─────────────────────
195
196/// Flat plane: both sides scale by \(\cos\theta\); PAR stays ≈ constant.
197/// Nose shifts so pose estimation still reports yaw (ratio remains cosine-equal).
198#[cfg(test)]
199pub fn synthetic_flat_par_frame(yaw_deg: f32, t_ms: u32) -> (LandmarkFrame, HeadPose) {
200    use super::landmark_types::Landmark2;
201    let cos = yaw_deg.to_radians().cos().abs().max(0.15);
202    // Stable eye line (IOD) for rigid pose; plane width compresses with cos.
203    let eye_l = 160.0f32;
204    let eye_r = 240.0f32;
205    let eye_c = 0.5 * (eye_l + eye_r);
206    // Slight nose shift for pose; both cheek half-widths = same cos scale → PAR fixed.
207    let nose_x = eye_c + yaw_deg * 0.55;
208    let half = 40.0 * cos;
209    let mut f = LandmarkFrame::empty(t_ms);
210    f.set(PadLandmarkId::NoseTip, Landmark2::new(nose_x, 150.0));
211    // Equal horizontal distances after accounting for nose offset: place edges
212    // so d_L == d_R == half (PAR = 1 for all yaw).
213    f.set(
214        PadLandmarkId::LeftCheek,
215        Landmark2::new(nose_x - half, 160.0),
216    );
217    f.set(
218        PadLandmarkId::RightCheek,
219        Landmark2::new(nose_x + half, 160.0),
220    );
221    f.set(PadLandmarkId::LeftEyeOuter, Landmark2::new(eye_l, 120.0));
222    f.set(PadLandmarkId::RightEyeOuter, Landmark2::new(eye_r, 120.0));
223    f.set(PadLandmarkId::Chin, Landmark2::new(nose_x, 210.0));
224    (
225        f,
226        HeadPose {
227            yaw_deg,
228            pitch_deg: 0.0,
229            roll_deg: 0.0,
230            scale: eye_r - eye_l,
231        },
232    )
233}
234
235/// 3D head: nose occludes receding cheek — one horizontal side collapses.
236/// Eyes stay on a stable IOD line so PnP-class yaw tracks the labeled turn.
237#[cfg(test)]
238pub fn synthetic_3d_par_frame(yaw_deg: f32, t_ms: u32) -> (LandmarkFrame, HeadPose) {
239    use super::landmark_types::Landmark2;
240    let mut f = LandmarkFrame::empty(t_ms);
241    let eye_l = 160.0f32;
242    let eye_r = 240.0f32;
243    let eye_c = 0.5 * (eye_l + eye_r);
244    // Nose migrates with yaw (subject look-left → +x) relative to fixed eyes.
245    let nose_x = eye_c + yaw_deg * 0.9;
246    // Receding side collapses toward nose; advancing side stays wide.
247    // Positive yaw: left is receding → d_L shrinks, d_R stays large → PAR ↓.
248    let collapse = (yaw_deg.abs() / 30.0).clamp(0.0, 1.0);
249    let d_recede = 40.0 * (1.0 - 0.85 * collapse).max(0.08);
250    let d_advance = 40.0 * (1.0 + 0.15 * collapse);
251    let (d_l, d_r) = if yaw_deg >= 0.0 {
252        (d_recede, d_advance)
253    } else {
254        (d_advance, d_recede)
255    };
256    f.set(PadLandmarkId::NoseTip, Landmark2::new(nose_x, 150.0));
257    f.set(
258        PadLandmarkId::LeftCheek,
259        Landmark2::new(nose_x - d_l, 160.0),
260    );
261    f.set(
262        PadLandmarkId::RightCheek,
263        Landmark2::new(nose_x + d_r, 160.0),
264    );
265    f.set(PadLandmarkId::LeftEyeOuter, Landmark2::new(eye_l, 120.0));
266    f.set(PadLandmarkId::RightEyeOuter, Landmark2::new(eye_r, 120.0));
267    f.set(
268        PadLandmarkId::Chin,
269        Landmark2::new(nose_x * 0.15 + eye_c * 0.85, 210.0),
270    );
271    (
272        f,
273        HeadPose {
274            yaw_deg,
275            pitch_deg: 0.0,
276            roll_deg: 0.0,
277            scale: eye_r - eye_l,
278        },
279    )
280}
281
282#[cfg(test)]
283mod tests {
284    use super::*;
285    use crate::biosense::liveness::landmark_types::Landmark2;
286
287    #[test]
288    fn par_frontal_near_one() {
289        let mut f = LandmarkFrame::empty(0);
290        f.set(PadLandmarkId::NoseTip, Landmark2::new(140.0, 150.0));
291        f.set(PadLandmarkId::LeftCheek, Landmark2::new(100.0, 160.0));
292        f.set(PadLandmarkId::RightCheek, Landmark2::new(180.0, 160.0));
293        let s = profile_asymmetry_ratio(&f).unwrap();
294        assert!((s.par - 1.0).abs() < 1e-5, "par={}", s.par);
295        assert!((s.d_l - 40.0).abs() < 1e-5);
296        assert!((s.d_r - 40.0).abs() < 1e-5);
297    }
298
299    #[test]
300    fn par_uses_x_only() {
301        // Same x, different y → identical PAR (y must not affect).
302        let mut a = LandmarkFrame::empty(0);
303        a.set(PadLandmarkId::NoseTip, Landmark2::new(50.0, 10.0));
304        a.set(PadLandmarkId::LeftCheek, Landmark2::new(10.0, 999.0));
305        a.set(PadLandmarkId::RightCheek, Landmark2::new(90.0, -50.0));
306        let mut b = LandmarkFrame::empty(0);
307        b.set(PadLandmarkId::NoseTip, Landmark2::new(50.0, 500.0));
308        b.set(PadLandmarkId::LeftCheek, Landmark2::new(10.0, 0.0));
309        b.set(PadLandmarkId::RightCheek, Landmark2::new(90.0, 0.0));
310        assert_eq!(
311            profile_asymmetry_ratio(&a).unwrap().par,
312            profile_asymmetry_ratio(&b).unwrap().par
313        );
314    }
315
316    #[test]
317    fn flat_mask_delta_near_zero() {
318        let mut frames = [LandmarkFrame::empty(0); 8];
319        let mut poses = [HeadPose::default(); 8];
320        for i in 0..8 {
321            let yaw = i as f32 * 5.0; // 0 → 35°
322            let (f, p) = synthetic_flat_par_frame(yaw, i as u32 * 100);
323            frames[i] = f;
324            poses[i] = p;
325        }
326        let v = evaluate_profile_asymmetry(&frames, &poses, DEFAULT_PAR_TAU);
327        match v {
328            ParVerdict::FlatSurface { delta_par, .. } => {
329                assert!(delta_par < 0.15, "flat delta_par={}", delta_par);
330            }
331            other => panic!("expected FlatSurface, got {:?}", other),
332        }
333    }
334
335    #[test]
336    fn live_3d_delta_exceeds_tau() {
337        let mut frames = [LandmarkFrame::empty(0); 8];
338        let mut poses = [HeadPose::default(); 8];
339        for i in 0..8 {
340            let yaw = i as f32 * 5.0; // 0 → 35°
341            let (f, p) = synthetic_3d_par_frame(yaw, i as u32 * 100);
342            frames[i] = f;
343            poses[i] = p;
344        }
345        let v = evaluate_profile_asymmetry(&frames, &poses, DEFAULT_PAR_TAU);
346        match v {
347            ParVerdict::Live3d { delta_par, .. } => {
348                assert!(delta_par > DEFAULT_PAR_TAU, "delta_par={}", delta_par);
349            }
350            other => panic!("expected Live3d, got {:?}", other),
351        }
352    }
353
354    #[test]
355    fn insufficient_yaw_rejected() {
356        let mut frames = [LandmarkFrame::empty(0); 6];
357        let mut poses = [HeadPose::default(); 6];
358        for i in 0..6 {
359            let yaw = i as f32 * 2.0; // max 10° < 25°
360            let (f, p) = synthetic_3d_par_frame(yaw, i as u32 * 100);
361            frames[i] = f;
362            poses[i] = p;
363        }
364        let v = evaluate_profile_asymmetry(&frames, &poses, DEFAULT_PAR_TAU);
365        assert!(
366            matches!(v, ParVerdict::InsufficientYaw { .. }),
367            "got {:?}",
368            v
369        );
370    }
371
372    #[test]
373    fn mediapipe_indices_documented() {
374        assert_eq!(PadLandmarkId::NoseTip.mediapipe_index(), 1);
375        assert_eq!(PadLandmarkId::LeftCheek.mediapipe_index(), 234);
376        assert_eq!(PadLandmarkId::RightCheek.mediapipe_index(), 454);
377    }
378}