docorient 0.1.0__py3-none-any.whl

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/_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/_version.py

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

docorient/batch/__init__.py

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

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/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

docorient/batch/worker.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import multiprocessing
+from typing import Any
+
+from docorient._imaging import determine_output_format, open_as_rgb, save_image
+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.types import OrientationResult, PageResult
+
+_shared_counter: Any = None
+_shared_lock: Any = None
+_shared_resume_log_path: str | None = None
+_shared_config_dict: dict[str, Any] | None = None
+
+
+def initialize_worker(
+    counter: multiprocessing.Value,
+    lock: multiprocessing.Lock,
+    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)
+
+
+def _process_single_source(
+    source_file_name: str,
+    pages: list[ScannedPage],
+    config: OrientationConfig,
+) -> list[PageResult]:
+    valid_pages = list(pages)
+    detection_results: list[OrientationResult] = []
+    page_errors: dict[int, str] = {}
+
+    for page_index, scanned_page in enumerate(valid_pages):
+        try:
+            image = open_as_rgb(scanned_page.image_path)
+            orientation = detect_orientation(image, config=config)
+            detection_results.append(orientation)
+            image.close()
+        except Exception as detection_error:
+            detection_results.append(OrientationResult(angle=0, method="error", reliable=False))
+            page_errors[page_index] = str(detection_error)
+
+    if len(valid_pages) > 1:
+        detection_results = _apply_majority_voting(detection_results)
+
+    page_results: list[PageResult] = []
+
+    for page_index, (scanned_page, orientation) in enumerate(zip(valid_pages, detection_results)):
+        error_message = page_errors.get(page_index)
+
+        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(
+                    corrected_image,
+                    scanned_page.output_path,
+                    output_format=output_format,
+                    quality=config.output_quality,
+                )
+                corrected_image.close()
+                image.close()
+            except Exception as save_error:
+                error_message = str(save_error)
+
+        page_results.append(
+            PageResult(
+                source_file=scanned_page.source_file,
+                page_number=scanned_page.page_number,
+                image_name=scanned_page.image_name,
+                input_path=scanned_page.image_path,
+                output_path=scanned_page.output_path,
+                orientation=orientation,
+                error=error_message,
+            )
+        )
+
+    return page_results
+
+
+def _record_completion(source_file_name: str) -> None:
+    with _shared_lock:
+        _shared_counter.value += 1
+        try:
+            with open(_shared_resume_log_path, "a") as resume_log:
+                resume_log.write(source_file_name + "\n")
+                resume_log.flush()
+        except OSError:
+            pass
+
+
+def process_batch(
+    batch: list[tuple[str, list[ScannedPage]]],
+) -> list[tuple[str, list[PageResult]]]:
+    config = _reconstruct_config()
+    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)
+        batch_results.append((source_file_name, page_results))
+        _record_completion(source_file_name)
+
+    return batch_results

