Rust PaddleOCR

https://github.com/zibo-chen/rust-paddle-ocr
Admin
A lightweight, efficient, and pure Rust OCR library based on PaddleOCR models, offering...
Tokens:6,740
Snippets:68
Trust Score:7.1
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### Use Pre-built MNN Static Library

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Build the project using a pre-built MNN static library. Ensure MNN_LIB_DIR and MNN_INCLUDE_DIR environment variables are set correctly.

```bash
MNN_LIB_DIR=/path/to/mnn/lib MNN_INCLUDE_DIR=/path/to/mnn/include \
  cargo build --features mnn-static
```

--------------------------------

### Use Pre-built MNN Dynamic Library

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Build the project using a pre-built MNN dynamic library. Ensure MNN_LIB_DIR and MNN_INCLUDE_DIR environment variables are set correctly.

```bash
MNN_LIB_DIR=/path/to/mnn/lib MNN_INCLUDE_DIR=/path/to/mnn/include \
  cargo build --features mnn-dynamic
```

--------------------------------

### Force MNN Build from Source

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use this command to force the build system to compile MNN from source, which is useful if you need custom MNN build options like GPU acceleration.

```bash
cargo build --features build-mnn-from-source
```

--------------------------------

### Basic OCR Engine Configuration

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Initialize the OcrEngine with a fast mode configuration. Ensure the model and charset paths are correct.

```rust
use ocr_rs::{OcrEngine, OcrEngineConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Use fast mode configuration
    let config = OcrEngineConfig::fast();
    
    let engine = OcrEngine::new(
        "models/PP-OCRv5_mobile_det.mnn",
        "models/PP-OCRv5_mobile_rec.mnn",
        "models/ppocr_keys_v5.txt",
        Some(config),
    )?;
    
    let image = image::open("test.jpg")?;
    let results = engine.recognize(&image)?;
    
    Ok(())
}
```

--------------------------------

### Scenario 1: Quick OCR Integration

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use the `OcrEngine` for end-to-end recognition. This is suitable for rapid prototyping and simple document recognition needs where only the final text result is required.

```APIDOC
## Scenario 1: Quick OCR Integration

### Description
Use the `OcrEngine` for end-to-end recognition. This is suitable for rapid prototyping and simple document recognition needs where only the final text result is required.

### Method Signature
```rust
OcrEngine::new(det_path: &str, rec_path: &str, charset_path: &str, use_gpu: Option<bool>) -> Result<OcrEngine, Box<dyn std::error::Error>>
```

### Usage Example
```rust
let engine = OcrEngine::new(det_path, rec_path, charset_path, None)?;
let results = engine.recognize(&image)?;
```
```

--------------------------------

### Use Specific Language Models in Rust

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Initialize the OcrEngine with specific language models for detection, recognition, and character sets. Ensure the model paths are correct.

```rust
use ocr_rs::OcrEngine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Use Korean model
    let engine = OcrEngine::new(
        "models/PP-OCRv5_mobile_det.mnn",
        "models/korean_PP-OCRv5_mobile_rec_infer.mnn",
        "models/ppocr_keys_korean.txt",
        None,
    )?;
    
    let image = image::open("korean_text.jpg")?;
    let results = engine.recognize(&image)?;
    
    for result in results {
        println!("{}: {:.2}%", result.text, result.confidence * 100.0);
    }
    
    Ok(())
}
```

--------------------------------

### End-to-End Recognition (Recommended)

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

This is the simplest way to use the OCR engine, performing both detection and recognition in a single call. It's recommended for most use cases.

```APIDOC
## End-to-End Recognition (Recommended)

### Description
Use `OcrEngine` to complete the full OCR process with a single call.

### Method
`OcrEngine::new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use ocr_rs::OcrEngine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create OCR engine (using default config)
    let engine = OcrEngine::new(
        "models/PP-OCRv5_mobile_det.mnn",
        "models/PP-OCRv5_mobile_rec.mnn",
        "models/ppocr_keys_v5.txt",
        None,
    )?;
    
    // Load image
    let image = image::open("test.jpg")?;
    
    // Perform detection and recognition in one call
    let results = engine.recognize(&image)?;
    
    // Output results
    for result in results {
        println!("Text: {}", result.text);
        println!("Confidence: {:.2}%", result.confidence * 100.0);
        println!("Position: ({}, {})", result.bbox.rect.left(), result.bbox.rect.top());
    }
    
    Ok(())
}
```

### Response
#### Success Response (200)
- `results` (Vec<OcrResult>) - A vector of OCR results, each containing text, confidence, and bounding box information.

#### Response Example
```json
[
  {
    "text": "example text",
    "confidence": 0.95,
    "bbox": {
      "rect": {
        "left": 100,
        "top": 50,
        "width": 200,
        "height": 30
      }
    }
  }
]
```
```

