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        // SAFETY: all pointer arguments are valid stack locations or null-initialised out-params; strings are valid C strings for the duration of the call.
52        let status = unsafe {
53            ffi::vn_detect_faces_in_path(
54                path_c.as_ptr(),
55                &mut out_array,
56                &mut out_count,
57                &mut err_msg,
58            )
59        };
60        if status != ffi::status::OK {
61            // SAFETY: the error pointer is either null or a bridge-allocated C string; `from_swift` frees it.
62            return Err(unsafe { from_swift(status, err_msg) });
63        }
64        Self::collect(out_array, out_count)
65    }
66
67    /// Detect faces in a [`CVPixelBuffer`](apple_cf::cv::CVPixelBuffer).
68    ///
69    /// # Errors
70    ///
71    /// See [`detect_in_path`](Self::detect_in_path).
72    pub fn detect_in_pixel_buffer(
73        &self,
74        pixel_buffer: &apple_cf::cv::CVPixelBuffer,
75    ) -> Result<Vec<DetectedFace>, VisionError> {
76        let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
77        let mut out_count: usize = 0;
78        let mut err_msg: *mut c_char = ptr::null_mut();
79        // SAFETY: all pointer arguments are valid stack locations or bridge-owned handles; strings are valid C strings for the duration of the call.
80        let status = unsafe {
81            ffi::vn_detect_faces_in_pixel_buffer(
82                pixel_buffer.as_ptr(),
83                &mut out_array,
84                &mut out_count,
85                &mut err_msg,
86            )
87        };
88        if status != ffi::status::OK {
89            // SAFETY: the error pointer is either null or a bridge-allocated C string; `from_swift` frees it.
90            return Err(unsafe { from_swift(status, err_msg) });
91        }
92        Self::collect(out_array, out_count)
93    }
94
95    #[allow(clippy::unnecessary_wraps)]
96    fn collect(
97        out_array: *mut core::ffi::c_void,
98        out_count: usize,
99    ) -> Result<Vec<DetectedFace>, VisionError> {
100        if out_array.is_null() || out_count == 0 {
101            return Ok(Vec::new());
102        }
103        let typed_array = out_array.cast::<ffi::DetectedFaceRaw>();
104        let mut results = Vec::with_capacity(out_count);
105        for i in 0..out_count {
106            // SAFETY: the pointer is valid for the reported element count; the index is in bounds.
107            let raw = unsafe { &*typed_array.add(i) };
108            let nan_to_none = |v: f32| if v.is_nan() { None } else { Some(v) };
109            results.push(DetectedFace {
110                bounding_box: BoundingBox {
111                    x: raw.bbox_x,
112                    y: raw.bbox_y,
113                    width: raw.bbox_w,
114                    height: raw.bbox_h,
115                },
116                confidence: raw.confidence,
117                roll: nan_to_none(raw.roll),
118                yaw: nan_to_none(raw.yaw),
119                pitch: nan_to_none(raw.pitch),
120            });
121        }
122        // SAFETY: the pointer/count pair was allocated by the bridge and is freed exactly once here.
123        unsafe { ffi::vn_detected_faces_free(out_array, out_count) };
124        Ok(results)
125    }
126}
apple_vision/detect_faces/mod.rs

apple_vision/detect_faces/
mod.rs
