crop-screenshot

Extracts foreground elements (menus, dialogs, popups) from screenshots and saves them as PNG with a transparent background (RGBA).

About

This is pure vibe coding. It exists solely to generate the images used in the VisualDiffer wiki. If it works, great — otherwise we'll just ask the AI to fix it.

Requirements

• Python 3.11+
• uv — environment and dependency manager

Installation

# Clone the repository
git clone <url>
cd crop-screenshot

# Create the venv and install dependencies in one step
uv sync

Dependencies (opencv-python-headless, numpy) are automatically installed in a local venv (.venv/).

Usage

crop.py — automatic detection

Extracts the foreground element from one or more screenshots. Detection is automatic: it identifies the "floating" rectangle (menu, dialog, tooltip) that does not touch the image edges and saves it as RGBA PNG with transparent corners.

uv run crop.py screenshot.png
uv run crop.py screenshots/*.png

Output is saved in cropped/ with the same filename as the input.

Options

Option	Default	Description
--outdir DIR	cropped	Output directory
--type auto|menu|dialog	auto	Element type to extract
--seed X,Y	—	Manual internal point (fallback when detection fails)
--bbox X,Y,W,H	—	Manual exact bounding box
--tolerance N	24	Color tolerance for background cleanup
--margin N	3	Extra margin around the crop (pixels)
--shrink N	2	Border erosion to remove background bleed
--min-score N	0.04	Minimum detection confidence threshold
--debug	—	Save _debug_<name>.png with highlighted candidates

Examples

# Automatic detection on multiple files
uv run crop.py screenshots/*.png

# Specify the element type
uv run crop.py screenshot.png --type menu

# Manual fallback with an internal point (useful when auto detection is wrong)
uv run crop.py screenshot.png --seed 640,400

# Precise manual bounding box
uv run crop.py screenshot.png --bbox 120,80,400,300

# Debug: save an image with the detected candidates highlighted
uv run crop.py screenshot.png --debug

---

crop_dialog.py — white dialogs

Simplified script for extracting white-background dialogs via thresholding. Does not produce transparency: crops the largest white rectangle found in the image.

uv run crop_dialog.py screenshot.png
uv run crop_dialog.py img1.png img2.png img3.png

Output is saved in cropped/.

---

Project structure

crop-screenshot/
├── crop.py            # main script (automatic detection, RGBA output)
├── crop_dialog.py     # simplified script for white dialogs
├── pyproject.toml     # project dependencies
├── uv.lock            # exact versions (commit this file)
├── screenshots/       # input images (example)
└── cropped/           # generated output (excluded from git)

Dependencies

Package	Version	Purpose
opencv-python-headless	≥ 4.13	Edge detection, contour finding, flood fill
numpy	≥ 2.4	Array and mask operations

Alternative without uv

If you prefer using pip directly:

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install opencv-python-headless numpy
python crop.py screenshot.png