mathcraft-ocr 0.2.2__tar.gz → 0.2.3__tar.gz

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/LICENSE

@@ -1,21 +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.
+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.2.2 → mathcraft_ocr-0.2.3}/MANIFEST.in

@@ -1,14 +1,14 @@
-include LICENSE
+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]
+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.2.2/mathcraft_ocr.egg-info → mathcraft_ocr-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mathcraft-ocr
-Version: 0.2.2
+Version: 0.2.3
 Summary: ONNX-only OCR runtime for mathematical documents
 Author: SakuraMathcraft
 License-Expression: MIT
@@ -139,10 +139,12 @@ mathcraft worker --provider auto
 
 ## Model Cache
 
-MathCraft reads models from:
+MathCraft reads models from a platform-specific default user data root:
 
 ```text
-%APPDATA%\MathCraft\models
+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:
@@ -169,7 +171,9 @@ mathcraft doctor --provider auto
 Open a new PowerShell window after removing the persistent variable. The default root is:
 
 ```text
-%APPDATA%\MathCraft\models
+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`.

mathcraft_ocr-0.2.3/README.md

@@ -0,0 +1,230 @@
+# MathCraft Models
+
+Model assets for **MathCraft OCR**, the ONNX-only OCR runtime used by LaTeXSnipper.
+
+MathCraft OCR recognizes formulae, text, and mixed mathematical documents with a compact ONNX model set. This repository provides the model release assets and the source package for the PyPI package `mathcraft-ocr` used by LaTeXSnipper.
+
+## Quick Start
+
+Current PyPI release line: `mathcraft-ocr 0.2.3`.
+
+Install the library and CLI without choosing an ONNX Runtime backend:
+
+```powershell
+pip install mathcraft-ocr
+mathcraft --help
+```
+
+Install exactly one ONNX Runtime backend before running OCR inference.
+
+CPU:
+
+```powershell
+pip install "mathcraft-ocr[cpu]"
+```
+
+GPU:
+
+```powershell
+pip install "mathcraft-ocr[gpu]"
+```
+
+Use only one ONNX Runtime backend in the same environment. Do not install `onnxruntime` and `onnxruntime-gpu` together.
+
+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 CUDA 11.x users installing manually should use the CUDA 11 feed shown by the wizard.
+
+Upgrade the current release with a chosen backend:
+
+```powershell
+pip install -U "mathcraft-ocr[gpu]"
+mathcraft --help
+```
+
+Check the runtime:
+
+```powershell
+mathcraft doctor --provider auto
+mathcraft models check
+mathcraft warmup --profile mixed --provider auto
+```
+
+Recognize an image:
+
+```powershell
+mathcraft ocr "C:\path\to\formula.png" --profile formula --provider auto --json
+```
+
+Mixed OCR to Markdown:
+
+```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"
+```
+
+When a file is written, the CLI prints the resolved output path:
+
+```text
+[MATHCRAFT_OUTPUT] written to D:\MathCraft\outputs\page.md
+```
+
+PowerShell custom model cache:
+
+```powershell
+$env:MATHCRAFT_HOME="D:\MathCraft\models"
+mathcraft doctor --provider auto
+```
+
+Persistent user-level cache path:
+
+```powershell
+setx MATHCRAFT_HOME "D:\MathCraft\models"
+```
+
+Open a new terminal after `setx`.
+
+Restore the default cache path:
+
+```powershell
+[Environment]::SetEnvironmentVariable("MATHCRAFT_HOME", $null, "User")
+Remove-Item Env:\MATHCRAFT_HOME -ErrorAction SilentlyContinue
+mathcraft doctor --provider auto
+```
+
+Open a new terminal after removing the persistent variable. The default root is platform-specific:
+
+```text
+Windows: %APPDATA%\MathCraft\models
+macOS: ~/Library/Application Support/LaTeXSnipper/MathCraft/models
+Linux: ${XDG_DATA_HOME:-~/.local/share}/LaTeXSnipper/MathCraft/models
+```
+
+## Python API
+
+```python
+from mathcraft_ocr import MathCraftRuntime
+
+runtime = MathCraftRuntime(provider_preference="auto")
+result = runtime.recognize_mixed(r"C:\path\to\page.png")
+
+print(result.text)
+for block in result.blocks:
+    print(block.role, block.kind, block.text[:80])
+```
+
+## Profiles
+
+| Profile | Use Case | Output |
+| --- | --- | --- |
+| `formula` | Formula screenshots | LaTeX formula text |
+| `text` | Plain text OCR | Text |
+| `mixed` | Text + formula documents | Markdown-ready structured text |
+
+## Runtime Release Notes
+
+`mathcraft-ocr 0.2.3` fixes cross-platform hardware sizing. Memory detection now uses optional `psutil`, Windows API, POSIX `sysconf`, and macOS `vm_stat`, so CPU batch sizing no longer falls back to Windows-only memory data on Linux or macOS. It also moves the default writable model cache to platform-native user data locations on macOS and Linux. The active `v1.0.0` ONNX model asset set is unchanged.
+
+Earlier `0.2.x` releases improved runtime-side formula post-processing without changing the active `v1.0.0` ONNX model asset set. They keep compact fraction expressions whole, avoid splitting matrix-like wide formulas, add relation-aware `aligned` output, and retry severe segmented-line artifacts with safer whole-line or whole-image recognition.
+
+Earlier `0.2.x` releases updated the runtime-side formula recognition path with line-aware formula splitting and reassembly. This improved long multi-line formula handling without changing the active `v1.0.0` ONNX model asset set.
+
+## Model Set
+
+Active release: `v1.0.0`
+
+| Model ID | Runtime | Purpose |
+| --- | --- | --- |
+| `mathcraft-formula-det` | ONNX | Mathematical formula region detection |
+| `mathcraft-formula-rec` | ONNX | Formula-to-LaTeX recognition |
+| `mathcraft-text-det` | ONNX | Fast multilingual text detection |
+| `mathcraft-text-rec` | ONNX | Fast multilingual text recognition |
+
+Release assets:
+
+```text
+mathcraft-formula-det.zip
+mathcraft-formula-rec.zip
+mathcraft-text-det.zip
+mathcraft-text-rec.zip
+SHA256SUMS.txt
+```
+
+Default writable model root:
+
+```text
+Windows: %APPDATA%\MathCraft\models
+macOS: ~/Library/Application Support/LaTeXSnipper/MathCraft/models
+Linux: ${XDG_DATA_HOME:-~/.local/share}/LaTeXSnipper/MathCraft/models
+```
+
+The runtime checks the manifest before initialization. Missing or incomplete model folders are repaired automatically by downloading only the affected model asset.
+
+Interrupted downloads are resumable. Partial archives are stored under the active writable model root:
+
+```text
+<MATHCRAFT_HOME>\.downloads\<model_id>.zip.part
+```
+
+After a model archive is fully downloaded, verified, and extracted, the `.part` file is removed automatically.
+
+## Results
+
+The examples below are generated from MathCraft's structured block output. Boxes show detected roles, order, column metadata, score, and layout flags.
+
+### Abstract Algebra, page 18
+
+Formula-heavy English mathematical prose with dense inline and display formulae.
+
+<img width="1700" height="2200" alt="debug_blocks" src="https://github.com/user-attachments/assets/855d0694-4068-4e32-ac5e-80f0c4178332" />
+
+### Dynamics journal, page 5
+
+Formula-dominant journal page with display equations, anchors, labels, headers, and page numbers.
+
+<img width="1700" height="2200" alt="debug_blocks" src="https://github.com/user-attachments/assets/b1498ee9-32fd-4d56-bbfb-876881758587" />
+
+### Chinese lecture note, page 1
+
+Chinese mathematical document page with mixed text and formula blocks.
+
+<img width="1654" height="2339" alt="debug_blocks" src="https://github.com/user-attachments/assets/5d153b2d-d089-4ee2-9ee7-c7f52eb099c9" />
+
+### Limits and series, page 1
+
+Sparse title/cover-style page used to check layout stability.
+
+<img width="1221" height="1898" alt="debug_blocks" src="https://github.com/user-attachments/assets/6c6404e0-bea4-4811-b135-feff3a063a18" />
+
+## Benchmark Snapshot
+
+Local `block_layout_regression_v4` telemetry:
+
+| Metric | Value |
+| --- | ---: |
+| Pages | 10 |
+| Total blocks | 495 |
+| Text characters | 21,417 |
+| Markdown lines | 304 |
+| Mean page time | 8.34 s |
+| Fastest page | 1.33 s |
+| Slowest page | 18.53 s |
+
+Environment:
+
+```text
+Provider: CUDAExecutionProvider
+Runtime: MathCraft OCR v1
+Backend: ONNX Runtime
+```
+
+## Why It Is Stable
+
+- ONNX Runtime only, no active PyTorch inference dependency.
+- Stable MathCraft-owned model IDs and folders.
+- Manifest-based file checks and cache repair.
+- Resumable model downloads for slow or interrupted networks.
+- Formula detection before text OCR.
+- Structured blocks for headings, paragraphs, display formulae, headers, page numbers, and columns.
+
+## LaTeXSnipper
+
+LaTeXSnipper already integrates MathCraft OCR. Normal users do not need to install this package manually. 

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/README_MATHCRAFT_OCR.md

@@ -93,10 +93,12 @@ mathcraft worker --provider auto
 
 ## Model Cache
 
-MathCraft reads models from:
+MathCraft reads models from a platform-specific default user data root:
 
 ```text
