trivision-ocr 1.0.0__tar.gz

trivision_ocr-1.0.0/.env.example

@@ -0,0 +1,18 @@
+# ─── Tesseract binary path ───────────────────────────────────────────────────
+# Windows default after winget install UB-Mannheim.TesseractOCR
+TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe
+
+# ─── GPU ─────────────────────────────────────────────────────────────────────
+# Set to "true" only if you have a CUDA-capable GPU + paddlepaddle-gpu installed
+USE_GPU=false
+
+# ─── Super-resolution ────────────────────────────────────────────────────────
+# EDSR 2× upscale — requires models/EDSR_x2.pb (run download_models.py first)
+# Adds ~3–8 seconds on CPU; set to "true" only on GPU or when accuracy is critical
+USE_SUPER_RESOLVE=false
+
+# ─── Models directory ────────────────────────────────────────────────────────
+MODELS_DIR=models
+
+# ─── Optional: pin GPU device ────────────────────────────────────────────────
+# CUDA_VISIBLE_DEVICES=0

trivision_ocr-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## [1.0.0] — 2026-03-22
+
+### Added
+- **PyPI Release**: Rebranded and packaged for PyPI deployment as `trivision-ocr`.
+- **Stage 0 — Adaptive Preprocessor**: Hough-line median deskew (robust on sparse engineering diagrams), CLAHE contrast enhancement, Otsu + adaptive binarization, optional EDSR 2× super-resolution.
+- **Stage 1 — Three-Engine OCR**: Tesseract (LSTM+CTC), PaddleOCR (PP-OCRv5 DBNet+SVTR), EasyOCR (CRAFT+CRNN). GPU engines run sequentially to avoid CUDA context conflicts.
+- **Stage 2 — Confidence-Weighted Voter**: IoU spatial grouping, per-engine weighting, agreement bonus (+15% per agreeing engine).
+- **Stage 3 — Domain Post-Corrector**: SymSpell spell correction with domain vocabulary protection (PRV, FCV, GV, BFP, HDPE, …).
+- Vision API-compatible JSON output with bonus `engine_count` and `confidence` fields.
+- `ocr-pipeline` CLI entry point.
+- `download_models.py` for one-time model file downloads.
+- `setup_venv.bat` for Windows venv bootstrap (CPU default, `gpu` argument for CUDA).
+- `MANIFEST.in` for proper package distribution.
+- Centralised `logger.py` for structured timestamped logging.
+- Unit test suite (`tests/test_voter.py`) — 7 tests, no GPU required.

trivision_ocr-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include .env.example
+include CHANGELOG.md
+include README.md
+recursive-include models *
+recursive-include tests *.png *.jpg *.jpeg *.tiff

