Document Scanner

Small OpenCV-based document scanner for macOS. It turns phone photos of paper documents into flattened scan-like outputs, with support for single images or folder queues.

The current default behavior is conservative:

• --keep-color is the default mode.
• In default mode, the script does geometric correction only: perspective warp plus optional deskew.
• --grayscale adds grayscale enhancement.
• --bw produces a binarized black-and-white scan.

Features

• Automatic document boundary detection from casual phone photos
• Manual four-corner selection UI when auto-detection is unreliable
• Folder batch mode
• Manual queue labeling for folders
• Background processing while you label the next image in a batch
• Debug image export for inspection
• Unicode-safe file loading and saving

Requirements

• Python 3
• opencv-python
• numpy

Install:

python3 -m pip install -r requirements.txt

Usage

Single image, default color-preserving output:

python3 document_scanner.py input.jpg output.png

Single image, manual corner selection:

python3 document_scanner.py input.jpg output.png --manual

Single image, grayscale:

python3 document_scanner.py input.jpg output.png --grayscale

Single image, black/white:

python3 document_scanner.py input.jpg output.png --bw

Folder input, manual queue mode:

python3 document_scanner.py input_folder output_folder --manual --debug

When input_path is a directory:

• images are processed in filename order
• output files are written to output_folder/<original_stem>_scan.png
• once you confirm one image, it starts processing in the background while you label the next one

Manual UI Controls

• Left click: add a corner
• Right click: undo the last corner
• u: undo the last corner
• r: reset all corners
• Enter or Space: confirm once 4 corners are selected
• q or Esc: cancel the current manual session

Suggested click order:

1. top-left
2. top-right
3. bottom-right
4. bottom-left

The script will reorder the points internally before warping.

Output Modes

Default: --keep-color

This mode keeps the original color content after:

• perspective correction
• optional residual deskew
• optional white padding from --pad

It does not apply grayscale conversion, binarization, CLAHE, luminance normalization, or color enhancement.

--grayscale

This mode converts the corrected page into an enhanced grayscale image for easier reading.

--bw

This mode produces a binarized black-and-white document using adaptive thresholding.

Debug Outputs

With --debug, the script saves intermediate files next to the output file in a sibling folder named like:

output_name_debug/

Typical artifacts include:

• manual selection overlay
• detection masks
• contour overlay
• warped document
• deskewed document
• final scan

Notes

• The manual UI is built with OpenCV windows.
• The final warped image preserves the document pixel density from the original source image.
• Optional deskew is content-based. If no reliable residual skew is detected, no extra rotation is applied.

Repository Files

• document_scanner.py: main script
• requirements.txt: Python dependencies
• .gitignore: local environment and generated artifact exclusions