Metadata-Version: 2.5
Name: monocr-onnx
Version: 0.3.2
Summary: On-device Mon (mnw) OCR, powered by ONNX Runtime
Project-URL: Homepage, https://github.com/MonDevHub/monocr-onnx
Project-URL: Repository, https://github.com/MonDevHub/monocr-onnx
Project-URL: Issues, https://github.com/MonDevHub/monocr-onnx/issues
Project-URL: Documentation, https://github.com/MonDevHub/monocr-onnx/tree/main/python
Author-email: Janakh <janakh@example.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: onnxruntime>=1.15.0
Requires-Dist: opencv-python-headless>=4.5.0
Requires-Dist: pdf2image>=1.16.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: tqdm>=4.60.0
Description-Content-Type: text/markdown

# MonOCR (Python SDK)

[![PyPI](https://img.shields.io/pypi/v/monocr-onnx.svg)](https://pypi.org/project/monocr-onnx/)

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

## Installation

```bash
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](https://huggingface.co/janakhpon/monocr) 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](https://huggingface.co/janakhpon/monocr) 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

```python
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

```bash
# 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](https://github.com/MonDevHub).

## License

MIT