--------------------------------

### Quick OCR Integration with OcrEngine

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use this for rapid prototyping or simple document recognition needs where only the final text result is required. No intermediate processing is necessary.

```rust
let engine = OcrEngine::new(det_path, rec_path, charset_path, None)?;
let results = engine.recognize(&image)?;
```

--------------------------------

### Scenario 4: Recognition Only

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Utilize the `RecOnlyEngine` when text location is already known and only recognition is needed. This is ideal for processing pre-cropped text line images or for batch recognition of fixed-format text.

```APIDOC
## Scenario 4: Recognition Only

### Description
Utilize the `RecOnlyEngine` when text location is already known and only recognition is needed. This is ideal for processing pre-cropped text line images or for batch recognition of fixed-format text.

### Method Signature
```rust
OcrEngine::rec_only(rec_path: &str, charset_path: &str, use_gpu: Option<bool>) -> Result<OcrEngine, Box<dyn std::error::Error>>
```

### Usage Example
```rust
let rec_engine = OcrEngine::rec_only("models/rec_model.mnn", "models/ppocr_keys.txt", None)?;
let text = rec_engine.recognize_text(&text_line_image)?;
```
```

--------------------------------

### End-to-End OCR Recognition with OcrEngine

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

This is the recommended and simplest way to perform OCR. It uses the OcrEngine to handle both detection and recognition in a single call. Ensure you have the necessary model files and character set file.

```rust
use ocr_rs::OcrEngine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create OCR engine (using default config)
    let engine = OcrEngine::new(
        "models/PP-OCRv5_mobile_det.mnn",
        "models/PP-OCRv5_mobile_rec.mnn",
        "models/ppocr_keys_v5.txt",
        None,
    )?;
    
    // Load image
    let image = image::open("test.jpg")?;
    
    // Perform detection and recognition in one call
    let results = engine.recognize(&image)?;
    
    // Output results
    for result in results {
        println!("Text: {}", result.text);
        println!("Confidence: {:.2}%", result.confidence * 100.0);
        println!("Position: ({}, {})", result.bbox.rect.left(), result.bbox.rect.top());
    }
    
    Ok(())
}
```

--------------------------------

### Load from Bytes

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

This scenario is suitable for embedded devices, model encryption, dynamic model downloading, and custom model storage formats by loading models directly from byte arrays.

```APIDOC
## Scenario 6: Embedded or Encrypted Deployment

### Description
Load models directly from byte arrays using `OcrEngine::from_bytes`.

### Method
`OcrEngine::from_bytes`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let det_bytes = include_bytes!("../models/det_model.mnn");
let rec_bytes = include_bytes!("../models/rec_model.mnn");
let charset_bytes = include_bytes!("../models/ppocr_keys.txt");

let engine = OcrEngine::from_bytes(det_bytes, rec_bytes, charset_bytes, None)?;
```

### Response
#### Success Response (200)
- `engine` (`OcrEngine`) - An initialized OCR engine loaded from byte data.

