Image Stitcher

Simple CLI that stacks multiple screenshots into one continuous image. It looks for repeated content between consecutive captures, trims the overlap, and keeps their shared UI regions lined up to minimize seams.

Requirements

• Python 3.9+
• Pillow (pip install pillow)
• Optional: uv for dependency management (pip install uv)

Setup

python -m venv .venv
source .venv/bin/activate
pip install pillow
# or with uv:
uv pip install pillow

To capture the current environment:

source .venv/bin/activate
uv pip freeze > requirements.txt

Usage

python main.py screenshots/*.png --output combined.png

You can mix glob patterns, explicit files, and directories. Paths are processed in the order you pass them, so number your screenshots (or rely on directory sorting) to keep the sequence correct.

Key Options

Flag	Description
-o / --output	Target file name (default stitched.png).
--align {left,center,right}	Horizontal alignment inside the final canvas. Handy when screenshots have different widths.
--background COLOR	Canvas fill color for unused areas (hex or any Pillow color name).
--max-overlap N	Maximum pixels to scan for vertical overlap. Increase for tall repeated sections.
--difference-threshold VALUE	Acceptable mean grayscale difference (0-255) between overlapping strips. Raise slightly for noisier captures.
--chunk-height PIXELS	Height of horizontal strips used when comparing overlaps. Smaller chunks are more precise but slower.

Tips for Cleaner Stitches

• Start with the defaults. If seams still show, try --chunk-height 20 and --difference-threshold 8.
• Limit --max-overlap to the highest repeated region you expect (e.g., 600 for tall navbars) to keep processing fast.
• Capture screenshots with a bit of overlap: 50–150 pixels is usually enough for the detector to lock on.

Output

The script emits a single RGB image and prints the absolute path of the saved file:

Saved stitched image to /path/to/combined.png

Open it in your favorite viewer or drop it into documentation as needed.***