Skip to main content

qualia_vision/biosense/biometrics/
sface_embed_from_tensor.rs

1//! SFace embedding from a caller-supplied float tensor (runtime-agnostic).
2//!
3//! Weight: OpenCV Zoo SFace **Apache-2.0** (PermissiveReady). Embedding is for
4//! sanctuary template vault — never packed into NQuin payloads.
5
6use crate::cv::error::CvError;
7
8/// SFace typically emits 128-d float features.
9pub const SFACE_EMBED_DIM: usize = 128;
10
11/// Copy and L2-normalize embedding into `out` (must be ≥ SFACE_EMBED_DIM).
12pub fn sface_embed_from_tensor(raw: &[f32], out: &mut [f32]) -> Result<usize, CvError> {
13    if raw.len() < SFACE_EMBED_DIM {
14        return Err(CvError::BufferTooSmall);
15    }
16    if out.len() < SFACE_EMBED_DIM {
17        return Err(CvError::BufferTooSmall);
18    }
19    let mut norm = 0.0f32;
20    for i in 0..SFACE_EMBED_DIM {
21        let v = raw[i];
22        out[i] = v;
23        norm += v * v;
24    }
25    let n = norm.sqrt();
26    if n > 1e-8 {
27        for i in 0..SFACE_EMBED_DIM {
28            out[i] /= n;
29        }
30    }
31    Ok(SFACE_EMBED_DIM)
32}
33
34/// Cosine similarity for two L2-normalized embeddings.
35pub fn sface_cosine(a: &[f32], b: &[f32]) -> Result<f32, CvError> {
36    if a.len() < SFACE_EMBED_DIM || b.len() < SFACE_EMBED_DIM {
37        return Err(CvError::BufferTooSmall);
38    }
39    let mut dot = 0.0f32;
40    for i in 0..SFACE_EMBED_DIM {
41        dot += a[i] * b[i];
42    }
43    Ok(dot.clamp(-1.0, 1.0))
44}
45
46#[cfg(test)]
47mod tests {
48    use super::*;
49
50    #[test]
51    fn normalize_unit() {
52        let mut raw = [0.0f32; SFACE_EMBED_DIM];
53        raw[0] = 3.0;
54        raw[1] = 4.0;
55        let mut out = [0.0f32; SFACE_EMBED_DIM];
56        sface_embed_from_tensor(&raw, &mut out).unwrap();
57        let n: f32 = out.iter().map(|v| v * v).sum::<f32>().sqrt();
58        assert!((n - 1.0).abs() < 1e-5);
59    }
60
61    #[test]
62    fn identical_cosine_one() {
63        let raw = [0.1f32; SFACE_EMBED_DIM];
64        let mut a = [0.0f32; SFACE_EMBED_DIM];
65        let mut b = [0.0f32; SFACE_EMBED_DIM];
66        sface_embed_from_tensor(&raw, &mut a).unwrap();
67        sface_embed_from_tensor(&raw, &mut b).unwrap();
68        let c = sface_cosine(&a, &b).unwrap();
69        assert!((c - 1.0).abs() < 1e-5);
70    }
71}