#### Response Example
None provided in source.
```

--------------------------------

### Document Orientation Model Builder

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use OcrEngineBuilder to construct an OcrEngine with a document orientation model. This is useful for automatically correcting document skew.

```rust
use ocr_rs::OcrEngineBuilder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = OcrEngineBuilder::new()
        .with_det_model_path("models/PP-OCRv5_mobile_det.mnn")
        .with_rec_model_path("models/PP-OCRv5_mobile_rec.mnn")
        .with_charset_path("models/ppocr_keys_v5.txt")
        .with_ori_model_path("models/PP-LCNet_x1_0_doc_ori.mnn")
        .build()?;

    Ok(())
}
```

--------------------------------

### Configure Fast OCR in Rust

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Set the OcrEngine to use fast, real-time processing mode by creating a configuration with `OcrEngineConfig::fast()`.

```rust
// Real-time processing
let config = OcrEngineConfig::fast();
```

--------------------------------

### Custom Detection and Recognition Parameters

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Configure OcrEngine with custom detection and recognition options, including threads, resolution, thresholds, merging, confidence scores, and batch size.

```rust
use ocr_rs::{OcrEngine, OcrEngineConfig, DetOptions, RecOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Custom configuration
    let config = OcrEngineConfig::new()
        .with_threads(8)
        .with_det_options(
            DetOptions::new()
                .with_max_side_len(1920)     // Higher detection resolution
                .with_box_threshold(0.6)     // Stricter bounding box threshold
                .with_merge_boxes(true)      // Merge adjacent text boxes
        )
        .with_rec_options(
            RecOptions::new()
                .with_min_score(0.5)         // Filter low confidence results
                .with_batch_size(16)         // Batch recognition size
        );
    
    let engine = OcrEngine::new(det_path, rec_path, charset_path, Some(config))?;
    
    Ok(())
}
```

--------------------------------

### Load Independent Detection and Recognition Models

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use this when you need custom pre-processing, different configurations for detection and recognition, or to insert complex logic between these steps. It allows for independent loading of detection and recognition models.

```rust
let det_model = DetModel::from_file("models/det_model.mnn", None)?;
    
let rec_model = RecModel::from_file(
    "models/rec_model.mnn",
    "models/ppocr_keys.txt",
    None
)?;

// Fully custom processing flow...
```

--------------------------------

### Batch Recognize Text Lines in Rust

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Improve performance by recognizing multiple text lines in a batch using `recognize_batch`. This is significantly faster than processing images individually.

```rust
// Batch recognizing multiple text lines is much faster than one by one
let results = rec_model.recognize_batch(&images)?;
```

--------------------------------

### Add rust-paddle-ocr Dependency to Cargo.toml

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Add this to your Cargo.toml to include the rust-paddle-ocr library. You can specify a specific branch or tag for version control.

```toml
[dependencies.rust-paddle-ocr]
git = "https://github.com/zibo-chen/rust-paddle-ocr.git"
```

```toml
[dependencies.rust-paddle-ocr]
git = "https://github.com/zibo-chen/rust-paddle-ocr.git"
branch = "next"
```

--------------------------------

### Configure GPU Acceleration for OCR in Rust

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Enable GPU acceleration for OCR processing. Use `OcrEngineConfig::gpu()` for macOS/iOS (Metal) or `with_backend(Backend::OpenCL)` for other platforms.

```rust
// macOS/iOS
let config = OcrEngineConfig::gpu();  // Uses Metal

// Other platforms
let config = OcrEngineConfig::new().with_backend(Backend::OpenCL);
```

--------------------------------

### OCR Engine with GPU Acceleration

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Configure the OcrEngine to use GPU acceleration. Select the appropriate backend for your operating system (Metal for macOS, OpenCL or Vulkan for others).

```rust
use ocr_rs::{OcrEngine, OcrEngineConfig, Backend};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Use GPU acceleration
    let config = OcrEngineConfig::new()
        .with_backend(Backend::Metal);    // macOS: Metal
        // .with_backend(Backend::OpenCL); // Cross-platform: OpenCL
        // .with_backend(Backend::Vulkan); // Windows/Linux: Vulkan
    
    let engine = OcrEngine::new(det_path, rec_path, charset_path, Some(config))?;
    
    Ok(())
}
```

--------------------------------

### Perform OCR with Convenience Function in Rust

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Utilize the `ocr_file` convenience function for a streamlined OCR process by providing file paths for the image and models. This function performs recognition in a single step.

```rust
use ocr_rs::ocr_file;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Perform OCR in one line of code
    let results = ocr_file(
        "test.jpg",
        "models/det_model.mnn",
        "models/rec_model.mnn",
        "models/ppocr_keys.txt",
    )?;
    
    for result in results {
        println!("{}", result.text);
    }
    
    Ok(())
}
```

--------------------------------

### Load Models from Bytes for Embedded Deployment

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Suitable for embedded devices, model encryption, or dynamic model loading. This method loads model data directly from byte arrays, allowing models to be compiled into the binary or fetched from network resources.

```rust
let det_bytes = include_bytes!("../models/det_model.mnn");
let rec_bytes = include_bytes!("../models/rec_model.mnn");
let charset_bytes = include_bytes!("../models/ppocr_keys.txt");

