uni-ocr

To perform basic OCR, initialize an OcrEngine with OcrProvider::Auto to automatically detect the best available provider on your system, then use recognize_file to extract text from an image path.

use uniocr::{OcrEngine, OcrProvider};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // auto-detect best available provider
    let engine = OcrEngine::new(OcrProvider::Auto)?;
    
    // perform ocr on an image
    let text = engine.recognize_file("path/to/image.png").await?;
    println!("extracted text: {}", text);
    
    Ok(())
}

The repository contains several example programs that you can run using cargo run. These demonstrate different use cases like batch processing and custom options:

# basic example
cargo run --example basic

# batch processing
cargo run --example batch_processing

# custom options
cargo run --example custom_options

# platform specific
cargo run --example platform_specific

If you intend to use OcrProvider::Tesseract, you must install the tesseract-ocr binary on your operating system:

macOS

brew install tesseract

Ubuntu

apt-get install tesseract-ocr

Windows

winget install tesseract

To use uni-ocr in your Rust project, add it to your Cargo.toml dependencies. You can pull it directly from the GitHub repository:

[dependencies]
uni-ocr = { git = "https://github.com/mediar-ai/uniocr.git" }

You can fine-tune OCR behavior using OcrOptions. This allows you to set supported languages, confidence thresholds, and timeouts. Use .with_options(options) on the OcrEngine to apply these settings. For processing multiple images efficiently, use recognize_batch.

use uni_ocr::{OcrEngine, OcrProvider, OcrOptions};

// configure ocr options
let options = OcrOptions::default()
    .languages(vec!["eng", "fra"])
    .confidence_threshold(0.8)
    .timeout(std::time::Duration::from_secs(30));

let engine = OcrEngine::new(OcrProvider::Auto)?
    .with_options(options);

// batch processing
let images = vec!["img1.png", "img2.png", "img3.png"];
let results = engine.recognize_batch(images).await?;

When using a custom OCR provider, you must provide a Credentials object to specify the connection details.

Fields:

• api_url: The endpoint URL for the OCR service (defaults to http://localhost:8000/ocr).
• api_key: The bearer token used for authorization.
• timeout_ms: The request timeout in milliseconds (defaults to 5000).

// Example of manual Credentials construction
let credentials = Credentials {
    api_url: "https://your-ocr-service.com/ocr".to_string(),
    api_key: "your_secret_token".to_string(),
    timeout_ms: 10000,
};

The OcrProvider enum allows you to specify which engine to use for text recognition. Supported providers include:

• OcrProvider::Auto: Automatically selects the best available provider for the current platform.
• OcrProvider::MacOS: Uses the native macOS Vision Kit API.
• OcrProvider::Windows: Uses the native Windows OCR engine.
• OcrProvider::Tesseract: Uses the Tesseract OCR engine (requires tesseract-ocr to be installed on the system).
• OcrProvider::GoogleCloud: Uses Google Cloud Vision (requires credentials).

// use native macos vision
let engine = OcrEngine::new(OcrProvider::MacOS)?;

// use windows ocr
let engine = OcrEngine::new(OcrProvider::Windows)?;

// use tesseract
let engine = OcrEngine::new(OcrProvider::Tesseract)?;

// use google cloud vision
// let engine = OcrEngine::new(OcrProvider::GoogleCloud {
//     credentials: ..., 
// })?;

The perform_ocr_custom function allows you to send a DynamicImage to a custom remote OCR endpoint.

Request Payload: The function automatically converts the image to a base64-encoded JPEG and sends a JSON payload containing:

• image: The base64 string of the JPEG image.
• languages: A list of language strings.

Authentication: It uses the Authorization: Bearer <api_key> header.

Returns: A Result containing a tuple of (String, String, Option<f64>) representing:

1. The extracted text.
2. The structured data (as a JSON string).
3. The confidence score (optional).

// Example usage of perform_ocr_custom
let result = perform_ocr_custom(
    &image,
    vec![Language::English],
    &credentials,
).await?;

let (text, structured_data, confidence) = result;

OcrOptions allows you to fine-tune the OCR process. It implements Default, which sets the language to English, a confidence_threshold of 0.0, and a timeout of 30 seconds.

You can customize these settings using the following builder methods:

• .languages(langs: Vec<Language>): Sets the list of languages to be used during recognition.
• .confidence_threshold(threshold: f32): Sets the minimum confidence score required.
• .timeout(timeout: Duration): Sets the maximum duration to wait for the OCR operation to complete.

use uniocr::OcrOptions;
use std::time::Duration;

let options = OcrOptions::default()
    .languages(vec![Language::English, Language::French])
    .confidence_threshold(0.5)
    .timeout(Duration::from_secs(10));

The OcrProvider enum determines which OCR engine is used by the OcrEngine.