docorient/cli.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from docorient._version import __version__
+from docorient.batch.processor import process_directory
+from docorient.config import OrientationConfig
+from docorient.detection.osd import is_tesseract_available
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="docorient",
+        description="Detect and correct document image orientation.",
+    )
+    parser.add_argument(
+        "input_dir",
+        type=str,
+        help="Directory containing document images to process.",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        type=str,
+        default=None,
+        dest="output_dir",
+        help="Output directory for corrected images. Default: auto-generated UUID.",
+    )
+    parser.add_argument(
+        "--workers", "-w",
+        type=int,
+        default=None,
+        help="Number of parallel worker processes. Default: cpu_count - 2.",
+    )
+    parser.add_argument(
+        "--limit", "-l",
+        type=int,
+        default=0,
+        help="Maximum number of images to process. 0 means all.",
+    )
+    parser.add_argument(
+        "--quality", "-q",
+        type=int,
+        default=92,
+        help="Output JPEG quality (1-100). Default: 92.",
+    )
+    parser.add_argument(
+        "--confidence",
+        type=float,
+        default=2.0,
+        help="OSD confidence threshold. Default: 2.0.",
+    )
+    parser.add_argument(
+        "--no-ocr",
+        action="store_true",
+        default=False,
+        help="Disable Tesseract OSD (only projection-based detection).",
+    )
+    parser.add_argument(
+        "--no-resume",
+        action="store_true",
+        default=False,
+        help="Disable resume from previous run.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="Only show what would be done, without processing.",
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"docorient {__version__}",
+    )
+    return parser
+
+
+def _print_dry_run_info(input_path: Path, config: OrientationConfig, limit: int) -> None:
+    from docorient.batch.scanner import scan_directory
+
+    temp_output = input_path.parent / "__dry_run_temp__"
+    pages_by_source = scan_directory(
+        input_path,
+        temp_output,
+        supported_extensions=config.supported_extensions,
+        limit=limit,
+    )
+
+    total_files = len(pages_by_source)
+    total_pages = sum(len(pages) for pages in pages_by_source.values())
+
+    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"  OCR:         {'enabled' if is_tesseract_available() else 'disabled'}")
+    print(f"  Quality:     {config.output_quality}")
+    print(f"  Resume:      {'enabled' if config.resume_enabled else 'disabled'}")
+    print(f"{'=' * 60}\n")
+
+
+def _print_summary(summary) -> None:
+    print(f"\n{'=' * 60}")
+    print("  SUMMARY")
+    print(f"{'=' * 60}")
+    print(f"  Output:               {summary.output_directory}")
+    print(f"  Files processed:      {summary.total_files}")
+    print(f"  Total pages:          {summary.total_pages}")
+    print(f"  Already correct (0°): {summary.already_correct}")
+    print(f"  Corrected:            {summary.corrected}")
+    if summary.corrected_by_majority > 0:
+        print(f"    (majority vote):    {summary.corrected_by_majority}")
+    print(f"  Errors:               {summary.errors}")
+    print(f"{'=' * 60}\n")
+
+    corrected_pages = [
+        page for page in summary.pages
+        if page.orientation.angle != 0 and page.error is None
+    ]
+    if corrected_pages:
+        print("Corrections applied:")
+        for page in corrected_pages:
+            print(f"  {page.image_name}: {page.orientation.angle}° ({page.orientation.method})")
+        print()
+
+
+def main() -> None:
+    parser = _build_argument_parser()
+    arguments = parser.parse_args()
+
+    input_path = Path(arguments.input_dir)
+    if not input_path.is_dir():
+        print(f"Error: '{arguments.input_dir}' is not a valid directory.", file=sys.stderr)
+        sys.exit(1)
+
+    osd_threshold = arguments.confidence if not arguments.no_ocr else float("inf")
+
+    config = OrientationConfig(
+        osd_confidence_threshold=osd_threshold,
+        output_quality=arguments.quality,
+        workers=arguments.workers,
+        resume_enabled=not arguments.no_resume,
+    )
+
+    if arguments.dry_run:
+        _print_dry_run_info(input_path, config, arguments.limit)
+        return
+
+    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"  OCR:         {'disabled' if arguments.no_ocr else 'enabled'}")
+    print(f"  Quality:     {config.output_quality}")
+    print(f"{'=' * 60}\n")
+
+    summary = process_directory(
+        input_dir=input_path,
+        output_dir=arguments.output_dir,
+        config=config,
+        limit=arguments.limit,
+    )
+
+    _print_summary(summary)
+
+
+if __name__ == "__main__":
+    main()

docorient/config.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import multiprocessing
+from dataclasses import dataclass, field
+
+DEFAULT_SUPPORTED_EXTENSIONS: tuple[str, ...] = (
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".tiff",
+    ".tif",
+    ".bmp",
+    ".gif",
+    ".webp",
+)
+
+RESUME_LOG_FILENAME = "_orientation_done.log"
+
+
+def _default_worker_count() -> int:
+    return max(1, multiprocessing.cpu_count() - 2)
+
+
+@dataclass(frozen=True, slots=True)
+class OrientationConfig:
+    osd_confidence_threshold: float = 2.0
+    output_quality: int = 92
+    max_osd_dimension: int = 1200
+    projection_target_dimension: int = 800
+    workers: int | None = None
+    resume_enabled: bool = True
+    supported_extensions: tuple[str, ...] = field(
+        default_factory=lambda: DEFAULT_SUPPORTED_EXTENSIONS
+    )
+
+    @property
+    def effective_workers(self) -> int:
+        if self.workers is not None:
+            return max(1, self.workers)
+        return _default_worker_count()