let engine = OcrEngine::from_bytes(det_bytes, rec_bytes, charset_bytes, None)?;
```

--------------------------------

### Scenario 2: Custom Post-Processing for Detection

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Utilize `OcrEngine`'s `detect` and `recognize_batch` methods for custom post-processing of detection results. This allows for filtering, adjusting, or reordering detected text boxes before recognition.

```APIDOC
## Scenario 2: Custom Post-Processing for Detection

### Description
Use `OcrEngine`'s `detect` and `recognize_batch` methods for custom post-processing of detection results. This allows for filtering, adjusting, or reordering detected text boxes before recognition.

### Method Signatures
```rust
OcrEngine::new(det_path: &str, rec_path: &str, charset_path: &str, use_gpu: Option<bool>) -> Result<OcrEngine, Box<dyn std::error::Error>>
OcrEngine::detect(&self, image: &Image) -> Result<Vec<DetectionBox>, Box<dyn std::error::Error>>
OcrEngine::det_model(&self) -> &DetModel
DetModel::detect_and_crop(&self, image: &Image) -> Result<Vec<Image>, Box<dyn std::error::Error>>
OcrEngine::recognize_batch(&self, images: &[Image]) -> Result<Vec<String>, Box<dyn std::error::Error>>
```

### Usage Example
```rust
let engine = OcrEngine::new(det_path, rec_path, charset_path, None)?;
// 1. Detect
let mut boxes = engine.detect(&image)?;
// 2. Custom processing (e.g., filter small boxes)
boxes.retain(|b| b.rect.width() > 50);
// 3. Recognize
let detections = engine.det_model().detect_and_crop(&image)?;
let results = engine.recognize_batch(&images)?;
```
```

--------------------------------

### Scenario 3: Detection Only

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Employ the `DetOnlyEngine` when only text detection is required. This is useful for document layout analysis, text region annotation, or as a pre-processing step for other recognition engines.

```APIDOC
## Scenario 3: Detection Only

### Description
Employ the `DetOnlyEngine` when only text detection is required. This is useful for document layout analysis, text region annotation, or as a pre-processing step for other recognition engines.

### Method Signature
```rust
OcrEngine::det_only(det_path: &str, use_gpu: Option<bool>) -> Result<OcrEngine, Box<dyn std::error::Error>>
```

