oar-ocr

Installation

cargo add oar-ocr

The default build enables ONNX Runtime binary downloads and SIMD acceleration. Add only the optional capabilities needed by your application. For example:

cargo add oar-ocr --features cuda,auto-download

This keeps the default download-binaries and simd features enabled, makes the ONNX Runtime CUDA execution provider available for selection, and downloads missing registered model files from ModelScope into $OAR_HOME when they are first used.

See the Cargo feature guide for all available features and the model guide for model download and cache behavior.

Builders also accept raw ONNX bytes such as include_bytes!, allowing models to be embedded in a single binary. See Loading Models from Memory.

OCR Pipeline

The pp_ocrv6 preset configures a PP-OCRv6 pipeline by model size, filling in the model names, the matching dictionary, and the official detection thresholds. With auto-download, the names resolve through the model registry; without it they resolve as local paths, so nothing changes for offline setups.

use oar_ocr::prelude::*;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ocr = OAROCRBuilder::pp_ocrv6(PpOcrV6Size::Small).build()?;

    let image = load_image(Path::new("document.jpg"))?;
    let results = ocr.predict(vec![image])?;

    for region in &results[0].text_regions {
        if let Some((text, confidence)) = region.text_with_confidence() {
            println!("{text} ({confidence:.2})");
        }
    }

    Ok(())
}

The preset's detection thresholds are defaults, so a text_type like seal still applies its own detection settings, and an explicit text_detection_config overrides everything. Sizes pick the models, the dictionary, and PaddleOCR's per-size box threshold (0.4 for Tiny, 0.45 for Small and Medium): PpOcrV6Size::Tiny runs the fastest pair over its reduced dictionary.

use oar_ocr::prelude::*;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ocr = OAROCRBuilder::pp_ocrv6(PpOcrV6Size::Tiny).build()?;

    let image = load_image(Path::new("document.jpg"))?;
    let results = ocr.predict(vec![image])?;
    for region in &results[0].text_regions {
        if let Some((text, confidence)) = region.text_with_confidence() {
            println!("{text} ({confidence:.2})");
        }
    }

    Ok(())
}

Document Structure Analysis

The pp_structurev3 preset configures the PP-StructureV3-style stack: PP-DocLayoutV3 layout, PP-OCRv6 Tiny text recognition, table classification, SLANeXt wired and SLANet+ wireless table structure, wired cell detection, and the table dictionary.

use oar_ocr::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let structure = OARStructureBuilder::pp_structurev3().build()?;

    let result = structure.predict("document.jpg")?;
    println!("{}", result.to_markdown());

    Ok(())
}

The exact chain the preset expands to, for swapping individual models:

use oar_ocr::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let structure = OARStructureBuilder::new("pp-doclayoutv3.onnx")
        .layout_model_name("PP-DocLayoutV3")
        .with_ocr(
            "pp-ocrv6_tiny_det.onnx",
            "pp-ocrv6_tiny_rec.onnx",
            "ppocrv6_tiny_dict.txt",
        )
        .with_table_classification("pp-lcnet_x1_0_table_cls.onnx")
        .with_wired_table_structure("slanext_wired.onnx")
        .with_wireless_table_structure("slanet_plus.onnx")
        .with_wired_table_cell_detection("rt-detr-l_wired_table_cell_det.onnx")
        .table_structure_dict_path("table_structure_dict_ch.txt")
        .build()?;

    let result = structure.predict("document.jpg")?;
    println!("{}", result.to_markdown());

    Ok(())
}

Vision-Language Page Parsing

With cargo add oar-ocr-vl --features auto-download (plus cargo add image for decoding), any supported VLM loads by its Hugging Face model ID; the checkpoint downloads from ModelScope (or Hugging Face) on first use and is cached under ~/.oar.

use oar_ocr_vl::{
    AnyPageParser, AnyPageParserModel, AnyPageParserOptions, AnyPageParserPretrainedOptions,
    PageParser, auto_device,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let parser = AnyPageParser::from_pretrained(
        AnyPageParserModel::PaddleOcrVl1_5,
        auto_device(),
        &AnyPageParserPretrainedOptions::default(),
    )?;

    let image = image::open("document.jpg")?.to_rgb8();
    let page = parser.parse_page(&image, &AnyPageParserOptions::default())?;
    println!("{}", page.markdown.unwrap_or_default());

    Ok(())
}