docorient/correction.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import overload
+
+from PIL import Image
+
+from docorient.config import OrientationConfig
+from docorient.detection.engine import detect_orientation
+from docorient.types import CorrectionResult, OrientationResult
+
+
+def _apply_rotation(image: Image.Image, angle: int) -> Image.Image:
+    if angle == 0:
+        return image.copy()
+    return image.rotate(angle, expand=True)
+
+
+@overload
+def correct_image(
+    image: Image.Image,
+    *,
+    config: OrientationConfig | None = ...,
+    return_metadata: bool = False,
+) -> Image.Image: ...
+
+
+@overload
+def correct_image(
+    image: Image.Image,
+    *,
+    config: OrientationConfig | None = ...,
+    return_metadata: bool = True,
+) -> CorrectionResult: ...
+
+
+def correct_image(
+    image: Image.Image,
+    *,
+    config: OrientationConfig | None = None,
+    return_metadata: bool = False,
+) -> Image.Image | CorrectionResult:
+    """Detect and correct the orientation of a single document image.
+
+    Args:
+        image: PIL Image to correct.
+        config: Optional configuration. Uses defaults if not provided.
+        return_metadata: If True, returns CorrectionResult with image and detection metadata.
+
+    Returns:
+        Corrected PIL Image, or CorrectionResult if return_metadata is True.
+    """
+    orientation = detect_orientation(image, config=config)
+    corrected_image = _apply_rotation(image, orientation.angle)
+
+    if return_metadata:
+        return CorrectionResult(image=corrected_image, orientation=orientation)
+    return corrected_image
+
+
+def _apply_majority_voting(
+    detection_results: list[OrientationResult],
+) -> list[OrientationResult]:
+    confident_angles = [
+        result.angle for result in detection_results if result.reliable
+    ]
+
+    if not confident_angles:
+        return detection_results
+
+    majority_angle = Counter(confident_angles).most_common(1)[0][0]
+    corrected_results = []
+
+    for result in detection_results:
+        if not result.reliable and result.angle != majority_angle:
+            corrected_results.append(
+                OrientationResult(
+                    angle=majority_angle,
+                    method=f"{result.method}->majority({majority_angle},was={result.angle})",
+                    reliable=True,
+                )
+            )
+        else:
+            corrected_results.append(result)
+
+    return corrected_results
+
+
+def correct_document_pages(
+    pages: list[Image.Image],
+    *,
+    config: OrientationConfig | None = None,
+) -> list[CorrectionResult]:
+    """Correct orientation of multiple pages from the same document using majority voting.
+
+    Detects orientation for each page individually, then applies majority voting
+    to override low-confidence detections with the most common angle.
+
+    Args:
+        pages: List of PIL Images representing pages of the same document.
+        config: Optional configuration. Uses defaults if not provided.
+
+    Returns:
+        List of CorrectionResult, one per input page.
+    """
+    effective_config = config or OrientationConfig()
+
+    detection_results = [
+        detect_orientation(page_image, config=effective_config) for page_image in pages
+    ]
+
+    if len(pages) > 1:
+        detection_results = _apply_majority_voting(detection_results)
+
+    correction_results = []
+    for page_image, orientation in zip(pages, detection_results):
+        corrected_page = _apply_rotation(page_image, orientation.angle)
+        correction_results.append(
+            CorrectionResult(image=corrected_page, orientation=orientation)
+        )
+
+    return correction_results

docorient/detection/__init__.py

@@ -0,0 +1,3 @@
+from docorient.detection.engine import detect_orientation
+
+__all__ = ["detect_orientation"]

docorient/detection/engine.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from PIL import Image
+
+from docorient.config import OrientationConfig
+from docorient.detection.osd import detect_orientation_by_osd
+from docorient.detection.projection import detect_orientation_by_projection
+from docorient.types import OrientationResult
+
+
+def detect_orientation(
+    image: Image.Image,
+    config: OrientationConfig | None = None,
+) -> OrientationResult:
+    """Detect the orientation of a document image.
+
+    Uses projection profile analysis for 90°/270° detection
+    and optionally Tesseract OSD for 180° detection.
+
+    Args:
+        image: PIL Image to analyze.
+        config: Optional configuration. Uses defaults if not provided.
+
+    Returns:
+        OrientationResult with detected angle, method description, and reliability flag.
+    """
+    effective_config = config or OrientationConfig()
+
+    projection_result = detect_orientation_by_projection(
+        image,
+        target_dimension=effective_config.projection_target_dimension,
+    )
+
+    if projection_result.angle in (90, 270):
+        return projection_result
+
+    osd_result = detect_orientation_by_osd(
+        image,
+        max_dimension=effective_config.max_osd_dimension,
+        confidence_threshold=effective_config.osd_confidence_threshold,
+    )
+
+    if osd_result is not None:
+        combined_method = f"{osd_result.method},{projection_result.method}"
+        return OrientationResult(
+            angle=osd_result.angle,
+            method=combined_method,
+            reliable=True,
+        )
+
+    return projection_result

