Skip to main content

rightkit_ocr/
types.rs

1//! Shared result types, error prefixes and the decode guard.
2//!
3//! One result shape for every backend: text + normalized top-left geometry +
4//! optional confidence (ViewRight's `OcrLine`, the most mature donor).
5
6use image::RgbImage;
7use serde::{Deserialize, Serialize};
8
9/// Prefix for a Windows backend that cannot recognize at all (no language pack).
10///
11/// Deprecated for keying: match [`OcrErrorKind::WindowsOcrUnavailable`] instead. The prefix
12/// stays in the error `Display` text for compatibility with existing log and UI matching.
13pub const WINDOWS_OCR_UNAVAILABLE: &str = "windows-ocr-unavailable:";
14/// Prefix for an Apple Vision request that could not be performed.
15///
16/// Deprecated for keying: match [`OcrErrorKind::MacosVisionUnavailable`] instead. The prefix
17/// stays in the error `Display` text for compatibility.
18pub const MACOS_VISION_UNAVAILABLE: &str = "macos-vision-unavailable:";
19/// Prefix for a platform with no native OCR backend at all (Linux builds).
20///
21/// Deprecated for keying: match [`OcrErrorKind::UnsupportedPlatform`] instead. The prefix stays
22/// in the error `Display` text for compatibility.
23pub const OCR_UNSUPPORTED_PLATFORM: &str = "ocr-unsupported-platform:";
24
25/// Does this error mean the native backend is unusable on this machine (a
26/// capability verdict, and the only thing that arms the ONNX fallback), as
27/// opposed to a per-image failure that must stay visible?
28///
29/// Equivalent to `OcrErrorKind::from_message(err).is_some_and(OcrErrorKind::is_backend_unavailable)`.
30/// Prefer [`OcrError::kind`](crate::OcrError::kind) or [`OcrErrorKind`] in new code.
31pub fn is_backend_unavailable(err: &str) -> bool {
32    OcrErrorKind::from_message(err).is_some_and(OcrErrorKind::is_backend_unavailable)
33}
34
35/// Typed classification of an OCR failure, so hosts key on a kind instead of message text.
36///
37/// The kind is the stable contract; `Display` text (including the legacy `...-unavailable:`
38/// prefixes) is for humans and logs. The enum is `#[non_exhaustive]`: match with a wildcard arm.
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
40#[serde(rename_all = "camelCase")]
41#[non_exhaustive]
42pub enum OcrErrorKind {
43    /// Apple Vision cannot perform recognition here (capability verdict; arms the ONNX fallback).
44    MacosVisionUnavailable,
45    /// `Windows.Media.Ocr` cannot recognize here, e.g. no language pack (capability verdict).
46    WindowsOcrUnavailable,
47    /// No native OCR backend is compiled for this platform (capability verdict).
48    UnsupportedPlatform,
49    /// Some other backend is unusable, e.g. the ONNX fallback was not compiled in.
50    BackendUnavailable,
51    /// The native backend is unusable and no ONNX fallback is configured.
52    NoFallbackConfigured,
53    /// Reserved. The crate never returns this today: a page with no observations that passes the
54    /// canary check is `Ok` with empty lines, and a failing canary is a backend verdict instead.
55    BlankPage,
56    /// The request bytes exceed the 32 MiB worker input limit.
57    RequestTooLarge,
58    /// The child exceeded its deadline, either the parent's own deadline or the child's watchdog.
59    WorkerTimeout,
60    /// The child's output exceeded the bounded protocol limit.
61    WorkerOutputExceeded,
62    /// The child's stdout was not a valid worker response.
63    WorkerProtocol,
64    /// The child could not start, exited with failure, or its pipes or wait failed.
65    WorkerFailed,
66    /// Model provenance is unresolved or incomplete.
67    Provenance,
68    /// An ONNX model artifact is missing, unsafe, or fails its digest check.
69    Artifact,
70    /// Any other runtime failure, including per-image faults that must stay visible.
71    Runtime,
72}
73
74impl OcrErrorKind {
75    /// Classify a legacy error message by its backend prefix.
76    ///
77    /// Returns `None` for ordinary failures. This is the only place the crate parses prefixes; a
78    /// child process reports errors as text, so the worker boundary calls it once per response.
79    pub fn from_message(message: &str) -> Option<Self> {
80        if message.starts_with(MACOS_VISION_UNAVAILABLE) {
81            Some(Self::MacosVisionUnavailable)
82        } else if message.starts_with(WINDOWS_OCR_UNAVAILABLE) {
83            Some(Self::WindowsOcrUnavailable)
84        } else if message.starts_with(OCR_UNSUPPORTED_PLATFORM) {
85            Some(Self::UnsupportedPlatform)
86        } else {
87            None
88        }
89    }
90
91    /// Is this a native capability verdict, i.e. the same set [`is_backend_unavailable`] accepts?
92    /// `BackendUnavailable` (for example, ONNX not compiled in) is not included.
93    pub fn is_backend_unavailable(self) -> bool {
94        matches!(
95            self,
96            Self::MacosVisionUnavailable | Self::WindowsOcrUnavailable | Self::UnsupportedPlatform
97        )
98    }
99
100    /// Stable snake_case name for logs and telemetry, e.g. `macos_vision_unavailable`.
101    pub fn as_str(self) -> &'static str {
102        match self {
103            Self::MacosVisionUnavailable => "macos_vision_unavailable",
104            Self::WindowsOcrUnavailable => "windows_ocr_unavailable",
105            Self::UnsupportedPlatform => "unsupported_platform",
106            Self::BackendUnavailable => "backend_unavailable",
107            Self::NoFallbackConfigured => "no_fallback_configured",
108            Self::BlankPage => "blank_page",
109            Self::RequestTooLarge => "request_too_large",
110            Self::WorkerTimeout => "worker_timeout",
111            Self::WorkerOutputExceeded => "worker_output_exceeded",
112            Self::WorkerProtocol => "worker_protocol",
113            Self::WorkerFailed => "worker_failed",
114            Self::Provenance => "provenance",
115            Self::Artifact => "artifact",
116            Self::Runtime => "runtime",
117        }
118    }
119}
120
121/// A normalized rectangle: 0..1 of the source image, **origin top-left**.
122#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
123#[serde(rename_all = "camelCase")]
124pub struct OcrRect {
125    pub x: f32,
126    pub y: f32,
127    pub width: f32,
128    pub height: f32,
129}
130
131/// One recognized line with its position on the image.
132#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
133#[serde(rename_all = "camelCase")]
134pub struct OcrLine {
135    pub text: String,
136    pub rect: OcrRect,
137    /// 0..1 where the backend reports it (Vision, ONNX). Windows.Media.Ocr
138    /// exposes none, so it is `None` there; `None` is not low confidence.
139    pub confidence: Option<f32>,
140}
141
142/// Which backend produced a result.
143#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
144#[serde(rename_all = "camelCase")]
145pub enum OcrBackend {
146    /// Apple Vision (macOS).
147    Vision,
148    /// Windows.Media.Ocr.
149    WindowsMedia,
150    /// The two-stage PP-OCR ONNX pipeline.
151    Onnx,
152}
153
154impl OcrBackend {
155    pub fn is_native(self) -> bool {
156        !matches!(self, Self::Onnx)
157    }
158}
159
160/// Largest image decoded, in pixels (enforced on the header, before any pixel
161/// buffer is allocated — a decompression-bomb guard).
162pub const MAX_PIXELS: u64 = 40_000_000;
163
164/// Decode PNG/JPEG bytes to RGB with the [`MAX_PIXELS`] guard.
165pub fn decode_encoded(bytes: &[u8]) -> Result<RgbImage, String> {
166    let reader = image::ImageReader::new(std::io::Cursor::new(bytes))
167        .with_guessed_format()
168        .map_err(|e| format!("Cannot read image header: {e}"))?;
169    let (w, h) = reader
170        .into_dimensions()
171        .map_err(|e| format!("Cannot read image dimensions: {e}"))?;
172    let pixels = u64::from(w) * u64::from(h);
173    if pixels > MAX_PIXELS {
174        return Err(format!(
175            "Image is {w}x{h} ({pixels} pixels), over the {MAX_PIXELS}-pixel limit"
176        ));
177    }
178    let image = image::load_from_memory(bytes).map_err(|e| format!("Cannot decode image: {e}"))?;
179    Ok(image.into_rgb8())
180}