1use std::path::{Path, PathBuf};
10use std::sync::Arc;
11
12use image::RgbImage;
13#[cfg(feature = "onnx")]
14use rightkit_ort::{configure_runtime, CandidateSource, RuntimeCandidate};
15use serde::Serialize;
16
17use crate::native;
18use crate::types::{decode_encoded, is_backend_unavailable, OcrBackend, OcrLine};
19use crate::worker::WorkerCommand;
20#[cfg(feature = "onnx")]
21use crate::OcrEngine;
22use crate::{OcrArtifactManifest, OcrError};
23
24#[cfg(feature = "onnx")]
27type OnnxSlot = OcrEngine;
28#[cfg(not(feature = "onnx"))]
29type OnnxSlot = std::convert::Infallible;
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum BackendPreference {
33 Auto,
35 Native,
37 Onnx,
39}
40
41#[derive(Debug, Clone, Default)]
43pub enum Isolation {
44 #[default]
46 InProcess,
47 Worker(WorkerCommand),
51}
52
53pub trait ModelLeaseHook: Send + Sync + std::fmt::Debug {
61 fn acquire_model_lease(
62 &self,
63 paths: &[PathBuf],
64 ) -> Result<Box<dyn std::any::Any + Send>, String>;
65}
66
67#[derive(Debug, Clone)]
69pub struct OnnxConfig {
70 pub model_dir: PathBuf,
71 pub manifest: OcrArtifactManifest,
72 pub ort_runtime: Option<PathBuf>,
75 pub lease_hook: Option<Arc<dyn ModelLeaseHook>>,
77}
78
79impl OnnxConfig {
80 pub fn new(model_dir: impl Into<PathBuf>, manifest: OcrArtifactManifest) -> Self {
81 Self {
82 model_dir: model_dir.into(),
83 manifest,
84 ort_runtime: None,
85 lease_hook: None,
86 }
87 }
88
89 pub fn with_lease_hook(mut self, hook: Arc<dyn ModelLeaseHook>) -> Self {
91 self.lease_hook = Some(hook);
92 self
93 }
94}
95
96#[derive(Debug, Clone)]
97pub struct OcrOptions {
98 pub preference: BackendPreference,
99 pub onnx: Option<OnnxConfig>,
100 pub isolation: Isolation,
101}
102
103impl OcrOptions {
104 pub fn new(preference: BackendPreference) -> Self {
105 Self {
106 preference,
107 onnx: None,
108 isolation: Isolation::InProcess,
109 }
110 }
111 pub fn with_onnx(mut self, onnx: OnnxConfig) -> Self {
112 self.onnx = Some(onnx);
113 self
114 }
115 pub fn with_isolation(mut self, isolation: Isolation) -> Self {
116 self.isolation = isolation;
117 self
118 }
119}
120
121impl Default for OcrOptions {
122 fn default() -> Self {
123 Self::new(BackendPreference::Auto)
124 }
125}
126
127#[derive(Debug, Clone, Serialize)]
129#[serde(rename_all = "camelCase")]
130pub struct OcrResult {
131 pub lines: Vec<OcrLine>,
132 pub backend: OcrBackend,
133 pub fallback_reason: Option<String>,
135}
136
137impl OcrResult {
138 pub fn text(&self) -> String {
140 self.lines
141 .iter()
142 .map(|l| l.text.as_str())
143 .collect::<Vec<_>>()
144 .join("\n")
145 }
146}
147
148#[derive(Debug, Clone, PartialEq, Eq)]
150pub struct OcrOutcome {
151 pub text: String,
152 pub backend: OcrBackend,
153}
154
155pub struct Ocr {
158 options: OcrOptions,
159 #[cfg_attr(not(feature = "onnx"), allow(dead_code))]
160 onnx: Option<OnnxSlot>,
161}
162
163impl Ocr {
164 pub fn new(options: OcrOptions) -> Self {
165 Self {
166 options,
167 onnx: None,
168 }
169 }
170
171 pub fn recognize_file(&mut self, path: &Path) -> Result<OcrResult, OcrError> {
172 let bytes = std::fs::read(path)
173 .map_err(|e| OcrError::Runtime(format!("Cannot read image {path:?}: {e}")))?;
174 self.recognize_encoded(&bytes)
175 }
176
177 pub fn recognize_encoded(&mut self, bytes: &[u8]) -> Result<OcrResult, OcrError> {
180 let img = decode_encoded(bytes)?;
181 self.recognize_inner(&img, Some(bytes))
182 }
183
184 pub fn recognize(&mut self, img: &RgbImage) -> Result<OcrResult, OcrError> {
185 self.recognize_inner(img, None)
186 }
187
188 pub fn recognize_with_provenance(&mut self, img: &RgbImage) -> Result<OcrOutcome, OcrError> {
190 self.recognize(img).map(|r| OcrOutcome {
191 text: r.text(),
192 backend: r.backend,
193 })
194 }
195
196 pub fn is_available(&self) -> bool {
200 matches!(self.probe_native(), Ok(true))
201 }
202
203 #[cfg(feature = "onnx")]
206 pub fn validate_fallback(&self) -> Result<(), OcrError> {
207 let cfg = self.options.onnx.as_ref().ok_or_else(|| {
208 OcrError::NoFallbackConfigured("no ONNX model config to validate".into())
209 })?;
210 configure_ort_runtime(cfg)?;
211 OcrEngine::validate_sessions(&cfg.model_dir, &cfg.manifest)
212 }
213
214 pub fn probe_native(&self) -> Result<bool, String> {
218 if native::native_backend().is_none() {
219 return Ok(false);
220 }
221 let result = match &self.options.isolation {
222 Isolation::Worker(cmd) => cmd.run(native::canary_png()),
223 Isolation::InProcess => {
224 decode_encoded(native::canary_png()).and_then(|i| native::recognize(&i))
225 }
226 };
227 match result {
228 Ok(lines) if !lines.is_empty() => Ok(true),
229 Ok(_) => Err("native canary returned no observations".into()),
230 Err(e) if is_backend_unavailable(&e) => Ok(false),
231 Err(e) => Err(e),
232 }
233 }
234
235 fn recognize_inner(
236 &mut self,
237 img: &RgbImage,
238 encoded: Option<&[u8]>,
239 ) -> Result<OcrResult, OcrError> {
240 match self.options.preference {
241 BackendPreference::Onnx => self.run_onnx(img, None),
242 BackendPreference::Native => {
243 let lines = self.run_native(img, encoded).map_err(native_error)?;
244 Ok(native_result(lines, None))
245 }
246 BackendPreference::Auto => match self.run_native(img, encoded) {
247 Ok(lines) => Ok(native_result(lines, None)),
248 Err(e) if is_backend_unavailable(&e) => {
249 if self.options.onnx.is_none() {
250 return Err(OcrError::NoFallbackConfigured(e));
251 }
252 self.run_onnx(img, Some(e))
253 }
254 Err(e) => Err(OcrError::Runtime(e)),
255 },
256 }
257 }
258
259 fn run_native(&self, img: &RgbImage, encoded: Option<&[u8]>) -> Result<Vec<OcrLine>, String> {
260 let Some(backend) = native::native_backend() else {
261 return Err(format!(
262 "{} no native OCR backend on this platform",
263 crate::types::OCR_UNSUPPORTED_PLATFORM
264 ));
265 };
266 match &self.options.isolation {
267 Isolation::InProcess => native::recognize(img),
268 Isolation::Worker(cmd) => {
269 let owned;
270 let bytes = match encoded {
271 Some(b) => b,
272 None => {
273 owned = encode_png(img)?;
274 &owned
275 }
276 };
277 let lines = cmd.run(bytes)?;
278 if !lines.is_empty() || backend != OcrBackend::Vision {
279 return Ok(lines);
280 }
281 match cmd.run(native::canary_png()) {
284 Ok(c) if !c.is_empty() => Ok(lines),
285 Ok(_) => Err(format!(
286 "{} Vision returned no observations and the canary in a fresh worker \
287 also returned none, so text recognition is not working here",
288 crate::types::MACOS_VISION_UNAVAILABLE
289 )),
290 Err(e) => Err(e),
291 }
292 }
293 }
294 }
295
296 #[cfg(not(feature = "onnx"))]
297 fn run_onnx(
298 &mut self,
299 _img: &RgbImage,
300 _fallback_reason: Option<String>,
301 ) -> Result<OcrResult, OcrError> {
302 Err(OcrError::BackendUnavailable(
303 "ONNX fallback not compiled in: rebuild rightkit-ocr with the `onnx` feature".into(),
304 ))
305 }
306
307 #[cfg(feature = "onnx")]
308 fn run_onnx(
309 &mut self,
310 img: &RgbImage,
311 fallback_reason: Option<String>,
312 ) -> Result<OcrResult, OcrError> {
313 let cfg = self.options.onnx.clone().ok_or_else(|| {
314 OcrError::NoFallbackConfigured("ONNX backend requested without model config".into())
315 })?;
316 if self.onnx.is_none() {
317 configure_ort_runtime(&cfg)?;
318 self.onnx = Some(OcrEngine::load_with_lease(
319 &cfg.model_dir,
320 &cfg.manifest,
321 cfg.lease_hook.as_deref(),
322 )?);
323 }
324 let lines = self.onnx.as_mut().expect("loaded above").run_lines(img)?;
325 Ok(OcrResult {
326 lines,
327 backend: OcrBackend::Onnx,
328 fallback_reason,
329 })
330 }
331}
332
333#[cfg(feature = "onnx")]
334fn configure_ort_runtime(cfg: &OnnxConfig) -> Result<(), OcrError> {
335 if let Some(rt) = &cfg.ort_runtime {
336 configure_runtime([RuntimeCandidate::new(rt.clone(), CandidateSource::Explicit)])
337 .map_err(|e| OcrError::Runtime(format!("ONNX runtime: {e:?}")))?;
338 }
339 Ok(())
340}
341
342fn native_result(lines: Vec<OcrLine>, fallback_reason: Option<String>) -> OcrResult {
343 OcrResult {
344 lines,
345 backend: native::native_backend().expect("native result implies native backend"),
346 fallback_reason,
347 }
348}
349
350fn native_error(e: String) -> OcrError {
351 if is_backend_unavailable(&e) {
352 OcrError::BackendUnavailable(e)
353 } else {
354 OcrError::Runtime(e)
355 }
356}
357
358fn encode_png(img: &RgbImage) -> Result<Vec<u8>, String> {
359 let mut out = Vec::new();
360 img.write_to(&mut std::io::Cursor::new(&mut out), image::ImageFormat::Png)
361 .map_err(|e| format!("Cannot encode image for worker: {e}"))?;
362 Ok(out)
363}