Metadata-Version: 2.4
Name: openocr-mlt-cuda
Version: 0.4.0
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
Requires-Dist: pyclipper==1.4.0
Requires-Dist: nvidia-cuda-runtime-cu12==12.4.127
Requires-Dist: nvidia-cublas-cu12==12.4.5.8
Requires-Dist: nvidia-cudnn-cu12==9.1.0.70
Requires-Dist: nvidia-cuda-nvrtc-cu12==12.4.127
Requires-Dist: nvidia-cufft-cu12==11.2.1.3
Requires-Dist: nvidia-curand-cu12==10.3.5.147
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

Validated on Linux x86_64 with Python 3.10.12. Create one virtual environment for the installation you want to use.

**CPU**

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

**NVIDIA CUDA**

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

Both packages provide the same Python import and CLI. Install only one package per environment. The CUDA package requires a compatible NVIDIA driver and installs CUDA 12 and cuDNN 9 user-space libraries. ONNX inference runs without PyTorch.

### Upgrading from 0.3.0

- A 0.3.0 CPU installation can be upgraded with `python -m pip install --upgrade openocr-mlt`.
- For a 0.3.0 CUDA installation, create a new environment and install `openocr-mlt-cuda` as shown above. The previous `openocr-mlt[cuda]` command applies to 0.3.0. A shared or explicitly configured model cache can be reused.

## 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 CPU installation uses CPU. The CUDA installation 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 require local assets. 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. 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).
