RustO! 🦀

Pure Rust OCR Library - Fast, Safe, and Cross-Platform

RustO! is a high-performance OCR (Optical Character Recognition) library written in pure Rust, based on RapidOCR and powered by PaddleOCR models with MNN inference engine.

🎯 Why RustO!?

🚀 Pure Rust - Zero OpenCV dependency, optional OpenCV backend available
🎯 High Accuracy - 99.3% parity with OpenCV-based implementations
⚡ Fast Performance - Optimized with LTO, single codegen unit compilation
🔒 Memory Safe - Leverages Rust's safety guarantees
🌐 Cross-Platform - Linux, macOS, Windows, iOS, Android support
🔧 FFI Ready - C FFI bindings for integration with other languages
📦 Easy to Use - Simple API, modern CLI with JSON/Text/TSV output

🏗️ Architecture

RustO! is built on top of proven OCR technology:

Based on: RapidOCR architecture
Models: PaddleOCR PPOCRv4/v5 models
Inference: MNN inference engine for high-performance cross-platform execution
Image Processing: Pure Rust implementation (image + imageproc crates)
Contour Detection: Custom Rust implementation matching OpenCV behavior

📁 Project Structure

rusto-rs/
├── src/
│   ├── lib.rs          # Public API
│   ├── main.rs         # CLI application
│   ├── ffi.rs          # C FFI bindings (optional)
│   ├── det.rs          # Text detection
│   ├── rec.rs          # Text recognition
│   ├── layout.rs       # Layout detection
│   ├── doc_pipeline.rs # Document pipeline (layout + OCR)
│   ├── preprocess.rs   # Image preprocessing
│   ├── postprocess.rs  # Result postprocessing
│   ├── contours.rs     # Pure Rust contour detection
│   ├── geometry.rs     # Geometric transformations + NMS
│   ├── image_impl.rs   # Image abstraction layer
│   └── ...
├── Cargo.toml          # Dependencies & optimization
├── docs/               # Documentation
├── examples/           # Example applications
│   ├── doc_pipeline_demo.rs  # Document pipeline example
│   └── ...
└── packages/           # Additional packages

Model Conversion

RustO! uses MNN inference engine. You need to convert PaddleOCR models to MNN format:

# Install required tools
pip install paddle2onnx
# Download and build MNN from https://github.com/alibaba/MNN

# Convert models using the provided script
python convert_paddle_to_mnn.py --ocr-dir ./models

See MODEL_CONVERSION.md for detailed conversion instructions.

Quick Start

1. Build the Library

# Pure Rust build (default)
cargo build --release

# With FFI bindings
cargo build --release --features ffi

# With OpenCV backend (optional)
cargo build --release --features use-opencv

2. Run CLI Application

# JSON output (default)
cargo run --release -- \
  --det-model path/to/det.mnn \
  --rec-model path/to/rec.mnn \
  --dict path/to/dict.txt \
  image.jpg

# Plain text output
cargo run --release -- \
  --det-model path/to/det.mnn \
  --rec-model path/to/rec.mnn \
  --dict path/to/dict.txt \
  --format text \
  image.jpg

# TSV output
cargo run --release -- \
  --det-model path/to/det.mnn \
  --rec-model path/to/rec.mnn \
  --dict path/to/dict.txt \
  --format tsv \
  image.jpg

3. Use as a Library

Add to your Cargo.toml:

[dependencies]
rusto = "0.1"

Then in your code:

use rusto::{RapidOCR, RapidOCRConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure OCR
    let config = RapidOCRConfig {
        det_model_path: "models/det.mnn".to_string(),
        rec_model_path: "models/rec.mnn".to_string(),
        dict_path: "models/dict.txt".to_string(),
    };
    
    // Create OCR instance
    let ocr = RapidOCR::new(config)?;
    
    // Run OCR on an image
    let results = ocr.ocr("image.jpg")?;
    
    // Process results
    for result in results {
        println!("Text: {}, Score: {:.3}", result.text, result.score);
        println!("Box: {:?}", result.box_points);
    }
    
    Ok(())
}

