Metadata-Version: 2.4
Name: uprightkit
Version: 0.1.0
Summary: Lightweight, pure-OpenCV document deskewing and orientation correction — no deep learning required.
Author-email: Girija Geddavalasa <thatsgirijag@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/uprightkit
Project-URL: Issues, https://github.com/yourusername/uprightkit/issues
Keywords: opencv,deskew,image-processing,document-scanner,ocr-preprocessing,pdf
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Scanners
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python-headless>=4.5
Requires-Dist: numpy>=1.20
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.23; extra == "pdf"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# uprightKit

Lightweight, pure-OpenCV document deskewing and orientation correction.
No deep learning, no model downloads, no GPU — just classical computer
vision (Hough transform + edge-density profiling).

It fixes two common problems with scanned/photographed documents:

1. **Fine skew** — the page is tilted a few degrees.
2. **180-degree flips** — the page was scanned/photographed upside down.

## Install

```bash
pip install uprightkit

# with PDF support:
pip install uprightkit[pdf]
```

## Usage

### Single image

```python
import uprightkit

uprightkit.fix_image("scan.jpg", output_path="scan_fixed.jpg")
```

### PDF (page by page)

```python
import uprightkit

uprightkit.fix_pdf("document.pdf", output_path="document_fixed.pdf")
```

### Already have a numpy array (e.g. in an existing OpenCV pipeline)?

```python
import cv2
import uprightkit

image = cv2.imread("scan.jpg")
fixed = uprightkit.fix_array(image)  # returns a numpy array, BGR
```

### Command line

```bash
uprightkit scan.jpg scan_fixed.jpg
uprightkit document.pdf document_fixed.pdf
uprightkit scan.jpg scan_fixed.jpg --no-flip-fix   # skip the 180-degree check
```

## Tuning

The 180-degree flip detector assumes a correctly-oriented page has more
text/content density near the top half than the bottom half. This holds for
many ID cards, forms, and letters — but not for every document layout. If you
get incorrect flips on your documents, disable it:

```python
uprightkit.fix_image("scan.jpg", output_path="out.jpg", correct_180_flip=False)
```

Other tunable parameters (`skew_angle_tolerance`, `flip_density_ratio`,
`hough_threshold`, `min_line_length`, `max_line_gap`) are documented in the
docstring of `uprightkit.fix_skew_and_orientation`.

## Why no deep learning?

This is intentionally a fast, dependency-light tool meant for preprocessing
pipelines (e.g. before OCR) where you don't want to pull in a multi-hundred-MB
model or pay GPU inference cost just to straighten a page.

## License

MIT --- see [LICENSE](LICENSE).