trivision_ocr-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: trivision-ocr
+Version: 1.0.0
+Summary: Multi-engine OCR pipeline — beats Google Vision API
+Author-email: Parthasarathy G <parthasarathyg693@gmail.com>
+License: MIT
+Keywords: ocr,tesseract,paddleocr,easyocr,vision-api
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-contrib-python-headless
+Requires-Dist: pytesseract
+Requires-Dist: Pillow
+Requires-Dist: paddleocr
+Requires-Dist: easyocr
+Requires-Dist: symspellpy
+Requires-Dist: numpy
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Provides-Extra: cpu
+Requires-Dist: paddlepaddle; extra == "cpu"
+Provides-Extra: gpu
+Requires-Dist: paddlepaddle-gpu; extra == "gpu"
+Provides-Extra: api
+Requires-Dist: fastapi; extra == "api"
+Requires-Dist: uvicorn[standard]; extra == "api"
+Requires-Dist: python-multipart; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+
+# ocr-pipeline
+
+Multi-engine OCR pipeline combining **Tesseract**, **PaddleOCR**, and **EasyOCR** with confidence-weighted voting and domain-aware spell correction. Output is compatible with the Google Vision API JSON schema.
+
+## Architecture
+
+```
+Image → [Preprocessor] → Tesseract ┐
+                       → PaddleOCR ├─→ [Voter] → [Corrector] → Vision API JSON
+                       → EasyOCR   ┘
+```
+
+| Stage | What it does | Your edge vs Vision API |
+|---|---|---|
+| 0 — Preprocessor | Hough deskew, CLAHE, binarize, optional 2× EDSR | Domain-specific prep; Vision API gets raw images |
+| 1 — Three engines | Tesseract (LSTM), PaddleOCR (DBNet+SVTR), EasyOCR (CRAFT+CRNN) | Different failure modes → ensemble eliminates each |
+| 2 — Voter | IoU spatial grouping + weighted confidence + agreement bonus | Cross-engine consensus exposed; Vision API hides this |
+| 3 — Corrector | SymSpell + domain vocabulary protection | Tuned to your label vocabulary; Vision API uses general LM |
+
+## Prerequisites
+
+**Tesseract binary (Windows — required):**
+```powershell
+winget install UB-Mannheim.TesseractOCR
+```
+
+**Python 3.10+** must be installed and on PATH.
+
+## Quick Start
+
+```powershell
+# 1. Clone / copy the project
+cd ocr-pipeline
+
+# 2. Create virtual environment and install (CPU default)
+setup_venv.bat
+
+# For GPU (CUDA + paddlepaddle-gpu):
+setup_venv.bat gpu
+
+# 3. Activate
+.venv\Scripts\activate
+
+# 4. Run on an image
+ocr-pipeline path\to\image.jpg --pretty
+
+# Save output to file
+ocr-pipeline path\to\image.jpg --output result.json
+
+# Text only
+ocr-pipeline path\to\image.jpg --text-only
+
+# Skip super-resolution (faster, no EDSR model needed)
+ocr-pipeline path\to\image.jpg --no-super-resolve
+```
+
+## Python API
+
+```python
+from ocr_pipeline import beat_vision_api
+
+result = beat_vision_api("path/to/image.jpg")
+print(result["responses"][0]["fullTextAnnotation"]["text"])
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and edit:
+
+```env
+TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe
+USE_GPU=false
+USE_SUPER_RESOLVE=false
+```
+
+Add project-specific label codes to `DOMAIN_TERMS` in `ocr_pipeline/config.py`.
+
+## Running Tests
+
+```powershell
+pytest tests/test_voter.py -v
+```
+
+All 7 tests run without GPU or model downloads.
+
+## Optional: Super-Resolution
+
+EDSR 2× upscale (~143 MB model) significantly improves small text on diagram scans. Enable it:
+
+1. Run `python download_models.py` and choose `y` when prompted for EDSR
+2. Set `USE_SUPER_RESOLVE=true` in `.env`
+
+## Project Structure
+
+```
+ocr-pipeline/
+├── ocr_pipeline/       ← Python package
+│   ├── config.py       ← All tunable parameters
+│   ├── preprocessor.py ← Stage 0
+│   ├── engines.py      ← Stage 1
+│   ├── voter.py        ← Stage 2
+│   ├── corrector.py    ← Stage 3
+│   └── pipeline.py     ← Orchestration
+├── tests/
+│   └── test_voter.py   ← Unit tests (no GPU)
+├── models/             ← Downloaded model files
+├── setup_venv.bat      ← Windows setup
+└── download_models.py  ← Model downloader
+```

trivision_ocr-1.0.0/README.md

@@ -0,0 +1,109 @@
+# ocr-pipeline
+
+Multi-engine OCR pipeline combining **Tesseract**, **PaddleOCR**, and **EasyOCR** with confidence-weighted voting and domain-aware spell correction. Output is compatible with the Google Vision API JSON schema.
+
+## Architecture
+
+```
+Image → [Preprocessor] → Tesseract ┐
+                       → PaddleOCR ├─→ [Voter] → [Corrector] → Vision API JSON
+                       → EasyOCR   ┘
+```
+
+| Stage | What it does | Your edge vs Vision API |
+|---|---|---|
+| 0 — Preprocessor | Hough deskew, CLAHE, binarize, optional 2× EDSR | Domain-specific prep; Vision API gets raw images |
+| 1 — Three engines | Tesseract (LSTM), PaddleOCR (DBNet+SVTR), EasyOCR (CRAFT+CRNN) | Different failure modes → ensemble eliminates each |
+| 2 — Voter | IoU spatial grouping + weighted confidence + agreement bonus | Cross-engine consensus exposed; Vision API hides this |
+| 3 — Corrector | SymSpell + domain vocabulary protection | Tuned to your label vocabulary; Vision API uses general LM |
+
+## Prerequisites
+
+**Tesseract binary (Windows — required):**
+```powershell
+winget install UB-Mannheim.TesseractOCR
+```
+
+**Python 3.10+** must be installed and on PATH.
+
+## Quick Start
+
+```powershell
+# 1. Clone / copy the project
+cd ocr-pipeline
+
+# 2. Create virtual environment and install (CPU default)
+setup_venv.bat
+
+# For GPU (CUDA + paddlepaddle-gpu):
+setup_venv.bat gpu
+
+# 3. Activate
+.venv\Scripts\activate
+
+# 4. Run on an image
+ocr-pipeline path\to\image.jpg --pretty
+
+# Save output to file
+ocr-pipeline path\to\image.jpg --output result.json
+
+# Text only
+ocr-pipeline path\to\image.jpg --text-only
+
+# Skip super-resolution (faster, no EDSR model needed)
+ocr-pipeline path\to\image.jpg --no-super-resolve
+```
+
+## Python API
+
+```python
+from ocr_pipeline import beat_vision_api
+
+result = beat_vision_api("path/to/image.jpg")
+print(result["responses"][0]["fullTextAnnotation"]["text"])
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and edit:
+
+```env
+TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe
+USE_GPU=false
+USE_SUPER_RESOLVE=false
+```
+
+Add project-specific label codes to `DOMAIN_TERMS` in `ocr_pipeline/config.py`.
+
+## Running Tests
+
+```powershell
+pytest tests/test_voter.py -v
+```
+
+All 7 tests run without GPU or model downloads.
+
+## Optional: Super-Resolution
+
+EDSR 2× upscale (~143 MB model) significantly improves small text on diagram scans. Enable it:
+
+1. Run `python download_models.py` and choose `y` when prompted for EDSR
+2. Set `USE_SUPER_RESOLVE=true` in `.env`
+
+## Project Structure
+
+```
+ocr-pipeline/
+├── ocr_pipeline/       ← Python package
+│   ├── config.py       ← All tunable parameters
+│   ├── preprocessor.py ← Stage 0
+│   ├── engines.py      ← Stage 1
+│   ├── voter.py        ← Stage 2
+│   ├── corrector.py    ← Stage 3
+│   └── pipeline.py     ← Orchestration
+├── tests/
+│   └── test_voter.py   ← Unit tests (no GPU)
+├── models/             ← Downloaded model files
+├── setup_venv.bat      ← Windows setup
+└── download_models.py  ← Model downloader
+```

