uprightkit 0.1.0

Lightweight, pure-OpenCV document deskewing and orientation correction — no deep learning required.

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

pip install uprightkit

# with PDF support:
pip install uprightkit[pdf]

Usage

Single image

import uprightkit

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

PDF (page by page)

import uprightkit

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

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

import cv2
import uprightkit

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

Command line

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:

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.