openocr-mlt

Multilingual OCR with ScriptMoE recognition and PP-OCRv6 medium text detection. The package provides cropped text recognition, whole-page OCR, a Python API, and a command-line interface.

Both models run with ONNX Runtime. Recognition uses autoregressive Prefill/Decode and KV caching. CPU and CUDA installations use separate runtime dependencies.

Installation

Use Linux x86_64 with Python 3.10.12 for the verified installation path. Select the CPU or CUDA extra in a virtual environment.

python3.10 -m venv .venv-cpu
.venv-cpu/bin/python -m pip install "openocr-mlt[cpu]"

For CUDA, use a separate environment:

python3.10 -m venv .venv-cuda
.venv-cuda/bin/python -m pip install "openocr-mlt[cuda]"

The CPU extra installs ONNX Runtime; the CUDA extra installs ONNX Runtime GPU and the required CUDA 12/cuDNN 9 user-space libraries. CUDA requires an NVIDIA driver. PyTorch is not required for ONNX inference. Install the CPU and CUDA extras in separate environments.

Model Preparation

Activate the environment you installed, for example source .venv-cpu/bin/activate.

Download and verify the registered model bundle:

python -m openocr_mlt fetch-models --cache-dir ./models

Activate the selected virtual environment before running these commands. The command downloads the pinned FP32 bundle, verifies the archive and 40 model files, and returns the recognition and detector directories. Subsequent calls verify and reuse the cache.

The bundle is 213,794,128 bytes and is hosted in ericleyu/openocr-mlt-models. It contains recognition graphs, shared weights, the character dictionary, the model manifest, and the PP-OCRv6 medium detector.

For offline use, copy the model archive to the target machine and import it locally:

python -m openocr_mlt fetch-models \
  --source ./scriptmoe-medium-fp32-20261101-v1.tar.gz \
  --cache-dir ./models --offline

The default cache location is $XDG_CACHE_HOME/openocr-mlt or ~/.cache/openocr-mlt. Download the model archive on a machine with access to Hugging Face and transfer it to the target machine when necessary. Offline package installation also requires local copies of the Python dependencies.

Python API

from openocr_mlt import OpenOCRMLT, fetch_models

models = fetch_models(cache_dir="./models")

with OpenOCRMLT(
    model_dir=models["recognition_dir"],
    det_model_dir=models["detector_dir"],
    device="cpu",
) as ocr:
    result = ocr.ocr("./example.png")
    print(result.to_dict())

Replace ./example.png with an existing image. Set device="cuda:0" in the CUDA environment to run detection and recognition on CUDA. The det_device and rec_device parameters select the two devices independently.

For cropped text recognition, initialize OpenOCRMLT with model_dir and call recognize(image). Results include the raw and filtered text, confidence score, status, decoding termination, and device information.

Command Line

Whole-page OCR:

python -m openocr_mlt ocr ./example.png \
  --model-dir ./models/scriptmoe-medium-fp32-20261101-v1/recognition \
  --det-model-dir ./models/scriptmoe-medium-fp32-20261101-v1/ppocrv6-medium-det-bce-v1 \
  --device cpu

Cropped text recognition:

python -m openocr_mlt recognize ./crop.png \
  --model-dir ./models/scriptmoe-medium-fp32-20261101-v1/recognition \
  --device cpu

Replace the image arguments with existing files. Run python -m openocr_mlt --help for all commands.

Configuration

The evaluation configuration uses recognition threshold 0.7 and maximum page side 2,000 pixels. Set rec_threshold=0.7 and page_max_side=2000 in the API, or pass --rec-threshold 0.7 --page-max-side 2000 to the OCR command.

Model Evaluation

The FP32 graphs were evaluated with openocr-mlt 0.3.0.dev14. The model bundle is unchanged.

Deployment validation used Linux x86_64, Python 3.10.12, ONNX Runtime 1.20.0, an Intel Xeon Gold 6226R CPU, and an NVIDIA RTX 3090 GPU. One CPU/CUDA recognition whitespace difference was observed on TextMuSS. Additional platforms, hardware and quantized execution remain future work.

Sources

• ScriptMoE: multilingual recognition model and decoding design.
• ppocrv6_onnx: detection preprocessing and postprocessing reference.
• PP-OCRv6 medium: detector distributed through Paddle's official model storage.

Component attribution and licensing information are included in the package's THIRD_PARTY_NOTICES.txt and in the model repository's THIRD_PARTY_NOTICES.md.