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