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}