qualia_vision/biosense/liveness/
landmark_jitter.rs1use super::landmark_types::{LandmarkFrame, PadLandmarkId};
8
9pub const DEFAULT_JITTER_WINDOW_MS: u32 = 1000;
11pub const MIN_JITTER_SAMPLES: usize = 8;
13pub const DEFAULT_MIN_JITTER: f32 = 0.00035;
15pub const DEFAULT_MAX_JITTER: f32 = 0.08;
17
18#[derive(Debug, Clone, Copy, PartialEq)]
19pub enum JitterVerdict {
20 Natural { rms: f32 },
21 TooStatic { rms: f32 },
22 TooSmoothOrGlitchy { rms: f32 },
23 InsufficientSamples,
24}
25
26#[derive(Debug, Clone, Copy)]
27pub struct JitterThresholds {
28 pub window_ms: u32,
29 pub min_rms: f32,
30 pub max_rms: f32,
31}
32
33impl Default for JitterThresholds {
34 fn default() -> Self {
35 Self {
36 window_ms: DEFAULT_JITTER_WINDOW_MS,
37 min_rms: DEFAULT_MIN_JITTER,
38 max_rms: DEFAULT_MAX_JITTER,
39 }
40 }
41}
42
43fn residual_rms_1d(t: &[f32], v: &[f32], n: usize) -> f32 {
45 if n < 3 {
46 return 0.0;
47 }
48 let (mean_t, mean_v) = {
49 let mut st = 0.0f32;
50 let mut sv = 0.0f32;
51 for i in 0..n {
52 st += t[i];
53 sv += v[i];
54 }
55 (st / n as f32, sv / n as f32)
56 };
57 let mut num = 0.0f32;
58 let mut den = 0.0f32;
59 for i in 0..n {
60 let dt = t[i] - mean_t;
61 num += dt * (v[i] - mean_v);
62 den += dt * dt;
63 }
64 let beta = if den > 1e-12 { num / den } else { 0.0 };
65 let alpha = mean_v - beta * mean_t;
66 let mut acc = 0.0f32;
67 for i in 0..n {
68 let e = v[i] - (alpha + beta * t[i]);
69 acc += e * e;
70 }
71 (acc / n as f32).sqrt()
72}
73
74fn point_series(
75 frames: &[LandmarkFrame],
76 id: PadLandmarkId,
77 t0: u32,
78 window_ms: u32,
79 t_out: &mut [f32; 64],
80 x_out: &mut [f32; 64],
81 y_out: &mut [f32; 64],
82) -> usize {
83 let mut n = 0usize;
84 for f in frames {
85 if f.t_ms < t0.saturating_sub(window_ms) {
86 continue;
87 }
88 if f.t_ms > t0 {
89 continue;
90 }
91 let Some(p) = f.get(id) else {
92 continue;
93 };
94 if n >= 64 {
95 break;
96 }
97 t_out[n] = f.t_ms as f32;
98 x_out[n] = p.x;
99 y_out[n] = p.y;
100 n += 1;
101 }
102 n
103}
104
105pub fn evaluate_landmark_jitter(frames: &[LandmarkFrame], thr: &JitterThresholds) -> JitterVerdict {
107 if frames.len() < MIN_JITTER_SAMPLES {
108 return JitterVerdict::InsufficientSamples;
109 }
110 let t_end = frames.last().map(|f| f.t_ms).unwrap_or(0);
111 let mut t_buf = [0.0f32; 64];
112 let mut x_buf = [0.0f32; 64];
113 let mut y_buf = [0.0f32; 64];
114
115 let ids = [
116 PadLandmarkId::NoseTip,
117 PadLandmarkId::LeftEyeOuter,
118 PadLandmarkId::RightEyeOuter,
119 ];
120 let mut rms_acc = 0.0f32;
121 let mut parts = 0u32;
122 let mut iod_ref = 0.0f32;
123
124 for id in ids {
125 let n = point_series(
126 frames,
127 id,
128 t_end,
129 thr.window_ms,
130 &mut t_buf,
131 &mut x_buf,
132 &mut y_buf,
133 );
134 if n < MIN_JITTER_SAMPLES {
135 continue;
136 }
137 let mut iod_sum = 0.0f32;
139 let mut iod_n = 0u32;
140 for f in frames {
141 if f.t_ms + thr.window_ms < t_end {
142 continue;
143 }
144 if let Some(iod) = f.interocular() {
145 iod_sum += iod;
146 iod_n += 1;
147 }
148 }
149 let iod = if iod_n > 0 {
150 iod_sum / iod_n as f32
151 } else {
152 1.0
153 };
154 iod_ref = iod;
155 let rx = residual_rms_1d(&t_buf, &x_buf, n) / iod;
156 let ry = residual_rms_1d(&t_buf, &y_buf, n) / iod;
157 rms_acc += (rx * rx + ry * ry).sqrt();
158 parts += 1;
159 }
160
161 if parts == 0 || iod_ref <= 0.0 {
162 return JitterVerdict::InsufficientSamples;
163 }
164 let rms = rms_acc / parts as f32;
165
166 if rms < thr.min_rms {
167 JitterVerdict::TooStatic { rms }
168 } else if rms > thr.max_rms {
169 JitterVerdict::TooSmoothOrGlitchy { rms }
170 } else {
171 JitterVerdict::Natural { rms }
172 }
173}
174
175pub fn mean_landmark_motion(a: &LandmarkFrame, b: &LandmarkFrame) -> f32 {
177 let mut acc = 0.0f32;
178 let mut n = 0u32;
179 for i in 0..PadLandmarkId::COUNT {
180 let mask = 1u8 << i;
181 if (a.valid_mask & mask) == 0 || (b.valid_mask & mask) == 0 {
182 continue;
183 }
184 acc += a.points[i].dist(b.points[i]);
185 n += 1;
186 }
187 if n == 0 {
188 0.0
189 } else {
190 acc / n as f32
191 }
192}
193
194#[cfg(test)]
195mod tests {
196 use super::*;
197 use crate::biosense::liveness::landmark_types::{Landmark2, LandmarkFrame, PadLandmarkId};
198
199 fn series(noise: f32) -> [LandmarkFrame; 16] {
200 let mut out = [LandmarkFrame::empty(0); 16];
201 for i in 0..16 {
202 let mut f = LandmarkFrame::empty((i as u32) * 60);
203 let n = (i as f32) * 0.02 + noise * ((i as f32 * 1.7).sin());
204 f.set(
205 PadLandmarkId::NoseTip,
206 Landmark2::new(140.0 + n, 150.0 + n * 0.5),
207 );
208 f.set(
209 PadLandmarkId::LeftEyeOuter,
210 Landmark2::new(100.0 + n * 0.3, 120.0),
211 );
212 f.set(
213 PadLandmarkId::RightEyeOuter,
214 Landmark2::new(180.0 + n * 0.3, 120.0),
215 );
216 out[i] = f;
217 }
218 out
219 }
220
221 #[test]
222 fn static_series_fails() {
223 let frames = series(0.0);
224 let v = evaluate_landmark_jitter(&frames, &JitterThresholds::default());
226 match v {
227 JitterVerdict::TooStatic { .. } => {}
228 JitterVerdict::Natural { rms } => assert!(rms < 0.01, "rms={}", rms),
229 other => panic!("unexpected {:?}", other),
230 }
231 }
232
233 #[test]
234 fn noisy_series_natural_or_elevated() {
235 let frames = series(0.8);
236 let thr = JitterThresholds {
237 min_rms: 0.0001,
238 max_rms: 1.0,
239 ..Default::default()
240 };
241 let v = evaluate_landmark_jitter(&frames, &thr);
242 assert!(
243 matches!(
244 v,
245 JitterVerdict::Natural { .. } | JitterVerdict::TooSmoothOrGlitchy { .. }
246 ),
247 "got {:?}",
248 v
249 );
250 }
251}