py-reform: PDF & Image Dewarping Library

A Python library for dewarping/straightening/reformatting document images and PDFs.

Features

• Dewarp/straighten single images
• Process entire PDFs or selected pages
• Return PIL images for further processing
• Save results as images or PDFs
• Progress tracking with tqdm
• Flexible error handling
• Automatic EXIF orientation handling
• Multiple dewarping models

Installation

pip install py-reform

Quick Start

Process a Single Image

from py_reform import straighten

# Process a single image
straight_image = straighten("curved_page.jpg")
straight_image.save("straight_page.jpg")

Process a PDF

from py_reform import straighten, save_pdf

# Process a PDF (all pages)
straight_pages = straighten("document.pdf")

# Save processed pages as a new PDF
save_pdf(straight_pages, "straight_document.pdf")

Process Specific PDF Pages

# Process specific PDF pages
straight_pages = straighten("document.pdf", pages=[0, 2, 5])

Choose a Different Dewarping Model

By default we use UVDoc, which works for all sorts of problematic images. If you just need to rotate the image, though, use deskew instead.

# Use the rotation-based deskew model
straight_image = straighten("document.jpg", model="deskew")

# Use the UVDoc model with custom parameters
straight_image = straighten("document.jpg", model="uvdoc", device="cpu")

# Configure deskew model parameters
straight_image = straighten("document.jpg", model="deskew", max_angle=15.0, num_peaks=30)

Create Before/After Comparisons

from py_reform.utils import create_comparison

straight_image = straighten("curved_page.jpg")

# Create a side-by-side comparison
comparison = create_comparison(["curved_page.jpg", straight_image])
comparison.save("comparison.jpg")

Error Handling

# Default: stop on error
result = straighten("document.pdf", errors="raise") 
# Skip errors, log warning
result = straighten("document.pdf", errors="ignore")
# Use original on error with warning
result = straighten("document.pdf", errors="warn")   

Working with Image Orientation

The library automatically handles EXIF orientation data in JPEG files, ensuring that images are correctly oriented before processing. You can also use these utilities directly:

from py_reform.utils import open_image, auto_rotate_image
import PIL.Image

# Open an image with automatic orientation correction
img = open_image("photo.jpg")

# Or correct orientation of an already opened image
img = PIL.Image.open("photo.jpg")
img = auto_rotate_image(img)

Available Models

• UVDoc
• deskew

Examples

See examples/examples.py

Citation

The UVDoc model is based on original work by Floor Verhoeven, Tanguy Magne, and Olga Sorkine-Hornung. If you use py-reform with the UVDoc model, please consider citing their work:

@inproceedings{UVDoc,
title={{UVDoc}: Neural Grid-based Document Unwarping},
author={Floor Verhoeven and Tanguy Magne and Olga Sorkine-Hornung},
booktitle = {SIGGRAPH ASIA, Technical Papers},
year = {2023},
url={https://doi.org/10.1145/3610548.3618174}
}

Original UVDoc repository: https://github.com/tanguymagne/UVDoc/

Anything else??

I'm pretty sure I wrote about two lines of code for this, the rest was all Cursor and Claude 3.7 Sonnet. My job was mostly making demands around pathlib and ditching OpenCV.