Both pipelines export the same page JSON: page.to_json(width, height) here, and StructureResult::to_json(width, height) for the classic structure pipeline.

Supported Models

The classic pipeline runs ONNX models through ONNX Runtime and supports the following model families. See the pre-trained model guide for exact checkpoints, dictionaries, download links, and auto-download names.

Classic ONNX Models

Available text-recognition checkpoints cover Chinese, Traditional Chinese, English, Arabic, Cyrillic, Devanagari, Greek, Eastern Slavic, Japanese, Georgian, Korean, Latin, Tamil, Telugu, and Thai scripts or languages.

Indra OCR runs as its own ONNX pipeline (oar_ocr::indra): small CPU-first models that read a page in 80+ languages into lines, layout blocks in reading order, and Markdown with HTML tables, with n-gram language models for unsure lines and optional inline LaTeX for math lines. See the usage guide.

Vision-Language Models

The oar-ocr-vl crate provides native Candle inference for compact document VLMs on CPU, CUDA, and Metal.

PaddleOCR-VL variants, GLM-OCR, TeleOCR, MiniCPM-OCR, OXR, jina-ocr-v1, and WeVisDoc integrate with the external-layout DocParser. OvisOCR2, OvisOCR3, WeVisDoc, Xiaomi-OCR-0, HPD-Parsing, Youtu-Parsing-Omni, and the MonkeyOCRv2 S/B parsing models also provide model-native full-page paths. Unlimited-OCR-2 parses whole pages, alone or several per request, through its model-native path only. HunyuanOCR and the MinerU models also use their model-native parsing pipelines.

PageParser::parse_document returns a DocumentOutput with pages and document Markdown. Unlimited-OCR-2 uses one joint request with tiled views by default; HunyuanOCR 1.5 and OvisOCR3 offer explicit joint-generation methods. See the page and document API guide.

MiniCPM-OCR uses the explicit repository ID openbmb/MiniCPM-OCR-1.0 through AnyPageParser and, like its official SDK, reads the regions PP-DocLayoutV3 detects; see the MiniCPM-OCR guide.

OXR uses the explicit repository ID SoMarkAI/OXR-1.0 through AnyPageParser. PP-DocLayout supplies regions, and OXR predicts their reading order with its grounding prompt by default. Oxr::with_reading_order(false) selects detector order. See the OXR guide for details and weight-license terms.

Chart-region recognition is opt-in through PaddleOcrVl::with_chart_recognition(true). GLM-OCR defaults to repetition penalty 1.1, and HunyuanOCR page parsing selects the loaded version's official prompt. See the VL usage guide for model defaults and controls.

See the oar-ocr-vl guide for setup and oar-ocr-vl/examples for runnable examples.

Documentation

• Usage guide — APIs, builder patterns, accelerators, and model loading
• Page JSON format — the shared output schema of both pipelines
• Benchmarking — reproducible pipeline baselines and comparisons
• Cargo features — defaults, execution providers, and feature combinations
• Pre-trained models — model files, dictionaries, and auto-download behavior
• Environment variables — runtime and performance overrides
• FAQ — common build and runtime issues

Examples

See the usage guide for other pipeline configurations and APIs. Complete classic-pipeline examples live in examples, while VLM examples live in oar-ocr-vl/examples.

Acknowledgments

This project builds upon the excellent work of several open-source projects:

• ort: Rust bindings for ONNX Runtime by pykeio. This crate provides the Rust interface to ONNX Runtime that powers the efficient inference engine in this OCR library.

• PaddleOCR: Baidu's awesome multilingual OCR toolkits based on PaddlePaddle. This project utilizes PaddleOCR's pre-trained models, which provide excellent accuracy and performance for text detection and recognition across multiple languages.

• Candle: A minimalist ML framework for Rust by Hugging Face. We use Candle to implement Vision-Language model inference.