1mod native;
15mod router;
16#[cfg(feature = "onnx")]
17mod support;
18mod types;
19pub mod worker;
20
21#[cfg(all(target_os = "macos", feature = "native"))]
22pub use native::vision;
23#[cfg(all(windows, feature = "native"))]
24pub use native::win_native;
25pub use native::{canary_png, native_backend};
26pub use router::{
27 BackendPreference, Isolation, ModelLeaseHook, NativeHealthHook, Ocr, OcrOptions, OcrOutcome,
28 OcrResult, OnnxConfig,
29};
30pub use types::{
31 decode_encoded, is_backend_unavailable, OcrBackend, OcrErrorKind, OcrLine, OcrRect,
32 MACOS_VISION_UNAVAILABLE, MAX_PIXELS, OCR_UNSUPPORTED_PLATFORM, WINDOWS_OCR_UNAVAILABLE,
33};
34pub use worker::{RunRecord, WorkerCommand, WorkerEvent, WorkerEvents, WorkerFailure, WorkerRun};
35
36#[cfg(feature = "onnx")]
37use image::{imageops, RgbImage};
38#[cfg(feature = "onnx")]
39use rightkit_onnx::ort;
40#[cfg(feature = "onnx")]
41use rightkit_onnx::ort::{session::Session, value::Tensor};
42#[cfg(feature = "onnx")]
43use rightkit_onnx::ProviderDiagnostic;
44#[cfg(feature = "onnx")]
45use sha2::{Digest, Sha256};
46use std::fmt;
47#[cfg(feature = "onnx")]
48use std::path::Path;
49use std::path::PathBuf;
50#[cfg(all(test, feature = "onnx"))]
51use support::ctc_greedy_decode;
52#[cfg(feature = "onnx")]
53use support::{
54 build_session, crop_box, ctc_greedy_decode_scored, dedup_boxes, det_chw_data, det_net_size,
55 extract_boxes, group_into_lines, load_image, load_vocab, rec_chw_data, BBox, DET_BAND_OVERLAP,
56 DET_MAX_W, DET_TILE_H,
57};
58
59#[derive(Debug, Clone, PartialEq, Eq)]
64pub enum OcrProvenance {
65 Resolved {
66 label: String,
67 source: String,
68 license: String,
69 },
70 Conflicting {
71 labels: Vec<String>,
72 },
73}
74
75#[derive(Debug, Clone, PartialEq, Eq)]
76pub struct OcrArtifactManifest {
77 pub provenance: OcrProvenance,
78 pub detector_sha256: String,
79 pub recognizer_sha256: String,
80 pub dictionary_sha256: String,
81 pub fixture_sha256: String,
82 pub expected_fixture_output: String,
83}
84
85impl OcrArtifactManifest {
86 pub fn characterized_windows_contract() -> Self {
87 Self {
88 provenance: OcrProvenance::Conflicting {
89 labels: vec!["PP-OCRv5".to_string(), "PP-OCRv6".to_string()],
90 },
91 detector_sha256: "eb13b44b25bb36f89528b68720af8a61d9cf381176107f465db1757b65d086e1"
92 .to_string(),
93 recognizer_sha256: "5435fd747c9e0efe15a96d0b378d5bd157e9492ed8fd80edf08f30d02fa24634"
94 .to_string(),
95 dictionary_sha256: "b5f2bfe2bdd9448429e3e82b51c789775d9b42f2403d082b00662eb77e401c5d"
96 .to_string(),
97 fixture_sha256: "803e102100c91a077607cd2d4750d9d748d86ced48fabc0f77062f26dcba0a4b"
98 .to_string(),
99 expected_fixture_output: "RIGHTKIT OCR 2026\nShared parity fixture".to_string(),
100 }
101 }
102
103 pub fn pp_ocr_v6() -> Self {
114 let mut manifest = Self::characterized_windows_contract();
115 manifest.provenance = OcrProvenance::Resolved {
116 label: "PP-OCRv6".to_string(),
117 source: "https://huggingface.co/PaddlePaddle/PP-OCRv6_medium_det_onnx (det) + \
118 https://huggingface.co/PaddlePaddle/PP-OCRv6_small_rec_onnx (rec + dict)"
119 .to_string(),
120 license: "Apache-2.0".to_string(),
121 };
122 manifest
123 }
124
125 pub fn with_resolved_provenance(
128 mut self,
129 label: impl Into<String>,
130 source: impl Into<String>,
131 license: impl Into<String>,
132 ) -> Result<Self, OcrError> {
133 self.provenance = OcrProvenance::Resolved {
134 label: label.into(),
135 source: source.into(),
136 license: license.into(),
137 };
138 self.validate_metadata()?;
139 Ok(self)
140 }
141
142 pub fn validate_metadata(&self) -> Result<(), OcrError> {
143 match &self.provenance {
144 OcrProvenance::Conflicting { labels } => Err(OcrError::UnresolvedProvenance {
145 labels: labels.clone(),
146 }),
147 OcrProvenance::Resolved {
148 label,
149 source,
150 license,
151 } if label.trim().is_empty()
152 || source.trim().is_empty()
153 || license.trim().is_empty() =>
154 {
155 Err(OcrError::InvalidProvenance)
156 }
157 OcrProvenance::Resolved { .. } => Ok(()),
158 }
159 }
160
161 #[cfg(feature = "onnx")]
162 pub fn validate_model_dir(&self, model_dir: &Path) -> Result<VerifiedOcrArtifacts, OcrError> {
163 self.validate_metadata()?;
164 if !model_dir.is_absolute() {
165 return Err(OcrError::UnsafeArtifactPath {
166 path: model_dir.to_path_buf(),
167 });
168 }
169 let root = model_dir
170 .canonicalize()
171 .map_err(|_| OcrError::MissingArtifact {
172 path: model_dir.to_path_buf(),
173 })?;
174 if !root.is_dir() {
175 return Err(OcrError::MissingArtifact { path: root });
176 }
177 Ok(VerifiedOcrArtifacts {
178 detector: verify_artifact(&root, "det.onnx", &self.detector_sha256)?,
179 recognizer: verify_artifact(&root, "rec.onnx", &self.recognizer_sha256)?,
180 dictionary: verify_artifact(&root, "en_dict.txt", &self.dictionary_sha256)?,
181 })
182 }
183}
184
185#[derive(Debug, Clone, PartialEq, Eq)]
186pub struct VerifiedOcrArtifacts {
187 pub detector: PathBuf,
188 pub recognizer: PathBuf,
189 pub dictionary: PathBuf,
190}
191
192#[derive(Debug, Clone, PartialEq, Eq)]
193pub enum OcrError {
194 UnresolvedProvenance {
195 labels: Vec<String>,
196 },
197 InvalidProvenance,
198 UnsafeArtifactPath {
199 path: PathBuf,
200 },
201 MissingArtifact {
202 path: PathBuf,
203 },
204 DigestMismatch {
205 path: PathBuf,
206 expected: String,
207 actual: String,
208 },
209 Runtime(String),
210 BackendUnavailable(String),
212 NoFallbackConfigured(String),
214}
215
216impl fmt::Display for OcrError {
217 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
218 match self {
219 Self::UnresolvedProvenance { labels } => write!(
220 f,
221 "OCR provenance conflict is unresolved: {}",
222 labels.join(" vs ")
223 ),
224 Self::InvalidProvenance => {
225 write!(
226 f,
227 "OCR provenance label, source, and license must be non-empty"
228 )
229 }
230 Self::UnsafeArtifactPath { path } => {
231 write!(f, "OCR artifact path must be absolute: {}", path.display())
232 }
233 Self::MissingArtifact { path } => {
234 write!(f, "OCR artifact is missing: {}", path.display())
235 }
236 Self::DigestMismatch {
237 path,
238 expected,
239 actual,
240 } => write!(
241 f,
242 "OCR artifact digest mismatch for {}: expected {expected}, got {actual}",
243 path.display()
244 ),
245 Self::Runtime(message) => write!(f, "OCR runtime error: {message}"),
246 Self::BackendUnavailable(message) => write!(f, "OCR backend unavailable: {message}"),
247 Self::NoFallbackConfigured(message) => {
248 write!(
249 f,
250 "OCR native backend unavailable and no ONNX fallback configured: {message}"
251 )
252 }
253 }
254 }
255}
256
257impl OcrError {
258 pub fn kind(&self) -> OcrErrorKind {
264 match self {
265 Self::UnresolvedProvenance { .. } | Self::InvalidProvenance => OcrErrorKind::Provenance,
266 Self::UnsafeArtifactPath { .. }
267 | Self::MissingArtifact { .. }
268 | Self::DigestMismatch { .. } => OcrErrorKind::Artifact,
269 Self::Runtime(_) => OcrErrorKind::Runtime,
270 Self::BackendUnavailable(message) => {
271 OcrErrorKind::from_message(message).unwrap_or(OcrErrorKind::BackendUnavailable)
272 }
273 Self::NoFallbackConfigured(_) => OcrErrorKind::NoFallbackConfigured,
274 }
275 }
276}
277
278impl std::error::Error for OcrError {}
279impl From<String> for OcrError {
280 fn from(value: String) -> Self {
281 Self::Runtime(value)
282 }
283}
284
285#[cfg(feature = "onnx")]
287fn artifact_paths(model_dir: &Path) -> Vec<PathBuf> {
288 ["det.onnx", "rec.onnx", "en_dict.txt"]
289 .iter()
290 .map(|name| model_dir.join(name))
291 .collect()
292}
293
294#[cfg(feature = "onnx")]
295fn verify_artifact(root: &Path, name: &str, expected: &str) -> Result<PathBuf, OcrError> {
296 let path = root.join(name);
297 let canonical = path
298 .canonicalize()
299 .map_err(|_| OcrError::MissingArtifact { path: path.clone() })?;
300 if !canonical.starts_with(root) || !canonical.is_file() {
301 return Err(OcrError::UnsafeArtifactPath { path: canonical });
302 }
303 let bytes = std::fs::read(&canonical).map_err(|_| OcrError::MissingArtifact {
304 path: canonical.clone(),
305 })?;
306 let actual: String = Sha256::digest(bytes)
307 .iter()
308 .map(|b| format!("{b:02x}"))
309 .collect();
310 if actual != expected {
311 return Err(OcrError::DigestMismatch {
312 path: canonical,
313 expected: expected.to_string(),
314 actual,
315 });
316 }
317 Ok(canonical)
318}
319
320#[cfg(feature = "onnx")]
321pub fn ocr_image_with_manifest(
322 path: &Path,
323 model_dir: &Path,
324 manifest: &OcrArtifactManifest,
325) -> Result<String, OcrError> {
326 let mut engine = OcrEngine::load_with_manifest(model_dir, manifest)?;
327 let img = load_image(path)?;
328 engine.run(&img)
329}
330
331#[cfg(all(test, feature = "onnx"))]
334mod tests;
335#[cfg(feature = "onnx")]
343pub struct OcrEngine {
344 det: Session,
345 rec: Session,
346 vocab: Vec<char>,
351 provider_diagnostics: Vec<ProviderDiagnostic>,
352 _lease: Option<Box<dyn std::any::Any + Send>>,
354}
355
356#[cfg(feature = "onnx")]
357impl OcrEngine {
358 pub fn load(model_dir: &Path) -> Result<Self, OcrError> {
361 Self::load_with_manifest(model_dir, &OcrArtifactManifest::pp_ocr_v6())
362 }
363
364 pub fn load_with_manifest(
373 model_dir: &Path,
374 manifest: &OcrArtifactManifest,
375 ) -> Result<Self, OcrError> {
376 Self::load_with_lease(model_dir, manifest, None)
377 }
378
379 pub fn load_with_lease(
385 model_dir: &Path,
386 manifest: &OcrArtifactManifest,
387 lease_hook: Option<&dyn ModelLeaseHook>,
388 ) -> Result<Self, OcrError> {
389 let lease = match lease_hook {
390 Some(hook) => Some(hook.acquire_model_lease(&artifact_paths(model_dir))?),
391 None => None,
392 };
393 let artifacts = manifest.validate_model_dir(model_dir)?;
394 let vocab = load_vocab(&artifacts.dictionary)?;
395 let (det, mut provider_diagnostics) = build_session(&artifacts.detector)?;
396 let (rec, rec_diagnostics) = build_session(&artifacts.recognizer)?;
397 provider_diagnostics.extend(rec_diagnostics);
398 Ok(OcrEngine {
399 det,
400 rec,
401 vocab,
402 provider_diagnostics,
403 _lease: lease,
404 })
405 }
406
407 pub fn validate_sessions(
412 model_dir: &Path,
413 manifest: &OcrArtifactManifest,
414 ) -> Result<(), OcrError> {
415 let artifacts = manifest.validate_model_dir(model_dir)?;
416 load_vocab(&artifacts.dictionary)?;
417 build_session(&artifacts.detector)?;
418 build_session(&artifacts.recognizer)?;
419 Ok(())
420 }
421
422 pub fn provider_diagnostics(&self) -> &[ProviderDiagnostic] {
423 &self.provider_diagnostics
424 }
425
426 pub fn run(&mut self, img: &RgbImage) -> Result<String, OcrError> {
428 let lines = self.run_lines(img)?;
429 Ok(lines
430 .into_iter()
431 .map(|l| l.text)
432 .collect::<Vec<_>>()
433 .join("\n"))
434 }
435
436 pub fn run_lines(&mut self, img: &RgbImage) -> Result<Vec<OcrLine>, OcrError> {
441 let boxes = self.detect(img)?;
442 if boxes.is_empty() {
443 return Ok(Vec::new());
444 }
445 let (iw, ih) = (img.width().max(1) as f32, img.height().max(1) as f32);
446 let rows = group_into_lines(boxes);
450 let mut out = Vec::new();
451 for row in rows {
452 let mut words = Vec::new();
453 let (mut x0, mut y0, mut x1, mut y1) = (u32::MAX, u32::MAX, 0u32, 0u32);
454 let (mut conf_sum, mut conf_n, mut conf_ok) = (0.0f32, 0u32, true);
455 for bbox in &row {
456 let crop = crop_box(img, bbox);
457 if crop.width() == 0 || crop.height() == 0 {
458 continue;
459 }
460 let (text, conf) = self.recognize(&crop)?;
461 let t = text.trim().to_string();
462 if t.is_empty() {
463 continue;
464 }
465 words.push(t);
466 x0 = x0.min(bbox.x0);
467 y0 = y0.min(bbox.y0);
468 x1 = x1.max(bbox.x1);
469 y1 = y1.max(bbox.y1);
470 match conf {
471 Some(c) => {
472 conf_sum += c;
473 conf_n += 1;
474 }
475 None => conf_ok = false,
476 }
477 }
478 if words.is_empty() {
479 continue;
480 }
481 let (x0, y0) = (x0 as f32 / iw, y0 as f32 / ih);
482 let (x1, y1) = ((x1 as f32 / iw).min(1.0), (y1 as f32 / ih).min(1.0));
483 out.push(OcrLine {
484 text: words.join(" "),
485 rect: OcrRect {
486 x: x0,
487 y: y0,
488 width: (x1 - x0).max(0.0),
489 height: (y1 - y0).max(0.0),
490 },
491 confidence: (conf_ok && conf_n > 0).then(|| conf_sum / conf_n as f32),
492 });
493 }
494 Ok(out)
495 }
496
497 fn detect(&mut self, img: &RgbImage) -> Result<Vec<BBox>, String> {
511 let (orig_w, orig_h) = (img.width(), img.height());
512
513 let ws = if orig_w > DET_MAX_W {
515 DET_MAX_W as f32 / orig_w as f32
516 } else {
517 1.0
518 };
519 let work = if ws < 1.0 {
520 let nh = ((orig_h as f32 * ws).round() as u32).max(1);
521 imageops::resize(img, DET_MAX_W, nh, imageops::FilterType::Lanczos3)
522 } else {
523 img.clone()
524 };
525 let (work_w, work_h) = (work.width(), work.height());
526
527 let mut bands: Vec<(u32, u32)> = Vec::new();
530 if work_h <= DET_TILE_H {
531 bands.push((0, work_h));
532 } else {
533 let step = DET_TILE_H - DET_BAND_OVERLAP;
534 let mut y = 0u32;
535 loop {
536 let end = (y + DET_TILE_H).min(work_h);
537 bands.push((y, end));
538 if end >= work_h {
539 break;
540 }
541 y += step;
542 }
543 }
544
545 let mut all: Vec<BBox> = Vec::new();
546 for (ys, ye) in bands {
547 let band = imageops::crop_imm(&work, 0, ys, work_w, ye - ys).to_image();
548 for mut b in self.detect_one(&band)? {
549 b.y0 += ys;
550 b.y1 += ys;
551 all.push(b);
552 }
553 }
554
555 if ws < 1.0 {
557 let inv = 1.0 / ws;
558 for b in all.iter_mut() {
559 b.x0 = (b.x0 as f32 * inv) as u32;
560 b.y0 = (b.y0 as f32 * inv) as u32;
561 b.x1 = ((b.x1 as f32 * inv) as u32).min(orig_w);
562 b.y1 = ((b.y1 as f32 * inv) as u32).min(orig_h);
563 }
564 }
565
566 let mut boxes = dedup_boxes(all);
567 boxes.sort_by(|a, b| a.y0.cmp(&b.y0).then(a.x0.cmp(&b.x0)));
568 Ok(boxes)
569 }
570
571 fn detect_one(&mut self, band: &RgbImage) -> Result<Vec<BBox>, String> {
573 let (bw, bh) = (band.width(), band.height());
574 let (net_w, net_h) = det_net_size(bw, bh);
575 let resized = imageops::resize(band, net_w, net_h, imageops::FilterType::Lanczos3);
576
577 let data = det_chw_data(&resized, net_w, net_h);
578 let shape = [1i64, 3, net_h as i64, net_w as i64];
579 let tensor =
580 Tensor::<f32>::from_array((shape, data)).map_err(|e| format!("det tensor: {e}"))?;
581
582 let outputs = self
583 .det
584 .run(ort::inputs![tensor])
585 .map_err(|e| format!("det run: {e}"))?;
586
587 let (out_shape, prob_flat) = outputs[0]
589 .try_extract_tensor::<f32>()
590 .map_err(|e| format!("det extract: {e}"))?;
591 let dims: &[i64] = out_shape;
593 let (oh, ow) = match dims {
594 [_, _, h, w] => (*h as usize, *w as usize),
595 s => return Err(format!("unexpected det output shape: {s:?}")),
596 };
597 let prob_2d: &[f32] = &prob_flat[0..oh * ow];
598
599 let scale_x = bw as f32 / ow as f32;
601 let scale_y = bh as f32 / oh as f32;
602 Ok(extract_boxes(
603 prob_2d, ow, oh, scale_x, scale_y, 0.3, bw, bh,
604 ))
605 }
606
607 fn recognize(&mut self, crop: &RgbImage) -> Result<(String, Option<f32>), String> {
612 let (h, w) = (crop.height(), crop.width());
613 let new_w = ((48.0 / h as f32) * w as f32).max(4.0) as u32;
614 let strip = imageops::resize(crop, new_w, 48, imageops::FilterType::Lanczos3);
615
616 let data = rec_chw_data(&strip, new_w);
617 let shape = [1i64, 3, 48, new_w as i64];
618 let tensor =
619 Tensor::<f32>::from_array((shape, data)).map_err(|e| format!("rec tensor: {e}"))?;
620
621 let outputs = self
622 .rec
623 .run(ort::inputs![tensor])
624 .map_err(|e| format!("rec run: {e}"))?;
625
626 let (out_shape, logits_flat) = outputs[0]
628 .try_extract_tensor::<f32>()
629 .map_err(|e| format!("rec extract: {e}"))?;
630 let dims: &[i64] = out_shape;
632 let (t_len, vocab_size) = match dims {
633 [_, t, v] => (*t as usize, *v as usize),
634 s => return Err(format!("unexpected rec output shape: {s:?}")),
635 };
636 let logits = &logits_flat[0..t_len * vocab_size];
638
639 Ok(ctc_greedy_decode_scored(
640 logits,
641 t_len,
642 vocab_size,
643 &self.vocab,
644 ))
645 }
646}
647
648