Metadata-Version: 2.4
Name: openocr-mlt
Version: 0.3.0
Summary: Offline multilingual OCR with ONNX Prefill/Decode recognition and PP-OCRv6 medium detection
Maintainer: ericleyu
Project-URL: Models, https://huggingface.co/ericleyu/openocr-mlt-models
Project-URL: Upstream recognition, https://github.com/YesianRohn/ScriptMoE
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy<2.3,>=2.2
Requires-Dist: Pillow<12.4,>=12.3
Requires-Dist: opencv-python-headless<5.1,>=5.0
Provides-Extra: cpu
Requires-Dist: onnxruntime==1.20.0; extra == "cpu"
Requires-Dist: pyclipper==1.4.0; extra == "cpu"
Provides-Extra: cuda
Requires-Dist: onnxruntime-gpu==1.20.0; extra == "cuda"
Requires-Dist: pyclipper==1.4.0; extra == "cuda"
Requires-Dist: nvidia-cuda-runtime-cu12==12.4.127; extra == "cuda"
Requires-Dist: nvidia-cublas-cu12==12.4.5.8; extra == "cuda"
Requires-Dist: nvidia-cudnn-cu12==9.1.0.70; extra == "cuda"
Requires-Dist: nvidia-cuda-nvrtc-cu12==12.4.127; extra == "cuda"
Requires-Dist: nvidia-cufft-cu12==11.2.1.3; extra == "cuda"
Requires-Dist: nvidia-curand-cu12==10.3.5.147; extra == "cuda"
Provides-Extra: torch
Requires-Dist: torch<2.6,>=2.5; extra == "torch"
Requires-Dist: torchvision<0.21,>=0.20; extra == "torch"
Requires-Dist: safetensors<0.9,>=0.8; extra == "torch"

# 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.

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

For CUDA, use a separate environment:

~~~bash
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:

~~~bash
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](https://huggingface.co/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:

~~~bash
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](https://huggingface.co/ericleyu/openocr-mlt-models/resolve/7ef39160a893fc7e605e146c1544ba64c1a57f43/scriptmoe-medium-fp32-20261101-v1.tar.gz) 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

~~~python
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:

~~~bash
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:

~~~bash
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

| Setting | Default |
|---|---|
| Precision | FP32 |
| Effective batch size | 1; images are processed serially |
| Maximum recognition length | 100 decoding steps |
| Maximum input ratio | 20 |
| Recognition confidence threshold | 0.5 |
| Maximum page side | 0, resizing disabled |

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.

| Task | Data | Result |
|---|---|---|
| CUDA recognition | TextMuSS, 10,899 crops | Official normalized weighted accuracy 85.0812%; ten-group macro accuracy 81.0928% |
| Whole-page OCR, CPU and CUDA | Fixed CC-OCR subset, 200 pages across ten languages, development/held-out split 100/100 | Held-out text F1: macro 72.5849%, micro 79.4545% |

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](https://github.com/YesianRohn/ScriptMoE): multilingual recognition model and decoding design.
- [ppocrv6_onnx](https://github.com/AIwork4me/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](https://huggingface.co/ericleyu/openocr-mlt-models/blob/7ef39160a893fc7e605e146c1544ba64c1a57f43/THIRD_PARTY_NOTICES.md).
