Skip to main content

qualia_vision/biosense/liveness/
landmark_jitter.rs

1//! Landmark noise-floor / micromotion analysis (passive liveness signal).
2//!
3//! Human pulse and micro-tremors create natural jitter. A statically held 3D
4//! mask has near-zero structural jitter; video replays often show overly smooth
5//! interpolated trajectories. Track high-frequency residual over ~1 s.
6
7use super::landmark_types::{LandmarkFrame, PadLandmarkId};
8
9/// Default analysis window (ms).
10pub const DEFAULT_JITTER_WINDOW_MS: u32 = 1000;
11/// Minimum samples inside the window.
12pub const MIN_JITTER_SAMPLES: usize = 8;
13/// Human-typical floor (normalized by interocular, per-frame residual RMS).
14pub const DEFAULT_MIN_JITTER: f32 = 0.00035;
15/// Upper bound — too high may indicate tracking noise / injection glitch.
16pub 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
43/// High-frequency residual of a landmark track after removing a linear trend.
44fn 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
105/// Evaluate jitter on nose + eye corners over the last `window_ms` ending at last frame.
106pub 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        // Normalize by mean interocular in window when available.
138        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
175/// Convenience: mean motion of packed points between two frames (legacy mesh_motion).
176pub 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        // Pure linear trend only → residual near 0.
225        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}