apple_vision/detect_faces/
mod.rs

1//! [`FaceDetector`] — wraps `VNDetectFaceRectanglesRequest`.
2
3use core::ffi::c_char;
4use core::ptr;
5use std::ffi::CString;
6use std::path::Path;
7
8use crate::error::{from_swift, VisionError};
9use crate::ffi;
10use crate::recognize_text::BoundingBox;
11
12/// One detected face.
13#[derive(Debug, Clone, PartialEq)]
14pub struct DetectedFace {
15    /// Bounding box in normalised image coordinates (origin bottom-left).
16    pub bounding_box: BoundingBox,
17    /// Detection confidence in `0.0..=1.0`.
18    pub confidence: f32,
19    /// Face roll in radians; `None` if not reported by the request revision.
20    pub roll: Option<f32>,
21    pub yaw: Option<f32>,
22    pub pitch: Option<f32>,
23}
24
25/// Face detector wrapper around `VNDetectFaceRectanglesRequest`.
26#[derive(Debug, Clone, Copy, Default)]
27pub struct FaceDetector;
28
29impl FaceDetector {
30    #[must_use]
31    pub const fn new() -> Self {
32        Self
33    }
34
35    /// Detect faces in the image at `path`.
36    ///
37    /// # Errors
38    ///
39    /// Returns [`VisionError::ImageLoadFailed`] / [`VisionError::RequestFailed`].
40    pub fn detect_in_path(&self, path: impl AsRef<Path>) -> Result<Vec<DetectedFace>, VisionError> {
41        let path_str = path
42            .as_ref()
43            .to_str()
44            .ok_or_else(|| VisionError::InvalidArgument("non-UTF-8 path".into()))?;
45        let path_c = CString::new(path_str)
46            .map_err(|e| VisionError::InvalidArgument(format!("path NUL byte: {e}")))?;
47
48        let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
49        let mut out_count: usize = 0;
50        let mut err_msg: *mut c_char = ptr::null_mut();
51        let status = unsafe {
52            ffi::vn_detect_faces_in_path(
53                path_c.as_ptr(),
54                &mut out_array,
55                &mut out_count,
56                &mut err_msg,
57            )
58        };
59        if status != ffi::status::OK {
60            return Err(unsafe { from_swift(status, err_msg) });
61        }
62        Self::collect(out_array, out_count)
63    }
64
65    /// Detect faces in a [`CVPixelBuffer`](apple_cf::cv::CVPixelBuffer).
66    ///
67    /// # Errors
68    ///
69    /// See [`detect_in_path`](Self::detect_in_path).
70    pub fn detect_in_pixel_buffer(
71        &self,
72        pixel_buffer: &apple_cf::cv::CVPixelBuffer,
73    ) -> Result<Vec<DetectedFace>, VisionError> {
74        let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
75        let mut out_count: usize = 0;
76        let mut err_msg: *mut c_char = ptr::null_mut();
77        let status = unsafe {
78            ffi::vn_detect_faces_in_pixel_buffer(
79                pixel_buffer.as_ptr(),
80                &mut out_array,
81                &mut out_count,
82                &mut err_msg,
83            )
84        };
85        if status != ffi::status::OK {
86            return Err(unsafe { from_swift(status, err_msg) });
87        }
88        Self::collect(out_array, out_count)
89    }
90
91    #[allow(clippy::unnecessary_wraps)]
92    fn collect(
93        out_array: *mut core::ffi::c_void,
94        out_count: usize,
95    ) -> Result<Vec<DetectedFace>, VisionError> {
96        if out_array.is_null() || out_count == 0 {
97            return Ok(Vec::new());
98        }
99        let typed_array = out_array.cast::<ffi::DetectedFaceRaw>();
100        let mut results = Vec::with_capacity(out_count);
101        for i in 0..out_count {
102            let raw = unsafe { &*typed_array.add(i) };
103            let nan_to_none = |v: f32| if v.is_nan() { None } else { Some(v) };
104            results.push(DetectedFace {
105                bounding_box: BoundingBox {
106                    x: raw.bbox_x,
107                    y: raw.bbox_y,
108                    width: raw.bbox_w,
109                    height: raw.bbox_h,
110                },
111                confidence: raw.confidence,
112                roll: nan_to_none(raw.roll),
113                yaw: nan_to_none(raw.yaw),
114                pitch: nan_to_none(raw.pitch),
115            });
116        }
117        unsafe { ffi::vn_detected_faces_free(out_array, out_count) };
118        Ok(results)
119    }
120}
apple_vision/detect_faces/mod.rs

apple_vision/detect_faces/
mod.rs
