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]"

CUDA 12 backend:

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

Windows DirectML backend:

pip install "mathcraft-ocr[directml]"

Intel OpenVINO backend on Windows or Linux:

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 Management 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 Management is recommended for that configuration.

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

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:

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.