4. Document Pipeline (Layout + OCR)

RustO! now supports document layout analysis combined with OCR for structured document processing:

use rusto::{DocPipeline, DocPipelineConfig, LayoutConfig, RustOConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure layout detection
    let layout_config = LayoutConfig::default("models/DocOCR/layout.mnn".into());
    
    // Configure OCR
    let ocr_config = RustOConfig::new_ppv5(
        "models/det.mnn".into(),
        "models/rec.mnn".into(),
        "models/dict.txt".into(),
    );
    
    // Create document pipeline
    let config = DocPipelineConfig {
        layout: layout_config,
        ocr: ocr_config,
    };
    
    let mut pipeline = DocPipeline::new(config)?;
    let result = pipeline.run("document.jpg")?;
    
    // Generate markdown output
    println!("{}", result.to_markdown());
    
    Ok(())
}

Supported Layout Elements:

Text, Title, Header, Footer
Figure, Figure Caption
Table, Table Caption
Reference, Equation

Example:

cargo run --example doc_pipeline_demo -- \
  --image document.jpg \
  --layout-model models/DocOCR/layout.mnn \
  --det-model models/det.mnn \
  --rec-model models/rec.mnn \
  --keys-path models/dict.txt

5. iOS Integration

Install via CocoaPods:

pod 'RustO', '~> 0.1'

Then in Swift:

import RustO

let ocr = try RapidOCR(
    detModelPath: Bundle.main.path(forResource: "det", ofType: "mnn")!,
    recModelPath: Bundle.main.path(forResource: "rec", ofType: "mnn")!,
    dictPath: Bundle.main.path(forResource: "dict", ofType: "txt")!
)

let results = try ocr.recognizeFile("image.jpg")
for result in results {
    print("\(result.text): \(result.score)")
}

API Reference

RapidOCRConfig

Configuration structure for initializing the OCR engine.

pub struct RapidOCRConfig {
    pub det_model_path: String,  // Path to detection MNN model
    pub rec_model_path: String,  // Path to recognition MNN model
    pub dict_path: String,       // Path to character dictionary
}

TextResult

OCR result for a single detected text region.

pub struct TextResult {
    pub text: String,                    // Recognized text
    pub score: f32,                      // Confidence score (0.0-1.0)
    pub box_points: [(f32, f32); 4],    // Bounding box corners
}

RapidOCR

Main OCR engine.

impl RapidOCR {
    // Create a new OCR instance
    pub fn new(config: RapidOCRConfig) -> Result<Self, EngineError>;
    
    // Run OCR on an image file
    pub fn ocr<P: AsRef<Path>>(&self, image_path: P) -> Result<Vec<TextResult>, EngineError>;
    
    // Run OCR on image data in memory
    pub fn ocr_from_bytes(&self, image_data: &[u8]) -> Result<Vec<TextResult>, EngineError>;
}

FFI Bindings

The library includes C FFI bindings for integration with other languages. Enable with the ffi feature:

cargo build --release --features ffi

This produces:

Linux: librusto.so
macOS: librusto.dylib
Windows: rusto.dll

See src/ffi.rs for the complete FFI API documentation.

📦 Models

RustO! uses PaddleOCR models converted to ONNX format:

Supported Models

PPOCRv4 - PaddleOCR version 4 models
PPOCRv5 - PaddleOCR version 5 models (recommended)

Model Components

Detection Model (det.onnx) - Detects text regions in images
Recognition Model (rec.onnx) - Recognizes text within detected regions
Dictionary (dict.txt) - Character dictionary for text recognition

Download Models

# Example: Download PPOCRv5 models
wget https://github.com/RapidAI/RapidOCR/releases/download/v1.3.0/det.onnx
wget https://github.com/RapidAI/RapidOCR/releases/download/v1.3.0/rec.onnx
wget https://github.com/RapidAI/RapidOCR/releases/download/v1.3.0/dict.txt

⚡ Performance

Benchmarks

Tested on typical document images:

Metric	Value
Detection	~80ms
Recognition (per box)	~120ms
Total (28 boxes)	~3.5s
Memory Peak	~200MB

