Metadata-Version: 2.4
Name: attention-upright
Version: 0.1.0
Summary: Automatic image orientation detection and correction using PaddleOCR
Author-email: Girija Geddavalasa <thatsgirijag@gmail.com>
Maintainer-email: Girija Geddavalasa <thatsgirijag@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/girijageddavalasa/attention
Project-URL: Repository, https://github.com/girijageddavalasa/attention
Project-URL: Issues, https://github.com/girijageddavalasa/attention/issues
Keywords: ocr,image-processing,orientation,deskew,paddleocr,computer-vision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: paddleocr>=2.6.0
Requires-Dist: paddlepaddle>=2.6.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: python-multipart>=0.0.6
Provides-Extra: gpu
Requires-Dist: paddlepaddle-gpu>=2.4.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Attention

[![PyPI version](https://img.shields.io/pypi/v/attention.svg)](https://pypi.org/project/attention/)
[![License: MIT](https://img.shields.io/licenses/MIT.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/attention.svg)](https://pypi.org/project/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)

```bash
pip install attention
```

### Installation with GPU Support

```bash
pip install attention[gpu]
```

### Local Development Installation

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

---

## 🚀 Quick Start

### 1. Simple Image Uprighting

```python
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

```python
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:

```python
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:

```bash
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** - [thatsgirijag@gmail.com](mailto:thatsgirijag@gmail.com)  
GitHub: [github.com/girijageddavalasa/attention](https://github.com/girijageddavalasa/attention)