trivision_ocr-1.0.0/ocr_pipeline/__init__.py

@@ -0,0 +1,20 @@
+"""
+ocr_pipeline — Multi-engine OCR pipeline.
+
+Top-level public API:
+    from ocr_pipeline import beat_vision_api
+    result = beat_vision_api("path/to/image.jpg")
+
+The pipeline import is lazy so that lightweight submodules (voter, config)
+can be imported in test environments without requiring all heavy ML deps.
+"""
+
+__version__ = "1.0.0"
+__all__ = ["beat_vision_api"]
+
+
+def __getattr__(name: str):
+    if name == "beat_vision_api":
+        from .pipeline import beat_vision_api  # noqa: PLC0415
+        return beat_vision_api
+    raise AttributeError(f"module 'ocr_pipeline' has no attribute {name!r}")

trivision_ocr-1.0.0/ocr_pipeline/config.py

@@ -0,0 +1,97 @@
+"""
+config.py — Central configuration for the OCR pipeline.
+
+Loads .env file automatically (via python-dotenv) so that TESSERACT_CMD and
+other settings work reliably on a fresh machine without needing system env vars.
+Import this module first in any other module — it also sets the Tesseract
+binary path so pytesseract works on Windows without extra setup.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytesseract
+from dotenv import load_dotenv
+
+# Load .env from the project root (two levels up from this file)
+_PROJECT_ROOT = Path(__file__).parent.parent
+load_dotenv(_PROJECT_ROOT / ".env", override=False)
+
+# ─── Tesseract binary (Windows) ──────────────────────────────────────────────
+# Set TESSERACT_CMD in .env or as a system env var to override.
+TESSERACT_CMD: str = os.environ.get(
+    "TESSERACT_CMD",
+    r"C:\Program Files\Tesseract-OCR\tesseract.exe",
+)
+pytesseract.pytesseract.tesseract_cmd = TESSERACT_CMD  # applied at import time
+
+# ─── Runtime flags ───────────────────────────────────────────────────────────
+USE_GPU: bool = os.environ.get("USE_GPU", "false").lower() == "true"
+USE_SUPER_RESOLVE: bool = os.environ.get("USE_SUPER_RESOLVE", "false").lower() == "true"
+
+# ─── Paths (pathlib — no hardcoded strings) ──────────────────────────────────
+MODELS_DIR: Path = Path(os.environ.get("MODELS_DIR", str(_PROJECT_ROOT / "models")))
+EDSR_MODEL_PATH: str = str(MODELS_DIR / "EDSR_x2.pb")
+SYMSPELL_DICT_PATH: str = str(MODELS_DIR / "frequency_dictionary_en_82_765.txt")
+
+# ─── Engine weights ──────────────────────────────────────────────────────────
+ENGINE_WEIGHTS: dict[str, float] = {
+    "paddleocr": 0.45,
+    "easyocr":   0.35,
+    "tesseract": 0.20,
+}
+
+# ─── Voter parameters ────────────────────────────────────────────────────────
+MIN_CONFIDENCE: float = 0.05
+IOU_THRESHOLD: float = 0.20
+TEXT_SIMILARITY_THRESHOLD: float = 0.80
+AGREEMENT_BONUS: float = 0.15
+MIN_TESSERACT_CONF: int = 0
+
+# ─── Preprocessing parameters ────────────────────────────────────────────────
+CLAHE_CLIP_LIMIT: float = 3.0
+CLAHE_TILE_GRID: tuple[int, int] = (8, 8)
+ADAPTIVE_BLOCK_SIZE: int = 31
+ADAPTIVE_C: int = 10
+
+HOUGH_THRESHOLD: int = 80
+HOUGH_MIN_LINE_LENGTH: int = 50
+HOUGH_MAX_LINE_GAP: int = 10
+HOUGH_MAX_ANGLE: float = 45.0
+
+# ─── Domain vocabulary ───────────────────────────────────────────────────────
+DOMAIN_TERMS: set[str] = {
+    "PRV", "FCV", "GV", "BFP", "MH", "DMH", "SV", "WM",
+    "HDPE", "DI", "MDIA", "NRV", "ARV", "PSV", "RFV",
+    "DN", "PN", "ID", "OD", "PVC", "GRP", "PE",
+    "GATE", "VALVE", "SLUICE", "BUTTERFLY", "CHECK", "BALL", "GLOBE",
+    "MANHOLE", "CHAMBER", "JUNCTION", "TEE", "BEND", "REDUCER",
+}
+
+# ─── SymSpell parameters ─────────────────────────────────────────────────────
+SYMSPELL_MAX_EDIT_DISTANCE: int = 2
+SYMSPELL_MIN_FREQUENCY: int = 50000
+
+# ─── OCR confusion aliases ───────────────────────────────────────────────────
+DOMAIN_MISREADS: dict[str, str] = {
+    "HOPE":  "HDPE",
+    "HDFE":  "HDPE",
+    "PNI6":  "PN16",
+    "PNI":   "PN1",
+    "BFP-S": "BFP-3",
+    "MHS":   "MH-5",
+    "MH5":   "MH-5",
+    "DN3OO": "DN300",
+}
+
+# ─── API auth ────────────────────────────────────────────────────────────────
+API_KEYS: set[str] = set(
+    k.strip()
+    for k in os.environ.get("API_KEYS", "").split(",")
+    if k.strip()
+)
+
+# ─── Benchmark / logging ─────────────────────────────────────────────────────
+LOG_LEVEL: str = os.environ.get("LOG_LEVEL", "INFO").upper()

trivision_ocr-1.0.0/ocr_pipeline/corrector.py

@@ -0,0 +1,91 @@
+"""
+corrector.py — Stage 3: Domain-aware SymSpell post-corrector.
+
+Post-processes voted OCR results by spell-correcting general English tokens
+while NEVER modifying domain-specific terms (valve codes, pipe labels, etc.).
+
+Logic per token:
+  1. Skip if the token is in DOMAIN_TERMS (any case normalisation applied).
+  2. Skip if the token looks like a numeric/alphanumeric code (e.g. "DN300").
+  3. Apply SymSpell with edit-distance ≤ 2; only accept suggestions with
+     high corpus frequency (avoids over-correcting rare but valid words).
+"""
+
+from __future__ import annotations
+
+import re
+
+from symspellpy import SymSpell, Verbosity
+
+from . import config
+
+# ── Initialise SymSpell once at module level ─────────────────────────────────
+_sym_spell: SymSpell | None = None
+
+
+def _get_sym_spell() -> SymSpell:
+    global _sym_spell
+    if _sym_spell is None:
+        _sym_spell = SymSpell(max_dictionary_edit_distance=config.SYMSPELL_MAX_EDIT_DISTANCE)
+        if not _sym_spell.load_dictionary(
+            config.SYMSPELL_DICT_PATH,
+            term_index=0,
+            count_index=1,
+        ):
+            print(
+                f"[WARN] SymSpell dictionary not found at {config.SYMSPELL_DICT_PATH}. "
+                "Run download_models.py. Spell correction disabled."
+            )
+            # Return an initialised-but-empty SymSpell so callers don't crash
+    return _sym_spell
+
+
+# ── Numeric / code pattern — never correct these tokens ──────────────────────
+_CODE_PATTERN = re.compile(r"^\d+[\w/\-]*$|^[\w/\-]*\d+[\w/\-]*$")
+
+
+def correct_token(token: str) -> str:
+    """
+    Correct a single OCR token, respecting domain vocabulary.
+
+    Returns the original token unchanged if:
+    - It matches a domain term (case-insensitive look-up)
+    - It looks like a numeric/alphanumeric code (e.g. "DN300", "2B-PRV")
+    """
+    upper = token.upper()
+    if upper in config.DOMAIN_TERMS:
+        return token
+    if upper in config.DOMAIN_MISREADS:
+        return config.DOMAIN_MISREADS[upper]
+
+    # Numeric / code pattern check
+    if _CODE_PATTERN.match(token):
+        return token
+
+    sym = _get_sym_spell()
+    suggestions = sym.lookup(
+        token,
+        Verbosity.CLOSEST,
+        max_edit_distance=config.SYMSPELL_MAX_EDIT_DISTANCE,
+        include_unknown=True,
+    )
+
+    if suggestions:
+        best = suggestions[0]
+        # Only accept if the correction is well attested in general English
+        if best.count >= config.SYMSPELL_MIN_FREQUENCY:
+            return best.term
+
+    return token
+
+
+def post_correct(voted_results: list[dict]) -> list[dict]:
+    """
+    Apply ``correct_token`` to every token in every result entry.
+
+    Modifies results in-place and also returns the list.
+    """
+    for item in voted_results:
+        tokens = item["text"].split()
+        item["text"] = " ".join(correct_token(t) for t in tokens)
+    return voted_results