qualia_vision/biosense/liveness/
profile_asymmetry_ratio.rs1use super::landmark_types::{LandmarkFrame, PadLandmarkId};
34use super::rigid_head_pose::HeadPose;
35
36pub const DEFAULT_PAR_TAU: f32 = 0.6;
39
40pub const MIN_YAW_SPAN_DEG: f32 = 25.0;
42
43pub const MIN_PAR_SAMPLES: usize = 4;
45
46const MIN_HORIZ_PX: f32 = 1e-3;
48
49#[derive(Debug, Clone, Copy, PartialEq)]
50pub enum ParVerdict {
51 Live3d {
53 delta_par: f32,
54 par_t0: f32,
55 par_t1: f32,
56 yaw_span_deg: f32,
57 },
58 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#[derive(Debug, Clone, Copy, PartialEq)]
74pub struct ParSample {
75 pub d_l: f32,
76 pub d_r: f32,
77 pub par: f32,
78}
79
80pub 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 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#[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
109pub 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 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 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#[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 let eye_l = 160.0f32;
204 let eye_r = 240.0f32;
205 let eye_c = 0.5 * (eye_l + eye_r);
206 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 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#[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 let nose_x = eye_c + yaw_deg * 0.9;
246 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 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; 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; 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; 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}