-%APPDATA%\MathCraft\models
+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:
@@ -123,7 +125,9 @@ mathcraft doctor --provider auto
 Open a new PowerShell window after removing the persistent variable. The default root is:
 
 ```text
-%APPDATA%\MathCraft\models
+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`.

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/mathcraft_ocr/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 __all__ = [
     "DoctorReport",

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/mathcraft_ocr/cache.py

@@ -14,7 +14,11 @@ def default_user_models_dir() -> Path:
     appdata = os.environ.get("APPDATA", "")
     if appdata:
         return Path(appdata) / "MathCraft" / "models"
-    return Path.home() / ".mathcraft" / "models"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "LaTeXSnipper" / "MathCraft" / "models"
+    xdg_data_home = os.environ.get("XDG_DATA_HOME", "").strip()
+    data_root = Path(xdg_data_home) if xdg_data_home else Path.home() / ".local" / "share"
+    return data_root / "LaTeXSnipper" / "MathCraft" / "models"
 
 
 def resolve_user_models_dir(cache_dir: str | Path | None = None) -> Path:

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/mathcraft_ocr/hardware.py

@@ -8,6 +8,7 @@ from functools import lru_cache
 import json
 import os
 import subprocess
+import sys
 
 from .providers import GPU_PROVIDER_NAMES, ProviderInfo
 
@@ -25,7 +26,7 @@ class HardwareInfo:
 
 @lru_cache(maxsize=1)
 def detect_hardware_info() -> HardwareInfo:
-    total_mb, free_mb = _windows_memory_status()
+    total_mb, free_mb = _memory_status()
     gpu_name, gpu_total_mb, gpu_free_mb, gpu_driver = _query_nvidia_smi()
     if not gpu_name:
         gpu_name, gpu_total_mb, gpu_driver = _query_windows_video_controller()
@@ -40,6 +41,79 @@ def detect_hardware_info() -> HardwareInfo:
     )
 
 
