Metadata-Version: 2.4
Name: openocr-mlt
Version: 0.5.2
Summary: Offline multilingual OCR with ONNX Prefill/Decode recognition and PP-OCRv6 medium detection
Maintainer: ericleyu
Project-URL: Models, https://modelscope.cn/models/Strawberry015/openocr-mlt-models
Project-URL: Model mirror, 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
Requires-Dist: onnxruntime-gpu==1.20.0; sys_platform == "linux" and platform_machine == "x86_64"
Requires-Dist: onnxruntime==1.20.0; sys_platform != "linux" or platform_machine != "x86_64"
Requires-Dist: pyclipper==1.4.0
Provides-Extra: cpu
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 ONNX Prefill/Decode recognition and PP-OCRv6 medium text detection. Run whole-page OCR, detection, or cropped text recognition locally.

## Installation

Tested on Linux x86_64 with Python 3.10. Create a virtual environment and install the package.

~~~bash
python3.10 -m venv .venv-ocr
source .venv-ocr/bin/activate
python -m pip install openocr-mlt
~~~

On Linux x86_64 this installation includes the CPU and CUDA providers in one ONNX Runtime package. NVIDIA CUDA requires a compatible driver. On the first CUDA inference, the Python task API reuses compatible system libraries or prepares the pinned CUDA 12 and cuDNN 9 libraries in the user's cache. CPU inference does not need these libraries. The first GPU setup can download about 1.32 GB of runtime libraries, separate from the model bundle. Download progress and source retries are written to standard error. If preparation fails, correct the reported issue and create a new OCR instance to retry, or set `device="cpu"`. PyTorch is optional.

For an existing 0.4.0 CPU or CUDA installation, use a new environment for this version and reuse the model cache. Only one ONNX Runtime distribution and one OCR package may be installed in each environment.

## Python API

~~~python
from openocr_mlt import OpenOCRMLT

with OpenOCRMLT(task="ocr") as ocr:
    page = ocr(image_path="page.jpg")
    print(page.text)

with OpenOCRMLT(task="det", device="cpu") as detector:
    boxes = detector(image_path="page.jpg")
    print([box.points for box in boxes])

with OpenOCRMLT(task="rec", device="cpu") as recognizer:
    lines = recognizer(image_path="crop.jpg")
    print([(line.text, line.score) for line in lines])
~~~

Pass an existing image path or use the image argument with a PIL image or a uint8 NumPy array. Arrays use BGR by default. Pass color_order="RGB" for RGB arrays. The default device is `"auto"`. The runtime uses CUDA when it can initialize the selected models and uses CPU when CUDA is unavailable. Use `device="cpu"` or `device="cuda:0"` to request a specific device. Explicit model directories and the original methods remain supported.

## Model preparation

The first task call downloads the FP32 model bundle if it is absent from the cache. The bundle is hosted on [ModelScope](https://modelscope.cn/models/Strawberry015/openocr-mlt-models/files). Hugging Face and its mirror are fallback sources. The downloader verifies the archive and all 40 model files before installing the cache. The default cache is `$XDG_CACHE_HOME/openocr-mlt` or `~/.cache/openocr-mlt`. The next task can reuse it offline.

Import a local archive in an offline environment with the following command.

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

Set `offline=True` on the Python task to use local models and CUDA libraries only. The fetch-models command prints the verified recognition and detector directories.

## Command line

~~~bash
python -m openocr_mlt fetch-models --cache-dir ./models
python -m openocr_mlt ocr ./page.jpg \
  --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
~~~

The CLI also supports detect and recognize. For CLI CUDA use, prepare the CUDA cache with a Python task first or provide compatible local libraries. Run python -m openocr_mlt --help for the available options.

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

Those model evaluations 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).
