pdforienter 0.1.0__py3-none-any.whl

pdforienter/__init__.py

@@ -0,0 +1,30 @@
+"""
+PDFOrienter — Intelligent, parallel PDF page rotation correction.
+
+Public API
+----------
+    run_pipeline(pdf_paths, output_dir) -> RunResult
+"""
+
+from typing import Any
+
+from pdforienter.models import FileResult, PageResult, PageType, RunResult
+
+__all__ = [
+    "run_pipeline",
+    "RunResult",
+    "FileResult",
+    "PageResult",
+    "PageType",
+]
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy export — defer importing the pipeline (and its transitive
+    # pytesseract / PyMuPDF dependencies) until the symbol is actually used.
+    if name == "run_pipeline":
+        from pdforienter.core.pipeline import run_pipeline
+        return run_pipeline
+    raise AttributeError(f"module 'pdforienter' has no attribute {name!r}")

pdforienter/cli.py

@@ -0,0 +1,66 @@
+"""
+Command-line interface for PDFOrienter.
+
+Usage
+-----
+    pdforienter <pdf_or_dir> [<pdf_or_dir> ...] --output <dir>
+
+Examples
+--------
+    pdforienter invoice.pdf --output ./fixed
+    pdforienter /scans/ report.pdf --output /corrected
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from pdforienter.core.pipeline import run_pipeline
+from pdforienter.logging.writer import write_log
+from pdforienter.utils.fs import resolve_pdf_paths
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pdforienter",
+        description="Automatically fix PDF page orientations.",
+    )
+    parser.add_argument(
+        "inputs",
+        nargs="+",
+        metavar="PDF_OR_DIR",
+        help="One or more PDF files or directories to process.",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        required=True,
+        metavar="OUTPUT_DIR",
+        help="Directory where corrected PDFs and the log will be saved.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    pdf_paths = resolve_pdf_paths(args.inputs)
+    if not pdf_paths:
+        print("No PDF files found in the provided paths.", file=sys.stderr)
+        return 1
+
+    print(f"Processing {len(pdf_paths)} PDF file(s)…")
+    result = run_pipeline(pdf_paths, args.output)
+    log_path = write_log(result, args.output)
+
+    print(
+        f"\nDone. {result.total_pages_changed}/{result.total_pages} pages rotated "
+        f"across {result.total_files} file(s) in {result.total_duration_seconds:.1f}s."
+    )
+    print(f"Log written to: {log_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pdforienter/config.py

@@ -0,0 +1,40 @@
+"""
+Global configuration and tuneable constants for PDFOrienter.
+"""
+
+import math
+import os
+
+# ---------------------------------------------------------------------------
+# Worker pool
+# ---------------------------------------------------------------------------
+# Use 75 % of available logical CPUs, minimum 1, to leave headroom for the OS
+# and other processes running on the same host.
+CPU_COUNT: int = os.cpu_count() or 1
+MAX_WORKERS: int = max(1, math.floor(CPU_COUNT * 0.75))
+
+# ---------------------------------------------------------------------------
+# Tesseract / OSD
+# ---------------------------------------------------------------------------
+# Tesseract Page Segmentation Mode 0 = Orientation and Script Detection only.
+# Much faster than full OCR — no character recognition is performed.
+TESSERACT_OSD_PSM: int = 0
+
+# Minimum OSD confidence (0-100) required to trust the detected orientation.
+OSD_CONFIDENCE_THRESHOLD: float = 10.0
+
+# ---------------------------------------------------------------------------
+# Rotation
+# ---------------------------------------------------------------------------
+# Only these discrete angles (degrees) are considered valid rotations.
+VALID_ROTATIONS: tuple[int, ...] = (0, 90, 180, 270)
+
+# ---------------------------------------------------------------------------
+# File limits
+# ---------------------------------------------------------------------------
+MAX_FILE_SIZE_MB: int = 200
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+LOG_DATE_FORMAT: str = "%Y-%m-%d %H:%M:%S"

pdforienter/core/analyzer.py

@@ -0,0 +1,80 @@
+"""
+analyse_page — the unit of work dispatched to each worker process.
+
+Responsibility: open one page, classify it, detect orientation, return
+a PageResult.  This function is intentionally self-contained so it can
+be safely pickled and sent to a ProcessPoolExecutor worker.
+"""
+
+from __future__ import annotations
+
+import time
+
+import fitz  # PyMuPDF
+
+from pdforienter.core.classifier import has_text_layer
+from pdforienter.core.detector import osd_orientation, text_orientation
+from pdforienter.models import PageResult, PageType
+
+
+def analyse_page(pdf_path: str, page_index: int) -> PageResult:
+    """
+    Analyse a single page and return its *PageResult*.
+
+    Parameters
+    ----------
+    pdf_path:
+        Absolute path to the source PDF.
+    page_index:
+        Zero-based page index within the document.
+    """
+    start = time.perf_counter()
+    page_number = page_index + 1  # convert to 1-based for reporting
+
+    doc = fitz.open(pdf_path)
+    try:
+        page = doc[page_index]
+        existing_rotation = int(page.rotation)
+
+        if has_text_layer(page):
+            page_type = PageType.TEXT
+            detected_angle, confidence = text_orientation(page)
+        else:
+            page_type = PageType.SCANNED
+            detected_angle, confidence = osd_orientation(page)
+
+        if detected_angle == 0:
+            changed = False
+            correction = 0
+            reason = "No rotation needed."
+        else:
+            changed = True
+            correction = detected_angle
+            reason = f"Rotation of {detected_angle}° detected (confidence {confidence:.1f})."
+
+    except Exception as exc:  # noqa: BLE001
+        return PageResult(
+            page_number=page_number,
+            page_type=PageType.SKIPPED,
+            detected_angle=0,
+            existing_rotation=0,
+            correction_applied=0,
+            changed=False,
+            confidence=-1.0,
+            reason=f"Error during analysis: {exc}",
+            duration_seconds=time.perf_counter() - start,
+        )
+    finally:
+        doc.close()
+
+    return PageResult(
+        page_number=page_number,
+        page_type=page_type,
+        detected_angle=detected_angle,
+        existing_rotation=existing_rotation,
+        correction_applied=correction,
+        changed=changed,
+        confidence=confidence,
+        reason=reason,
+        duration_seconds=time.perf_counter() - start,
+    )

pdforienter/core/classifier.py

@@ -0,0 +1,18 @@
+"""
+Determine whether a PDF page has a selectable text layer.
+
+Responsibility: single — classify one page as TEXT or SCANNED.
+"""
+
+from __future__ import annotations
+
+import fitz  # PyMuPDF
+
+# Minimum number of characters required to treat a page as text-based.
+_MIN_CHAR_COUNT: int = 20
+
+
+def has_text_layer(page: fitz.Page) -> bool:
+    """Return True when *page* contains enough selectable text to analyse."""
+    text = page.get_text("text")
+    return len(text.strip()) >= _MIN_CHAR_COUNT

pdforienter/core/corrector.py

@@ -0,0 +1,61 @@
+"""
+Apply collected rotation corrections to a PDF in a single write pass.
+
+Responsibility: given a list of PageResults, mutate the document's
+rotation metadata for every changed page and save once.
+"""
+
+from __future__ import annotations
+
+import time
+
+import fitz  # PyMuPDF
+
+from pdforienter.models import PageResult
+
+
+def apply_rotations(
+    input_path: str,
+    output_path: str,
+    page_results: list[PageResult],
+) -> float:
+    """
+    Write *output_path* with all required rotations applied in one pass.
+
+    Parameters
+    ----------
+    input_path:
+        Source PDF path.
+    output_path:
+        Destination PDF path (will be created / overwritten).
+    page_results:
+        Analysis results; only pages with ``changed=True`` are modified.
+
+    Returns
+    -------
+    float
+        Wall-clock seconds spent on the correction pass.
+    """
+    start = time.perf_counter()
+
+    doc = fitz.open(input_path)
+    try:
+        for result in page_results:
+            if not result.changed:
+                continue
+            page = doc[result.page_number - 1]  # back to 0-based
+            new_rotation = _normalise_rotation(
+                result.existing_rotation + result.correction_applied
+            )
+            page.set_rotation(new_rotation)
+
+        doc.save(output_path, garbage=4, deflate=True)
+    finally:
+        doc.close()
+
+    return time.perf_counter() - start
+
+
+def _normalise_rotation(degrees: int) -> int:
+    """Reduce *degrees* into the half-open range [0, 360)."""
+    return degrees % 360

pdforienter/core/detector.py

@@ -0,0 +1,91 @@
+"""
+Detect the orientation of a single PDF page.
+
+Two strategies:
+  1. text_orientation  — fast; uses PyMuPDF's character direction vectors.
+  2. osd_orientation   — slower; renders the page and calls Tesseract OSD.
+
+Responsibility: return (angle_degrees, confidence) for one page.
+"""
+
+from __future__ import annotations
+
+import fitz  # PyMuPDF
+
+from pdforienter.config import OSD_CONFIDENCE_THRESHOLD, TESSERACT_OSD_PSM
+
+# Resolution used when rasterising a page for OSD.
+_RENDER_DPI: int = 150  # lower = faster; sufficient for orientation detection
+
+
+# ---------------------------------------------------------------------------
+# Text-layer strategy
+# ---------------------------------------------------------------------------
+
+def text_orientation(page: fitz.Page) -> tuple[int, float]:
+    """
+    Infer orientation from character direction vectors in the text layer.
+
+    Returns (angle, confidence) where angle ∈ {0, 90, 180, 270} and
+    confidence is a value in [0, 100].
+    """
+    blocks = page.get_text("rawdict", flags=fitz.TEXT_PRESERVE_WHITESPACE)["blocks"]
+    angle_votes: dict[int, int] = {0: 0, 90: 0, 180: 0, 270: 0}
+
+    for block in blocks:
+        for line in block.get("lines", []):
+            direction = line.get("dir", (1, 0))
+            angle = _direction_to_angle(direction)
+            angle_votes[angle] += len(line.get("spans", []))
+
+    total = sum(angle_votes.values())
+    if total == 0:
+        return 0, 0.0
+
+    dominant = max(angle_votes, key=angle_votes.__getitem__)
+    confidence = (angle_votes[dominant] / total) * 100.0
+    return dominant, confidence
+
+
+def _direction_to_angle(direction: tuple[float, float]) -> int:
+    """Map a (cos, sin) direction vector to the nearest 90-degree angle."""
+    dx, dy = direction
+    if dx > 0.5:
+        return 0
+    if dx < -0.5:
+        return 180
+    if dy > 0.5:
+        return 270
+    return 90
+
+
+# ---------------------------------------------------------------------------
+# OSD (Tesseract) strategy
+# ---------------------------------------------------------------------------
+
+def osd_orientation(page: fitz.Page) -> tuple[int, float]:
+    """
+    Detect orientation by rasterising *page* and running Tesseract OSD.
+
+    Returns (angle, confidence).  Falls back to (0, 0.0) on any error.
+    """
+    try:
+        # Heavy imports kept lazy: text-only workloads never need Tesseract,
+        # and pytesseract pulls in pandas at module-load time.
+        import pytesseract
+        from PIL import Image
+
+        pix = page.get_pixmap(dpi=_RENDER_DPI, colorspace=fitz.csGRAY)
+        img = Image.frombytes("L", (pix.width, pix.height), pix.samples)
+        osd = pytesseract.image_to_osd(
+            img,
+            config=f"--psm {TESSERACT_OSD_PSM}",
+            output_type=pytesseract.Output.DICT,
+        )
+        angle = int(osd.get("rotate", 0))
+        confidence = float(osd.get("orientation_conf", 0.0))
+        if confidence < OSD_CONFIDENCE_THRESHOLD:
+            return 0, confidence
+        return angle, confidence
+    except Exception:  # noqa: BLE001
+        return 0, 0.0

pdforienter/core/pipeline.py

@@ -0,0 +1,55 @@
+"""
+run_pipeline — public entry point for PDFOrienter.
+
+Accepts one or more PDF paths, processes them (potentially in parallel
+across files), aggregates results, and returns a RunResult.
+
+Responsibility: top-level orchestration only; no PDF logic here.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from pdforienter.config import MAX_WORKERS
+from pdforienter.core.processor import process_file
+from pdforienter.models import FileResult, RunResult
+from pdforienter.utils.fs import ensure_dir
+from pdforienter.utils.resources import peak_ram_mb
+
+
+def run_pipeline(
+    pdf_paths: list[str],
+    output_dir: str,
+) -> RunResult:
+    """
+    Process one or more PDF files and return a *RunResult*.
+
+    Parameters
+    ----------
+    pdf_paths:
+        List of absolute or relative paths to PDF files.
+    output_dir:
+        Directory where corrected PDFs and the log file will be written.
+    """
+    ensure_dir(output_dir)
+    run_start = time.perf_counter()
+
+    file_results: list[FileResult] = [
+        process_file(str(Path(p).resolve()), output_dir)
+        for p in pdf_paths
+    ]
+
+    return RunResult(
+        total_files=len(file_results),
+        total_pages=sum(r.total_pages for r in file_results),
+        total_pages_changed=sum(r.pages_changed for r in file_results),
+        total_text_pages=sum(r.text_pages for r in file_results),
+        total_scanned_pages=sum(r.scanned_pages for r in file_results),
+        total_skipped_pages=sum(r.skipped_pages for r in file_results),
+        workers_used=MAX_WORKERS,
+        peak_ram_mb=peak_ram_mb(),
+        total_duration_seconds=time.perf_counter() - run_start,
+        file_results=file_results,
+    )

pdforienter/core/processor.py

@@ -0,0 +1,116 @@
+"""
+Orchestrate the two-phase pipeline for a single PDF file.
+
+Phase 1 — Parallel detection  : all pages analysed concurrently.
+Phase 2 — Single-pass correction: all rotations applied in one write.
+
+Responsibility: coordinate analyzer + corrector for one file.
+"""
+
+from __future__ import annotations
+
+import time
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+import fitz  # PyMuPDF
+
+from pdforienter.config import MAX_WORKERS
+from pdforienter.core.analyzer import analyse_page
+from pdforienter.core.corrector import apply_rotations
+from pdforienter.models import FileResult, PageResult, PageType
+
+
+def process_file(input_path: str, output_dir: str) -> FileResult:
+    """
+    Run the full detection + correction pipeline for *input_path*.
+
+    Parameters
+    ----------
+    input_path:
+        Absolute path to the source PDF.
+    output_dir:
+        Directory where the corrected PDF will be written.
+    """
+    file_start = time.perf_counter()
+    output_path = _build_output_path(input_path, output_dir)
+
+    try:
+        page_count = _page_count(input_path)
+        page_results = _detect_all_pages(input_path, page_count)
+        correction_duration = _correct_file(input_path, output_path, page_results)
+    except Exception as exc:  # noqa: BLE001
+        return FileResult(
+            input_path=input_path,
+            output_path=output_path,
+            total_pages=0,
+            pages_changed=0,
+            text_pages=0,
+            scanned_pages=0,
+            skipped_pages=0,
+            error=str(exc),
+            total_duration_seconds=time.perf_counter() - file_start,
+        )
+
+    detection_duration = sum(r.duration_seconds for r in page_results)
+
+    return FileResult(
+        input_path=input_path,
+        output_path=output_path,
+        total_pages=page_count,
+        pages_changed=sum(1 for r in page_results if r.changed),
+        text_pages=sum(1 for r in page_results if r.page_type == PageType.TEXT),
+        scanned_pages=sum(1 for r in page_results if r.page_type == PageType.SCANNED),
+        skipped_pages=sum(1 for r in page_results if r.page_type == PageType.SKIPPED),
+        page_results=page_results,
+        detection_duration_seconds=detection_duration,
+        correction_duration_seconds=correction_duration,
+        total_duration_seconds=time.perf_counter() - file_start,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _page_count(pdf_path: str) -> int:
+    doc = fitz.open(pdf_path)
+    count = int(doc.page_count)
+    doc.close()
+    return count
+
+
+def _detect_all_pages(pdf_path: str, page_count: int) -> list[PageResult]:
+    """Dispatch one worker per page; collect results in page order."""
+    results: dict[int, PageResult] = {}
+
+    with ProcessPoolExecutor(max_workers=MAX_WORKERS) as pool:
+        future_map = {
+            pool.submit(analyse_page, pdf_path, idx): idx
+            for idx in range(page_count)
+        }
+        for future in as_completed(future_map):
+            idx = future_map[future]
+            results[idx] = future.result()
+
+    return [results[i] for i in range(page_count)]
+
+
+def _correct_file(
+    input_path: str,
+    output_path: str,
+    page_results: list[PageResult],
+) -> float:
+    """Apply rotations only when at least one page needs changing."""
+    if not any(r.changed for r in page_results):
+        # Nothing to do — copy input to output as-is.
+        import shutil
+        shutil.copy2(input_path, output_path)
+        return 0.0
+
+    return apply_rotations(input_path, output_path, page_results)
+
+
+def _build_output_path(input_path: str, output_dir: str) -> str:
+    stem = Path(input_path).stem
+    return str(Path(output_dir) / f"{stem}_corrected.pdf")

pdforienter/logging/formatter.py

@@ -0,0 +1,87 @@
+"""
+Format a RunResult into a human-readable, structured text log.
+
+Responsibility: serialisation only — no I/O, no business logic.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pdforienter.config import LOG_DATE_FORMAT
+from pdforienter.models import FileResult, RunResult
+
+
+def format_run_log(result: RunResult) -> str:
+    """Return the full log string for *result*."""
+    sections = [
+        _header(),
+        _run_summary(result),
+        _separator(),
+        *[_file_section(fr) for fr in result.file_results],
+        _footer(),
+    ]
+    return "\n".join(sections)
+
+
+# ---------------------------------------------------------------------------
+# Section builders
+# ---------------------------------------------------------------------------
+
+def _header() -> str:
+    now = datetime.now().strftime(LOG_DATE_FORMAT)
+    return f"PDFOrienter Run Log — {now}\n{'=' * 60}"
+
+
+def _run_summary(r: RunResult) -> str:
+    return (
+        f"\n[RUN SUMMARY]\n"
+        f"  Total files processed : {r.total_files}\n"
+        f"  Total pages           : {r.total_pages}\n"
+        f"  Pages rotated         : {r.total_pages_changed}\n"
+        f"  Text pages            : {r.total_text_pages}\n"
+        f"  Scanned pages (OCR)   : {r.total_scanned_pages}\n"
+        f"  Skipped pages         : {r.total_skipped_pages}\n"
+        f"  Workers used          : {r.workers_used}\n"
+        f"  Peak RAM usage        : {r.peak_ram_mb:.1f} MB\n"
+        f"  Total time            : {r.total_duration_seconds:.2f}s\n"
+    )
+
+
+def _file_section(fr: FileResult) -> str:
+    lines = [
+        f"[FILE] {fr.input_path}",
+        f"  Output          : {fr.output_path}",
+        f"  Total pages     : {fr.total_pages}",
+        f"  Pages changed   : {fr.pages_changed}",
+        f"  Text pages      : {fr.text_pages}",
+        f"  Scanned pages   : {fr.scanned_pages}",
+        f"  Skipped pages   : {fr.skipped_pages}",
+        f"  Detection time  : {fr.detection_duration_seconds:.2f}s",
+        f"  Correction time : {fr.correction_duration_seconds:.2f}s",
+        f"  Total time      : {fr.total_duration_seconds:.2f}s",
+    ]
+
+    if fr.error:
+        lines.append(f"  ERROR           : {fr.error}")
+    else:
+        lines.append("  [PAGE DETAILS]")
+        for pr in fr.page_results:
+            status = "CHANGED" if pr.changed else "OK"
+            lines.append(
+                f"    p{pr.page_number:>4} | {pr.page_type.value:<7} | "
+                f"{status:<7} | angle={pr.detected_angle:>3}° | "
+                f"conf={pr.confidence:>5.1f} | {pr.duration_seconds:.2f}s | "
+                f"{pr.reason}"
+            )
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _separator() -> str:
+    return "-" * 60
+
+
+def _footer() -> str:
+    return "=" * 60 + "\nEnd of log.\n"

pdforienter/logging/writer.py

@@ -0,0 +1,25 @@
+"""
+Write formatted log content to disk.
+
+Responsibility: file I/O for log output only.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from pdforienter.models import RunResult
+from pdforienter.logging.formatter import format_run_log
+
+
+def write_log(result: RunResult, output_dir: str) -> str:
+    """
+    Serialise *result* and write the log to *output_dir*.
+
+    Returns the absolute path of the written log file.
+    """
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log_path = Path(output_dir) / f"pdforienter_{timestamp}.log"
+    log_path.write_text(format_run_log(result), encoding="utf-8")
+    return str(log_path)

pdforienter/models.py

@@ -0,0 +1,66 @@
+"""
+Pure-data classes used throughout PDFOrienter.
+
+No business logic lives here — only typed containers so every module
+shares a common vocabulary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class PageType(str, Enum):
+    TEXT = "text"       # selectable text layer present
+    SCANNED = "scanned" # image-only — OCR/OSD required
+    SKIPPED = "skipped" # could not be analysed (no text, low confidence …)
+
+
+@dataclass
+class PageResult:
+    """Analysis + correction outcome for a single PDF page."""
+
+    page_number: int          # 1-based
+    page_type: PageType
+    detected_angle: int       # angle reported by detector (degrees)
+    existing_rotation: int    # rotation already stored in PDF metadata
+    correction_applied: int   # net rotation written to the page (degrees)
+    changed: bool
+    confidence: float         # 0-100; -1 when N/A
+    reason: str               # human-readable explanation
+    duration_seconds: float   # wall-clock time for this page
+
+
+@dataclass
+class FileResult:
+    """Aggregated outcome for one PDF file."""
+
+    input_path: str
+    output_path: str
+    total_pages: int
+    pages_changed: int
+    text_pages: int
+    scanned_pages: int
+    skipped_pages: int
+    page_results: list[PageResult] = field(default_factory=list)
+    detection_duration_seconds: float = 0.0
+    correction_duration_seconds: float = 0.0
+    total_duration_seconds: float = 0.0
+    error: str | None = None
+
+
+@dataclass
+class RunResult:
+    """Top-level summary for an entire PDFOrienter run."""
+
+    total_files: int
+    total_pages: int
+    total_pages_changed: int
+    total_text_pages: int
+    total_scanned_pages: int
+    total_skipped_pages: int
+    workers_used: int
+    peak_ram_mb: float
+    total_duration_seconds: float
+    file_results: list[FileResult] = field(default_factory=list)

pdforienter/utils/fs.py

@@ -0,0 +1,32 @@
+"""
+Filesystem utility helpers.
+
+Responsibility: path / directory operations only.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def ensure_dir(directory: str) -> Path:
+    """Create *directory* (and all parents) if it does not already exist."""
+    path = Path(directory)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def resolve_pdf_paths(inputs: list[str]) -> list[str]:
+    """
+    Expand a list of paths to absolute PDF file paths.
+
+    Directories are walked recursively; non-PDF files are ignored.
+    """
+    resolved: list[str] = []
+    for raw in inputs:
+        p = Path(raw).resolve()
+        if p.is_dir():
+            resolved.extend(str(f) for f in sorted(p.rglob("*.pdf")))
+        elif p.suffix.lower() == ".pdf" and p.is_file():
+            resolved.append(str(p))
+    return resolved

pdforienter/utils/resources.py

@@ -0,0 +1,22 @@
+"""
+System resource measurement helpers.
+
+Responsibility: CPU and RAM telemetry only.
+"""
+
+from __future__ import annotations
+
+import os
+
+import psutil
+
+
+def peak_ram_mb() -> float:
+    """Return the current process RSS memory usage in megabytes."""
+    process = psutil.Process(os.getpid())
+    return float(process.memory_info().rss) / (1024 ** 2)
+
+
+def cpu_count() -> int:
+    """Return the number of logical CPUs available to the current process."""
+    return os.cpu_count() or 1

pdforienter-0.1.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: pdforienter
+Version: 0.1.0
+Summary: Intelligent, parallel PDF page rotation correction.
+Author: InfinitiBit GmbH
+Maintainer: InfinitiBit GmbH
+License: MIT
+Project-URL: Homepage, https://github.com/MdRahmatUllah/pdforienter
+Project-URL: Repository, https://github.com/MdRahmatUllah/pdforienter
+Project-URL: Issues, https://github.com/MdRahmatUllah/pdforienter/issues
+Project-URL: Documentation, https://github.com/MdRahmatUllah/pdforienter/blob/main/TECHNICAL.md
+Keywords: pdf,rotation,ocr,tesseract,document
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyMuPDF>=1.23
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: Pillow>=10.0
+Requires-Dist: psutil>=5.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# PDFOrienter
+
+**Intelligent, parallel PDF page rotation correction for Python.**
+
+PDFOrienter analyses every page of one or more PDF files, detects incorrect orientations, and fixes them in a single write pass — with no unnecessary re-processing.
+
+---
+
+## Features
+
+- **Two-phase pipeline** — detect all pages in parallel, then apply all corrections in a single write
+- **Smart strategy selection** — uses fast text-direction analysis for text-based pages; falls back to Tesseract OSD only for image/scanned pages
+- **Dynamic parallelism** — automatically uses 75 % of available CPU cores; scales from 4 to 64+ cores without any configuration change
+- **Detailed structured logging** — per-page and per-file timing, rotation details, confidence scores, RAM and CPU usage
+- **Zero intermediate files** — corrected PDFs are written once; originals are never modified
+- **Package-ready** — clean modular design, typed, fully testable
+
+---
+
+## Requirements
+
+### Python
+
+Python 3.10 or newer.
+
+### System dependency — Tesseract
+
+Tesseract must be installed on the host system **before** installing PDFOrienter.
+
+**Ubuntu / Debian**
+```bash
+sudo apt-get update && sudo apt-get install -y tesseract-ocr
+```
+
+**macOS (Homebrew)**
+```bash
+brew install tesseract
+```
+
+**Windows**
+
+Download and run the installer from the [Tesseract UB Mannheim releases](https://github.com/UB-Mannheim/tesseract/wiki), then add the install directory to your `PATH`.
+
+---
+
+## Installation
+
+```bash
+pip install pdforienter
+```
+
+For development (includes linting + test tools):
+
+```bash
+git clone https://github.com/your-org/pdforienter.git
+cd pdforienter
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### Command line
+
+```bash
+# Fix a single PDF
+pdforienter invoice.pdf --output ./fixed
+
+# Fix every PDF in a directory
+pdforienter /scans/ --output /corrected
+
+# Mix files and directories
+pdforienter report.pdf /archive/ receipts.pdf --output ./out
+```
+
+### Python API
+
+```python
+from pdforienter import run_pipeline
+from pdforienter.logging.writer import write_log
+
+result = run_pipeline(
+    pdf_paths=["invoice.pdf", "report.pdf"],
+    output_dir="./corrected",
+)
+
+# Write the structured log file
+log_path = write_log(result, "./corrected")
+
+print(f"{result.total_pages_changed} pages corrected in {result.total_duration_seconds:.1f}s")
+print(f"Log: {log_path}")
+```
+
+---
+
+## Log File
+
+Every run produces a timestamped `.log` file in the output directory.
+
+```
+PDFOrienter Run Log — 2024-11-01 14:32:05
+============================================================
+
+[RUN SUMMARY]
+  Total files processed : 3
+  Total pages           : 247
+  Pages rotated         : 18
+  Text pages            : 201
+  Scanned pages (OCR)   : 46
+  Skipped pages         : 0
+  Workers used          : 6
+  Peak RAM usage        : 312.4 MB
+  Total time            : 42.18s
+
+------------------------------------------------------------
+[FILE] /scans/invoice.pdf
+  Output          : /corrected/invoice_corrected.pdf
+  Total pages     : 12
+  Pages changed   : 3
+  Text pages      : 8
+  Scanned pages   : 4
+  Skipped pages   : 0
+  Detection time  : 9.41s
+  Correction time : 0.23s
+  Total time      : 9.64s
+  [PAGE DETAILS]
+     p   1 | text    | OK      | angle=  0° | conf= 98.2 | 0.11s | No rotation needed.
+     p   2 | scanned | CHANGED | angle= 90° | conf= 87.5 | 2.34s | Rotation of 90° detected (confidence 87.5).
+     ...
+```
+
+---
+
+## Project Structure
+
+```
+pdforienter/
+├── pdforienter/
+│   ├── __init__.py          # Public API: run_pipeline
+│   ├── config.py            # Tuneable constants (worker count, thresholds)
+│   ├── models.py            # Typed data classes (PageResult, FileResult, RunResult)
+│   ├── cli.py               # Command-line interface
+│   ├── core/
+│   │   ├── pipeline.py      # Top-level orchestrator
+│   │   ├── processor.py     # Per-file orchestrator (Phase 1 + Phase 2)
+│   │   ├── analyzer.py      # Per-page worker (dispatched to subprocess)
+│   │   ├── classifier.py    # Text vs scanned page detection
+│   │   ├── detector.py      # Orientation detection (text + OSD strategies)
+│   │   └── corrector.py     # Single-pass rotation applier
+│   ├── logging/
+│   │   ├── formatter.py     # RunResult → structured log string
+│   │   └── writer.py        # Write log file to disk
+│   └── utils/
+│       ├── fs.py            # Filesystem helpers
+│       └── resources.py     # CPU / RAM telemetry
+├── tests/
+│   └── test_core.py
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Configuration
+
+All tuneable constants live in `pdforienter/config.py`.
+
+| Constant | Default | Description |
+|---|---|---|
+| `MAX_WORKERS` | `floor(cpu_count × 0.75)` | Worker processes for parallel page analysis |
+| `OSD_CONFIDENCE_THRESHOLD` | `10.0` | Minimum Tesseract OSD confidence to trust a result |
+| `TESSERACT_OSD_PSM` | `0` | Tesseract page segmentation mode (0 = OSD only) |
+| `_RENDER_DPI` (detector.py) | `150` | DPI used when rasterising pages for OSD |
+| `_MIN_CHAR_COUNT` (classifier.py) | `20` | Minimum characters to classify a page as text-based |
+
+---
+
+## How It Works
+
+### Phase 1 — Parallel Detection
+
+Each page is dispatched to a subprocess worker via `ProcessPoolExecutor`. Workers run concurrently up to `MAX_WORKERS`.
+
+For each page:
+1. **Classify** — does the page have selectable text?
+2. **Detect orientation**
+   - *Text page* → analyse character direction vectors (fast, no OCR)
+   - *Scanned page* → rasterise at 150 DPI and run Tesseract OSD
+3. Return a `PageResult` with the detected angle, confidence, and timing
+
+### Phase 2 — Single-Pass Correction
+
+After all pages are analysed, a single `fitz.Document.save()` call applies every rotation and writes the corrected PDF. No intermediate files are created.
+
+---
+
+## Performance
+
+Typical estimates on an 8-core server (6 workers) with mixed text/scanned PDFs:
+
+| Scenario | Estimate |
+|---|---|
+| 2 000 pages, all text-based | ~1–2 minutes |
+| 2 000 pages, mixed 50/50 | ~7–8 minutes |
+| 2 000 pages, all scanned | ~15–17 minutes |
+
+RAM usage: ~200–400 MB per Tesseract worker. 6 workers ≈ 2.5 GB peak. Well within a 16 GB server.
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT

pdforienter-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+pdforienter/__init__.py,sha256=zWu665aCLdZahwZo69vWM8J2yQKfjqdI2wGanGpbENQ,758
+pdforienter/cli.py,sha256=4N7J4LPorKH8UejoRexdGgDoVyCz8jIHDhgCiloQSt0,1733
+pdforienter/config.py,sha256=4urbIquQOfLUMQtlC-PswQt2Eo-qAtyXEQ2ZGuBzvIk,1651
+pdforienter/models.py,sha256=zb7kWikz3omLSitjP3PKMBJcR8LiRDdD8wOOVF2kmWc,1883
+pdforienter/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdforienter/core/analyzer.py,sha256=IHrZdExx79w-K-7YWE-cU8q_4_99i91xqp4lwTVeGwo,2407
+pdforienter/core/classifier.py,sha256=3wZhXHmAF8uKu3feW9w-zsFjgKyMYoPJQun9hGzzNOk,496
+pdforienter/core/corrector.py,sha256=Zf_RevNTNCpZw5UswVagsjwc2XhSx9Ld-OMojjIpsqg,1530
+pdforienter/core/detector.py,sha256=9XV6b9E1HJkzfwaTtKNu2DlljTY9g8LRbI_PbE5wOb4,3094
+pdforienter/core/pipeline.py,sha256=CNGOWz-1G5ziVNYmMxipHvpvocIDjtQQEE2g-6qZLaw,1702
+pdforienter/core/processor.py,sha256=5cBX-LWDytH_8DdXAU5wBbE5P6gC-fpvmWVFg4aF8Eo,3858
+pdforienter/logging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdforienter/logging/formatter.py,sha256=Rp2SgjtAi54FGosVyXQwGqdI4KNj-6JLp7h78zqYNoc,2820
+pdforienter/logging/writer.py,sha256=BtYWZVe-wiZ1r-JzpIc15K2vh1LFrU6_5Uq2urzAqjU,686
+pdforienter/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdforienter/utils/fs.py,sha256=cNzJa5O6riV-rvpitLsfzG1CvcluJrqQnLIcquRnQU0,841
+pdforienter/utils/resources.py,sha256=F6193tGVylCYpYtsOVz3w5J0gVtRwreLCY3aFGmasvg,485
+pdforienter-0.1.0.dist-info/licenses/LICENSE,sha256=yBPpeen2dS_xfsiwE5iPbH-ekYEKDBLZO715EvKLIkc,1073
+pdforienter-0.1.0.dist-info/METADATA,sha256=0Ec4TJfk336-JZsypMscNYEapp7fUykG5XfpkzICnEc,8105
+pdforienter-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pdforienter-0.1.0.dist-info/entry_points.txt,sha256=HNa3K0WeJyLE91iQyjk0xodYDr93Mgx9oLWywv2-AS0,53
+pdforienter-0.1.0.dist-info/top_level.txt,sha256=8M7epoDEGKPZEBAUa1IpCgc_C9OjF4D6R7pLJpRtO0g,12
+pdforienter-0.1.0.dist-info/RECORD,,

pdforienter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdforienter-0.1.0.dist-info/entry_points.txt

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

pdforienter-0.1.0.dist-info/licenses/LICENSE

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

pdforienter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdforienter