mathcraft-ocr 0.1.0__tar.gz

mathcraft_ocr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MathCraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mathcraft_ocr-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README_MATHCRAFT_OCR.md
+include pyproject.toml
+graft mathcraft_ocr
+prune build
+prune dist
+prune docs
+prune release_assets
+prune scripts
+prune src
+prune test
+prune test_pdf
+global-exclude __pycache__
+global-exclude *.py[cod]

mathcraft_ocr-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: mathcraft-ocr
+Version: 0.1.0
+Summary: ONNX-only OCR runtime for mathematical documents
+Author: SakuraMathcraft
+License-Expression: MIT
+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 :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pillow<12,>=10
+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
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: packaging>=23
+Provides-Extra: cpu
+Requires-Dist: onnxruntime~=1.19.2; extra == "cpu"
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu~=1.19.2; extra == "gpu"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+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.
+- CPU/GPU provider selection through ONNX Runtime.
+- JSONL worker mode for GUI or service integration.
+
+## Installation
+
+CPU backend:
+
+```bash
+pip install "mathcraft-ocr[cpu]"
+```
+
+GPU backend:
+
+```bash
+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.
+
+## 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:
+
+```bash
+mathcraft models check
+```
+
+Inspect runtime:
+
+```bash
+mathcraft doctor --provider auto
+```
+
+Warm up models:
+
+```bash
+mathcraft warmup --profile mixed --provider auto
+```
+
+Recognize an image:
+
+```bash
+mathcraft ocr page.png --profile mixed --provider auto --output result.md
+mathcraft ocr formula.png --profile formula --json
+```
+
+Run JSONL worker mode:
+
+```bash
+mathcraft worker --provider auto
+```
+
+## Model Cache
+
+MathCraft reads models from:
+
+```text
+%APPDATA%\MathCraft\models
+```
+
+or from a custom root:
+
+```bash
+set MATHCRAFT_HOME=D:\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 when available and valid, otherwise CPU.
+- `cpu`: force CPU.
+- `gpu`: request CUDA-capable ONNX Runtime.
+
+The actual provider is available on results through the `provider` field.
+
+## Development
+
+Run tests from the repository root:
+
+```bash
+python test/test_mathcraft_ocr.py
+python test/test_mathcraft_document_engine.py
+```
+
+Build package artifacts:
+
+```bash
+python -m pip wheel . --no-deps -w release_assets/mathcraft-ocr-package/dist
+python -m build --outdir release_assets/mathcraft-ocr-package/dist
+```
+
+## License
+
+MIT. See `LICENSE`.

mathcraft_ocr-0.1.0/README_MATHCRAFT_OCR.md

@@ -0,0 +1,142 @@
+# 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.
+- CPU/GPU provider selection through ONNX Runtime.
+- JSONL worker mode for GUI or service integration.
+
+## Installation
+
+CPU backend:
+
+```bash
+pip install "mathcraft-ocr[cpu]"
+```
+
+GPU backend:
+
+```bash
+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.
+
+## 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:
+
+```bash
+mathcraft models check
+```
+
+Inspect runtime:
+
+```bash
+mathcraft doctor --provider auto
+```
+
+Warm up models:
+
+```bash
+mathcraft warmup --profile mixed --provider auto
+```
+
+Recognize an image:
+
+```bash
+mathcraft ocr page.png --profile mixed --provider auto --output result.md
+mathcraft ocr formula.png --profile formula --json
+```
+
+Run JSONL worker mode:
+
+```bash
+mathcraft worker --provider auto
+```
+
+## Model Cache
+
+MathCraft reads models from:
+
+```text
+%APPDATA%\MathCraft\models
+```
+
+or from a custom root:
+
+```bash
+set MATHCRAFT_HOME=D:\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 when available and valid, otherwise CPU.
+- `cpu`: force CPU.
+- `gpu`: request CUDA-capable ONNX Runtime.
+
+The actual provider is available on results through the `provider` field.
+
+## Development
+
+Run tests from the repository root:
+
+```bash
+python test/test_mathcraft_ocr.py
+python test/test_mathcraft_document_engine.py
+```
+
+Build package artifacts:
+
+```bash
+python -m pip wheel . --no-deps -w release_assets/mathcraft-ocr-package/dist
+python -m build --outdir release_assets/mathcraft-ocr-package/dist
+```
+
+## License
+
+MIT. See `LICENSE`.

