MonOCR (Python SDK)

The official Python SDK for Mon language OCR, powered by ONNX Runtime. Optimized for high-throughput batch processing and production server environments.

Installation

pip install "monocr-onnx>=0.3.0"

Features

• Pinned to one network: the v3.5 recogniser at revision d3d9d5e, with 160px input height, 276 characters, 277 CTC classes. No accuracy figure is claimed here; see the model card for the held-out result and its caveats.
• Parallel Processing: Native support for multithreaded batch OCR.
• Pinned Model: Weights and charset are fetched from one immutable Hugging Face revision, checksummed, and cached per revision.
• One API for images and PDFs: the same call shape for a line, a page and a document.
• Line segmentation: adaptive thresholding, with padding relative to each line's height.

Quick Start

from monocr_onnx import MonOCR

# Initialize engine (downloads model automatically on first run)
engine = MonOCR()

# Recognize single image
text = engine.predict("document.png")
print(text)

# Recognize single line (for custom layout analysis)
line_text = engine.predict_line("line_crop.png")

API Reference

MonOCR(model_path=None, charset_path=None)

Initialize the OCR engine. If paths are omitted, the pinned model and its charset are downloaded on first use.

Loading refuses a model whose output class count or input height disagrees with the charset — a mismatched pair still runs and still returns text, it is just the wrong text.

predict(image_path) -> str

Recognize text from a single image file or page. Alias for predict_page.

predict_line(image) -> str

Recognize text from a single cropped text line image (PIL).

predict_page(image_path) -> str

Segment an image into lines and recognize each.

CLI Usage

# Recognize an image
monocr image input.jpg

# Process a PDF
monocr pdf document.pdf

# Batch directory processing
monocr batch ./input

# Pre-fetch the model and charset
monocr download

Model artifact

The model and its charset are pinned to janakhpon/monocr@d3d9d5e (v3.5: 160px input height, 276 characters, 277 CTC classes) and verified by sha256 after download. They are never fetched from main — that ref has already moved under this package once, replacing a 64px / 225-class network with the current one.

The cache lives at ~/.monocr/models/<revision>/, so bumping the pin misses the cache rather than silently reusing old weights.

If you installed 0.1.0, a stale ~/.monocr/models/monocr.onnx may still be on disk. Nothing reads it any more; monocr download will point it out and it is safe to delete.

Requirements

• Python 3.11+ — onnxruntime 1.24.1 ships no wheel below cp311 and no sdist, so 3.10 and below have nothing to install
• opencv-python-headless (line segmentation)
• onnxruntime 1.24.1 (CPU or GPU), pinned in uv.lock

Maintenance

Maintained by MonDevHub.

License

MIT