docorient/detection/osd.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import warnings
+
+from PIL import Image
+
+from docorient._imaging import downscale_to_max_dimension
+from docorient.types import OrientationResult
+
+_tesseract_available: bool | None = None
+
+
+def is_tesseract_available() -> bool:
+    global _tesseract_available
+    if _tesseract_available is None:
+        try:
+            import pytesseract  # noqa: F401
+
+            _tesseract_available = True
+        except ImportError:
+            _tesseract_available = False
+    return _tesseract_available
+
+
+def _query_tesseract_osd(image: Image.Image) -> tuple[int, float]:
+    import pytesseract
+
+    try:
+        osd_result = pytesseract.image_to_osd(image, output_type=pytesseract.Output.DICT)
+        detected_angle = int(osd_result.get("orientation", 0))
+        detection_confidence = float(osd_result.get("orientation_conf", 0.0))
+        return detected_angle, detection_confidence
+    except pytesseract.TesseractError:
+        return 0, 0.0
+
+
+def detect_orientation_by_osd(
+    image: Image.Image,
+    max_dimension: int = 1200,
+    confidence_threshold: float = 2.0,
+) -> OrientationResult | None:
+    """Detect document orientation using Tesseract OSD.
+
+    Returns OrientationResult if a confident detection is made, None otherwise.
+    Returns None immediately if pytesseract is not installed.
+    """
+    if not is_tesseract_available():
+        warnings.warn(
+            "pytesseract is not installed. 180° detection is disabled. "
+            "Install with: pip install docorient[ocr]",
+            UserWarning,
+            stacklevel=2,
+        )
+        return None
+
+    downscaled_image = downscale_to_max_dimension(image, max_dimension)
+    detected_angle, detection_confidence = _query_tesseract_osd(downscaled_image)
+
+    if downscaled_image is not image:
+        downscaled_image.close()
+
+    if detection_confidence < confidence_threshold:
+        return None
+
+    if detected_angle not in (90, 180, 270):
+        return None
+
+    return OrientationResult(
+        angle=detected_angle,
+        method=f"osd(angle={detected_angle},conf={detection_confidence:.1f})",
+        reliable=True,
+    )

docorient/detection/projection.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image
+
+from docorient._imaging import downscale_to_max_dimension
+from docorient.types import OrientationResult
+
+PROJECTION_ANALYSIS_DIMENSION = 800
+ENERGY_EPSILON = 1e-10
+
+
+def _compute_projection_energy(pixel_array: np.ndarray, threshold: float) -> tuple[float, float]:
+    binary_mask = (pixel_array < threshold).astype(np.float32)
+    horizontal_projection = binary_mask.sum(axis=1)
+    vertical_projection = binary_mask.sum(axis=0)
+    horizontal_energy = float(np.mean(np.diff(horizontal_projection) ** 2))
+    vertical_energy = float(np.mean(np.diff(vertical_projection) ** 2))
+    return horizontal_energy, vertical_energy
+
+
+def _compute_energy_ratio(horizontal_energy: float, vertical_energy: float) -> float:
+    return horizontal_energy / (vertical_energy + ENERGY_EPSILON)
+
+
+def detect_orientation_by_projection(
+    image: Image.Image,
+    target_dimension: int = PROJECTION_ANALYSIS_DIMENSION,
+) -> OrientationResult:
+    """Detect document orientation using horizontal/vertical projection profile energy analysis.
+
+    Returns OrientationResult with angle 0 (horizontal), 90 or 270 (vertical, needs rotation).
+    """
+    grayscale_image = image.convert("L")
+    downscaled_image = downscale_to_max_dimension(grayscale_image, target_dimension)
+    if downscaled_image is not grayscale_image:
+        grayscale_image.close()
+
+    pixel_array = np.array(downscaled_image, dtype=np.float32)
+    downscaled_image.close()
+    brightness_threshold = float(pixel_array.mean())
+
+    horizontal_energy, vertical_energy = _compute_projection_energy(
+        pixel_array, brightness_threshold
+    )
+    energy_ratio = _compute_energy_ratio(horizontal_energy, vertical_energy)
+
+    if energy_ratio > 1.0:
+        return OrientationResult(
+            angle=0,
+            method=f"projection(h/v={energy_ratio:.2f},horizontal)",
+            reliable=True,
+        )
+
+    rotated_array = np.rot90(pixel_array, k=1)
+    rotated_horizontal_energy, rotated_vertical_energy = _compute_projection_energy(
+        rotated_array, brightness_threshold
+    )
+    rotated_energy_ratio = _compute_energy_ratio(rotated_horizontal_energy, rotated_vertical_energy)
+
+    if rotated_energy_ratio > energy_ratio:
+        return OrientationResult(
+            angle=90,
+            method=f"projection(h/v={energy_ratio:.2f}->90ccw:{rotated_energy_ratio:.2f})",
+            reliable=True,
+        )
+
+    return OrientationResult(
+        angle=270,
+        method=f"projection(h/v={energy_ratio:.2f}->270ccw)",
+        reliable=True,
+    )

