Batch Contrast

Batch restore grayscale images, scanned pages, line art, and PDFs while keeping the originals untouched.

Setup

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Basic use

# Preserve gray detail
./.venv/bin/python batch_contrast.py /path/to/input -o /path/to/output

# Hard black and white
./.venv/bin/python batch_contrast.py scans -o cleaned --mode document

# Nested folders or a no-write inspection
./.venv/bin/python batch_contrast.py scans -o cleaned --recursive
./.venv/bin/python batch_contrast.py scans -o cleaned --dry-run

Presets and previews

./.venv/bin/python batch_contrast.py scans --preset faded-scan
./.venv/bin/python batch_contrast.py scans --preset line-art
./.venv/bin/python batch_contrast.py scans --preset document \
  --preview-report preview.html --preview-limit 12

Built-in presets are grayscale, document, faded-scan, and line-art. Explicit processing options override preset and configuration values. Preview reports are self-contained HTML files with before/after images and processing diagnostics.

Restoration

# Uneven lighting
./.venv/bin/python batch_contrast.py scans --mode document \
  --threshold-method adaptive --adaptive-block-size 35 --adaptive-offset 10

# Faded, noisy, or rotated pages
./.venv/bin/python batch_contrast.py scans --normalize-background \
  --denoise medium --sharpen light --deskew --auto-crop

Threshold methods are fixed, otsu, and adaptive. Deskewing corrects confident rotations up to 15 degrees. Auto-crop uses --crop-padding 10 by default.

Existing outputs and resumable jobs

./.venv/bin/python batch_contrast.py scans --if-exists skip
./.venv/bin/python batch_contrast.py scans --if-exists overwrite
./.venv/bin/python batch_contrast.py scans --manifest run.jsonl
./.venv/bin/python batch_contrast.py scans --manifest run.jsonl --resume

The default conflict policy is version, producing names such as page-2.png. The older --overwrite flag remains as an alias. A JSON Lines manifest records source signatures, resolved settings, output, status, diagnostics, timing, and errors. Resume skips only successful, unchanged outputs that still exist.

YAML recipes

preset: faded-scan
deskew: true
auto_crop: true
denoise: medium
sharpen: light

./.venv/bin/python batch_contrast.py scans --config recipe.yaml

Precedence is explicit CLI option, config value, preset value, then built-in default. Recipes contain processing settings only.

PDF workflows

# Restore PDF pages as PNG files
./.venv/bin/python batch_contrast.py book.pdf -o cleaned-pages \
  --mode document --threshold-method adaptive

# Restore a PDF or combine a folder into one PDF
./.venv/bin/python batch_contrast.py book.pdf --output-pdf cleaned.pdf
./.venv/bin/python batch_contrast.py scans --recursive \
  --output-pdf cleaned.pdf --pdf-dpi 300

The final PDF is written only after every page succeeds. Original PDF page sizes and basic metadata are preserved.

Exit codes

• 0: all eligible items succeeded or were intentionally skipped
• 1: one or more items failed
• 2: invalid arguments, configuration, or input
• 130: interrupted