mathcraft_ocr-0.1.0/mathcraft_ocr/__init__.py

@@ -0,0 +1,39 @@
+# coding: utf-8
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DoctorReport",
+    "FormulaRecognitionResult",
+    "MathCraftBlock",
+    "MathCraftError",
+    "MathCraftRuntime",
+    "MixedRecognitionResult",
+    "OCRRegion",
+    "__version__",
+    "run_doctor",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name in {
+        "FormulaRecognitionResult",
+        "MathCraftBlock",
+        "MathCraftRuntime",
+        "MixedRecognitionResult",
+        "OCRRegion",
+    }:
+        from . import api
+
+        return getattr(api, name)
+    if name in {"DoctorReport", "run_doctor"}:
+        from . import doctor
+
+        return getattr(doctor, name)
+    if name == "MathCraftError":
+        from .errors import MathCraftError
+
+        return MathCraftError
+    raise AttributeError(name)

mathcraft_ocr-0.1.0/mathcraft_ocr/__main__.py

@@ -0,0 +1,6 @@
+# coding: utf-8
+
+from .cli import main
+
+
+raise SystemExit(main())

mathcraft_ocr-0.1.0/mathcraft_ocr/adapters/__init__.py

@@ -0,0 +1,13 @@
+# coding: utf-8
+
+from .formula_detector import warmup_formula_detector
+from .formula_recognizer import warmup_formula_recognizer
+from .text_detector import warmup_text_detector
+from .text_recognizer import warmup_pp_text_recognizer
+
+__all__ = [
+    "warmup_formula_detector",
+    "warmup_formula_recognizer",
+    "warmup_text_detector",
+    "warmup_pp_text_recognizer",
+]

mathcraft_ocr-0.1.0/mathcraft_ocr/adapters/common.py

@@ -0,0 +1,46 @@
+# coding: utf-8
+
+from __future__ import annotations
+
+import importlib
+from functools import lru_cache
+from pathlib import Path
+
+from ..providers import GPU_PROVIDER_NAMES, ProviderInfo
+
+
+def _ort():
+    return importlib.import_module("onnxruntime")
+
+
+def session_providers(provider_info: ProviderInfo) -> list[str]:
+    available = list(provider_info.available_providers)
+    active = provider_info.active_provider
+    if active and active in GPU_PROVIDER_NAMES and "CPUExecutionProvider" in available:
+        return [active, "CPUExecutionProvider"]
+    if "CPUExecutionProvider" in available:
+        return ["CPUExecutionProvider"]
+    return available
+
+
+def create_session(model_path: str | Path, provider_info: ProviderInfo):
+    model_path = str(Path(model_path).resolve())
+    providers = tuple(session_providers(provider_info))
+    session = _create_session_cached(model_path, providers)
+    actual = list(session.get_providers() or [])
+    active = provider_info.active_provider
+    if active and active in GPU_PROVIDER_NAMES and active not in actual:
+        raise RuntimeError(
+            f"requested ONNX GPU provider {active}, but session providers are {actual}"
+        )
+    return session
+
+
+@lru_cache(maxsize=16)
+def _create_session_cached(model_path: str, providers: tuple[str, ...]):
+    ort = _ort()
+    return ort.InferenceSession(model_path, providers=list(providers))
+
+
+def clear_session_cache() -> None:
+    _create_session_cached.cache_clear()

mathcraft_ocr-0.1.0/mathcraft_ocr/adapters/formula_detector.py

