Metadata-Version: 2.4
Name: mathcraft-ocr
Version: 0.2.9
Summary: ONNX-only OCR runtime for mathematical documents
Author: SakuraMathcraft
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/SakuraMathcraft/LaTeXSnipper
Project-URL: Models, https://github.com/SakuraMathcraft/MathCraft-Models
Project-URL: Issues, https://github.com/SakuraMathcraft/LaTeXSnipper/issues
Keywords: ocr,latex,math,onnx,document-ocr,formula-recognition
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=2
Requires-Dist: pillow<13,>=12
Requires-Dist: opencv-python<5,>=4.10
Requires-Dist: rapidocr==3.5.0
Requires-Dist: transformers==4.55.4
Requires-Dist: tokenizers==0.21.4
Provides-Extra: cpu
Requires-Dist: onnxruntime<1.30,>=1.20; extra == "cpu"
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu<1.30,>=1.27; extra == "gpu"
Provides-Extra: gpu-cu12
Requires-Dist: onnxruntime-gpu<1.27,>=1.21; extra == "gpu-cu12"
Provides-Extra: directml
Requires-Dist: onnxruntime-directml<1.30,>=1.20; platform_system == "Windows" and extra == "directml"
Provides-Extra: openvino
Requires-Dist: onnxruntime-openvino<1.30,>=1.20; (platform_system == "Windows" or platform_system == "Linux") and extra == "openvino"
Provides-Extra: dev
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: pandoc
Requires-Dist: pypandoc>=1.15; extra == "pandoc"
Dynamic: license-file

# MathCraft OCR

MathCraft OCR is an ONNX-only OCR runtime for mathematical documents. It provides formula recognition, text recognition, mixed text/formula page OCR, explicit model-cache management, and structured block output for downstream Markdown or TeX document engines.

The package is developed for LaTeXSnipper but is usable as a standalone Python library.

## Features

- ONNX Runtime inference only; no active PyTorch OCR runtime.
- Formula OCR: image to LaTeX.
- Text OCR: multilingual PP-OCRv5 mobile detector/recognizer.
- Mixed OCR: formula detection, text masking, batched recognition, and layout merge.
- Manifest-driven model cache with SHA-256 file checks.
- Automatic repair for missing or incomplete model directories.
- Resumable model downloads for interrupted first-run cache repair.
- CPU/GPU provider selection through ONNX Runtime.
- JSONL worker mode for GUI or service integration.

## Installation

CPU backend:

```powershell
pip install "mathcraft-ocr[cpu]"
```

GPU backend:

```powershell
pip install "mathcraft-ocr[gpu]"
```

CUDA 12 backend:

```powershell
pip install "mathcraft-ocr[gpu-cu12]"
```

Windows DirectML backend:

```powershell
pip install "mathcraft-ocr[directml]"
```

Intel OpenVINO backend on Windows or Linux:

```powershell
pip install "mathcraft-ocr[openvino]"
```

Install only one backend extra in a clean environment. The CPU, CUDA/TensorRT, DirectML, and OpenVINO ONNX Runtime distributions must not be mixed in the same environment. The standard `onnxruntime` macOS wheel includes CoreML EP support.

LaTeXSnipper's dependency wizard selects the ONNX Runtime GPU line from the detected CUDA toolkit: CUDA 11.x uses ONNX Runtime 1.20 from the official CUDA 11 feed, CUDA 12.x uses ONNX Runtime 1.21-1.26 from PyPI, and CUDA 13.x uses ONNX Runtime 1.27-1.29 from PyPI. The static `mathcraft-ocr[gpu]` extra follows the current PyPI default (CUDA 13 and Python 3.11+); use `gpu-cu12` for CUDA 12. CUDA 11 installations must also select the official CUDA 11 package feed, so LaTeXSnipper's dependency wizard is recommended for that configuration.

## Quick Start

```python
from mathcraft_ocr import MathCraftRuntime

runtime = MathCraftRuntime(provider_preference="auto")
result = runtime.recognize_mixed("page.png")

print(result.text)
for block in result.blocks:
    print(block.role, block.kind, block.text[:80])
```

Formula-only recognition:

```python
from mathcraft_ocr import MathCraftRuntime

runtime = MathCraftRuntime(provider_preference="cpu")
formula = runtime.recognize_formula("formula.png")
print(formula.text)
```

