Skip to main content

qualia_vision/biosense/liveness/
non_rigid_z.rs

1//! Non-rigid occlusion gate for 2D mask rejection.
2//!
3//! **Does not use model-inferred Z.** MediaPipe depth is a statistical prior
4//! and will pass flat-screen attacks. The real lock is
5//! [`crate::biosense::liveness::profile_asymmetry_ratio()`]
6//! — Profile Asymmetry Ratio on raw image \(x\) of landmarks 1 / 234 / 454.
7//!
8//! This module is a thin compatibility façade over PAR so existing call sites
9//! (`evaluate_non_rigid_z`, `NonRigidVerdict`) keep working.
10
11use super::landmark_types::LandmarkFrame;
12use super::profile_asymmetry_ratio::{
13    evaluate_profile_asymmetry, ParVerdict, DEFAULT_PAR_TAU, MIN_YAW_SPAN_DEG,
14};
15use super::rigid_head_pose::HeadPose;
16
17/// Default τ for baseline-normalized ΔPAR (see PAR module).
18pub const DEFAULT_MIN_NONRIGID_SCORE: f32 = DEFAULT_PAR_TAU;
19
20pub use super::profile_asymmetry_ratio::MIN_YAW_SPAN_DEG as MIN_Z_YAW_SPAN_DEG;
21
22#[derive(Debug, Clone, Copy, PartialEq)]
23pub enum NonRigidVerdict {
24    /// PAR occlusion spike — live 3D head in image space.
25    Live3d { score: f32 },
26    /// ΔPAR ≈ 0 under yaw — planar / flat surface.
27    FlatSurface { score: f32 },
28    /// Yaw span < 25° or too few samples.
29    InsufficientMotion,
30    /// Missing nose / left / right edge landmarks.
31    MissingLandmarks,
32}
33
34/// Evaluate the flat-mask lock via **PAR only** (raw 2D \(x\)).
35///
36/// `min_score` is τ for `|PAR(t1)/PAR(t0) - 1|` (default 0.6).
37/// `poses` select peak yaw and enforce ≥ 25° span — not a Z source.
38pub fn evaluate_non_rigid_z(
39    frames: &[LandmarkFrame],
40    poses: &[HeadPose],
41    min_score: f32,
42) -> NonRigidVerdict {
43    match evaluate_profile_asymmetry(frames, poses, min_score) {
44        ParVerdict::Live3d { delta_par, .. } => NonRigidVerdict::Live3d { score: delta_par },
45        ParVerdict::FlatSurface { delta_par, .. } => {
46            NonRigidVerdict::FlatSurface { score: delta_par }
47        }
48        ParVerdict::InsufficientYaw { .. } | ParVerdict::InsufficientSamples => {
49            NonRigidVerdict::InsufficientMotion
50        }
51        ParVerdict::MissingLandmarks => NonRigidVerdict::MissingLandmarks,
52    }
53}
54
55/// Re-export span constant for orchestrator docs.
56pub const REQUIRED_YAW_FOR_PAR: f32 = MIN_YAW_SPAN_DEG;
57
58#[cfg(test)]
59pub use super::profile_asymmetry_ratio::{synthetic_3d_par_frame, synthetic_flat_par_frame};
60
61#[cfg(test)]
62mod tests {
63    use super::*;
64    use crate::biosense::liveness::profile_asymmetry_ratio::{
65        synthetic_3d_par_frame, synthetic_flat_par_frame,
66    };
67
68    #[test]
69    fn flat_surface_rejected_via_par() {
70        let mut frames = [LandmarkFrame::empty(0); 8];
71        let mut poses = [HeadPose::default(); 8];
72        for i in 0..8 {
73            let (f, p) = synthetic_flat_par_frame(i as f32 * 5.0, i as u32 * 100);
74            frames[i] = f;
75            poses[i] = p;
76        }
77        let v = evaluate_non_rigid_z(&frames, &poses, DEFAULT_MIN_NONRIGID_SCORE);
78        assert!(
79            matches!(v, NonRigidVerdict::FlatSurface { .. }),
80            "got {:?}",
81            v
82        );
83    }
84
85    #[test]
86    fn live_3d_accepted_via_par() {
87        let mut frames = [LandmarkFrame::empty(0); 8];
88        let mut poses = [HeadPose::default(); 8];
89        for i in 0..8 {
90            let (f, p) = synthetic_3d_par_frame(i as f32 * 5.0, i as u32 * 100);
91            frames[i] = f;
92            poses[i] = p;
93        }
94        let v = evaluate_non_rigid_z(&frames, &poses, DEFAULT_MIN_NONRIGID_SCORE);
95        assert!(
96            matches!(v, NonRigidVerdict::Live3d { score } if score > 0.6),
97            "got {:?}",
98            v
99        );
100    }
101}