apple-vision 0.12.0

Safe Rust bindings for Apple's Vision framework — OCR, object detection, face landmarks on macOS
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

//! Edge contour detection (`VNDetectContoursRequest`).

use core::ffi::c_char;
use core::ptr;
use std::ffi::CString;
use std::path::Path;

use crate::error::{from_swift, VisionError};
use crate::ffi;
use crate::face_landmarks::LandmarkPoint;

/// A single closed contour, represented as an ordered list of points
/// in normalised image coordinates.
#[derive(Debug, Clone, PartialEq)]
pub struct Contour {
    /// Vertices in path order, normalised to `0.0..=1.0`.
    pub points: Vec<LandmarkPoint>,
    /// Number of child (nested) contours inside this one.
    pub child_count: isize,
    /// Bounding-box width / height of this contour.
    pub aspect_ratio: f32,
}

/// Options for `detect_contours_in_path`.
#[derive(Debug, Clone, Copy)]
pub struct ContourOptions {
    /// `0.0..=1.0` — Apple's per-pixel contrast adjustment before
    /// detection. Default 2.0 in the SDK; we mirror that.
    pub contrast_adjustment: f32,
    /// If `true`, look for dark shapes against a light background.
    /// If `false`, light shapes against a dark background.
    pub detects_dark_on_light: bool,
}

impl Default for ContourOptions {
    fn default() -> Self {
        Self {
            contrast_adjustment: 2.0,
            detects_dark_on_light: true,
        }
    }
}

/// Detect top-level contours in the image at `path`. Only the
/// outermost (top-level) contours are returned; nested contours are
/// counted but not enumerated.
///
/// # Errors
///
/// Returns [`VisionError::ImageLoadFailed`] / [`VisionError::RequestFailed`].
pub fn detect_contours_in_path(
    path: impl AsRef<Path>,
    options: ContourOptions,
) -> Result<Vec<Contour>, VisionError> {
    let path_str = path
        .as_ref()
        .to_str()
        .ok_or_else(|| VisionError::InvalidArgument("non-UTF-8 path".into()))?;
    let path_c = CString::new(path_str)
        .map_err(|e| VisionError::InvalidArgument(format!("path NUL byte: {e}")))?;

    let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
    let mut out_count: usize = 0;
    let mut err_msg: *mut c_char = ptr::null_mut();
    let status = unsafe {
        ffi::vn_detect_contours_in_path(
            path_c.as_ptr(),
            options.contrast_adjustment,
            options.detects_dark_on_light,
            &mut out_array,
            &mut out_count,
            &mut err_msg,
        )
    };
    if status != ffi::status::OK {
        return Err(unsafe { from_swift(status, err_msg) });
    }
    if out_array.is_null() || out_count == 0 {
        return Ok(Vec::new());
    }
    let typed = out_array.cast::<ffi::ContourRaw>();
    let mut v = Vec::with_capacity(out_count);
    for i in 0..out_count {
        let raw = unsafe { &*typed.add(i) };
        let mut pts = Vec::with_capacity(raw.point_count);
        for k in 0..raw.point_count {
            let x = unsafe { *raw.point_xs.add(k) };
            let y = unsafe { *raw.point_ys.add(k) };
            pts.push(LandmarkPoint { x, y });
        }
        v.push(Contour {
            points: pts,
            child_count: raw.child_count,
            aspect_ratio: raw.aspect_ratio,
        });
    }
    unsafe { ffi::vn_contours_free(out_array, out_count) };
    Ok(v)
}