ocr_rs/
lib.rs

1//! # Rust PaddleOCR
2//!
3//! A high-performance OCR library based on PaddleOCR models, using the MNN inference framework.
4//!
5//! ## Version 2.0 New Features
6//!
7//! - **New API Design**: Complete layered API from low-level models to high-level pipeline
8//! - **Flexible Model Loading**: Support loading models from file paths or memory bytes
9//! - **Configurable Detection Parameters**: Support custom detection thresholds, resolution, etc.
10//! - **GPU Acceleration**: Support multiple GPU backends including Metal, OpenCL, Vulkan
11//! - **Batch Processing**: Support batch text recognition for improved throughput
12//!
13//! ## Quick Start
14//!
15//! ### Simple Usage - Using High-Level API (Recommended)
16//!
17//! ```ignore
18//! use ocr_rs::{OcrEngine, OcrEngineConfig};
19//!
20//! fn main() -> Result<(), Box<dyn std::error::Error>> {
21//!     // Create OCR engine
22//!     let engine = OcrEngine::new(
23//!         "models/det_model.mnn",
24//!         "models/rec_model.mnn",
25//!         "models/ppocr_keys.txt",
26//!         None, // Use default config
27//!     )?;
28//!
29//!     // Open and recognize image
30//!     let image = image::open("test.jpg")?;
31//!     let results = engine.recognize(&image)?;
32//!
33//!     for result in results {
34//!         println!("Text: {}, Confidence: {:.2}%", result.text, result.confidence * 100.0);
35//!         println!("Position: ({}, {})", result.bbox.rect.left(), result.bbox.rect.top());
36//!     }
37//!
38//!     Ok(())
39//! }
40//! ```
41//!
42//! ### Advanced Usage - Using Low-Level API
43//!
44//! ```ignore
45//! use ocr_rs::{DetModel, RecModel, DetOptions, DetPrecisionMode};
46//!
47//! fn main() -> Result<(), Box<dyn std::error::Error>> {
48//!     // Create detection model
49//!     let det = DetModel::from_file("models/det_model.mnn", None)?
50//!         .with_options(DetOptions::fast());
51//!
52//!     // Create recognition model
53//!     let rec = RecModel::from_file("models/rec_model.mnn", "models/ppocr_keys.txt", None)?;
54//!
55//!     // Load image
56//!     let image = image::open("test.jpg")?;
57//!
58//!     // Detect and crop text regions
59//!     let detections = det.detect_and_crop(&image)?;
60//!
61//!     // Recognize each text region
62//!     for (cropped_img, bbox) in detections {
63//!         let result = rec.recognize(&cropped_img)?;
64//!         println!("Position: ({}, {}), Text: {}",
65//!             bbox.rect.left(), bbox.rect.top(), result.text);
66//!     }
67//!
68//!     Ok(())
69//! }
70//! ```
71//!
72//! ### GPU Acceleration
73//!
74//! ```ignore
75//! use ocr_rs::{OcrEngine, OcrEngineConfig, Backend};
76//!
77//! let config = OcrEngineConfig::new()
78//!     .with_backend(Backend::Metal);  // macOS/iOS
79//!     // .with_backend(Backend::OpenCL);  // Cross-platform
80//!
81//! let engine = OcrEngine::new(det_path, rec_path, charset_path, Some(config))?;
82//! ```
83//!
84//! ## Module Structure
85//!
86//! - [`mnn`]: MNN inference engine wrapper, provides low-level inference capabilities
87//! - [`det`]: Text detection module ([`DetModel`]), detects text regions in images
88//! - [`rec`]: Text recognition module ([`RecModel`]), recognizes text content
89//! - [`engine`]: High-level OCR pipeline ([`OcrEngine`]), all-in-one OCR solution
90//! - [`preprocess`]: Image preprocessing utilities, including normalization, scaling, etc.
91//! - [`postprocess`]: Post-processing utilities, including NMS, box merging, sorting, etc.
92//! - [`error`]: Error types [`OcrError`]
93//!
94//! ## API Hierarchy
95//!
96//! ```text
97//! ┌─────────────────────────────────────────┐
98//! │        OcrEngine (High-Level API)       │
99//! │   Complete detection and recognition    │
100//! ├─────────────────────────────────────────┤
101//! │     DetModel      │      RecModel       │
102//! │  Detection Model  │  Recognition Model  │
103//! ├─────────────────────────────────────────┤
104//! │          InferenceEngine (MNN)          │
105//! │         Low-level inference engine      │
106//! └─────────────────────────────────────────┘
107//! ```
108//!
109//! ## Supported Models
110//!
111//! - **PP-OCRv4**: Stable version, good compatibility
112//! - **PP-OCRv5**: Recommended version, supports multiple languages, higher accuracy
113//! - **PP-OCRv5 FP16**: Efficient version, faster inference, lower memory usage
114
115// Core modules
116pub mod det;
117pub mod engine;
118pub mod error;
119pub mod mnn;
120pub mod postprocess;
121pub mod preprocess;
122pub mod rec;
123mod ori;
124
125// Re-export commonly used types
126pub use det::{DetModel, DetOptions, DetPrecisionMode};
127pub use engine::{
128    ocr_file, DetOnlyEngine, OcrEngine, OcrEngineBuilder, OcrEngineConfig, OcrResult_,
129    RecOnlyEngine,
130};
131pub use error::{OcrError, OcrResult};
132pub use mnn::{Backend, InferenceConfig, InferenceEngine, PrecisionMode};
133pub use postprocess::TextBox;
134pub use ori::{OriModel, OriOptions, OriPreprocessMode, OrientationResult};
135pub use rec::{RecModel, RecOptions, RecognitionResult};
136
137/// Get library version
138pub fn version() -> &'static str {
139    env!("CARGO_PKG_VERSION")
140}
141
142/// Get MNN version
143pub fn mnn_version() -> String {
144    mnn::get_version()
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn test_version() {
153        let v = version();
154        assert!(!v.is_empty());
155    }
156}
ocr_rs/lib.rs

ocr_rs/
lib.rs
