docorient 0.3.2__tar.gz → 0.4.0__tar.gz

docorient-0.4.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.4.0 (2026-02-27)
+
+- **Breaking:** remove Tesseract/pytesseract dependency entirely
+- **Breaking:** remove `SecondaryEngine`, `TesseractNotAvailableError`, `[ocr]` extra
+- **Breaking:** remove `secondary_confidence_threshold` and `secondary_max_dimension` from `OrientationConfig`
+- Add `FlipClassifierEngine`: MobileNetV2-based ONNX neural network for 180° detection
+- ONNX model (~8.5 MB) ships embedded in the package — no external binaries needed
+- Model trained on 3,000+ diverse document images from 5 public datasets (FUNSD, Invoices & Receipts, CORD-v2, DocLayNet, DocumentVQA)
+- CNN standalone accuracy: 96.8% — combined pipeline accuracy: 98% across all 4 orientations
+- Inference latency: ~5ms per image (CNN) / ~20ms per image (full pipeline)
+- Add `flip_confidence_threshold` to `OrientationConfig`
+- `onnxruntime` is now a core dependency (no longer optional)
+- Detection pipeline now resolves all 4 angles (0°, 90°, 180°, 270°) without external tools
+- Pipeline: PrimaryEngine detects axis (H/V), FlipClassifier resolves flip within each axis
+- Update CLI: remove `--no-secondary` and `--confidence` flags
+- Bump status to "Development Status :: 4 - Beta"
+
+## 0.3.2 (2026-02-27)
+
+- Fix: update project URLs to correct GitHub repository
+- Add changelog link to PyPI metadata
+
+## 0.3.1 (2026-02-27)
+
+- Fix: author metadata corrected to Lucas Gabriel Vaz
+- Remove `tesseract` from PyPI keywords
+
+## 0.3.0 (2026-02-27)
+
+- **Breaking:** detection engines refactored to class-based architecture with `DetectionEngine` Protocol
+- Introduce `DetectionPipeline` for extensible engine orchestration
+- Introduce `PrimaryEngine` and `SecondaryEngine` classes
+- Extract `rotation.py` and `voting.py` as standalone modules
+- Encapsulate worker state in `WorkerContext` dataclass
+- Transform `_imaging.py` functions into `ImageIO` class
+- Decompose `process_directory` into focused sub-functions
+- Apply custom exceptions throughout codebase
+- Export `DetectionEngine`, `DetectionPipeline`, `PrimaryEngine` in public API
+
+## 0.2.0 (2026-02-26)
+
+- **Breaking:** renamed config params and CLI flags for internal engines
+- Updated `OrientationResult.method` trace strings
+
+## 0.1.1 (2026-02-26)
+
+- Docs: added `if __name__ == "__main__":` note for `process_directory` on macOS/Windows
+
+## 0.1.0 (2026-02-25)
+
+- Initial release
+- Primary engine for 90°/270° detection
+- Single image and batch directory processing
+- Multi-page majority voting
+- Resumable batch processing
+- CLI interface

