apple_vision/animals/
mod.rs

1//! Animal recognition (`VNRecognizeAnimalsRequest`).
2//!
3//! Currently the SDK supports `"Dog"` and `"Cat"` identifiers.
4
5use core::ffi::c_char;
6use core::ptr;
7use std::ffi::CString;
8use std::path::Path;
9
10use crate::error::{from_swift, VisionError};
11use crate::ffi;
12use crate::recognize_text::BoundingBox;
13use crate::sdk;
14
15/// Public alias for `VNAnimalIdentifier`.
16pub type AnimalIdentifier = sdk::AnimalIdentifier;
17
18/// One detected animal.
19#[derive(Debug, Clone, PartialEq)]
20pub struct RecognizedAnimal {
21    /// Apple's identifier string — e.g. `"Dog"`, `"Cat"`.
22    pub identifier: String,
23    pub confidence: f32,
24    pub bounding_box: BoundingBox,
25}
26
27impl RecognizedAnimal {
28    #[must_use]
29    pub fn identifier_kind(&self) -> Option<AnimalIdentifier> {
30        AnimalIdentifier::from_str(&self.identifier)
31    }
32}
33
34/// Recognise animals in the image at `path`.
35///
36/// # Errors
37///
38/// Returns [`VisionError::ImageLoadFailed`] / [`VisionError::RequestFailed`].
39pub fn recognize_animals_in_path(
40    path: impl AsRef<Path>,
41) -> Result<Vec<RecognizedAnimal>, VisionError> {
42    let path_str = path
43        .as_ref()
44        .to_str()
45        .ok_or_else(|| VisionError::InvalidArgument("non-UTF-8 path".into()))?;
46    let path_c = CString::new(path_str)
47        .map_err(|e| VisionError::InvalidArgument(format!("path NUL byte: {e}")))?;
48
49    let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
50    let mut out_count: usize = 0;
51    let mut err_msg: *mut c_char = ptr::null_mut();
52    // SAFETY: all pointer arguments are valid stack locations or null-initialised out-params; strings are valid C strings for the duration of the call.
53    let status = unsafe {
54        ffi::vn_recognize_animals_in_path(
55            path_c.as_ptr(),
56            &mut out_array,
57            &mut out_count,
58            &mut err_msg,
59        )
60    };
61    if status != ffi::status::OK {
62        // SAFETY: the error pointer is either null or a bridge-allocated C string; `from_swift` frees it.
63        return Err(unsafe { from_swift(status, err_msg) });
64    }
65    if out_array.is_null() || out_count == 0 {
66        return Ok(Vec::new());
67    }
68    let typed = out_array.cast::<ffi::RecognizedAnimalRaw>();
69    let mut v = Vec::with_capacity(out_count);
70    for i in 0..out_count {
71        // SAFETY: the pointer is valid for the reported element count; the index is in bounds.
72        let raw = unsafe { &*typed.add(i) };
73        let identifier = if raw.identifier.is_null() {
74            String::new()
75        } else {
76            // SAFETY: the C string pointer is non-null (checked above) and valid for the duration of this borrow.
77            unsafe { core::ffi::CStr::from_ptr(raw.identifier) }
78                .to_string_lossy()
79                .into_owned()
80        };
81        v.push(RecognizedAnimal {
82            identifier,
83            confidence: raw.confidence,
84            bounding_box: BoundingBox {
85                x: raw.bbox_x,
86                y: raw.bbox_y,
87                width: raw.bbox_w,
88                height: raw.bbox_h,
89            },
90        });
91    }
92    // SAFETY: the pointer/count pair was allocated by the bridge and is freed exactly once here.
93    unsafe { ffi::vn_recognized_animals_free(out_array, out_count) };
94    Ok(v)
95}
apple_vision/animals/mod.rs

apple_vision/animals/
mod.rs