Comparison with OpenCV-based implementations

Aspect	RustO!	OpenCV-based
Speed	✅ Similar (±10%)	Baseline
Accuracy	✅ 99.3% parity	100%
Binary Size	✅ Smaller	Larger (OpenCV deps)
Memory Usage	✅ Lower	Higher (OpenCV overhead)
Dependencies	✅ Minimal	OpenCV required
Safety	✅ Memory safe	Manual memory management

Configuration

Cargo Features

[features]
default = []           # Pure Rust mode
use-opencv = ["opencv"] # Use OpenCV backend
ffi = []               # Enable C FFI bindings

Build Profiles

[profile.release]
opt-level = 3          # Maximum optimization
lto = "fat"            # Link-time optimization
codegen-units = 1      # Single codegen unit for better optimization
strip = true           # Strip symbols
panic = "abort"        # Smaller binary

Development

Run Tests

cd rapidocr
cargo test
cargo test --features use-opencv  # Test OpenCV backend

Run Benchmarks

cargo bench

Check Code

cargo clippy
cargo fmt --check

Known Issues

Rust Library (contours.rs)

⚠️ Unused functions (400+ lines) - cleanup pending
⚠️ Minor lint warnings - non-blocking

Remaining Parity Gap (0.7%)

2 minor text differences out of 28 boxes
Caused by: Spacing ("Gol. Darah:" vs "Gol. Darah :")
Impact: Negligible for production use

License

MIT (or your license)

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests: cargo test
Submit a pull request

Support

📧 Email: support@rapidocr.com
💬 Discussions: GitHub Discussions
🐛 Issues: GitHub Issues

🙏 Acknowledgments

RustO! builds upon the excellent work of:

RapidOCR - Architecture and design inspiration
PaddleOCR - State-of-the-art OCR models (PPOCRv4/v5)
ONNX Runtime - Cross-platform inference engine
Rust Community - Excellent tooling and libraries (image, imageproc, nalgebra)

📝 Citation

If you use RustO! in your research or project, please cite:

@software{rusto2024,
  title = {RustO! - Pure Rust OCR Library},
  author = {byrizki},
  year = {2024},
  url = {https://github.com/byrizki/rusto-rs},
  note = {Based on RapidOCR and powered by PaddleOCR models}
}

Also consider citing the underlying technologies:

PaddleOCR: https://github.com/PaddlePaddle/PaddleOCR
RapidOCR: https://github.com/RapidAI/RapidOCR

Status: Production Ready 🚀
Version: 0.1.2
License: MIT

Made with ❤️ and 🦀 Rust

Report Bug · Request Feature · Contribute

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.cargo		.cargo
.github/workflows		.github/workflows
crates		crates
examples		examples
models		models
packages		packages
src		src
vendor		vendor
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
check_ops.py		check_ops.py
convert_paddle_to_mnn.py		convert_paddle_to_mnn.py
create_test_images.py		create_test_images.py
debug_ocr.py		debug_ocr.py
lefthook.yml		lefthook.yml
raw_to_csv.py		raw_to_csv.py
test_paddleocr.py		test_paddleocr.py
test_preprocess.py		test_preprocess.py

License

byrizki/rusto-rs

Folders and files

Latest commit

History

Repository files navigation

RustO! 🦀

🎯 Why RustO!?

🏗️ Architecture

📁 Project Structure

Model Conversion

Quick Start

1. Build the Library

2. Run CLI Application

3. Use as a Library

4. Document Pipeline (Layout + OCR)

5. iOS Integration

API Reference

RapidOCRConfig

TextResult

RapidOCR

FFI Bindings

📦 Models

Supported Models

Model Components

Download Models

⚡ Performance

Benchmarks

Comparison with OpenCV-based implementations

Configuration

Cargo Features

Build Profiles

Development

Run Tests

Run Benchmarks

Check Code

Known Issues

Rust Library (contours.rs)

Remaining Parity Gap (0.7%)

License

Contributing

Support

🙏 Acknowledgments

📝 Citation

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages