apple_vision/rectangles/
mod.rs

1//! Rectangle + document-segmentation detection.
2//!
3//! `VNDetectRectanglesRequest` finds quadrilaterals (signs, photos,
4//! book pages); `VNDetectDocumentSegmentationRequest` finds full
5//! document boundaries — both return the same observation shape.
6
7use core::ffi::c_char;
8use core::ptr;
9use std::ffi::CString;
10use std::path::Path;
11
12use crate::error::{from_swift, VisionError};
13use crate::face_landmarks::LandmarkPoint;
14use crate::ffi;
15use crate::recognize_text::BoundingBox;
16
17/// A detected quadrilateral with axis-aligned bounding box plus
18/// individual corner points (in normalised image coordinates,
19/// bottom-left origin).
20#[derive(Debug, Clone, PartialEq)]
21pub struct RectangleObservation {
22    pub bounding_box: BoundingBox,
23    pub confidence: f32,
24    pub top_left: LandmarkPoint,
25    pub top_right: LandmarkPoint,
26    pub bottom_left: LandmarkPoint,
27    pub bottom_right: LandmarkPoint,
28}
29
30/// Optional tuning for `detect_rectangles_in_path`. Pass `default()`
31/// to use Apple's defaults.
32#[derive(Debug, Clone, Copy, Default)]
33pub struct RectangleOptions {
34    /// `0` ⇒ Apple default.
35    pub max_observations: usize,
36    /// `0` ⇒ Apple default.
37    pub minimum_aspect_ratio: f32,
38    /// `0` ⇒ Apple default.
39    pub maximum_aspect_ratio: f32,
40    /// `0` ⇒ Apple default (normalised size of smallest rectangle).
41    pub minimum_size: f32,
42    /// `0` ⇒ Apple default.
43    pub minimum_confidence: f32,
44}
45
46/// Detect rectangles in the image at `path`.
47///
48/// # Errors
49///
50/// Returns [`VisionError::ImageLoadFailed`] / [`VisionError::RequestFailed`].
51pub fn detect_rectangles_in_path(
52    path: impl AsRef<Path>,
53    options: RectangleOptions,
54) -> Result<Vec<RectangleObservation>, VisionError> {
55    let path_str = path
56        .as_ref()
57        .to_str()
58        .ok_or_else(|| VisionError::InvalidArgument("non-UTF-8 path".into()))?;
59    let path_c = CString::new(path_str)
60        .map_err(|e| VisionError::InvalidArgument(format!("path NUL byte: {e}")))?;
61
62    let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
63    let mut out_count: usize = 0;
64    let mut err_msg: *mut c_char = ptr::null_mut();
65
66    // SAFETY: all pointer arguments are valid stack locations or bridge-owned handles; strings are valid C strings for the duration of the call.
67    let status = unsafe {
68        ffi::vn_detect_rectangles_in_path(
69            path_c.as_ptr(),
70            options.max_observations,
71            options.minimum_aspect_ratio,
72            options.maximum_aspect_ratio,
73            options.minimum_size,
74            options.minimum_confidence,
75            &mut out_array,
76            &mut out_count,
77            &mut err_msg,
78        )
79    };
80    if status != ffi::status::OK {
81        // SAFETY: the error pointer is either null or a bridge-allocated C string; `from_swift` frees it.
82        return Err(unsafe { from_swift(status, err_msg) });
83    }
84    // SAFETY: the pointer/count pair comes directly from the bridge and `collect_rects` consumes it exactly once.
85    Ok(unsafe { collect_rects(out_array, out_count) })
86}
87
88/// Detect a full document's boundary in the image at `path`. Returns
89/// at most one rectangle (the document outline).
90///
91/// # Errors
92///
93/// Returns [`VisionError::ImageLoadFailed`] / [`VisionError::RequestFailed`].
94pub fn detect_document_segmentation_in_path(
95    path: impl AsRef<Path>,
96) -> Result<Vec<RectangleObservation>, VisionError> {
97    let path_str = path
98        .as_ref()
99        .to_str()
100        .ok_or_else(|| VisionError::InvalidArgument("non-UTF-8 path".into()))?;
101    let path_c = CString::new(path_str)
102        .map_err(|e| VisionError::InvalidArgument(format!("path NUL byte: {e}")))?;
103
104    let mut out_array: *mut core::ffi::c_void = ptr::null_mut();
105    let mut out_count: usize = 0;
106    let mut err_msg: *mut c_char = ptr::null_mut();
107
108    // SAFETY: all pointer arguments are valid stack locations or null-initialised out-params; strings are valid C strings for the duration of the call.
109    let status = unsafe {
110        ffi::vn_detect_document_segmentation_in_path(
111            path_c.as_ptr(),
112            &mut out_array,
113            &mut out_count,
114            &mut err_msg,
115        )
116    };
117    if status != ffi::status::OK {
118        // SAFETY: the error pointer is either null or a bridge-allocated C string; `from_swift` frees it.
119        return Err(unsafe { from_swift(status, err_msg) });
120    }
121    // SAFETY: the pointer/count pair comes directly from the bridge and `collect_rects` consumes it exactly once.
122    Ok(unsafe { collect_rects(out_array, out_count) })
123}
124
125/// Convert a bridge-allocated rectangle array into Rust-owned observations.
126///
127/// # Safety
128///
129/// `out_array` must be either null or point to `out_count` consecutive
130/// `RectangleObservationRaw` elements allocated by the Swift bridge.
131/// This function consumes that allocation and frees it exactly once.
132unsafe fn collect_rects(
133    out_array: *mut core::ffi::c_void,
134    out_count: usize,
135) -> Vec<RectangleObservation> {
136    if out_array.is_null() || out_count == 0 {
137        return Vec::new();
138    }
139    let typed = out_array.cast::<ffi::RectangleObservationRaw>();
140    let mut v = Vec::with_capacity(out_count);
141    for i in 0..out_count {
142        // SAFETY: the pointer is valid for the reported element count; the index is in bounds.
143        let r = unsafe { &*typed.add(i) };
144        v.push(RectangleObservation {
145            bounding_box: BoundingBox {
146                x: r.bbox_x,
147                y: r.bbox_y,
148                width: r.bbox_w,
149                height: r.bbox_h,
150            },
151            confidence: r.confidence,
152            top_left: LandmarkPoint {
153                x: r.tl_x,
154                y: r.tl_y,
155            },
156            top_right: LandmarkPoint {
157                x: r.tr_x,
158                y: r.tr_y,
159            },
160            bottom_left: LandmarkPoint {
161                x: r.bl_x,
162                y: r.bl_y,
163            },
164            bottom_right: LandmarkPoint {
165                x: r.br_x,
166                y: r.br_y,
167            },
168        });
169    }
170    // SAFETY: the pointer/count pair was allocated by the bridge and is freed exactly once here.
171    unsafe { ffi::vn_rectangle_observations_free(out_array, out_count) };
172    v
173}
apple_vision/rectangles/mod.rs

apple_vision/rectangles/
mod.rs
