1use super::action_threshold::{action_met_at_frame, action_onset_at_frame, ActionThresholds};
15use super::camera_stream_integrity::{
16 check_camera_stream_integrity, CameraStreamAttestation, StreamIntegrityVerdict,
17};
18use super::challenge_kind::ChallengeKind;
19use super::landmark_jitter::{evaluate_landmark_jitter, JitterThresholds, JitterVerdict};
20use super::landmark_types::{LandmarkFrame, MeshBlendProxies};
21use super::non_rigid_z::{evaluate_non_rigid_z, NonRigidVerdict, DEFAULT_MIN_NONRIGID_SCORE};
22use super::rigid_head_pose::{estimate_head_pose, HeadPose};
23use super::temporal_window::{
24 check_temporal_window, temporal_is_terminal_fail, TemporalGate, TemporalWindow,
25};
26use crate::biosense::consent::BiosenseConsent;
27use crate::cv::error::CvError;
28
29#[derive(Debug, Clone, Copy)]
31pub struct MeshFrameSignals {
32 pub yaw: f32,
33 pub pitch: f32,
34 pub smile: f32,
35 pub blink: f32,
36 pub mesh_motion: f32,
37}
38
39#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub enum PadReason {
41 Pass,
42 NoConsent,
43 Timeout,
44 TimeToStartExceeded,
45 TimeToCompleteExceeded,
46 WrongAction,
47 StaticMesh,
48 FlatSurface,
49 InsufficientFrames,
50 VirtualCamera,
51 UnattestedStream,
52 JitterAnomaly,
53 PoseUnavailable,
54}
55
56#[derive(Debug, Clone, Copy)]
57pub struct PadResult {
58 pub passed: bool,
59 pub reason: PadReason,
60 pub challenge: ChallengeKind,
61}
62
63pub struct PadThresholds {
65 pub temporal: TemporalWindow,
66 pub action: ActionThresholds,
67 pub jitter: JitterThresholds,
68 pub min_nonrigid_score: f32,
70 pub min_frames: usize,
71 pub require_nonrigid_z: bool,
73 pub require_jitter: bool,
75}
76
77impl Default for PadThresholds {
78 fn default() -> Self {
79 Self {
80 temporal: TemporalWindow::default(),
81 action: ActionThresholds::default(),
82 jitter: JitterThresholds::default(),
83 min_nonrigid_score: DEFAULT_MIN_NONRIGID_SCORE,
84 min_frames: 8,
85 require_nonrigid_z: true,
86 require_jitter: true,
87 }
88 }
89}
90
91pub type BlendRow = Option<MeshBlendProxies>;
93
94pub fn evaluate_landmark_pad(
96 consent: BiosenseConsent,
97 challenge: ChallengeKind,
98 frames: &[LandmarkFrame],
99 blends: &[BlendRow],
100 stream: CameraStreamAttestation,
101 thr: &PadThresholds,
102) -> Result<PadResult, CvError> {
103 if !consent.may_process() {
104 return Ok(fail(challenge, PadReason::NoConsent));
105 }
106
107 match check_camera_stream_integrity(stream) {
108 StreamIntegrityVerdict::Ok => {}
109 StreamIntegrityVerdict::VirtualCamera => {
110 return Ok(fail(challenge, PadReason::VirtualCamera));
111 }
112 StreamIntegrityVerdict::UnattestedPhysicalRequired => {
113 return Ok(fail(challenge, PadReason::UnattestedStream));
114 }
115 }
116
117 if frames.len() < thr.min_frames {
118 return Ok(fail(challenge, PadReason::InsufficientFrames));
119 }
120
121 let mut pose0: Option<HeadPose> = None;
123 let mut poses_ok = 0usize;
124 let mut onset_ms: Option<u32> = None;
125 let mut complete_ms: Option<u32> = None;
126 let mut any_action = false;
127 let mut blink_events = 0u32;
128 let mut prev_blink = 0.0f32;
129 let mut last_t = 0u32;
130
131 let mut z_frames: [LandmarkFrame; 64] = [LandmarkFrame::empty(0); 64];
133 let mut z_poses: [HeadPose; 64] = [HeadPose::default(); 64];
134 let mut z_n = 0usize;
135
136 for (i, frame) in frames.iter().enumerate() {
137 last_t = frame.t_ms;
138 let Some(pose) = estimate_head_pose(frame) else {
139 continue;
140 };
141 poses_ok += 1;
142 let p0 = match pose0 {
143 Some(p) => p,
144 None => {
145 pose0 = Some(pose);
146 pose
147 }
148 };
149
150 if z_n < 64 {
151 z_frames[z_n] = *frame;
152 z_poses[z_n] = pose;
153 z_n += 1;
154 }
155
156 let blend = blends.get(i).copied().flatten();
157 if challenge == ChallengeKind::BlinkTwice {
158 if let Some(b) = blend {
159 if prev_blink < thr.action.blink_peak * 0.5 && b.blink >= thr.action.blink_peak {
160 blink_events += 1;
161 }
162 prev_blink = b.blink;
163 }
164 }
165
166 if onset_ms.is_none() {
167 let onset = if challenge == ChallengeKind::BlinkTwice {
168 blink_events >= 1
169 } else if matches!(challenge, ChallengeKind::Smile | ChallengeKind::OpenMouth) {
170 action_met_at_frame(challenge, pose, p0, frame, blend, &thr.action)
171 || action_onset_at_frame(challenge, pose, p0, &thr.action)
172 } else {
173 action_onset_at_frame(challenge, pose, p0, &thr.action)
174 };
175 if onset {
176 onset_ms = Some(frame.t_ms);
177 }
178 }
179
180 let met = if challenge == ChallengeKind::BlinkTwice {
181 blink_events >= 2
182 } else {
183 action_met_at_frame(challenge, pose, p0, frame, blend, &thr.action)
184 };
185 if met {
186 any_action = true;
187 if complete_ms.is_none() {
188 complete_ms = Some(frame.t_ms);
189 }
190 }
191 }
192
193 if poses_ok < thr.min_frames.saturating_sub(2).max(4) {
194 return Ok(fail(challenge, PadReason::PoseUnavailable));
195 }
196
197 let gate = check_temporal_window(thr.temporal, onset_ms, complete_ms, last_t);
198 if temporal_is_terminal_fail(gate) {
199 let reason = match gate {
200 TemporalGate::TimeToStartExceeded => PadReason::TimeToStartExceeded,
201 TemporalGate::TimeToCompleteExceeded => PadReason::TimeToCompleteExceeded,
202 TemporalGate::InvalidTimeline => PadReason::Timeout,
203 TemporalGate::Ok => PadReason::Timeout,
204 };
205 return Ok(fail(challenge, reason));
206 }
207
208 if !any_action {
209 if last_t >= thr.temporal.ttc_ms {
211 return Ok(fail(challenge, PadReason::WrongAction));
212 }
213 return Ok(fail(challenge, PadReason::WrongAction));
214 }
215
216 if thr.require_nonrigid_z && challenge.is_rotation() {
218 let v = evaluate_non_rigid_z(&z_frames[..z_n], &z_poses[..z_n], thr.min_nonrigid_score);
219 match v {
220 NonRigidVerdict::Live3d { .. } => {}
221 NonRigidVerdict::FlatSurface { .. } => {
222 return Ok(fail(challenge, PadReason::FlatSurface));
223 }
224 NonRigidVerdict::InsufficientMotion | NonRigidVerdict::MissingLandmarks => {
225 return Ok(fail(challenge, PadReason::FlatSurface));
227 }
228 }
229 }
230
231 if thr.require_jitter {
232 match evaluate_landmark_jitter(frames, &thr.jitter) {
233 JitterVerdict::Natural { .. } => {}
234 JitterVerdict::TooStatic { .. } => {
235 return Ok(fail(challenge, PadReason::StaticMesh));
236 }
237 JitterVerdict::TooSmoothOrGlitchy { .. } => {
238 return Ok(fail(challenge, PadReason::JitterAnomaly));
239 }
240 JitterVerdict::InsufficientSamples => {
241 return Ok(fail(challenge, PadReason::InsufficientFrames));
242 }
243 }
244 }
245
246 Ok(PadResult {
247 passed: true,
248 reason: PadReason::Pass,
249 challenge,
250 })
251}
252
253pub fn evaluate_challenge_pad(
257 consent: BiosenseConsent,
258 challenge: ChallengeKind,
259 frames: &[MeshFrameSignals],
260 thr: &PadThresholds,
261) -> Result<PadResult, CvError> {
262 if !consent.may_process() {
263 return Ok(fail(challenge, PadReason::NoConsent));
264 }
265 if frames.len() < thr.min_frames {
266 return Ok(fail(challenge, PadReason::InsufficientFrames));
267 }
268
269 let yaw0 = frames[0].yaw;
270 let pitch0 = frames[0].pitch;
271 let mut max_smile = 0.0f32;
272 let mut blink_events = 0u32;
273 let mut prev_blink = frames[0].blink;
274 let mut motion_sum = 0.0f32;
275 let mut yaw_max = yaw0;
276 let mut yaw_min = yaw0;
277 let mut pitch_max = pitch0;
278 let mut pitch_min = pitch0;
279
280 for f in frames {
281 max_smile = max_smile.max(f.smile);
282 yaw_max = yaw_max.max(f.yaw);
283 yaw_min = yaw_min.min(f.yaw);
284 pitch_max = pitch_max.max(f.pitch);
285 pitch_min = pitch_min.min(f.pitch);
286 motion_sum += f.mesh_motion;
287 if prev_blink < thr.action.blink_peak * 0.5 && f.blink >= thr.action.blink_peak {
288 blink_events += 1;
289 }
290 prev_blink = f.blink;
291 }
292 let mean_motion = motion_sum / frames.len() as f32;
293 if mean_motion < thr.jitter.min_rms.max(0.002) {
294 return Ok(fail(challenge, PadReason::StaticMesh));
295 }
296
297 let yaw_thr = thr.action.yaw_deg.to_radians();
300 let action_ok = match challenge {
301 ChallengeKind::YawLeft => (yaw_max - yaw0) >= yaw_thr,
302 ChallengeKind::YawRight => (yaw0 - yaw_min) >= yaw_thr,
303 ChallengeKind::Smile => max_smile >= thr.action.smile_blend,
304 ChallengeKind::BlinkTwice => blink_events >= 2,
305 ChallengeKind::OpenMouth => max_smile >= thr.action.smile_blend, ChallengeKind::PitchUp => (pitch0 - pitch_min) >= yaw_thr * 0.7,
307 ChallengeKind::PitchDown => (pitch_max - pitch0) >= yaw_thr * 0.7,
308 };
309
310 if action_ok {
311 Ok(PadResult {
312 passed: true,
313 reason: PadReason::Pass,
314 challenge,
315 })
316 } else {
317 Ok(fail(challenge, PadReason::WrongAction))
318 }
319}
320
321pub fn issue_challenge(seed: u64) -> ChallengeKind {
323 ChallengeKind::from_seed(seed)
324}
325
326pub fn issue_rotation_challenge(seed: u64) -> ChallengeKind {
328 ChallengeKind::from_seed_prefer_rotation(seed)
329}
330
331fn fail(challenge: ChallengeKind, reason: PadReason) -> PadResult {
332 PadResult {
333 passed: false,
334 reason,
335 challenge,
336 }
337}
338
339#[cfg(test)]
340mod tests {
341 use super::*;
342 use crate::biosense::consent::{BiosenseConsent, BiosensePurpose};
343 use crate::biosense::liveness::landmark_types::Landmark2;
344 use crate::biosense::liveness::profile_asymmetry_ratio::{
345 synthetic_3d_par_frame, synthetic_flat_par_frame,
346 };
347
348 fn consent() -> BiosenseConsent {
349 BiosenseConsent::grant_security_template(1)
350 }
351
352 fn yaw_trajectory(live3d: bool) -> (Vec<LandmarkFrame>, Vec<BlendRow>) {
354 let mut frames = Vec::new();
355 let blends = vec![None; 12];
356 for i in 0..12 {
357 let t = 40 + i as u32 * 80;
358 let yaw = i as f32 * 4.0; let (mut f, _pose_label) = if live3d {
360 synthetic_3d_par_frame(yaw, t)
361 } else {
362 synthetic_flat_par_frame(yaw, t)
363 };
364 f.t_ms = t;
365 if live3d {
367 let j = ((i as f32) * 2.1).sin() * 0.45;
368 if let Some(n) = f.get(crate::biosense::liveness::PadLandmarkId::NoseTip) {
369 f.set(
370 crate::biosense::liveness::PadLandmarkId::NoseTip,
371 Landmark2::new(n.x + j, n.y + j * 0.3),
372 );
373 }
374 }
375 frames.push(f);
376 }
377 (frames, blends)
378 }
379
380 #[test]
381 fn smile_legacy_pass() {
382 let mut frames = [MeshFrameSignals {
383 yaw: 0.0,
384 pitch: 0.0,
385 smile: 0.0,
386 blink: 0.0,
387 mesh_motion: 0.01,
388 }; 10];
389 frames[5].smile = 0.8;
390 let mut thr = PadThresholds::default();
391 thr.action.yaw_deg = 14.3; let r = evaluate_challenge_pad(consent(), ChallengeKind::Smile, &frames, &thr).unwrap();
393 assert!(r.passed);
394 assert_eq!(r.reason, PadReason::Pass);
395 }
396
397 #[test]
398 fn static_mesh_fails_legacy() {
399 let frames = [MeshFrameSignals {
400 yaw: 0.0,
401 pitch: 0.0,
402 smile: 0.9,
403 blink: 0.0,
404 mesh_motion: 0.0,
405 }; 10];
406 let r = evaluate_challenge_pad(
407 consent(),
408 ChallengeKind::Smile,
409 &frames,
410 &PadThresholds::default(),
411 )
412 .unwrap();
413 assert!(!r.passed);
414 assert_eq!(r.reason, PadReason::StaticMesh);
415 }
416
417 #[test]
418 fn no_consent_fails() {
419 let frames = [MeshFrameSignals {
420 yaw: 0.0,
421 pitch: 0.0,
422 smile: 0.9,
423 blink: 0.0,
424 mesh_motion: 0.01,
425 }; 10];
426 let r = evaluate_challenge_pad(
427 BiosenseConsent::denied(BiosensePurpose::Security),
428 ChallengeKind::Smile,
429 &frames,
430 &PadThresholds::default(),
431 )
432 .unwrap();
433 assert!(!r.passed);
434 assert_eq!(r.reason, PadReason::NoConsent);
435 }
436
437 #[test]
438 fn virtual_camera_fails_closed() {
439 let (frames, blends) = yaw_trajectory(true);
440 let r = evaluate_landmark_pad(
441 consent(),
442 ChallengeKind::YawLeft,
443 &frames,
444 &blends,
445 CameraStreamAttestation::virtual_camera(),
446 &PadThresholds::default(),
447 )
448 .unwrap();
449 assert!(!r.passed);
450 assert_eq!(r.reason, PadReason::VirtualCamera);
451 }
452
453 #[test]
454 fn live_yaw_left_passes_with_par() {
455 let (frames, blends) = yaw_trajectory(true);
456 let mut thr = PadThresholds::default();
457 thr.jitter.min_rms = 0.00005;
458 thr.min_nonrigid_score = DEFAULT_MIN_NONRIGID_SCORE; thr.action.yaw_deg = 18.0;
460 let r = evaluate_landmark_pad(
461 consent(),
462 ChallengeKind::YawLeft,
463 &frames,
464 &blends,
465 CameraStreamAttestation::default(),
466 &thr,
467 )
468 .unwrap();
469 assert!(
470 r.passed
471 || matches!(
472 r.reason,
473 PadReason::WrongAction
474 | PadReason::StaticMesh
475 | PadReason::JitterAnomaly
476 | PadReason::TimeToStartExceeded
477 | PadReason::TimeToCompleteExceeded
478 | PadReason::PoseUnavailable
479 ),
480 "unexpected {:?}",
481 r.reason
482 );
483 assert_ne!(r.reason, PadReason::FlatSurface);
485 }
486
487 #[test]
488 fn flat_mask_fails_par_gate() {
489 let (frames, blends) = yaw_trajectory(false);
490 let mut thr = PadThresholds::default();
491 thr.require_jitter = false;
492 thr.min_nonrigid_score = DEFAULT_MIN_NONRIGID_SCORE; thr.action.yaw_deg = 15.0;
494 let r = evaluate_landmark_pad(
495 consent(),
496 ChallengeKind::YawLeft,
497 &frames,
498 &blends,
499 CameraStreamAttestation::default(),
500 &thr,
501 )
502 .unwrap();
503 assert!(!r.passed);
504 assert!(
505 matches!(
506 r.reason,
507 PadReason::FlatSurface | PadReason::WrongAction | PadReason::StaticMesh
508 ),
509 "got {:?}",
510 r.reason
511 );
512 }
513}