### Usage Example
```rust
let det_engine = OcrEngine::det_only("models/det_model.mnn", None)?;
let text_boxes = det_engine.detect(&image)?;
// Use detection boxes for other processing...
```
```

--------------------------------

### Recognition Only with RecOnlyEngine

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Ideal when text location is already known and only recognition is needed. This is useful for processing pre-cropped images or for handwriting recognition.

```rust
let rec_engine = OcrEngine::rec_only(
    "models/rec_model.mnn",
    "models/ppocr_keys.txt",
    None
)?;
let text = rec_engine.recognize_text(&text_line_image)?;
```

--------------------------------

### Independent Model Calls for Maximum Flexibility

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Create detection and recognition models independently or use single-function engines. This offers the most flexibility for complex workflows.

```rust
use ocr_rs::{DetModel, RecModel, DetOptions, RecOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Method A: Create detection and recognition models separately
    let det_model = DetModel::from_file("models/det_model.mnn", None)?;
    
    let rec_model = RecModel::from_file(
        "models/rec_model.mnn",
        "models/ppocr_keys.txt",
        None
    )?.with_options(RecOptions::new().with_min_score(0.5));
    
    let image = image::open("test.jpg")?;
    
    // Detect and crop
    let detections = det_model.detect_and_crop(&image)?;
    
    // Batch recognize
    let images: Vec<_> = detections.iter().map(|(img, _)| img.clone()).collect();
    let results = rec_model.recognize_batch(&images)?;
    
    // Process results...
    
    // Method B: Create detection-only engine
    let det_only = OcrEngine::det_only("models/det_model.mnn", None)?;
    let text_boxes = det_only.detect(&image)?;
    
    // Method C: Create recognition-only engine
    let rec_only = OcrEngine::rec_only(
        "models/rec_model.mnn",
        "models/ppocr_keys.txt",
        None
    )?;
    let text = rec_only.recognize_text(&cropped_image)?;
    
    Ok(())
}
```

--------------------------------

### Load Models from Memory Bytes in Rust

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Load OCR models directly from byte arrays, which is useful for embedded systems or encrypted models. Ensure model files are read into byte vectors.

```rust
use ocr_rs::OcrEngine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Read model bytes from file (or other sources)
    let det_bytes = std::fs::read("models/det_model.mnn")?;
    let rec_bytes = std::fs::read("models/rec_model.mnn")?;
    let charset_bytes = std::fs::read("models/ppocr_keys.txt")?;
    
    // Create engine from bytes
    let engine = OcrEngine::from_bytes(
        &det_bytes,
        &rec_bytes,
        &charset_bytes,
        None,
    )?;
    
    let image = image::open("test.jpg")?;
    let results = engine.recognize(&image)?;
    
    Ok(())
}
```

--------------------------------

### Custom Post-Processing for Detection with OcrEngine

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Suitable for scenarios requiring filtering, adjusting, or sorting detection results before recognition. This involves custom processing of detected boxes.

```rust
let engine = OcrEngine::new(det_path, rec_path, charset_path, None)?;
// 1. Detect
let mut boxes = engine.detect(&image)?;
// 2. Custom processing (e.g., filter small boxes)
boxes.retain(|b| b.rect.width() > 50);
// 3. Recognize
let detections = engine.det_model().detect_and_crop(&image)?;
let results = engine.recognize_batch(&images)?;
```

--------------------------------

### Layered OCR Calls with Custom Processing

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use OcrEngine to call detection and recognition separately. This allows for custom processing between steps, such as filtering or sorting detected text regions.

```rust
use ocr_rs::OcrEngine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = OcrEngine::new(det_path, rec_path, charset_path, None)?;
    let image = image::open("test.jpg")?;
    
    // 1. Detection only first
    let text_boxes = engine.detect(&image)?;
    println!("Detected {} text regions", text_boxes.len());
    
    // Custom processing can be done here, e.g.:
    // - Filter unwanted regions
    // - Adjust box positions
    // - Sort by position, etc. 
    
    // 2. Get detection model and manually crop
    let det_model = engine.det_model();
    let detections = det_model.detect_and_crop(&image)?;
    
    // 3. Batch recognize cropped images
    let cropped_images: Vec<_> = detections.iter()
        .map(|(img, _)| img.clone())
        .collect();
    let rec_results = engine.recognize_batch(&cropped_images)?;
    
    for (result, (_, bbox)) in rec_results.iter().zip(detections.iter()) {
        println!("{}: {:.2}%", result.text, result.confidence * 100.0);
    }
    
    Ok(())
}
```

--------------------------------

### Independent Models (`DetModel` + `RecModel`)

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

This scenario is suitable for custom pre-processing workflows, different configurations for detection and recognition, inserting complex logic between detection and recognition, and performance optimization.

```APIDOC
## Scenario 5: Fully Custom Workflow

### Description
Use independent `DetModel` and `RecModel` for custom processing flows.

### Method
`DetModel::from_file` and `RecModel::from_file`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let det_model = DetModel::from_file("models/det_model.mnn", None)?;
    
let rec_model = RecModel::from_file(
    "models/rec_model.mnn",
    "models/ppocr_keys.txt",
    None
)?;

// Fully custom processing flow...
```

### Response
#### Success Response (200)
- `det_model` (`DetModel`) - An instance of the text detection model.
- `rec_model` (`RecModel`) - An instance of the text recognition model.

#### Response Example
None provided in source.
```

--------------------------------

### Detection Only with DetOnlyEngine

Source: https://github.com/zibo-chen/rust-paddle-ocr/blob/next/README.md

Use this when only text region locations are needed, such as for document layout analysis or text annotation tools. It can be used with other recognition engines.

```rust
let det_engine = OcrEngine::det_only("models/det_model.mnn", None)?;
let text_boxes = det_engine.detect(&image)?;
// Use detection boxes for other processing...
```
Tokens:
Raw