Skip to main content

qualia_vision/biosense/face_mesh/
pack_landmark_frame.rs

1//! Pack a flat MediaPipe Face Mesh buffer into a PAD [`LandmarkFrame`].
2//!
3//! Accepts **xy** (`468 × 2`) or **xyz** (`468 × 3`) interleaved `f32` layouts.
4//! **Model Z is always ignored** — only \(x, y\) enter [`Landmark2`].
5
6use super::mediapipe_index::{
7    mediapipe_index_for_pad, MEDIAPIPE_FACE_MESH_COUNT, PAD_LANDMARK_IDS,
8};
9use crate::biosense::liveness::landmark_types::{Landmark2, LandmarkFrame};
10use crate::cv::error::CvError;
11
12/// Flat buffer layout from a MediaPipe-compatible landmarker.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum LandmarkBufferLayout {
15    /// Interleaved `[x0, y0, x1, y1, …]` — length `468 * 2`.
16    XyInterleaved,
17    /// Interleaved `[x0, y0, z0, x1, y1, z1, …]` — length `468 * 3`.
18    /// The \(z\) components are **discarded** (never used for PAD).
19    XyzInterleaved,
20}
21
22impl LandmarkBufferLayout {
23    #[inline]
24    /// Components per landmark.
25    pub const fn components_per_landmark(self) -> usize {
26        match self {
27            Self::XyInterleaved => 2,
28            Self::XyzInterleaved => 3,
29        }
30    }
31
32    #[inline]
33    /// `expected` length.
34    pub const fn expected_len(self) -> usize {
35        MEDIAPIPE_FACE_MESH_COUNT * self.components_per_landmark()
36    }
37}
38
39/// Pack one MediaPipe mesh frame into the eight-slot PAD landmark frame.
40///
41/// * `t_ms` — challenge-relative timestamp.
42/// * `buf` — flat landmark buffer (xy or xyz).
43/// * `layout` — stride / component count.
44///
45/// Only the eight PAD indices are read. Finite \(x,y\) are marked valid;
46/// non-finite or missing slots stay unset. Z is never read into geometry.
47pub fn pack_landmark_frame(
48    t_ms: u32,
49    buf: &[f32],
50    layout: LandmarkBufferLayout,
51) -> Result<LandmarkFrame, CvError> {
52    if buf.len() < layout.expected_len() {
53        return Err(CvError::BufferTooSmall);
54    }
55
56    let stride = layout.components_per_landmark();
57    let mut frame = LandmarkFrame::empty(t_ms);
58
59    for id in PAD_LANDMARK_IDS {
60        let mp = mediapipe_index_for_pad(id) as usize;
61        if mp >= MEDIAPIPE_FACE_MESH_COUNT {
62            continue;
63        }
64        let base = mp * stride;
65        // xy always at base+0 / base+1; if xyz, base+2 is Z — intentionally unread.
66        let x = buf[base];
67        let y = buf[base + 1];
68        if x.is_finite() && y.is_finite() {
69            frame.set(id, Landmark2::new(x, y));
70        }
71    }
72
73    Ok(frame)
74}
75
76#[cfg(test)]
77mod tests {
78    use super::*;
79    use crate::biosense::face_mesh::mediapipe_index::PAD_MEDIAPIPE_INDICES;
80    use crate::biosense::liveness::landmark_types::PadLandmarkId;
81
82    fn fill_xy() -> [f32; MEDIAPIPE_FACE_MESH_COUNT * 2] {
83        let mut buf = [0.0f32; MEDIAPIPE_FACE_MESH_COUNT * 2];
84        for (slot, &mp) in PAD_MEDIAPIPE_INDICES.iter().enumerate() {
85            let i = mp as usize;
86            buf[i * 2] = 10.0 + slot as f32;
87            buf[i * 2 + 1] = 100.0 + slot as f32;
88        }
89        buf
90    }
91
92    #[test]
93    fn packs_xy_slots() {
94        let buf = fill_xy();
95        let f = pack_landmark_frame(42, &buf, LandmarkBufferLayout::XyInterleaved).unwrap();
96        assert_eq!(f.t_ms, 42);
97        for id in PAD_LANDMARK_IDS {
98            let p = f.get(id).unwrap();
99            let slot = id as usize;
100            assert!((p.x - (10.0 + slot as f32)).abs() < 1e-5);
101            assert!((p.y - (100.0 + slot as f32)).abs() < 1e-5);
102        }
103    }
104
105    #[test]
106    fn xyz_ignores_z() {
107        let mut buf = [0.0f32; MEDIAPIPE_FACE_MESH_COUNT * 3];
108        let mp = PadLandmarkId::NoseTip.mediapipe_index() as usize;
109        buf[mp * 3] = 1.5;
110        buf[mp * 3 + 1] = 2.5;
111        buf[mp * 3 + 2] = 999.0; // must not appear in Landmark2
112        let f = pack_landmark_frame(0, &buf, LandmarkBufferLayout::XyzInterleaved).unwrap();
113        let n = f.get(PadLandmarkId::NoseTip).unwrap();
114        assert!((n.x - 1.5).abs() < 1e-6);
115        assert!((n.y - 2.5).abs() < 1e-6);
116        // Landmark2 has no z field — packing path never stored 999.
117    }
118
119    #[test]
120    fn short_buffer_errors() {
121        let tiny = [0.0f32; 10];
122        assert!(matches!(
123            pack_landmark_frame(0, &tiny, LandmarkBufferLayout::XyInterleaved),
124            Err(CvError::BufferTooSmall)
125        ));
126    }
127}