docorient 0.2.0__tar.gz → 0.3.2__tar.gz

docorient-0.3.2/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.2.0 → docorient-0.3.2}/PKG-INFO

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: docorient
-Version: 0.2.0
-Summary: Document image orientation detection and correction using projection profile analysis and optional Tesseract OSD.
-Project-URL: Homepage, https://github.com/cebraspe-lab/docorient
-Project-URL: Repository, https://github.com/cebraspe-lab/docorient
-Project-URL: Issues, https://github.com/cebraspe-lab/docorient/issues
-Author: Cebraspe Lab
+Version: 0.3.2
+Summary: Document image orientation detection and correction.
+Project-URL: Homepage, https://github.com/lucasleirbag/DocOrient
+Project-URL: Repository, https://github.com/lucasleirbag/DocOrient
+Project-URL: Issues, https://github.com/lucasleirbag/DocOrient/issues
+Project-URL: Changelog, https://github.com/lucasleirbag/DocOrient/blob/main/CHANGELOG.md
+Author: Lucas Gabriel Vaz
 License-Expression: MIT
 License-File: LICENSE
-Keywords: correction,document,image,ocr,orientation,rotation,tesseract
+Keywords: correction,document,image,ocr,orientation,rotation
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

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

@@ -6,21 +6,24 @@
 src/docorient/
 ├── __init__.py              Public API re-exports
 ├── _version.py              Version string
-├── _imaging.py              Internal image utilities
+├── _imaging.py              ImageIO class for image operations
 ├── config.py                OrientationConfig dataclass
 ├── types.py                 Result dataclasses
 ├── exceptions.py            Exception hierarchy
+├── rotation.py              Image rotation utility
+├── voting.py                Majority voting logic
 ├── correction.py            correct_image, correct_document_pages
 ├── cli.py                   CLI entry point
 ├── detection/
-│   ├── __init__.py          Re-exports detect_orientation
-│   ├── engine.py            Detection orchestrator
-│   ├── primary.py           Primary detection engine (90°/270°)
-│   └── secondary.py         Secondary detection engine (180°)
+│   ├── __init__.py          Re-exports detection API
+│   ├── base.py              DetectionEngine Protocol
+│   ├── engine.py            DetectionPipeline orchestrator
+│   ├── primary.py           PrimaryEngine (90°/270°)
+│   └── secondary.py         SecondaryEngine (180°)
 └── batch/
     ├── __init__.py          Re-exports process_directory
     ├── scanner.py           Directory scanning and grouping
-    ├── worker.py            Multiprocessing worker logic
+    ├── worker.py            WorkerContext and multiprocessing logic
     └── processor.py         Batch orchestrator with resume and progress
 ```
 
@@ -30,17 +33,22 @@ src/docorient/
 detect_orientation()
         │
         ▼
-Primary Engine (detection/primary.py)
+DetectionPipeline.run()
+Iterates through list[DetectionEngine]
+        │
+        ▼
+PrimaryEngine.detect()
 Analyzes pixel density distribution to determine text alignment.
         │
         ├── angle ∈ {90, 270} ──► Return result immediately
         │
-        └── angle = 0 (aligned) ──► Secondary Engine available?
+        └── angle = 0 (aligned) ──► SecondaryEngine.detect()
+                                            │
+                                  is_available()?
                                             │
                                Yes ─────────┴───────── No
                                 ▼                       ▼
-                     Secondary Engine          Return 0° (no change)
-                     (detection/secondary.py)
+                     Runs secondary analysis    Return 0° (no change)
                      Checks for 180° inversion
                      with confidence scoring
                                 │
@@ -51,27 +59,52 @@ Analyzes pixel density distribution to determine text alignment.
               Return 180°           Return 0°
 ```
 
