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:

pip install "mathcraft-ocr[cpu]"

GPU backend:

pip install "mathcraft-ocr[gpu]"

Install only one backend extra in a clean environment. onnxruntime and onnxruntime-gpu should not be mixed in the same environment.

LaTeXSnipper's dependency wizard selects the ONNX Runtime GPU wheel line from the detected CUDA toolkit. CUDA 11.x uses the ONNX Runtime CUDA 11 package feed, CUDA 12.x uses the stable PyPI GPU wheels, and CUDA 13.x uses the ONNX Runtime CUDA 13 nightly feed. Static mathcraft-ocr[gpu] package metadata cannot inspect the local CUDA toolkit, so it keeps a broad stable PyPI range; CUDA 11.x users installing manually should use the CUDA 11 feed shown by the wizard.

Quick Start

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:

from mathcraft_ocr import MathCraftRuntime

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

CLI

Check model cache:

mathcraft models check

Inspect runtime:

mathcraft doctor --provider auto

Warm up models:

mathcraft warmup --profile mixed --provider auto

Recognize an image:

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:

mathcraft worker --provider auto

Model Cache

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

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:

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

Persist the custom root for future PowerShell sessions:

setx MATHCRAFT_HOME "D:\MathCraft\models"

Restore the default user cache root:

[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:

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

Provider Selection

provider_preference accepts:

• auto: prefer CUDA when available and valid, otherwise CPU.
• cpu: force CPU.
• gpu: request CUDA-capable ONNX Runtime.

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:

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

Build package artifacts:

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

License

GPL-3.0-only. See LICENSE.