attention-upright 0.1.0

Automatic image orientation detection and correction using PaddleOCR

Attention

Attention is a production-ready, high-accuracy Python library for automatically detecting and correcting document and image orientation using PaddleOCR.

Designed specifically for document intelligence, identity card verification (PAN cards, Aadhar, Passports, Driving Licenses), and general OCR pipelines, Attention handles complex rotations (0°, 90°, 180°, 270°, and fine fractional skew) with mathematical precision.

---

🌟 Key Features

• 📐 Dynamic Short-Edge Midpoint Axis Selection: Calculates true text reading directions regardless of initial word rotation.
• 🎯 Hybrid Deep-Learning & Geometric Deskew: Combines PaddleOCR's PP-LCNet_x1_0_doc_ori coarse orientation classifier with sub-degree vector geometric deskew.
• 🛡️ 180° Ambiguity Disambiguation: Evaluates text line crops to resolve upside-down text without false flips.
• 🔠 Noise-Resilient Text Filtering: Prioritizes non-ambiguous words ($\ge 5$ alphabetic letters) and automatically filters out phone UI system buttons ("Delete", "Share", "Edit", etc.).
• ⚡ High-Performance Downscaling Pre-Processing: Downscales large photos during OCR detection (MAX_DETECTION_DIM = 960) for 3x–5x faster CPU execution.
• 🦥 Lazy Initialization: Models load lazily on first use to ensure fast import times.
• 🖼️ In-Memory & Batch Ready: Fully supports in-memory NumPy arrays and OpenCV image buffers without writing temporary files to disk.

---

📦 Installation

Basic Installation (CPU)

pip install attention

Installation with GPU Support

pip install attention[gpu]

Local Development Installation

git clone https://github.com/girijageddavalasa/attention.git
cd Attention
pip install -e .

---

🚀 Quick Start

1. Simple Image Uprighting

import cv2
from attention import upright_image

# Load a rotated image
image = cv2.imread("rotated_document.jpg")

# Upright the image
uprighted = upright_image(image)

# Save the corrected image
cv2.imwrite("upright_document.jpg", uprighted)

2. Get Rotation Angle & Detailed Debug Info

from attention import upright_image

uprighted, angle, debug = upright_image(
    image, 
    return_angle=True, 
    return_debug=True
)

print(f"Rotation Applied: {angle:.2f}°")
print(f"Detected Text: '{debug['detected_text']}' (Conf: {debug['confidence']:.4f})")
print(f"Ambiguity Debug: {debug['ambiguity_debug']}")

---

⚙️ Configuration Options

Customize pipeline parameters using the Config class:

from attention import Config

# Downscale max dimension for 3x-5x faster OCR detection (default: 960)
Config.MAX_DETECTION_DIM = 960

# Enable/disable bilateral pre-filtering (default: True)
Config.USE_BILATERAL_FILTER = True

# Minimum OCR confidence threshold
Config.OCR_MIN_CONF = 0.0

---

🧠 How It Works

1. Bilateral Filtering & Downscaling: Smooths background noise and resizes high-resolution photos for high-speed text detection.
2. Text Line Detection & Candidate Selection: Runs PaddleOCR and filters candidate text lines, bypassing phone UI labels and ambiguous letter sequences (IONSXZ).
3. Short-Edge Midpoint Vector Axis: Calculates vector start/end points along the shortest edge pairs of the bounding box to find true text baseline direction.
4. Coarse & Fine Rotation Matrix: Combines document orientation classifier angle ($0^\circ, 90^\circ, 180^\circ, 270^\circ$) with fine-grained tilt ($\theta$).
5. Noise-Resilient 180° Verification: Evaluates cropped word ROI orientations to prevent floating-point noise flips.
6. Full-Canvas Affine Rotation: Rotates the original high-resolution image with expanded canvas boundaries to prevent corner cropping.

---

🛠️ Testing & API Server

Attention includes a built-in FastAPI test server with a live browser dashboard:

python test_api.py

Open http://localhost:8001 in your browser to test single images or process entire image folders with live real-time side-by-side gallery streaming.

---

📄 License

Distributed under the MIT License. See LICENSE for details.

👤 Author

Girija Geddavalasa - [e-mail]
GitHub: github.com/girijageddavalasa/attention