+## Engine Architecture
+
+The detection system is built on a `DetectionEngine` Protocol:
+
+```
+DetectionEngine (Protocol)
+├── name: str
+└── detect(image, config) → OrientationResult | None
+
+PrimaryEngine implements DetectionEngine
+├── Always returns OrientationResult (never None)
+└── Detects 0°, 90°, 270° via energy analysis
+
+SecondaryEngine implements DetectionEngine
+├── Returns None when unavailable or low confidence
+└── Detects 180° via optional OCR dependency
+
+DetectionPipeline
+├── Holds list[DetectionEngine] (default: [PrimaryEngine(), SecondaryEngine()])
+└── Executes engines in sequence with short-circuit logic
+```
+
 ## Batch Processing Pipeline
 
 ```
 process_directory()
         │
         ▼
+   _resolve_output_directory()
+   Resolves explicit path or generates UUID
+        │
+        ▼
    scan_directory()          ← scanner.py
    Groups images by
    source document name
         │
         ▼
-   Load resume log           ← _orientation_done.log
-   Skip already done files
-        │
-        ▼
-   Distribute pending
-   sources into N batches    ← N = effective_workers
+   _filter_pending_sources()
+   Loads resume log, skips completed
         │
         ▼
-   multiprocessing.Pool      ← worker.py
+   _run_parallel_processing()
    ┌─────────────────────────────────────┐
+   │  multiprocessing.Pool              │
+   │  WorkerContext encapsulates state   │
+   │                                     │
    │  For each source in batch:          │
    │  1. Run detection per page          │
    │  2. Apply majority voting           │
@@ -93,12 +126,12 @@ Majority voting resolves this:
 2. Find the most common angle (`Counter.most_common`)
 3. Override any unreliable detection that differs from the majority
 
-Implemented in `correction._apply_majority_voting()`, reused by both
+Implemented in `voting.apply_majority_voting()`, reused by both
 `correct_document_pages()` and `batch/worker._process_single_source()`.
 
 ## Multiprocessing Design
 
-- **No shared mutable state** — each worker reconstructs `OrientationConfig` from a dict
+- **WorkerContext dataclass** encapsulates all shared state in a single object
 - **Progress tracking** via `multiprocessing.Value` + `multiprocessing.Lock`
 - **Resume log** written atomically per source file, protected by the shared lock
 - **`maxtasksperchild=1`** prevents memory accumulation in long jobs

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

@@ -28,9 +28,8 @@ ruff check src/ tests/ --fix
 - No comments — code must be self-explanatory through naming
 - Descriptive variable names — never single-letter variables in non-trivial scopes
 - Full type hints on all function signatures
-- Docstrings only on public API functions
 - Functions must do exactly one thing, max ~30 lines of logic
-- No global state — configuration is always passed as a parameter
+- Configuration is always passed as a parameter
 
 ## Publishing a New Version
 

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

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docorient"
-version = "0.2.0"
-description = "Document image orientation detection and correction using projection profile analysis and optional Tesseract OSD."
+version = "0.3.2"
+description = "Document image orientation detection and correction."
 readme = "README.md"
 license = "MIT"
 requires-python = ">= 3.10"
-authors = [{ name = "Cebraspe Lab" }]
-keywords = ["document", "orientation", "rotation", "ocr", "image", "correction", "tesseract"]
+authors = [{ name = "Lucas Gabriel Vaz" }]
+keywords = ["document", "orientation", "rotation", "ocr", "image", "correction"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -37,9 +37,10 @@ dev = ["pytest >= 8.0", "pytest-cov", "ruff >= 0.4", "build", "twine"]
 docorient = "docorient.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/cebraspe-lab/docorient"
-Repository = "https://github.com/cebraspe-lab/docorient"
-Issues = "https://github.com/cebraspe-lab/docorient/issues"
+Homepage = "https://github.com/lucasleirbag/DocOrient"
+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.targets.wheel]
 packages = ["src/docorient"]

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

@@ -2,7 +2,10 @@ from docorient._version import __version__
 from docorient.batch.processor import process_directory
 from docorient.config import OrientationConfig
 from docorient.correction import correct_document_pages, correct_image
-from docorient.detection.engine import detect_orientation
+from docorient.detection.base import DetectionEngine
+from docorient.detection.engine import DetectionPipeline, detect_orientation
+from docorient.detection.primary import PrimaryEngine
+from docorient.detection.secondary import SecondaryEngine
 from docorient.exceptions import (
     BatchProcessingError,
     CorrectionError,
@@ -22,11 +25,15 @@ __all__ = [
     "BatchSummary",
     "CorrectionError",
     "CorrectionResult",
+    "DetectionEngine",
     "DetectionError",
+    "DetectionPipeline",
     "DocorientError",
     "OrientationConfig",
     "OrientationResult",
     "PageResult",
+    "PrimaryEngine",
+    "SecondaryEngine",
     "TesseractNotAvailableError",
     "__version__",
     "correct_document_pages",

docorient-0.3.2/src/docorient/_imaging.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image
+
+FORMAT_MAPPING: dict[str, str] = {
+    ".jpg": "JPEG",
+    ".jpeg": "JPEG",
+    ".png": "PNG",
+    ".tiff": "TIFF",
+    ".tif": "TIFF",
+    ".bmp": "BMP",
+    ".gif": "GIF",
+    ".webp": "WEBP",
+}
+
+
+class ImageIO:
+    @staticmethod
+    def open_as_rgb(image_path: str | Path) -> Image.Image:
+        return Image.open(image_path).convert("RGB")
+
+    @staticmethod
+    def downscale(image: Image.Image, max_dimension: int) -> Image.Image:
+        image_width, image_height = image.size
+        largest_side = max(image_width, image_height)
+
+        if largest_side <= max_dimension:
+            return image
+
+        scale_factor = max_dimension / largest_side
+        target_width = int(image_width * scale_factor)
+        target_height = int(image_height * scale_factor)
+        return image.resize((target_width, target_height), Image.LANCZOS)
+
+    @staticmethod
+    def save(
+        image: Image.Image,
+        output_path: str | Path,
+        output_format: str = "JPEG",
+        quality: int = 92,
+    ) -> None:
+        image.save(output_path, output_format, quality=quality)
+
+    @staticmethod
+    def resolve_format(file_path: str | Path) -> str:
+        extension = Path(file_path).suffix.lower()
+        return FORMAT_MAPPING.get(extension, "JPEG")

docorient-0.3.2/src/docorient/_version.py

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

{docorient-0.2.0 → docorient-0.3.2}/src/docorient/batch/processor.py

@@ -12,6 +12,7 @@ from tqdm import tqdm
 from docorient.batch.scanner import ScannedPage, scan_directory
 from docorient.batch.worker import initialize_worker, process_batch
 from docorient.config import RESUME_LOG_FILENAME, OrientationConfig
+from docorient.exceptions import BatchProcessingError
 from docorient.types import BatchSummary, PageResult
 
 
@@ -71,76 +72,43 @@ def _build_summary(
     )
 
 
-def process_directory(
-    input_dir: str | Path,
-    *,
-    output_dir: str | Path | None = None,
-    config: OrientationConfig | None = None,
-    limit: int = 0,
-    show_progress: bool = True,
-) -> BatchSummary:
-    """Process all images in a directory, detecting and correcting orientation.
-
-    Args:
-        input_dir: Path to directory containing document images.
-        output_dir: Path for corrected output. None generates a UUID-named directory.
-        config: Processing configuration. Uses defaults if not provided.
-        limit: Maximum number of images to process. 0 means all.
-        show_progress: Whether to display a tqdm progress bar.
-
-    Returns:
-        BatchSummary with statistics and per-page results.
-    """
-    effective_config = config or OrientationConfig()
-    input_path = Path(input_dir).resolve()
-
+def _resolve_output_directory(
+    input_path: Path, output_dir: str | Path | None
+) -> Path:
     if output_dir is None:
-        output_path = input_path.parent / str(uuid.uuid4())
-    else:
-        output_path = Path(output_dir).resolve()
+        return input_path.parent / str(uuid.uuid4())
+    return Path(output_dir).resolve()
 
-    output_path.mkdir(parents=True, exist_ok=True)
 
-    pages_by_source = scan_directory(
-        input_path,
-        output_path,
-        supported_extensions=effective_config.supported_extensions,
-        limit=limit,
-    )
-
-    source_file_names = list(pages_by_source.keys())
-    total_files = len(source_file_names)
-    total_pages = sum(len(pages) for pages in pages_by_source.values())
-
-    if total_pages == 0:
-        return _build_summary(str(input_path), str(output_path), 0, {}, [])
-
-    resume_log_path = output_path / RESUME_LOG_FILENAME
-    already_completed_sources = set()
-
-    if effective_config.resume_enabled:
-        already_completed_sources = _load_completed_sources(resume_log_path)
-
-    pending_sources = [
+def _filter_pending_sources(
+    pages_by_source: dict[str, list[ScannedPage]],
+    source_file_names: list[str],
+    resume_log_path: Path,
+    resume_enabled: bool,
+) -> list[tuple[str, list[ScannedPage]]]:
+    already_completed = set()
+    if resume_enabled:
+        already_completed = _load_completed_sources(resume_log_path)
+
+    return [
         (source_name, pages_by_source[source_name])
         for source_name in source_file_names
-        if source_name not in already_completed_sources
+        if source_name not in already_completed
     ]
 
-    all_page_results: dict[str, list[PageResult]] = {}
-
-    if not pending_sources:
-        return _build_summary(
-            str(input_path), str(output_path), total_files, all_page_results, source_file_names
-        )
 
-    worker_count = min(effective_config.effective_workers, len(pending_sources))
+def _run_parallel_processing(
+    pending_sources: list[tuple[str, list[ScannedPage]]],
+    config: OrientationConfig,
+    resume_log_path: Path,
+    show_progress: bool,
+) -> dict[str, list[PageResult]]:
+    worker_count = min(config.effective_workers, len(pending_sources))
     batches = _distribute_into_batches(pending_sources, worker_count)
 
     progress_counter = multiprocessing.Value("i", 0)
     progress_lock = multiprocessing.Lock()
-
-    config_as_dict = asdict(effective_config)
+    config_as_dict = asdict(config)
 
     worker_pool = multiprocessing.Pool(
         processes=worker_count,
@@ -154,6 +122,7 @@ def process_directory(
     ]
     worker_pool.close()
 
+    progress_bar = None
     if show_progress:
         progress_bar = tqdm(
             total=len(pending_sources),
@@ -161,8 +130,6 @@ def process_directory(
             unit="file",
             bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}]",
         )
-    else:
-        progress_bar = None
 
     try:
         while not all(async_result.ready() for async_result in async_results):
@@ -182,15 +149,61 @@ def process_directory(
         progress_bar.refresh()
         progress_bar.close()
 
+    all_page_results: dict[str, list[PageResult]] = {}
     for async_result in async_results:
         try:
             batch_results = async_result.get(timeout=60)
             for source_name, page_results in batch_results:
                 all_page_results[source_name] = page_results
-        except Exception:
-            pass
+        except Exception as pool_error:
+            raise BatchProcessingError(
+                f"Worker pool error: {pool_error}"
+            ) from pool_error
 
     worker_pool.join()
+    return all_page_results
+
+
+def process_directory(
+    input_dir: str | Path,
+    *,
+    output_dir: str | Path | None = None,
+    config: OrientationConfig | None = None,
+    limit: int = 0,
+    show_progress: bool = True,
+) -> BatchSummary:
+    effective_config = config or OrientationConfig()
+    input_path = Path(input_dir).resolve()
+    output_path = _resolve_output_directory(input_path, output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    pages_by_source = scan_directory(
+        input_path,
+        output_path,
+        supported_extensions=effective_config.supported_extensions,
+        limit=limit,
+    )
+
+    source_file_names = list(pages_by_source.keys())
+    total_files = len(source_file_names)
+
+    if not pages_by_source:
+        return _build_summary(str(input_path), str(output_path), 0, {}, [])
+
+    resume_log_path = output_path / RESUME_LOG_FILENAME
+
+    pending_sources = _filter_pending_sources(
+        pages_by_source, source_file_names, resume_log_path, effective_config.resume_enabled
+    )
+
+    if not pending_sources:
+        return _build_summary(
+            str(input_path), str(output_path), total_files, {}, source_file_names
+        )
+
+    all_page_results = _run_parallel_processing(
+        pending_sources, effective_config, resume_log_path, show_progress
+    )
 
     return _build_summary(
         str(input_path), str(output_path), total_files, all_page_results, source_file_names

{docorient-0.2.0 → docorient-0.3.2}/src/docorient/batch/worker.py

@@ -1,19 +1,28 @@
 from __future__ import annotations
 
 import multiprocessing
+from dataclasses import dataclass
 from typing import Any
 
-from docorient._imaging import determine_output_format, open_as_rgb, save_image
+from docorient._imaging import ImageIO
 from docorient.batch.scanner import ScannedPage
 from docorient.config import OrientationConfig
-from docorient.correction import _apply_majority_voting, _apply_rotation
 from docorient.detection.engine import detect_orientation
+from docorient.exceptions import CorrectionError, DetectionError
+from docorient.rotation import apply_rotation
 from docorient.types import OrientationResult, PageResult
+from docorient.voting import apply_majority_voting
 
-_shared_counter: Any = None
-_shared_lock: Any = None
-_shared_resume_log_path: str | None = None
-_shared_config_dict: dict[str, Any] | None = None
+
+@dataclass
+class WorkerContext:
+    progress_counter: Any
+    progress_lock: Any
+    resume_log_path: str
+    config: OrientationConfig
+
+
+_worker_context: WorkerContext | None = None
 
 
 def initialize_worker(
@@ -22,17 +31,13 @@ def initialize_worker(
     resume_log_path: str,
     config_dict: dict[str, Any],
 ) -> None:
-    global _shared_counter, _shared_lock, _shared_resume_log_path, _shared_config_dict
-    _shared_counter = counter
-    _shared_lock = lock
-    _shared_resume_log_path = resume_log_path
-    _shared_config_dict = config_dict
-
-
-def _reconstruct_config() -> OrientationConfig:
-    if _shared_config_dict is None:
-        return OrientationConfig()
-    return OrientationConfig(**_shared_config_dict)
+    global _worker_context
+    _worker_context = WorkerContext(
+        progress_counter=counter,
+        progress_lock=lock,
+        resume_log_path=resume_log_path,
+        config=OrientationConfig(**config_dict),
+    )
 
 
 def _process_single_source(
@@ -46,16 +51,19 @@ def _process_single_source(
 
     for page_index, scanned_page in enumerate(valid_pages):
         try:
-            image = open_as_rgb(scanned_page.image_path)
+            image = ImageIO.open_as_rgb(scanned_page.image_path)
             orientation = detect_orientation(image, config=config)
             detection_results.append(orientation)
             image.close()
-        except Exception as detection_error:
+        except Exception as original_error:
+            wrapped = DetectionError(
+                f"Detection failed for {scanned_page.image_name}: {original_error}"
+            )
             detection_results.append(OrientationResult(angle=0, method="error", reliable=False))
-            page_errors[page_index] = str(detection_error)
+            page_errors[page_index] = str(wrapped)
 
     if len(valid_pages) > 1:
-        detection_results = _apply_majority_voting(detection_results)
+        detection_results = apply_majority_voting(detection_results)
 
     page_results: list[PageResult] = []
 
@@ -64,10 +72,10 @@ def _process_single_source(
 
         if error_message is None:
             try:
-                image = open_as_rgb(scanned_page.image_path)
-                corrected_image = _apply_rotation(image, orientation.angle)
-                output_format = determine_output_format(scanned_page.output_path)
-                save_image(
+                image = ImageIO.open_as_rgb(scanned_page.image_path)
+                corrected_image = apply_rotation(image, orientation.angle)
+                output_format = ImageIO.resolve_format(scanned_page.output_path)
+                ImageIO.save(
                     corrected_image,
                     scanned_page.output_path,
                     output_format=output_format,
@@ -75,8 +83,11 @@ def _process_single_source(
                 )
                 corrected_image.close()
                 image.close()
-            except Exception as save_error:
-                error_message = str(save_error)
+            except Exception as original_error:
+                wrapped = CorrectionError(
+                    f"Correction failed for {scanned_page.image_name}: {original_error}"
+                )
+                error_message = str(wrapped)
 
         page_results.append(
             PageResult(
@@ -94,10 +105,11 @@ def _process_single_source(
 
 
 def _record_completion(source_file_name: str) -> None:
-    with _shared_lock:
-        _shared_counter.value += 1
+    assert _worker_context is not None
+    with _worker_context.progress_lock:
+        _worker_context.progress_counter.value += 1
         try:
-            with open(_shared_resume_log_path, "a") as resume_log:
+            with open(_worker_context.resume_log_path, "a") as resume_log:
                 resume_log.write(source_file_name + "\n")
                 resume_log.flush()
         except OSError:
@@ -107,11 +119,13 @@ def _record_completion(source_file_name: str) -> None:
 def process_batch(
     batch: list[tuple[str, list[ScannedPage]]],
 ) -> list[tuple[str, list[PageResult]]]:
-    config = _reconstruct_config()
+    assert _worker_context is not None
     batch_results: list[tuple[str, list[PageResult]]] = []
 
     for source_file_name, scanned_pages in batch:
-        page_results = _process_single_source(source_file_name, scanned_pages, config)
+        page_results = _process_single_source(
+            source_file_name, scanned_pages, _worker_context.config
+        )
         batch_results.append((source_file_name, page_results))
         _record_completion(source_file_name)