docorient 0.1.1

Document image orientation detection and correction using projection profile analysis and optional Tesseract OSD.

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

pip install docorient

For 180° detection via Tesseract OSD:

pip install docorient[ocr]

Note: The [ocr] extra requires Tesseract installed on your system.

Quick Start

Detect orientation

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

from docorient import correct_image

corrected = correct_image(image)
corrected.save("fixed.jpg")

Correct with metadata

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)

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

Note (macOS/Windows): process_directory uses multiprocessing internally. Always call it inside if __name__ == "__main__": when running as a script.

from docorient import process_directory, OrientationConfig

if __name__ == "__main__":
    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

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

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