docorient/exceptions.py

@@ -0,0 +1,18 @@
+class DocorientError(Exception):
+    pass
+
+
+class DetectionError(DocorientError):
+    pass
+
+
+class CorrectionError(DocorientError):
+    pass
+
+
+class BatchProcessingError(DocorientError):
+    pass
+
+
+class TesseractNotAvailableError(DocorientError):
+    pass

docorient/types.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from PIL import Image as PILImage
+
+
+@dataclass(frozen=True, slots=True)
+class OrientationResult:
+    angle: int
+    method: str
+    reliable: bool
+
+
+@dataclass(frozen=True, slots=True)
+class CorrectionResult:
+    image: PILImage.Image
+    orientation: OrientationResult
+
+
+@dataclass(frozen=True, slots=True)
+class PageResult:
+    source_file: str
+    page_number: int
+    image_name: str
+    input_path: str
+    output_path: str
+    orientation: OrientationResult
+    error: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BatchSummary:
+    input_directory: str
+    output_directory: str
+    total_files: int
+    total_pages: int
+    already_correct: int
+    corrected: int
+    corrected_by_majority: int
+    errors: int
+    pages: tuple[PageResult, ...]

docorient-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+docorient/__init__.py,sha256=J_B5pjSvSZknWhctdEYtRs2iOwGoVrOAzL7NtRmGQ54,919
+docorient/_imaging.py,sha256=iO0-LjaH5QjiHcTUzHML5LCVcTAYxZlD4oK9lZJ078A,1232
+docorient/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+docorient/cli.py,sha256=zNepvIuVt-clLL37XzFZTaCcleV8jiPnIQ2DwmCPDRs,5467
+docorient/config.py,sha256=AVeX4GbsdgJyBC9uIeAD8fvIMKAJuRkeSh-JsR_elPk,951
+docorient/correction.py,sha256=L-uuOcGQKZXqFnTFccl4SvR20dOezNinLndrIx5OSDk,3630
+docorient/exceptions.py,sha256=vdWkgbQH3DJLce5LFlKe9AnIUYmRMho4Sq0p9HdKVRo,257
+docorient/types.py,sha256=qo3KbtyJOo-xxXivMAErOBeX6AnxtBDlELuj4bGFfys,840
+docorient/batch/__init__.py,sha256=tr5WRSoQC0PRNB4N_Z7TwkR3ZzOyCmD-KStlMjAvz6I,89
+docorient/batch/processor.py,sha256=3PvwGAxvKQdJO1yRlxnMtIngvb9oZArlUfL2ajdO6JY,6349
+docorient/batch/scanner.py,sha256=0CGUbRwPnEkDJKYyHYkNCXffy5DZXV3s-cplvjQ-XSo,1555
+docorient/batch/worker.py,sha256=qBegpAqTajoUHOI4QhjxvoZuvnPysvcbgmRTIF8wi_I,4097
+docorient/detection/__init__.py,sha256=1i2bVoFXfpQe8u7O3HjRpkXqAFxi6kNvA8xbYZkVZjA,92
+docorient/detection/engine.py,sha256=iG4CoY1ofoCrXSc5QjzoiB9UHi6RmLQf8lQ2Wz_FTxU,1567
+docorient/detection/osd.py,sha256=EiI0yYPx5VgwoaX4AXXAVAeH2KF5QGaRLAXwmRTGhNA,2148
+docorient/detection/projection.py,sha256=-WugLjtgzqi3fP7XxAAJLpRRTzGzNwSpcWd4MULOUeI,2594
+docorient-0.1.0.dist-info/METADATA,sha256=kp2j0qcfAZJp4-bQ5hl9TFPE5tSWLQgV_38ZtoIHY3k,3890
+docorient-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+docorient-0.1.0.dist-info/entry_points.txt,sha256=yxZkcXy-6woVnA6vxEX3vi_ywPaa2RsQkn282hDrEDc,49
+docorient-0.1.0.dist-info/licenses/LICENSE,sha256=wUKLgf8GreWy4jQrdQOyEUBchTfAns3QvgCNgW_IlNc,1069
+docorient-0.1.0.dist-info/RECORD,,

docorient-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docorient-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docorient = docorient.cli:main

docorient-0.1.0.dist-info/licenses/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.