+def _memory_status() -> tuple[int, int]:
+    for probe in (_psutil_memory_status, _windows_memory_status, _posix_memory_status):
+        total_mb, free_mb = probe()
+        if total_mb > 0:
+            if free_mb <= 0:
+                _, macos_free_mb = _macos_vm_stat_memory_status()
+                free_mb = macos_free_mb
+            return total_mb, free_mb
+    return 0, 0
+
+
+def _psutil_memory_status() -> tuple[int, int]:
+    try:
+        import psutil  # type: ignore[import-not-found]
+
+        mem = psutil.virtual_memory()
+        return _bytes_to_mb(int(mem.total)), _bytes_to_mb(int(mem.available))
+    except Exception:
+        return 0, 0
+
+
+def _posix_memory_status() -> tuple[int, int]:
+    if os.name == "nt":
+        return 0, 0
+    try:
+        page_size = int(os.sysconf("SC_PAGE_SIZE"))
+        phys_pages = int(os.sysconf("SC_PHYS_PAGES"))
+    except Exception:
+        return 0, 0
+    total_mb = _bytes_to_mb(page_size * phys_pages)
+    free_mb = 0
+    try:
+        avail_pages = int(os.sysconf("SC_AVPHYS_PAGES"))
+        free_mb = _bytes_to_mb(page_size * avail_pages)
+    except Exception:
+        pass
+    return total_mb, free_mb
+
+
+def _macos_vm_stat_memory_status() -> tuple[int, int]:
+    if sys.platform != "darwin":
+        return 0, 0
+    try:
+        proc = subprocess.run(
+            ["vm_stat"],
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=2.0,
+        )
+    except Exception:
+        return 0, 0
+    if proc.returncode != 0:
+        return 0, 0
+    page_size = 4096
+    free_pages = 0
+    for raw_line in proc.stdout.splitlines():
+        line = raw_line.strip()
+        if line.startswith("Mach Virtual Memory Statistics:") and "page size of" in line:
+            page_size = _safe_int(line.rsplit("page size of", 1)[-1].split("bytes", 1)[0])
+            if page_size <= 0:
+                page_size = 4096
+            continue
+        if line.startswith(("Pages free:", "Pages inactive:", "Pages speculative:")):
+            value = line.split(":", 1)[-1].strip().rstrip(".")
+            free_pages += _safe_int(value)
+    if free_pages <= 0:
+        return 0, 0
+    return 0, _bytes_to_mb(page_size * free_pages)
+
+
 def choose_rec_batch_num(
     provider_info: ProviderInfo,
     hardware: HardwareInfo | None = None,
@@ -198,6 +272,10 @@ def _windows_memory_status() -> tuple[int, int]:
 
 def _safe_int(value: str) -> int:
     try:
-        return int(float(str(value).strip()))
+        return int(float(str(value).strip().replace(",", "")))
     except Exception:
         return 0
+
+
+def _bytes_to_mb(value: int) -> int:
+    return max(0, int(value) // (1024 * 1024))

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3/mathcraft_ocr.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mathcraft-ocr
-Version: 0.2.2
+Version: 0.2.3
 Summary: ONNX-only OCR runtime for mathematical documents
 Author: SakuraMathcraft
 License-Expression: MIT
@@ -139,10 +139,12 @@ mathcraft worker --provider auto
 
 ## Model Cache
 
-MathCraft reads models from:
+MathCraft reads models from a platform-specific default user data root:
 
 ```text
-%APPDATA%\MathCraft\models
+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:
@@ -169,7 +171,9 @@ mathcraft doctor --provider auto
 Open a new PowerShell window after removing the persistent variable. The default root is:
 
 ```text
-%APPDATA%\MathCraft\models
+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`.

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/mathcraft_ocr.egg-info/SOURCES.txt

@@ -1,8 +1,8 @@
 LICENSE
 MANIFEST.in
+README.md
 README_MATHCRAFT_OCR.md
 pyproject.toml
-readme.md
 mathcraft_ocr/__init__.py
 mathcraft_ocr/__main__.py
 mathcraft_ocr/api.py

{mathcraft_ocr-0.2.2 → mathcraft_ocr-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mathcraft-ocr"
-version = "0.2.2"
+version = "0.2.3"
 description = "ONNX-only OCR runtime for mathematical documents"
 readme = "README_MATHCRAFT_OCR.md"
 requires-python = ">=3.10"
@@ -79,17 +79,13 @@ exclude = ["src*", "test*", "scripts*", "docs*", "release_assets*", "build*", "d
 [tool.setuptools.package-data]
 mathcraft_ocr = ["manifests/*.json"]
 
-[tool.pytest.ini_options]
-pythonpath = ["src"]
-testpaths = ["test"]
-addopts = ["--ignore=python311", "--ignore=tools/deps", "--ignore=.venv", "--ignore=build", "--ignore=dist"]
-
 [tool.vulture]
 paths = ["src"]
 exclude = [
   "build/",
   "python311/",
-  "tools/deps/python311/"
+  "src/deps/python311/",
+  "src/get-pip.py"
 ]
 min_confidence = 70
 sort_by_size = true

mathcraft_ocr-0.2.2/readme.md

@@ -1,389 +0,0 @@
-# LaTeXSnipper ✨
-
-<div align="center">
-
-> A desktop math workspace for **capture -> recognize -> handwrite -> edit -> compute**
-<img width="1919" height="1020" alt="封面" src="https://github.com/user-attachments/assets/9d00310b-d1b6-4321-b961-8837b3efb864" />
-
-![Stars](https://img.shields.io/github/stars/SakuraMathcraft/LaTeXSnipper?style=flat-square&label=Stars&color=FFD700)
-![Forks](https://img.shields.io/github/forks/SakuraMathcraft/LaTeXSnipper?style=flat-square&label=Forks&color=1f6feb)
-![Issues](https://img.shields.io/github/issues/SakuraMathcraft/LaTeXSnipper?style=flat-square&label=Issues&color=d1481e)
-![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)
-![Version](https://img.shields.io/badge/version-v2.3.2_Final_Stable-brightgreen?style=flat-square)
-![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-orange?style=flat-square)
-![Python](https://img.shields.io/badge/python-3.11-blue?style=flat-square)
-
-[![GitHub Release](https://img.shields.io/github/v/release/SakuraMathcraft/LaTeXSnipper?style=flat-square&include_prereleases)](https://github.com/SakuraMathcraft/LaTeXSnipper/releases)
-[![Last Commit](https://img.shields.io/github/last-commit/SakuraMathcraft/LaTeXSnipper?style=flat-square)](https://github.com/SakuraMathcraft/LaTeXSnipper/commits)
-[![Activity](https://img.shields.io/github/commit-activity/m/SakuraMathcraft/LaTeXSnipper?style=flat-square&label=Activity)](https://github.com/SakuraMathcraft/LaTeXSnipper/graphs/commit-activity)
-
-[FAQ](docs/faq.md) · [Releases](https://github.com/SakuraMathcraft/LaTeXSnipper/releases)
-
-### Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=SakuraMathcraft/LaTeXSnipper&type=Date)](https://star-history.com/#SakuraMathcraft/LaTeXSnipper&Date)
-
-</div>
-
----
-
-## Overview
-
-**LaTeXSnipper** is no longer just a "screenshot formula -> LaTeX" utility.
-It is a desktop workspace built for end-to-end math content workflows:
-
-- Capture and recognize mathematical content from screenshots
-- Continue editing and computing in the integrated math workbench
-- Handwrite expressions in a dedicated canvas and convert to LaTeX
-- Send results back to the main editor or copy to clipboard
-
----
-
-## Feature Walkthrough
-
-### Math Workbench
-
-<img width="1308" height="834" alt="数学工作台-暗色" src="https://github.com/user-attachments/assets/320a84b3-293d-4947-bc95-fbac88b1f664" />
-
-The Math Workbench supports a complete workflow:
-
-1. Capture and recognize formulas from the main window
-2. Load results into the workbench in one click
-3. Edit expressions in the `MathLive` area
-4. Use the virtual math keyboard for fractions, superscripts, integrals, series, and more
-5. Run `Compute / Simplify / Numeric / Expand / Factor / Solve`
-6. Write results back to the editor or copy as LaTeX / MathJSON
-
-### Auto Typesetting Document Window
-
-<img width="1919" height="1014" alt="v2 3深色" src="https://github.com/user-attachments/assets/c6dffd39-26d9-4e54-aba9-a4b010d3603e" />
-
-The Auto Typesetting Document Window supports source-level editing with synchronized preview:
-
-1. Open "Auto Typesetting" from the handwriting window
-2. Edit full source in the left `TeX Document` pane
-3. Insert complex expressions with the built-in formula editor
-4. Compile and preview PDF directly
-5. Navigate bi-directionally between source and PDF via SyncTeX
-6. Export `.tex` or `PDF` when needed
-
-### Handwriting Recognition
-
-<img width="1408" height="916" alt="手写识别readme" src="https://github.com/user-attachments/assets/3fe98e41-218e-452c-96c1-cc805ab3e0f2" />
-
-The handwriting window supports the following flow:
-
-1. Open "Handwriting Recognition" from the main window
-2. Write formulas directly on an isolated canvas
-3. Trigger MathCraft mixed OCR automatically after pen-up, so handwritten text and formulas can be kept together
-4. See live `LaTeX output` and rendered preview on the right
-5. Use "Auto Typesetting" when handwritten notes contain document text, Chinese or English labels, and multi-line formulas
-6. Copy LaTeX directly or insert it back into the main editor
-
-### PDF Recognition and Bilingual Reading
-
-The main window includes PDF recognition and a separate bilingual reading tool:
-
-1. Use "PDF Recognition" to select page count, output format, and render DPI
-2. Built-in MathCraft PDF recognition uses mixed mode for text and formula recovery
-3. External PDF recognition supports OpenAI-compatible, Ollama, and MinerU providers
-4. Save editable Markdown or LaTeX results from the PDF result window
-5. Use "Bilingual Reading" to open a text-layer PDF, view the current page, and translate with Argos, Azure, Google Cloud, or DeepL
-
----
-
-## Core Features
-
-| Feature | Description |
-|------|------|
-| 📸 Formula recognition | MathCraft OCR for formulas, text, and mixed content |
-| 📄 PDF recognition | Page-based PDF recognition with Markdown/LaTeX output and DPI control |
-| 🌐 Bilingual reading | PDF text-layer reading with local Argos or remote translation engines |
-| ✍️ Handwriting recognition | Dedicated handwriting window with auto-recognition and live preview |
-| 🧮 Math workbench | Separate workspace for editing, computation, and write-back |
-| ⌨️ Formula editing | Integrated `MathLive math-field` with virtual math keyboard |
-| 🔄 Multi-format export | 30 export choices across LaTeX, Markdown, MathML, HTML, OMML, SVG, Typst, Word, EPUB, RTF, wiki formats, and more |
-| 📐 Core computation | Compute, simplify, numeric evaluate, expand, factor, solve |
-| 🧠 Advanced fallback | Local `SymPy/mpmath` engine for harder expressions |
-| 🌙 Theme support | Light/Dark adaptation across windows and tools |
-| 🔐 Offline-first | Recognition and advanced solving can run locally for privacy |
-
----
-
-## Computation Coverage
-
-The workbench currently covers common scenarios such as:
-
-- Polynomial expansion
-- Factorization
-- Equation solving
-- Irrational/complex root fallback solving
-- Definite and improper integrals
-- Infinite series
-- Infinite products
-- Limits
-- Derivatives
-- Numeric approximation and constant recognition
-
-For heavy expressions, the engine uses automatic fallback:
-
-1. Try frontend `Compute Engine` first
-2. Switch to local advanced engine on timeout/failure/unreliable results
-3. Use `SymPy/mpmath` for robust fallback
-4. Recover closed forms for selected known constants from numeric output
-
----
-
-## Export Formats
-
-LaTeXSnipper exposes a shared export menu in the main window and favorites window.
-
-Built-in formula export formats:
-
-- LaTeX inline, display, and equation
-- Markdown inline and block math
-- MathML standard, `.mml`, `<m>`, and attribute forms
-- HTML, Word OMML, and SVG code
-
-Optional Pandoc export formats are enabled after installing the `PANDOC` layer in the dependency wizard:
-
-- Word `.docx`, ODT `.odt`, EPUB `.epub`, InDesign `.icml`
-- RTF, plain text, standalone HTML, LaTeX `.tex`, Typst `.typ`
-- GitHub Markdown, CommonMark, reStructuredText
-- MediaWiki, DokuWiki, Org-mode, Textile, Jira Wiki, and man page output
-
-Pandoc is optional. If it is not installed, the core recognition, editing, handwriting, preview, and built-in export formats continue to work normally.
-
----
-
-## Quick Start
-
-### Option 1: Download the executable
-
-1. Visit the [Releases page](https://github.com/SakuraMathcraft/LaTeXSnipper/releases)
-2. Download the latest `LaTeXSnipperSetup-<version>.exe`
-3. Run the installer
-4. Complete environment setup via the dependency wizard on first launch
-5. Start capturing, handwriting, or using the math workbench
-
-### Option 2: Run from source
-
-Windows:
-
-```bash
-git clone https://github.com/SakuraMathcraft/LaTeXSnipper.git
-cd LaTeXSnipper
-
-python -m venv .venv
-.\.venv\Scripts\activate
-
-pip install -r requirements.txt
-python src/main.py
-```
-
-Linux:
-
-```bash
-git clone https://github.com/SakuraMathcraft/LaTeXSnipper.git
-cd LaTeXSnipper
-
-python3 -m venv .venv
-source .venv/bin/activate
-
-pip install -r requirements-linux.txt
-python src/main.py
-```
-
-macOS:
-
-```bash
-git clone https://github.com/SakuraMathcraft/LaTeXSnipper.git
-cd LaTeXSnipper
-
-python3 -m venv .venv
-source .venv/bin/activate
-
-pip install -r requirements-macos.txt
-python src/main.py
-```
-
----
-
-## Platform Support
-
-| Platform | Status | Notes |
-|------|------|------|
-| Windows | Primary release target | Native global hotkey, Qt capture, GitHub/Inno and Store/MSIX packaging. |
-| Linux | Supported via provider layer | `pynput` global hotkey, Qt capture first, optional Wayland/X11 CLI or portal fallbacks. |
-| macOS | Supported via provider layer | Native global hotkey, Qt capture with `screencapture` fallback, Screen Recording permission may be required. |
-
-Close/background behavior follows each desktop platform. Windows hides the main
-window to the system tray when it is closed. Linux does the same when a system
-tray is available, and asks before exiting if no tray is available. macOS keeps
-the app running when the main window is closed/minimized; Dock or menu Quit is
-the explicit exit path. The macOS global hotkey uses Carbon and normally does
-not require Accessibility permission, while screenshot capture requires Screen
-Recording permission.
-
-The dependency wizard manages Python dependency layers only. It does not install
-or uninstall system packages. On Linux, tools such as `grim`, `maim`, and
-`gnome-screenshot` can improve screenshot fallback behavior, but they are
-installed by the user or distribution package manager, not by LaTeXSnipper.
-The default screenshot shortcut is `Ctrl+F` on all three platforms. The shortcut
-setting currently accepts `Ctrl+letter` and `Ctrl+Shift+letter` combinations so
-custom shortcuts remain inside the cross-platform supported set. Linux global
-shortcuts are still subject to desktop environment and Wayland compositor policy.
-Linux and macOS both create optional runtime dependency environments in the
-user state directory, so they need a usable system Python 3.10+ with venv/pip
-support. Debian/Ubuntu `.deb` installs declare `python3` and `python3-venv`;
-macOS users should install Python through Homebrew (`brew install python`) or
-the official python.org macOS installer when the system does not provide a
-usable `python3`.
-The dependency wizard shows its UI before running `ensurepip`, `pip` upgrade,
-or `setuptools`/`wheel` repair; those steps run after the user starts dependency
-installation.
-
-### Packaging
-
-Windows packaging:
-
-- `LaTeXSnipper.spec`
-- `Inno/latexsnipper.iss`
-- `scripts/build_store_msix.ps1`
-
-Linux packaging:
-
-- `LaTeXSnipper-linux.spec`
-- `scripts/build_deb.sh`
-- `packaging/debian/`
-
-macOS packaging:
-
-- `LaTeXSnipper-macos.spec`
-- `scripts/build_macos.sh`
-
-Linux/macOS build scripts prepare isolated, platform-scoped build runtimes under
-`tools/deps/`, for example `tools/deps/python311-linux-x86_64`. The Windows IDE
-interpreter is `tools/deps/python311`. The repository-root `python311` directory
-is treated as a template runtime and must not be mutated by packaging scripts.
-
-GitHub Actions release builds run the platform package jobs in one workflow:
-
-- Windows: Inno installer; SignPath-signed artifact is preferred, with an unsigned fallback when signing is unavailable.
-- Linux: Debian/Ubuntu `.deb` package from `scripts/build_deb.sh`.
-- macOS: `.app.zip` and `.dmg` artifacts from `scripts/build_macos.sh`.
-
-The release workflow expects these GitHub Actions variables:
-`SIGNPATH_ORGANIZATION_ID`, `SIGNPATH_PROJECT_SLUG`,
-`SIGNPATH_SIGNING_POLICY_SLUG`, and
-`SIGNPATH_ARTIFACT_CONFIGURATION_SLUG`. It also requires the
-`SIGNPATH_API_TOKEN` secret. The SignPath artifact configuration is mirrored in
-`.signpath/artifact-configurations/windows-installer.xml`; copy that XML into
-the matching SignPath project artifact configuration.
-
----
-
-## Project Structure
-
-```text
-LaTeXSnipper/
-|-- mathcraft_ocr/                 # Standalone MathCraft OCR runtime and CLI
-|-- src/
-|   |-- main.py                    # Main desktop application entry
-|   |-- backend/                   # OCR wrapper, CUDA diagnostics, capture, platform services
-|   |-- bootstrap/                 # Dependency wizard and runtime verification
-|   |-- capture/                   # Screenshot capture controllers
-|   |-- core/                      # Document composition, export contracts, restart contracts
-|   |-- cross_platform/            # OS-specific screenshot and platform helpers
-|   |-- editor/                    # Math workbench and formula editing UI
-|   |-- exporting/                 # Formula, Markdown, Pandoc, and document export helpers
-|   |-- handwriting/               # Handwriting canvas, PDF preview, document tools
-|   |-- preview/                   # MathJax preview and render helpers
-|   |-- recognition/               # OCR and PDF recognition controllers
-|   |-- runtime/                   # Startup, config, history, logging, distribution, runtime helpers
-|   |-- ui/                        # Main window, settings, dialogs, and UI controllers
-|   |-- update/                    # GitHub release update checks and installer launch flow
-|   |-- workers/                   # Background worker helpers
-|   `-- assets/                    # Icons and bundled web/math resources
-|-- tools/
-|   `-- deps/                      # Local developer/build dependency environment
-|-- user_manual/                   # Local manual source and generated PDF
-|-- Inno/                          # GitHub Release installer scripts
-|-- packaging/                     # Debian and MSIX packaging resources
-|-- scripts/                       # Build, release, and regression utilities
-|-- docs/                          # Design and architecture notes
-|-- LaTeXSnipper.spec              # PyInstaller GitHub build (Windows)
-|-- LaTeXSnipper-linux.spec        # PyInstaller Linux build
-|-- LaTeXSnipper-macos.spec        # PyInstaller macOS build
-|-- pyproject.toml
-|-- requirements.txt
-|-- requirements-linux.txt
-|-- requirements-macos.txt
-|-- requirements-build.txt
-|-- version_info.txt
-`-- README.md
-```
-
----
-
-## Contributing
-
-Contributions are welcome:
-
-1. Fork the repository
-2. Create a feature branch
-3. Commit your changes
-4. Push your branch
-5. Open a Pull Request
-
-All pull requests must follow [Developer Code Standards](docs/developer_code_standards.md).
-Before requesting review, run:
-
-```powershell
-.\tools\deps\python311\python.exe -m ruff check .
-.\tools\deps\python311\python.exe -m pytest test
-.\tools\deps\python311\python.exe -m pyright
-.\tools\deps\python311\python.exe -m compileall -q src mathcraft_ocr test
-```
-
-Cross-platform PRs must not change the Windows dependency surface or installer
-behavior unless Windows is explicitly in scope and separately validated.
-
-Recommended focus areas:
-
-- Handwriting UX
-- Math workbench UX
-- Advanced solver stability
-- Packaged runtime verification
-- Theme consistency across windows
-
----
-
-## License
-
-This project is open-sourced under the [MIT License](LICENSE).
-
----
-
-## Acknowledgements
-
-Special thanks to:
-
-- [pix2tex](https://github.com/lukas-blecher/LaTeX-OCR)
-- [MathLive](https://github.com/arnog/mathlive)
-- [MathLive Compute Engine](https://mathlive.io/compute-engine/)
-- [SymPy](https://www.sympy.org/)
-- [mpmath](https://mpmath.org/)
-- [MathJax](https://www.mathjax.org/)
-- [PyQt6](https://www.riverbankcomputing.com/software/pyqt/)
-- [QFluentWidgets](https://github.com/zhiyiYo/PyQt-Fluent-Widgets)
-
----
-
-<div align="center">
-
-| Download | Issues | Discussions | Wiki |
-|---|---|---|---|
-| [Latest Release](https://github.com/SakuraMathcraft/LaTeXSnipper/releases/latest) | [Open an Issue](https://github.com/SakuraMathcraft/LaTeXSnipper/issues) | [Discussions](https://github.com/SakuraMathcraft/LaTeXSnipper/discussions) | [Project Wiki](https://github.com/SakuraMathcraft/LaTeXSnipper/wiki) |
-
-</div>