docorient 0.1.0__tar.gz

docorient-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-02-25)
+
+- Initial release
+- Projection profile engine for 90°/270° detection
+- Optional Tesseract OSD engine for 180° detection
+- Single image and batch directory processing
+- Multi-page majority voting
+- Resumable batch processing
+- CLI interface

docorient-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cebraspe Lab
+
+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.

docorient-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: docorient
+Version: 0.1.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
+License-Expression: MIT
+License-File: LICENSE
+Keywords: correction,document,image,ocr,orientation,rotation,tesseract
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+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
+
+Document image orientation detection and correction.
+
+Detects and fixes rotation (0°, 90°, 180°, 270°) in scanned document images using projection profile analysis and optional Tesseract OSD.
+
+## Installation
+
+```bash
+pip install docorient
+```
+
+For 180° detection via Tesseract OSD:
+
+```bash
+pip install docorient[ocr]
+```
+
+> **Note:** The `[ocr]` extra requires [Tesseract](https://github.com/tesseract-ocr/tesseract) installed on your system.
+
+## Quick Start
+
+### Detect orientation
+
+```python
+from PIL import Image
+from docorient import detect_orientation
+
+image = Image.open("document.jpg")
+result = detect_orientation(image)
+
+print(result.angle)     # 0, 90, 180, or 270
+print(result.method)    # detection method used
+print(result.reliable)  # confidence flag
+```
+
+### Correct a single image
+
+```python
+from docorient import correct_image
+
+corrected = correct_image(image)
+corrected.save("fixed.jpg")
+```
+
+### Correct with metadata
+
+```python
+from docorient import correct_image
+
+result = correct_image(image, return_metadata=True)
+print(result.orientation.angle)
+result.image.save("fixed.jpg")
+```
+
+### Correct multi-page document (majority voting)
+
+```python
+from docorient import correct_document_pages
+
+pages = [Image.open(f"page_{i}.jpg") for i in range(5)]
+corrected_pages = correct_document_pages(pages)
+```
+
+### Batch process a directory
+
+```python
+from docorient import process_directory, OrientationConfig
+
+config = OrientationConfig(workers=4, output_quality=95)
+summary = process_directory("./scans", output_dir="./fixed", config=config)
+
+print(f"Corrected: {summary.corrected}/{summary.total_pages}")
+```
+
+### CLI
+
+```bash
+docorient ./scans --output ./fixed --workers 4
+docorient ./scans --dry-run
+docorient ./scans --no-ocr --limit 100
+```
+
+## How It Works
+
+1. **Projection profile analysis** detects 90° and 270° rotations by comparing horizontal vs vertical text energy
+2. **Tesseract OSD** (optional) detects 180° rotation with confidence thresholding
+3. **Majority voting** across pages of the same document improves reliability
+
+## Supported Formats
+
+Any format readable by Pillow: JPEG, PNG, TIFF, BMP, GIF, WebP, and more.
+
+## Configuration
+
+```python
+from docorient import OrientationConfig
+
+config = OrientationConfig(
+    osd_confidence_threshold=2.0,
+    output_quality=92,
+    max_osd_dimension=1200,
+    projection_target_dimension=800,
+    workers=4,
+    resume_enabled=True,
+)
+```
+
+## License
+
+MIT

docorient-0.1.0/README.md

@@ -0,0 +1,111 @@
+# docorient
+
+Document image orientation detection and correction.
+
+Detects and fixes rotation (0°, 90°, 180°, 270°) in scanned document images using projection profile analysis and optional Tesseract OSD.
+
+## Installation
+
+```bash
+pip install docorient
+```
+
+For 180° detection via Tesseract OSD:
+
+```bash
+pip install docorient[ocr]
+```
+
+> **Note:** The `[ocr]` extra requires [Tesseract](https://github.com/tesseract-ocr/tesseract) installed on your system.
+
+## Quick Start
+
+### Detect orientation
+
+```python
+from PIL import Image
+from docorient import detect_orientation
+
+image = Image.open("document.jpg")
+result = detect_orientation(image)
+
+print(result.angle)     # 0, 90, 180, or 270
+print(result.method)    # detection method used
+print(result.reliable)  # confidence flag
+```
+
+### Correct a single image
+
+```python
+from docorient import correct_image
+
+corrected = correct_image(image)
+corrected.save("fixed.jpg")
+```
+
+### Correct with metadata
+
+```python
+from docorient import correct_image
+
+result = correct_image(image, return_metadata=True)
+print(result.orientation.angle)
+result.image.save("fixed.jpg")
+```
+
+### Correct multi-page document (majority voting)
+
+```python
+from docorient import correct_document_pages
+
+pages = [Image.open(f"page_{i}.jpg") for i in range(5)]
+corrected_pages = correct_document_pages(pages)
+```
+
+### Batch process a directory
+
+```python
+from docorient import process_directory, OrientationConfig
+
+config = OrientationConfig(workers=4, output_quality=95)
+summary = process_directory("./scans", output_dir="./fixed", config=config)
+
+print(f"Corrected: {summary.corrected}/{summary.total_pages}")
+```
+
+### CLI
+
+```bash
+docorient ./scans --output ./fixed --workers 4
+docorient ./scans --dry-run
+docorient ./scans --no-ocr --limit 100
+```
+
+## How It Works
+
+1. **Projection profile analysis** detects 90° and 270° rotations by comparing horizontal vs vertical text energy
+2. **Tesseract OSD** (optional) detects 180° rotation with confidence thresholding
+3. **Majority voting** across pages of the same document improves reliability
+
+## Supported Formats
+
+Any format readable by Pillow: JPEG, PNG, TIFF, BMP, GIF, WebP, and more.
+
+## Configuration
+
+```python
+from docorient import OrientationConfig
+
+config = OrientationConfig(
+    osd_confidence_threshold=2.0,
+    output_quality=92,
+    max_osd_dimension=1200,
+    projection_target_dimension=800,
+    workers=4,
+    resume_enabled=True,
+)
+```
+
+## License
+
+MIT

docorient-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "docorient"
+version = "0.1.0"
+description = "Document image orientation detection and correction using projection profile analysis and optional Tesseract OSD."
+readme = "README.md"
+license = "MIT"
+requires-python = ">= 3.10"
+authors = [{ name = "Cebraspe Lab" }]
+keywords = ["document", "orientation", "rotation", "ocr", "image", "correction", "tesseract"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "Pillow >= 10.0",
+    "numpy >= 1.24",
+    "tqdm >= 4.60",
+]
+
+[project.optional-dependencies]
+ocr = ["pytesseract >= 0.3.10"]
+dev = ["pytest >= 8.0", "pytest-cov", "ruff >= 0.4", "build", "twine"]
+
+[project.scripts]
+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"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docorient"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+ignore = ["B905"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

docorient-0.1.0/src/docorient/__init__.py

@@ -0,0 +1,36 @@
+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.exceptions import (
+    BatchProcessingError,
+    CorrectionError,
+    DetectionError,
+    DocorientError,
+    TesseractNotAvailableError,
+)
+from docorient.types import (
+    BatchSummary,
+    CorrectionResult,
+    OrientationResult,
+    PageResult,
+)
+
+__all__ = [
+    "BatchProcessingError",
+    "BatchSummary",
+    "CorrectionError",
+    "CorrectionResult",
+    "DetectionError",
+    "DocorientError",
+    "OrientationConfig",
+    "OrientationResult",
+    "PageResult",
+    "TesseractNotAvailableError",
+    "__version__",
+    "correct_document_pages",
+    "correct_image",
+    "detect_orientation",
+    "process_directory",
+]

docorient-0.1.0/src/docorient/_imaging.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image
+
+
+def open_as_rgb(image_path: str | Path) -> Image.Image:
+    return Image.open(image_path).convert("RGB")
+
+
+def downscale_to_max_dimension(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)
+
+
+def save_image(
+    image: Image.Image,
+    output_path: str | Path,
+    output_format: str = "JPEG",
+    quality: int = 92,
+) -> None:
+    image.save(output_path, output_format, quality=quality)
+
+
+def determine_output_format(file_path: str | Path) -> str:
+    extension = Path(file_path).suffix.lower()
+    format_mapping = {
+        ".jpg": "JPEG",
+        ".jpeg": "JPEG",
+        ".png": "PNG",
+        ".tiff": "TIFF",
+        ".tif": "TIFF",
+        ".bmp": "BMP",
+        ".gif": "GIF",
+        ".webp": "WEBP",
+    }
+    return format_mapping.get(extension, "JPEG")

docorient-0.1.0/src/docorient/_version.py

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

docorient-0.1.0/src/docorient/batch/__init__.py

@@ -0,0 +1,3 @@
+from docorient.batch.processor import process_directory
+
+__all__ = ["process_directory"]

docorient-0.1.0/src/docorient/batch/processor.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import multiprocessing
+import sys
+import time
+import uuid
+from dataclasses import asdict
+from pathlib import Path
+
+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.types import BatchSummary, PageResult
+
+
+def _load_completed_sources(resume_log_path: Path) -> set[str]:
+    if not resume_log_path.exists():
+        return set()
+    with open(resume_log_path) as resume_log:
+        return {line.strip() for line in resume_log if line.strip()}
+
+
+def _distribute_into_batches(
+    items: list[tuple[str, list[ScannedPage]]],
+    batch_count: int,
+) -> list[list[tuple[str, list[ScannedPage]]]]:
+    batches: list[list[tuple[str, list[ScannedPage]]]] = [[] for _ in range(batch_count)]
+    for item_index, item in enumerate(items):
+        target_batch = item_index % batch_count
+        batches[target_batch].append(item)
+    return batches
+
+
+def _build_summary(
+    input_directory: str,
+    output_directory: str,
+    total_files: int,
+    all_page_results: dict[str, list[PageResult]],
+    source_file_names: list[str],
+) -> BatchSummary:
+    all_pages: list[PageResult] = []
+    already_correct_count = 0
+    corrected_count = 0
+    corrected_by_majority_count = 0
+    error_count = 0
+
+    for source_name in source_file_names:
+        for page_result in all_page_results.get(source_name, []):
+            all_pages.append(page_result)
+            if page_result.error is not None:
+                error_count += 1
+            elif page_result.orientation.angle != 0:
+                corrected_count += 1
+                if "->majority" in page_result.orientation.method:
+                    corrected_by_majority_count += 1
+            else:
+                already_correct_count += 1
+
+    return BatchSummary(
+        input_directory=input_directory,
+        output_directory=output_directory,
+        total_files=total_files,
+        total_pages=len(all_pages),
+        already_correct=already_correct_count,
+        corrected=corrected_count,
+        corrected_by_majority=corrected_by_majority_count,
+        errors=error_count,
+        pages=tuple(all_pages),
+    )
+
+
+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()
+
+    if output_dir is None:
+        output_path = input_path.parent / str(uuid.uuid4())
+    else:
+        output_path = 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 = [
+        (source_name, pages_by_source[source_name])
+        for source_name in source_file_names
+        if source_name not in already_completed_sources
+    ]
+
+    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))
+    batches = _distribute_into_batches(pending_sources, worker_count)
+
+    progress_counter = multiprocessing.Value("i", 0)
+    progress_lock = multiprocessing.Lock()
+
+    config_as_dict = asdict(effective_config)
+
+    worker_pool = multiprocessing.Pool(
+        processes=worker_count,
+        initializer=initialize_worker,
+        initargs=(progress_counter, progress_lock, str(resume_log_path), config_as_dict),
+        maxtasksperchild=1,
+    )
+
+    async_results = [
+        worker_pool.apply_async(process_batch, (batch,)) for batch in batches
+    ]
+    worker_pool.close()
+
+    if show_progress:
+        progress_bar = tqdm(
+            total=len(pending_sources),
+            desc="Correcting",
+            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):
+            if progress_bar is not None:
+                progress_bar.n = progress_counter.value
+                progress_bar.refresh()
+            time.sleep(0.3)
+    except KeyboardInterrupt:
+        worker_pool.terminate()
+        worker_pool.join()
+        if progress_bar is not None:
+            progress_bar.close()
+        sys.exit(1)
+
+    if progress_bar is not None:
+        progress_bar.n = progress_counter.value
+        progress_bar.refresh()
+        progress_bar.close()
+
+    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
+
+    worker_pool.join()
+
+    return _build_summary(
+        str(input_path), str(output_path), total_files, all_page_results, source_file_names
+    )

docorient-0.1.0/src/docorient/batch/scanner.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+PAGE_PATTERN = re.compile(r"^(.+)_p(\d+)\.\w+$")
+
+
+@dataclass(frozen=True, slots=True)
+class ScannedPage:
+    source_file: str
+    page_number: int
+    image_name: str
+    image_path: str
+    output_path: str
+
+
+def scan_directory(
+    input_directory: Path,
+    output_directory: Path,
+    supported_extensions: tuple[str, ...],
+    limit: int = 0,
+) -> dict[str, list[ScannedPage]]:
+    all_image_paths = sorted(
+        image_path
+        for image_path in input_directory.iterdir()
+        if image_path.is_file() and image_path.suffix.lower() in supported_extensions
+    )
+
+    if limit > 0:
+        all_image_paths = all_image_paths[:limit]
+
+    pages_by_source: dict[str, list[ScannedPage]] = {}
+
+    for image_path in all_image_paths:
+        image_name = image_path.name
+        page_match = PAGE_PATTERN.match(image_name)
+
+        if page_match:
+            source_file_name = page_match.group(1)
+            page_number = int(page_match.group(2))
+        else:
+            source_file_name = image_path.stem
+            page_number = 1
+
+        output_path = output_directory / image_name
+
+        scanned_page = ScannedPage(
+            source_file=source_file_name,
+            page_number=page_number,
+            image_name=image_name,
+            image_path=str(image_path),
+            output_path=str(output_path),
+        )
+
+        pages_by_source.setdefault(source_file_name, []).append(scanned_page)
+
+    return pages_by_source