## CLI

Check model cache:

```powershell
mathcraft models check
```

Inspect runtime:

```powershell
mathcraft doctor --provider auto
```

Warm up models:

```powershell
mathcraft warmup --profile mixed --provider auto
```

Recognize an image:

```powershell
mathcraft ocr "C:\path\to\page.png" --profile mixed --provider auto --output result.md
mathcraft ocr "C:\path\to\page.png" --profile mixed --provider auto --output-dir "D:\MathCraft\outputs"
mathcraft ocr "C:\path\to\formula.png" --profile formula --provider auto --json
```

Run JSONL worker mode:

```powershell
mathcraft worker --provider auto
```

## Model Cache

MathCraft reads models from a platform-specific default user data root:

```text
Windows: %APPDATA%\MathCraft\models
macOS: ~/Library/Application Support/LaTeXSnipper/MathCraft/models
Linux: ${XDG_DATA_HOME:-~/.local/share}/LaTeXSnipper/MathCraft/models
```

or from a custom root:

```powershell
$env:MATHCRAFT_HOME="D:\MathCraft\models"
mathcraft doctor --provider auto
```

Persist the custom root for future PowerShell sessions:

```powershell
setx MATHCRAFT_HOME "D:\MathCraft\models"
```

Restore the default user cache root:

```powershell
[Environment]::SetEnvironmentVariable("MATHCRAFT_HOME", $null, "User")
Remove-Item Env:\MATHCRAFT_HOME -ErrorAction SilentlyContinue
mathcraft doctor --provider auto
```

Open a new PowerShell window after removing the persistent variable. The default root is:

```text
Windows: %APPDATA%\MathCraft\models
macOS: ~/Library/Application Support/LaTeXSnipper/MathCraft/models
Linux: ${XDG_DATA_HOME:-~/.local/share}/LaTeXSnipper/MathCraft/models
```

Model artifacts are downloaded from the MathCraft-Models release assets declared in `mathcraft_ocr/manifests/models.v1.json`.

## Runtime Profiles

| Profile | Models | Output |
| --- | --- | --- |
| `formula` | formula detector + formula recognizer | LaTeX string |
| `text` | text detector + text recognizer | OCR text and text blocks |
| `mixed` | formula detector + formula recognizer + text detector + text recognizer | Markdown-ready structured blocks |

## Provider Selection

`provider_preference` accepts:

- `auto`: prefer CUDA, then a platform accelerator, and finally CPU; TensorRT remains explicit because of its first-use engine build cost.
- `cpu`: force CPU.
- `gpu`: request the first available supported accelerator.
- `cuda`: request CUDA.
- `tensorrt` or `trt`: request TensorRT, followed by CUDA and CPU for unsupported nodes.
- `directml` or `dml`: request DirectML.
- `coreml`: request CoreML.
- `openvino`: request OpenVINO.

Advanced callers can pass an explicit ordered provider list and provider options:

```python
runtime = MathCraftRuntime(
    providers=[
        (
            "TensorrtExecutionProvider",
            {
                "device_id": 0,
                "trt_engine_cache_enable": True,
                "trt_engine_cache_path": "./trt-cache",
            },
        ),
        ("CUDAExecutionProvider", {"device_id": 0}),
    ]
)
```

`auto` deliberately prefers CUDA over TensorRT because TensorRT can spend substantial time building an engine on first use. Select `tensorrt` explicitly when its native runtime is installed; enable its engine cache for repeated startup performance.

The actual provider is available on recognition results through the `provider` field. Doctor and warmup reports also expose `device_id`, `device_name`, `device_uuid`, and `device_verified` under `provider_info`. GPU sessions bind the reported `device_id` explicitly; `device_verified` becomes true only after the runtime confirms the device used by initialized inference sessions.

## Development

Run tests from the repository root:

```powershell
cd E:\LaTexSnipper
python .\test\test_mathcraft_ocr.py
python .\test\test_mathcraft_document_engine.py
```

Build package artifacts:

```powershell
cd E:\LaTexSnipper
python -m build --no-isolation --outdir .\release_assets\mathcraft-ocr-package\dist .
```

## License

GPL-3.0-only. See `LICENSE`.