{docorient-0.3.2 → docorient-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docorient
-Version: 0.3.2
+Version: 0.4.0
 Summary: Document image orientation detection and correction.
 Project-URL: Homepage, https://github.com/lucasleirbag/DocOrient
 Project-URL: Repository, https://github.com/lucasleirbag/DocOrient
@@ -9,8 +9,8 @@ Project-URL: Changelog, https://github.com/lucasleirbag/DocOrient/blob/main/CHAN
 Author: Lucas Gabriel Vaz
 License-Expression: MIT
 License-File: LICENSE
-Keywords: correction,document,image,ocr,orientation,rotation
-Classifier: Development Status :: 3 - Alpha
+Keywords: correction,document,image,onnx,orientation,rotation
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -22,6 +22,7 @@ Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.16
 Requires-Dist: pillow>=10.0
 Requires-Dist: tqdm>=4.60
 Provides-Extra: dev
@@ -30,8 +31,6 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
-Provides-Extra: ocr
-Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
 Description-Content-Type: text/markdown
 
 # docorient
@@ -42,7 +41,9 @@ Description-Content-Type: text/markdown
 
 Document image orientation detection and correction.
 
-Automatically detects and fixes rotation (0°, 90°, 180°, 270°) in scanned document images using a two-stage detection pipeline, with support for multi-page majority voting and parallel batch processing.
+Automatically detects and fixes rotation (0°, 90°, 180°, 270°) in scanned document images using a two-stage pipeline: energy-based axis detection + neural network flip classification. Achieves **98% accuracy** across all four orientations. Includes multi-page majority voting and parallel batch processing.
+
+No external dependencies like Tesseract required — the neural model ships embedded in the package (~8.5 MB).
 
 ---
 
@@ -52,18 +53,6 @@ Automatically detects and fixes rotation (0°, 90°, 180°, 270°) in scanned do
 pip install docorient
 ```
 
-To enable full 180° detection:
-
-```bash
-pip install docorient[ocr]
-```
-
-> **Note:** The `[ocr]` extra requires [Tesseract](https://github.com/tesseract-ocr/tesseract) installed on your system.
->
-> - **macOS:** `brew install tesseract`
-> - **Ubuntu/Debian:** `sudo apt install tesseract-ocr`
-> - **Windows:** [installer](https://github.com/UB-Mannheim/tesseract/wiki)
-
 ---
 
 ## Quick Start
@@ -134,26 +123,37 @@ if __name__ == "__main__":
 ```bash
 docorient ./scans --output ./fixed
 docorient ./scans --output ./fixed --workers 4 --quality 95
-docorient ./scans --no-secondary --limit 100
+docorient ./scans --limit 100
 docorient ./scans --dry-run
 docorient --version
 ```
 
 ---
 
+## How It Works
+
+DocOrient uses a two-stage detection pipeline:
+
+1. **PrimaryEngine** — Analyzes horizontal and vertical energy distribution to determine if text is horizontal (0°/180°) or vertical (90°/270°). Fast, pure NumPy, ~97% accurate for axis detection.
+
+2. **FlipClassifierEngine** — A MobileNetV2-based neural network (exported as ONNX, ~8.5 MB) that classifies whether a document is upside-down (180°). Trained on 3,000+ diverse document images from 5 public datasets (forms, invoices, receipts, technical documents, varied layouts). Achieves 96.8% standalone accuracy. Runs via ONNX Runtime at ~5ms per image on CPU.
+
+The pipeline combines both: PrimaryEngine detects the axis, FlipClassifier resolves the ambiguity within each axis pair (0 vs 180, 90 vs 270). Combined pipeline accuracy: **98%** across all four orientations (~20ms per image).
+
+---
+
 ## Configuration Reference
 
 ```python
 from docorient import OrientationConfig
 
 config = OrientationConfig(
-    secondary_confidence_threshold=2.0,  # Minimum confidence for secondary engine (default: 2.0)
-    output_quality=92,                   # JPEG output quality 1-100 (default: 92)
-    secondary_max_dimension=1200,        # Max image size for secondary engine (default: 1200)
-    primary_max_dimension=800,           # Max image size for primary engine (default: 800)
-    workers=4,                           # Parallel workers; None = cpu_count-2 (default: None)
-    resume_enabled=True,                 # Resume interrupted batch jobs (default: True)
-    supported_extensions=(               # File extensions to process
+    flip_confidence_threshold=0.50,  # CNN confidence threshold (default: 0.50)
+    output_quality=92,               # JPEG output quality 1-100 (default: 92)
+    primary_max_dimension=800,       # Max image size for primary engine (default: 800)
+    workers=4,                       # Parallel workers; None = cpu_count-2 (default: None)
+    resume_enabled=True,             # Resume interrupted batch jobs (default: True)
+    supported_extensions=(           # File extensions to process
         ".jpg", ".jpeg", ".png",
         ".tiff", ".tif", ".bmp",
         ".gif", ".webp",
@@ -165,7 +165,7 @@ config = OrientationConfig(
 
 ## API Reference
 
-### `detect_orientation(image, config=None) → OrientationResult`
+### `detect_orientation(image, config=None) -> OrientationResult`
 
 Detects the orientation of a document image without modifying it.
 
@@ -188,20 +188,20 @@ Detects the orientation of a document image without modifying it.
 
 Detects and corrects the orientation of a single image.
 
-- `return_metadata=False` → returns `PIL.Image.Image`
-- `return_metadata=True` → returns `CorrectionResult`
+- `return_metadata=False` -> returns `PIL.Image.Image`
+- `return_metadata=True` -> returns `CorrectionResult`
 
 **`CorrectionResult`** fields: `image: PIL.Image.Image`, `orientation: OrientationResult`
 
 ---
 
-### `correct_document_pages(pages, *, config=None) → list[CorrectionResult]`
+### `correct_document_pages(pages, *, config=None) -> list[CorrectionResult]`
 
 Corrects orientation for all pages of a multi-page document with majority voting.
 
 ---
 
-### `process_directory(input_dir, *, output_dir=None, config=None, limit=0, show_progress=True) → BatchSummary`
+### `process_directory(input_dir, *, output_dir=None, config=None, limit=0, show_progress=True) -> BatchSummary`
 
 Processes all images in a directory in parallel.
 
@@ -227,11 +227,11 @@ Processes all images in a directory in parallel.
 
 ```
 contrato_p1.jpg  ┐
-contrato_p2.jpg  ├─► grouped as "contrato" → majority voting applied
+contrato_p2.jpg  ├── grouped as "contrato" -> majority voting applied
 contrato_p3.jpg  ┘
 
 edital_p1.jpg    ┐
-edital_p2.jpg    ┘─► grouped as "edital"
+edital_p2.jpg    ┘── grouped as "edital"
 ```
 
 Files that don't match the pattern are treated as single-page documents.
@@ -260,7 +260,6 @@ from docorient import (
     DetectionError,
     CorrectionError,
     BatchProcessingError,
-    TesseractNotAvailableError,
 )
 ```
 
@@ -269,10 +268,10 @@ from docorient import (
 ## Development
 
 ```bash
-git clone https://github.com/lucasleirbag/docorient.git
-cd docorient
+git clone https://github.com/lucasleirbag/DocOrient.git
+cd DocOrient
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev,ocr]"
+pip install -e ".[dev]"
 pytest tests/ -v
 ruff check src/ tests/
 ```

{docorient-0.3.2 → docorient-0.4.0}/README.md

@@ -6,7 +6,9 @@
 
 Document image orientation detection and correction.
 
-Automatically detects and fixes rotation (0°, 90°, 180°, 270°) in scanned document images using a two-stage detection pipeline, with support for multi-page majority voting and parallel batch processing.
+Automatically detects and fixes rotation (0°, 90°, 180°, 270°) in scanned document images using a two-stage pipeline: energy-based axis detection + neural network flip classification. Achieves **98% accuracy** across all four orientations. Includes multi-page majority voting and parallel batch processing.
+
+No external dependencies like Tesseract required — the neural model ships embedded in the package (~8.5 MB).
 
 ---
 
@@ -16,18 +18,6 @@ Automatically detects and fixes rotation (0°, 90°, 180°, 270°) in scanned do
 pip install docorient
 ```
 
-To enable full 180° detection:
-
-```bash
-pip install docorient[ocr]
-```
-
-> **Note:** The `[ocr]` extra requires [Tesseract](https://github.com/tesseract-ocr/tesseract) installed on your system.
->
-> - **macOS:** `brew install tesseract`
-> - **Ubuntu/Debian:** `sudo apt install tesseract-ocr`
-> - **Windows:** [installer](https://github.com/UB-Mannheim/tesseract/wiki)
-
 ---
 
 ## Quick Start
@@ -98,26 +88,37 @@ if __name__ == "__main__":
 ```bash
 docorient ./scans --output ./fixed
 docorient ./scans --output ./fixed --workers 4 --quality 95
-docorient ./scans --no-secondary --limit 100
+docorient ./scans --limit 100
 docorient ./scans --dry-run
 docorient --version
 ```
 
 ---
 
+## How It Works
+
+DocOrient uses a two-stage detection pipeline:
+
+1. **PrimaryEngine** — Analyzes horizontal and vertical energy distribution to determine if text is horizontal (0°/180°) or vertical (90°/270°). Fast, pure NumPy, ~97% accurate for axis detection.
+
+2. **FlipClassifierEngine** — A MobileNetV2-based neural network (exported as ONNX, ~8.5 MB) that classifies whether a document is upside-down (180°). Trained on 3,000+ diverse document images from 5 public datasets (forms, invoices, receipts, technical documents, varied layouts). Achieves 96.8% standalone accuracy. Runs via ONNX Runtime at ~5ms per image on CPU.
+
+The pipeline combines both: PrimaryEngine detects the axis, FlipClassifier resolves the ambiguity within each axis pair (0 vs 180, 90 vs 270). Combined pipeline accuracy: **98%** across all four orientations (~20ms per image).
+
+---
+
 ## Configuration Reference
 
 ```python
 from docorient import OrientationConfig
 
 config = OrientationConfig(
-    secondary_confidence_threshold=2.0,  # Minimum confidence for secondary engine (default: 2.0)
-    output_quality=92,                   # JPEG output quality 1-100 (default: 92)
-    secondary_max_dimension=1200,        # Max image size for secondary engine (default: 1200)
-    primary_max_dimension=800,           # Max image size for primary engine (default: 800)
-    workers=4,                           # Parallel workers; None = cpu_count-2 (default: None)
-    resume_enabled=True,                 # Resume interrupted batch jobs (default: True)
-    supported_extensions=(               # File extensions to process
+    flip_confidence_threshold=0.50,  # CNN confidence threshold (default: 0.50)
+    output_quality=92,               # JPEG output quality 1-100 (default: 92)
+    primary_max_dimension=800,       # Max image size for primary engine (default: 800)
+    workers=4,                       # Parallel workers; None = cpu_count-2 (default: None)
+    resume_enabled=True,             # Resume interrupted batch jobs (default: True)
+    supported_extensions=(           # File extensions to process
         ".jpg", ".jpeg", ".png",
         ".tiff", ".tif", ".bmp",
         ".gif", ".webp",
@@ -129,7 +130,7 @@ config = OrientationConfig(
 
 ## API Reference
 
-### `detect_orientation(image, config=None) → OrientationResult`
+### `detect_orientation(image, config=None) -> OrientationResult`
 
 Detects the orientation of a document image without modifying it.
 
@@ -152,20 +153,20 @@ Detects the orientation of a document image without modifying it.
 
 Detects and corrects the orientation of a single image.
 
-- `return_metadata=False` → returns `PIL.Image.Image`
-- `return_metadata=True` → returns `CorrectionResult`
+- `return_metadata=False` -> returns `PIL.Image.Image`
+- `return_metadata=True` -> returns `CorrectionResult`
 
 **`CorrectionResult`** fields: `image: PIL.Image.Image`, `orientation: OrientationResult`
 
 ---
 
-### `correct_document_pages(pages, *, config=None) → list[CorrectionResult]`
+### `correct_document_pages(pages, *, config=None) -> list[CorrectionResult]`
 
 Corrects orientation for all pages of a multi-page document with majority voting.
 
 ---
 
-### `process_directory(input_dir, *, output_dir=None, config=None, limit=0, show_progress=True) → BatchSummary`
+### `process_directory(input_dir, *, output_dir=None, config=None, limit=0, show_progress=True) -> BatchSummary`
 
 Processes all images in a directory in parallel.
 
@@ -191,11 +192,11 @@ Processes all images in a directory in parallel.
 
 ```
 contrato_p1.jpg  ┐
-contrato_p2.jpg  ├─► grouped as "contrato" → majority voting applied
+contrato_p2.jpg  ├── grouped as "contrato" -> majority voting applied
 contrato_p3.jpg  ┘
 
 edital_p1.jpg    ┐
-edital_p2.jpg    ┘─► grouped as "edital"
+edital_p2.jpg    ┘── grouped as "edital"
 ```
 
 Files that don't match the pattern are treated as single-page documents.
@@ -224,7 +225,6 @@ from docorient import (
     DetectionError,
     CorrectionError,
     BatchProcessingError,
-    TesseractNotAvailableError,
 )
 ```
 
@@ -233,10 +233,10 @@ from docorient import (
 ## Development
 
 ```bash
-git clone https://github.com/lucasleirbag/docorient.git
-cd docorient
+git clone https://github.com/lucasleirbag/DocOrient.git
+cd DocOrient
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev,ocr]"
+pip install -e ".[dev]"
 pytest tests/ -v
 ruff check src/ tests/
 ```

{docorient-0.3.2 → docorient-0.4.0}/docs/architecture.md

@@ -18,8 +18,10 @@ src/docorient/
 │   ├── __init__.py          Re-exports detection API
 │   ├── base.py              DetectionEngine Protocol
 │   ├── engine.py            DetectionPipeline orchestrator
-│   ├── primary.py           PrimaryEngine (90°/270°)
-│   └── secondary.py         SecondaryEngine (180°)
+│   ├── primary.py           PrimaryEngine (axis detection)
+│   └── flip_classifier.py   FlipClassifierEngine (180° CNN)
+├── models/
+│   └── orientation_detector.onnx   MobileNetV2 ONNX model (~8.5 MB)
 └── batch/
     ├── __init__.py          Re-exports process_directory
     ├── scanner.py           Directory scanning and grouping
@@ -34,35 +36,28 @@ detect_orientation()
         │
         ▼
 DetectionPipeline.run()
-Iterates through list[DetectionEngine]
+Iterates through [PrimaryEngine, FlipClassifierEngine]
         │
         ▼
 PrimaryEngine.detect()
-Analyzes pixel density distribution to determine text alignment.
+Analyzes pixel energy distribution to classify axis:
+  - Horizontal text (0° or 180°)
+  - Vertical text (90° or 270°)
         │
-        ├── angle ∈ {90, 270} ──► Return result immediately
+        ▼
+FlipClassifierEngine via _resolve_flip()
+        │
+        ├── If horizontal → CNN classifies directly
+        │   ├── Upright → return 0°
+        │   └── Upside-down → return 180°
         │
-        └── angle = 0 (aligned) ──► SecondaryEngine.detect()
-                                            │
-                                  is_available()?
-                                            │
-                               Yes ─────────┴───────── No
-                                ▼                       ▼
-                     Runs secondary analysis    Return 0° (no change)
-                     Checks for 180° inversion
-                     with confidence scoring
-                                │
-                  confidence >= threshold?
-                                │
-                    Yes ────────┴──────── No
-                     ▼                    ▼
-              Return 180°           Return 0°
+        └── If vertical → normalize by rotating 90° CCW, then CNN classifies
+            ├── Upright (was at 90°) → return 90°
+            └── Upside-down (was at 270°) → return 270°
 ```
 
 ## Engine Architecture
 
-The detection system is built on a `DetectionEngine` Protocol:
-
 ```
 DetectionEngine (Protocol)
 ├── name: str
@@ -70,17 +65,57 @@ DetectionEngine (Protocol)
 
 PrimaryEngine implements DetectionEngine
 ├── Always returns OrientationResult (never None)
-└── Detects 0°, 90°, 270° via energy analysis
+├── Computes horizontal/vertical energy via pixel projection
+└── Classifies text axis with ~97% accuracy
 
-SecondaryEngine implements DetectionEngine
-├── Returns None when unavailable or low confidence
-└── Detects 180° via optional OCR dependency
+FlipClassifierEngine implements DetectionEngine
+├── Returns None when confidence below threshold
+├── Uses embedded MobileNetV2 ONNX model
+├── Binary classification: upright vs upside-down
+├── Inference via ONNX Runtime (~5ms on CPU)
+├── Trained on 3,000+ diverse documents (96.8% accuracy)
+└── Model input: 224×224 RGB, ImageNet-normalized
 
 DetectionPipeline
-├── Holds list[DetectionEngine] (default: [PrimaryEngine(), SecondaryEngine()])
-└── Executes engines in sequence with short-circuit logic
+├── Holds list[DetectionEngine] (default: [PrimaryEngine(), FlipClassifierEngine()])
+├── PrimaryEngine detects axis
+└── FlipClassifier resolves flip direction within the detected axis
 ```
 
+## FlipClassifier Details
+
+The FlipClassifierEngine wraps a MobileNetV2 fine-tuned for binary classification:
+
+- **Task**: Classify if a document image is upside-down (180° rotated)
+- **Architecture**: MobileNetV2 with custom binary classifier head
+- **Input**: 224×224 RGB image, center-cropped from 256×256 resize
+- **Normalization**: ImageNet mean/std
+- **Output**: Single logit → sigmoid → P(upside_down)
+- **Export format**: ONNX (opset 13)
+- **Model size**: ~8.5 MB
+- **Inference**: ~5ms per image on CPU via ONNX Runtime
+- **Standalone accuracy**: 96.8% (validation set)
+- **Pipeline accuracy**: 98% across all 4 orientations (0°, 90°, 180°, 270°)
+
+### Training Data
+
+The model was trained on 3,049 document images from 5 diverse public datasets:
+
+| Dataset | Count | Type |
+|---|---|---|
+| FUNSD | 199 | Scanned forms |
+| Invoices & Receipts | 250 | Financial documents |
+| CORD-v2 | 900 | Point-of-sale receipts |
+| DocLayNet v1.1 | 1,000 | Varied document layouts |
+| DocumentVQA | 700 | Diverse document types |
+
+Each image generates 2 training samples (upright + 180° flipped), with 3x augmentation
+(random crop, color jitter, blur, grayscale, perspective, erasing). Total effective
+training samples: ~15,500.
+
+For vertical images (90°/270°), the pipeline first normalizes by rotating 90° CCW,
+then passes the horizontally-aligned image to the classifier.
+
 ## Batch Processing Pipeline
 
 ```

{docorient-0.3.2 → docorient-0.4.0}/docs/contributing.md

@@ -3,10 +3,10 @@
 ## Setup
 
 ```bash
-git clone https://github.com/lucasleirbag/docorient.git
-cd docorient
+git clone https://github.com/lucasleirbag/DocOrient.git
+cd DocOrient
 python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev,ocr]"
+pip install -e ".[dev]"
 ```
 
 ## Running Tests
@@ -31,6 +31,27 @@ ruff check src/ tests/ --fix
 - Functions must do exactly one thing, max ~30 lines of logic
 - Configuration is always passed as a parameter
 
+## Retraining the FlipClassifier Model
+
+The CNN model can be retrained with updated or expanded datasets:
+
+```bash
+pip install torch torchvision datasets onnxscript
+python scripts/training/train_orientation_cnn.py
+```
+
+The script automatically downloads and caches images from 5 public datasets to `data/image_cache/`.
+On subsequent runs, the cache is reused (no re-download). Training uses MPS (Apple Silicon)
+or CUDA when available. The exported ONNX model is saved to `models/orientation_detector.onnx`.
+
+After retraining, copy the model to the package and validate:
+
+```bash
+cp models/orientation_detector.onnx src/docorient/models/orientation_detector.onnx
+python scripts/training/export_and_validate.py
+pytest tests/ -v
+```
+
 ## Publishing a New Version
 
 1. Update `version` in `pyproject.toml` and `src/docorient/_version.py`

{docorient-0.3.2 → docorient-0.4.0}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docorient"
-version = "0.3.2"
+version = "0.4.0"
 description = "Document image orientation detection and correction."
 readme = "README.md"
 license = "MIT"
 requires-python = ">= 3.10"
 authors = [{ name = "Lucas Gabriel Vaz" }]
-keywords = ["document", "orientation", "rotation", "ocr", "image", "correction"]
+keywords = ["document", "orientation", "rotation", "image", "correction", "onnx"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -27,10 +27,10 @@ dependencies = [
     "Pillow >= 10.0",
     "numpy >= 1.24",
     "tqdm >= 4.60",
+    "onnxruntime >= 1.16",
 ]
 
 [project.optional-dependencies]
-ocr = ["pytesseract >= 0.3.10"]
 dev = ["pytest >= 8.0", "pytest-cov", "ruff >= 0.4", "build", "twine"]
 
 [project.scripts]
@@ -42,9 +42,15 @@ Repository = "https://github.com/lucasleirbag/DocOrient"
 Issues = "https://github.com/lucasleirbag/DocOrient/issues"
 Changelog = "https://github.com/lucasleirbag/DocOrient/blob/main/CHANGELOG.md"
 
+[tool.hatch.build]
+exclude = ["/data", "/models", "/scripts"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/docorient"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"src/docorient/models/orientation_detector.onnx" = "docorient/models/orientation_detector.onnx"
+
 [tool.ruff]
 target-version = "py310"
 line-length = 100

{docorient-0.3.2 → docorient-0.4.0}/src/docorient/__init__.py

@@ -4,14 +4,13 @@ from docorient.config import OrientationConfig
 from docorient.correction import correct_document_pages, correct_image
 from docorient.detection.base import DetectionEngine
 from docorient.detection.engine import DetectionPipeline, detect_orientation
+from docorient.detection.flip_classifier import FlipClassifierEngine
 from docorient.detection.primary import PrimaryEngine
-from docorient.detection.secondary import SecondaryEngine
 from docorient.exceptions import (
     BatchProcessingError,
     CorrectionError,
     DetectionError,
     DocorientError,
-    TesseractNotAvailableError,
 )
 from docorient.types import (
     BatchSummary,
@@ -29,12 +28,11 @@ __all__ = [
     "DetectionError",
     "DetectionPipeline",
     "DocorientError",
+    "FlipClassifierEngine",
     "OrientationConfig",
     "OrientationResult",
     "PageResult",
     "PrimaryEngine",
-    "SecondaryEngine",
-    "TesseractNotAvailableError",
     "__version__",
     "correct_document_pages",
     "correct_image",

docorient-0.4.0/src/docorient/_version.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{docorient-0.3.2 → docorient-0.4.0}/src/docorient/cli.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from docorient._version import __version__
 from docorient.batch.processor import process_directory
 from docorient.config import OrientationConfig
-from docorient.detection.secondary import is_secondary_engine_available
+from docorient.detection.flip_classifier import is_flip_classifier_available
 
 
 def _build_argument_parser() -> argparse.ArgumentParser:
@@ -45,18 +45,6 @@ def _build_argument_parser() -> argparse.ArgumentParser:
         default=92,
         help="Output JPEG quality (1-100). Default: 92.",
     )
-    parser.add_argument(
-        "--confidence",
-        type=float,
-        default=2.0,
-        help="Secondary engine confidence threshold. Default: 2.0.",
-    )
-    parser.add_argument(
-        "--no-secondary",
-        action="store_true",
-        default=False,
-        help="Disable secondary engine (primary engine only).",
-    )
     parser.add_argument(
         "--no-resume",
         action="store_true",
@@ -91,16 +79,18 @@ def _print_dry_run_info(input_path: Path, config: OrientationConfig, limit: int)
     total_files = len(pages_by_source)
     total_pages = sum(len(pages) for pages in pages_by_source.values())
 
+    flip_status = "available" if is_flip_classifier_available() else "unavailable"
+
     print(f"\n{'=' * 60}")
     print("  DRY RUN - No changes will be made")
     print(f"{'=' * 60}")
-    print(f"  Input:            {input_path}")
-    print(f"  Files:            {total_files} source documents")
-    print(f"  Pages:            {total_pages} images")
-    print(f"  Workers:          {config.effective_workers}")
-    print(f"  Secondary engine: {'enabled' if is_secondary_engine_available() else 'disabled'}")
-    print(f"  Quality:          {config.output_quality}")
-    print(f"  Resume:           {'enabled' if config.resume_enabled else 'disabled'}")
+    print(f"  Input:             {input_path}")
+    print(f"  Files:             {total_files} source documents")
+    print(f"  Pages:             {total_pages} images")
+    print(f"  Workers:           {config.effective_workers}")
+    print(f"  Flip classifier:   {flip_status}")
+    print(f"  Quality:           {config.output_quality}")
+    print(f"  Resume:            {'enabled' if config.resume_enabled else 'disabled'}")
     print(f"{'=' * 60}\n")
 
 
@@ -138,10 +128,7 @@ def main() -> None:
         print(f"Error: '{arguments.input_dir}' is not a valid directory.", file=sys.stderr)
         sys.exit(1)
 
-    secondary_threshold = arguments.confidence if not arguments.no_secondary else float("inf")
-
     config = OrientationConfig(
-        secondary_confidence_threshold=secondary_threshold,
         output_quality=arguments.quality,
         workers=arguments.workers,
         resume_enabled=not arguments.no_resume,
@@ -151,14 +138,16 @@ def main() -> None:
         _print_dry_run_info(input_path, config, arguments.limit)
         return
 
+    flip_status = "available" if is_flip_classifier_available() else "unavailable"
+
     print(f"\n{'=' * 60}")
     print(f"  docorient v{__version__}")
     print(f"{'=' * 60}")
-    print(f"  Input:            {input_path}")
-    print(f"  Output:           {arguments.output_dir or 'auto (UUID)'}")
-    print(f"  Workers:          {config.effective_workers}")
-    print(f"  Secondary engine: {'disabled' if arguments.no_secondary else 'enabled'}")
-    print(f"  Quality:          {config.output_quality}")
+    print(f"  Input:             {input_path}")
+    print(f"  Output:            {arguments.output_dir or 'auto (UUID)'}")
+    print(f"  Workers:           {config.effective_workers}")
+    print(f"  Flip classifier:   {flip_status}")
+    print(f"  Quality:           {config.output_quality}")
     print(f"{'=' * 60}\n")
 
     summary = process_directory(

{docorient-0.3.2 → docorient-0.4.0}/src/docorient/config.py

@@ -23,9 +23,8 @@ def _default_worker_count() -> int:
 
 @dataclass(frozen=True, slots=True)
 class OrientationConfig:
-    secondary_confidence_threshold: float = 2.0
+    flip_confidence_threshold: float = 0.50
     output_quality: int = 92
-    secondary_max_dimension: int = 1200
     primary_max_dimension: int = 800
     workers: int | None = None
     resume_enabled: bool = True

{docorient-0.3.2 → docorient-0.4.0}/src/docorient/detection/__init__.py

@@ -1,13 +1,13 @@
 from docorient.detection.base import DetectionEngine
 from docorient.detection.engine import DetectionPipeline, detect_orientation
+from docorient.detection.flip_classifier import FlipClassifierEngine, is_flip_classifier_available
 from docorient.detection.primary import PrimaryEngine
-from docorient.detection.secondary import SecondaryEngine, is_secondary_engine_available
 
 __all__ = [
     "DetectionEngine",
     "DetectionPipeline",
+    "FlipClassifierEngine",
     "PrimaryEngine",
-    "SecondaryEngine",
     "detect_orientation",
-    "is_secondary_engine_available",
+    "is_flip_classifier_available",
 ]

docorient-0.4.0/src/docorient/detection/engine.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from PIL import Image
+
+from docorient.config import OrientationConfig
+from docorient.detection.base import DetectionEngine
+from docorient.detection.flip_classifier import FlipClassifierEngine
+from docorient.detection.primary import PrimaryEngine
+from docorient.types import OrientationResult
+
+
+def _build_default_engines() -> list[DetectionEngine]:
+    return [PrimaryEngine(), FlipClassifierEngine()]
+
+
+class DetectionPipeline:
+    def __init__(self, engines: list[DetectionEngine] | None = None) -> None:
+        self.engines: list[DetectionEngine] = engines or _build_default_engines()
+
+    def run(self, image: Image.Image, config: OrientationConfig) -> OrientationResult:
+        primary_result: OrientationResult | None = None
+
+        for engine in self.engines:
+            if engine.name == "primary":
+                primary_result = engine.detect(image, config)
+                continue
+
+            if engine.name == "flip_classifier":
+                flip_result = self._resolve_flip(engine, image, config, primary_result)
+                if flip_result is not None:
+                    return flip_result
+                continue
+
+        if primary_result is not None:
+            return primary_result
+
+        return OrientationResult(angle=0, method="none", reliable=False)
+
+    @staticmethod
+    def _resolve_flip(
+        engine: DetectionEngine,
+        image: Image.Image,
+        config: OrientationConfig,
+        primary_result: OrientationResult | None,
+    ) -> OrientationResult | None:
+        is_vertical = primary_result is not None and primary_result.angle in (90, 270)
+        normalized_image = (
+            image.transpose(Image.Transpose.ROTATE_90) if is_vertical else image
+        )
+
+        flip_result = engine.detect(normalized_image, config)
+
+        if is_vertical and normalized_image is not image:
+            normalized_image.close()
+
+        if flip_result is None:
+            return None
+
+        if is_vertical:
+            final_angle = 270 if flip_result.angle == 180 else 90
+        else:
+            final_angle = flip_result.angle
+
+        combined_method = flip_result.method
+        if primary_result is not None:
+            combined_method = f"{flip_result.method},{primary_result.method}"
+
+        return OrientationResult(
+            angle=final_angle,
+            method=combined_method,
+            reliable=flip_result.reliable,
+        )
+
+
+_default_pipeline = DetectionPipeline()
+
+
+def detect_orientation(
+    image: Image.Image,
+    config: OrientationConfig | None = None,
+) -> OrientationResult:
+    effective_config = config or OrientationConfig()
+    return _default_pipeline.run(image, effective_config)

docorient-0.4.0/src/docorient/detection/flip_classifier.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from docorient.config import OrientationConfig
+from docorient.types import OrientationResult
+
+MODEL_INPUT_SIZE = 224
+IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+_onnx_session_cache: object | None = None
+_onnx_available: bool | None = None
+
+
+def _check_onnxruntime_available() -> bool:
+    global _onnx_available
+    if _onnx_available is None:
+        try:
+            import onnxruntime  # noqa: F401
+            _onnx_available = True
+        except ImportError:
+            _onnx_available = False
+    return _onnx_available
+
+
+def _get_model_path() -> Path:
+    model_ref = resources.files("docorient.models").joinpath("orientation_detector.onnx")
+    return Path(str(model_ref))
+
+
+def _get_onnx_session() -> object:
+    global _onnx_session_cache
+    if _onnx_session_cache is None:
+        import onnxruntime as ort
+        model_path = _get_model_path()
+        _onnx_session_cache = ort.InferenceSession(
+            str(model_path),
+            providers=["CPUExecutionProvider"],
+        )
+    return _onnx_session_cache
+
+
+def _preprocess_image(image: Image.Image) -> np.ndarray:
+    rgb_image = image.convert("RGB")
+    resized_image = rgb_image.resize((256, 256), Image.LANCZOS)
+
+    crop_left = (256 - MODEL_INPUT_SIZE) // 2
+    crop_top = (256 - MODEL_INPUT_SIZE) // 2
+    cropped_image = resized_image.crop((
+        crop_left,
+        crop_top,
+        crop_left + MODEL_INPUT_SIZE,
+        crop_top + MODEL_INPUT_SIZE,
+    ))
+
+    pixel_array = np.array(cropped_image, dtype=np.float32) / 255.0
+    normalized_array = (pixel_array - IMAGENET_MEAN) / IMAGENET_STD
+    transposed_array = normalized_array.transpose(2, 0, 1)
+    return np.expand_dims(transposed_array, axis=0)
+
+
+def _classify_upside_down(image: Image.Image) -> tuple[bool, float]:
+    session = _get_onnx_session()
+    input_name = session.get_inputs()[0].name
+    input_tensor = _preprocess_image(image)
+    outputs = session.run(None, {input_name: input_tensor})
+    logit = float(outputs[0][0][0])
+    probability = 1.0 / (1.0 + np.exp(-logit))
+    return logit > 0.0, probability
+
+
+class FlipClassifierEngine:
+    @property
+    def name(self) -> str:
+        return "flip_classifier"
+
+    @staticmethod
+    def is_available() -> bool:
+        if not _check_onnxruntime_available():
+            return False
+        return _get_model_path().exists()
+
+    def detect(
+        self, image: Image.Image, config: OrientationConfig
+    ) -> OrientationResult | None:
+        if not self.is_available():
+            return None
+
+        is_flipped, confidence = _classify_upside_down(image)
+
+        effective_confidence = confidence if is_flipped else (1.0 - confidence)
+        if effective_confidence < config.flip_confidence_threshold:
+            return None
+
+        if is_flipped:
+            return OrientationResult(
+                angle=180,
+                method=f"flip_classifier(flipped,conf={confidence:.2f})",
+                reliable=True,
+            )
+
+        return OrientationResult(
+            angle=0,
+            method=f"flip_classifier(upright,conf={confidence:.2f})",
+            reliable=True,
+        )
+
+
+def is_flip_classifier_available() -> bool:
+    return FlipClassifierEngine.is_available()

{docorient-0.3.2 → docorient-0.4.0}/src/docorient/exceptions.py

@@ -12,7 +12,3 @@ class CorrectionError(DocorientError):
 
 class BatchProcessingError(DocorientError):
     pass
-
-
-class TesseractNotAvailableError(DocorientError):
-    pass

docorient-0.4.0/src/docorient/models/__init__.py

@@ -0,0 +1 @@
+

{docorient-0.3.2 → docorient-0.4.0}/tests/test_detection.py

@@ -31,21 +31,18 @@ class TestPrimaryEngine:
         assert isinstance(result, OrientationResult)
 
 
-class TestDetectionEngine:
-    def test_aligned_image_detection(self, horizontal_text_image):
+class TestDetectionPipeline:
+    def test_horizontal_image_detection(self, horizontal_text_image):
         result = detect_orientation(horizontal_text_image)
-        assert result.angle == 0
+        assert result.angle in (0, 180)
         assert result.reliable is True
 
-    def test_rotated_image_detection(self, vertical_text_image):
+    def test_vertical_image_detection(self, vertical_text_image):
         result = detect_orientation(vertical_text_image)
         assert result.angle in (90, 270)
 
     def test_with_custom_config(self, horizontal_text_image):
-        config = OrientationConfig(
-            secondary_confidence_threshold=10.0,
-            primary_max_dimension=400,
-        )
+        config = OrientationConfig(primary_max_dimension=400)
         result = detect_orientation(horizontal_text_image, config=config)
         assert isinstance(result, OrientationResult)
 

docorient-0.3.2/CHANGELOG.md

@@ -1,44 +0,0 @@
-# Changelog
-
-## 0.3.2 (2026-02-27)
-
-- Fix: update project URLs to correct GitHub repository
-- Add changelog link to PyPI metadata
-
-## 0.3.1 (2026-02-27)
-
-- Fix: author metadata corrected to Lucas Gabriel Vaz
-- Remove `tesseract` from PyPI keywords
-
-## 0.3.0 (2026-02-27)
-
-- **Breaking:** detection engines refactored to class-based architecture with `DetectionEngine` Protocol
-- Introduce `DetectionPipeline` for extensible engine orchestration
-- Introduce `PrimaryEngine` and `SecondaryEngine` classes
-- Extract `rotation.py` and `voting.py` as standalone modules
-- Encapsulate worker state in `WorkerContext` dataclass
-- Transform `_imaging.py` functions into `ImageIO` class
-- Decompose `process_directory` into focused sub-functions
-- Apply custom exceptions (`DetectionError`, `CorrectionError`, `BatchProcessingError`) throughout codebase
-- Export `DetectionEngine`, `DetectionPipeline`, `PrimaryEngine`, `SecondaryEngine` in public API
-
-## 0.2.0 (2026-02-26)
-
-- **Breaking:** renamed config params `osd_confidence_threshold` → `secondary_confidence_threshold`, `max_osd_dimension` → `secondary_max_dimension`, `projection_target_dimension` → `primary_max_dimension`
-- **Breaking:** renamed CLI flag `--no-ocr` → `--no-secondary`
-- Internal engines renamed to `primary` and `secondary`
-- Updated `OrientationResult.method` trace strings
-
-## 0.1.1 (2026-02-26)
-
-- Docs: added `if __name__ == "__main__":` note for `process_directory` on macOS/Windows
-
-## 0.1.0 (2026-02-25)
-
-- Initial release
-- Primary engine for 90°/270° detection
-- Optional secondary engine for 180° detection
-- Single image and batch directory processing
-- Multi-page majority voting
-- Resumable batch processing
-- CLI interface

docorient-0.3.2/src/docorient/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.2"

docorient-0.3.2/src/docorient/detection/engine.py

@@ -1,55 +0,0 @@
-from __future__ import annotations
-
-from PIL import Image
-
-from docorient.config import OrientationConfig
-from docorient.detection.base import DetectionEngine
-from docorient.detection.primary import PrimaryEngine
-from docorient.detection.secondary import SecondaryEngine
-from docorient.types import OrientationResult
-
-
-class DetectionPipeline:
-    def __init__(self, engines: list[DetectionEngine] | None = None) -> None:
-        self.engines: list[DetectionEngine] = engines or [PrimaryEngine(), SecondaryEngine()]
-
-    def run(self, image: Image.Image, config: OrientationConfig) -> OrientationResult:
-        primary_result: OrientationResult | None = None
-
-        for engine in self.engines:
-            result = engine.detect(image, config)
-
-            if result is None:
-                continue
-
-            if engine.name == "primary":
-                primary_result = result
-                if result.angle in (90, 270):
-                    return result
-                continue
-
-            if primary_result is not None:
-                combined_method = f"{result.method},{primary_result.method}"
-            else:
-                combined_method = result.method
-            return OrientationResult(
-                angle=result.angle,
-                method=combined_method,
-                reliable=True,
-            )
-
-        if primary_result is not None:
-            return primary_result
-
-        return OrientationResult(angle=0, method="none", reliable=False)
-
-
-_default_pipeline = DetectionPipeline()
-
-
-def detect_orientation(
-    image: Image.Image,
-    config: OrientationConfig | None = None,
-) -> OrientationResult:
-    effective_config = config or OrientationConfig()
-    return _default_pipeline.run(image, effective_config)

docorient-0.3.2/src/docorient/detection/secondary.py

@@ -1,75 +0,0 @@
-from __future__ import annotations
-
-import warnings
-
-from PIL import Image
-
-from docorient._imaging import ImageIO
-from docorient.config import OrientationConfig
-from docorient.types import OrientationResult
-
-_secondary_engine_available: bool | None = None
-
-
-class SecondaryEngine:
-    @property
-    def name(self) -> str:
-        return "secondary"
-
-    @staticmethod
-    def is_available() -> bool:
-        global _secondary_engine_available
-        if _secondary_engine_available is None:
-            try:
-                import pytesseract  # noqa: F401
-
-                _secondary_engine_available = True
-            except ImportError:
-                _secondary_engine_available = False
-        return _secondary_engine_available
-
-    def detect(
-        self, image: Image.Image, config: OrientationConfig
-    ) -> OrientationResult | None:
-        if not self.is_available():
-            warnings.warn(
-                "Secondary engine not available. 180° detection is disabled. "
-                "Install with: pip install docorient[ocr]",
-                UserWarning,
-                stacklevel=2,
-            )
-            return None
-
-        downscaled_image = ImageIO.downscale(image, config.secondary_max_dimension)
-        detected_angle, detection_confidence = self._run_engine(downscaled_image)
-
-        if downscaled_image is not image:
-            downscaled_image.close()
-
-        if detection_confidence < config.secondary_confidence_threshold:
-            return None
-
-        if detected_angle not in (90, 180, 270):
-            return None
-
-        return OrientationResult(
-            angle=detected_angle,
-            method=f"secondary(angle={detected_angle},conf={detection_confidence:.1f})",
-            reliable=True,
-        )
-
-    @staticmethod
-    def _run_engine(image: Image.Image) -> tuple[int, float]:
-        import pytesseract
-
-        try:
-            result = pytesseract.image_to_osd(image, output_type=pytesseract.Output.DICT)
-            detected_angle = int(result.get("orientation", 0))
-            detection_confidence = float(result.get("orientation_conf", 0.0))
-            return detected_angle, detection_confidence
-        except pytesseract.TesseractError:
-            return 0, 0.0
-
-
-def is_secondary_engine_available() -> bool:
-    return SecondaryEngine.is_available()