@@ -0,0 +1,131 @@
+# coding: utf-8
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from .common import create_session
+
+
+@dataclass(frozen=True)
+class FormulaBox:
+    box: tuple[
+        tuple[float, float],
+        tuple[float, float],
+        tuple[float, float],
+        tuple[float, float],
+    ]
+    score: float
+    label: str
+
+
+def warmup_formula_detector(model_dir: str | Path, provider_info) -> None:
+    root = Path(model_dir)
+    candidates = sorted(root.glob("*mfd*.onnx"))
+    if not candidates:
+        raise FileNotFoundError(f"no mfd onnx file found under {root}")
+    create_session(candidates[0], provider_info)
+
+
+def _letterbox(image: np.ndarray, target_size: int = 768) -> tuple[np.ndarray, float, tuple[float, float]]:
+    height, width = image.shape[:2]
+    scale = min(target_size / width, target_size / height)
+    new_w = int(round(width * scale))
+    new_h = int(round(height * scale))
+    resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)
+    canvas = np.full((target_size, target_size, 3), 114, dtype=np.uint8)
+    pad_x = (target_size - new_w) / 2
+    pad_y = (target_size - new_h) / 2
+    left = int(round(pad_x - 0.1))
+    top = int(round(pad_y - 0.1))
+    canvas[top : top + new_h, left : left + new_w] = resized
+    return canvas, scale, (float(left), float(top))
+
+
+def _nms_xyxy(boxes: np.ndarray, scores: np.ndarray, iou_threshold: float) -> list[int]:
+    if len(boxes) == 0:
+        return []
+    x1 = boxes[:, 0]
+    y1 = boxes[:, 1]
+    x2 = boxes[:, 2]
+    y2 = boxes[:, 3]
+    areas = np.maximum(0.0, x2 - x1) * np.maximum(0.0, y2 - y1)
+    order = scores.argsort()[::-1]
+    keep: list[int] = []
+    while order.size > 0:
+        current = int(order[0])
+        keep.append(current)
+        if order.size == 1:
+            break
+        rest = order[1:]
+        xx1 = np.maximum(x1[current], x1[rest])
+        yy1 = np.maximum(y1[current], y1[rest])
+        xx2 = np.minimum(x2[current], x2[rest])
+        yy2 = np.minimum(y2[current], y2[rest])
+        inter_w = np.maximum(0.0, xx2 - xx1)
+        inter_h = np.maximum(0.0, yy2 - yy1)
+        intersection = inter_w * inter_h
+        union = areas[current] + areas[rest] - intersection
+        iou = np.divide(intersection, union, out=np.zeros_like(intersection), where=union > 0)
+        order = rest[iou <= iou_threshold]
+    return keep
+
+
+def detect_formula_boxes(
+    image_rgb: np.ndarray,
+    model_dir: str | Path,
+    provider_info,
+    *,
+    confidence_threshold: float = 0.25,
+    iou_threshold: float = 0.45,
+    input_size: int = 768,
+) -> tuple[FormulaBox, ...]:
+    root = Path(model_dir)
+    candidates = sorted(root.glob("*mfd*.onnx"))
+    if not candidates:
+        raise FileNotFoundError(f"no mfd onnx file found under {root}")
+    session = create_session(candidates[0], provider_info)
+    preprocessed, scale, (pad_x, pad_y) = _letterbox(image_rgb, input_size)
+    model_input = (
+        preprocessed.astype(np.float32).transpose(2, 0, 1)[np.newaxis, ...] / 255.0
+    )
+    output = session.run(None, {session.get_inputs()[0].name: model_input})[0]
+    preds = np.asarray(output[0]).T
+    if preds.size == 0 or preds.shape[1] < 6:
+        return ()
+    xywh = preds[:, :4]
+    class_scores = preds[:, 4:]
+    class_ids = np.argmax(class_scores, axis=1)
+    scores = class_scores[np.arange(len(class_scores)), class_ids]
+    mask = scores >= confidence_threshold
+    if not np.any(mask):
+        return ()
+    xywh = xywh[mask]
+    class_ids = class_ids[mask]
+    scores = scores[mask]
+
+    x, y, w, h = xywh[:, 0], xywh[:, 1], xywh[:, 2], xywh[:, 3]
+    boxes = np.stack([x - w / 2, y - h / 2, x + w / 2, y + h / 2], axis=1)
+    boxes[:, [0, 2]] = (boxes[:, [0, 2]] - pad_x) / scale
+    boxes[:, [1, 3]] = (boxes[:, [1, 3]] - pad_y) / scale
+    height, width = image_rgb.shape[:2]
+    boxes[:, [0, 2]] = np.clip(boxes[:, [0, 2]], 0, width)
+    boxes[:, [1, 3]] = np.clip(boxes[:, [1, 3]], 0, height)
+
+    labels = ("embedding", "isolated")
+    keep = _nms_xyxy(boxes, scores, iou_threshold)
+    results: list[FormulaBox] = []
+    for index in keep:
+        x1, y1, x2, y2 = boxes[index].tolist()
+        results.append(
+            FormulaBox(
+                box=((x1, y1), (x2, y1), (x2, y2), (x1, y2)),
+                score=float(scores[index]),
+                label=labels[int(class_ids[index])] if int(class_ids[index]) < len(labels) else str(int(class_ids[index])),
+            )
+        )
+    return tuple(results)