image_cleanup_upscale v1.0.0

name: image_cleanup_upscale description: Clean up and upscale low-res images: despeckle, upscale (Real-ESRGAN or Lanczos), sharpen, quality-check the result, and export a web-optimized copy. Triggers when an agent needs to upscale a screenshot, asset, or photo, reduce JPEG artifacts, or prep images for the web. metadata: { "includeInPrompt": true }

Image Cleanup and Upscale

Purpose

Turn low-res, artifacty images into clean, larger, web-ready versions without making them look worse. The pipeline runs in a fixed order because order is the whole trick: clean first, upscale second, sharpen last. Sharpening a dirty source just amplifies JPEG blocks and noise.

Workflow

1. Decide the content type. Photo, illustration, or screenshot. Photos get JPEG despeckle and moderate sharpening. Illustrations skip despeckle (flat color must stay flat). Screenshots get the lightest sharpening so text stays crisp.

1. Run the pipeline with bin/cleanup.py:

bash
python3 bin/cleanup.py input.jpg -o out.png --scale 2 --content photo
python3 bin/cleanup.py shot.png -o shot2x.png --scale 2 --content screenshot --no-despeckle
python3 bin/cleanup.py input.jpg -o out.png --scale 4 --content illustration --web --max-bytes 300000

Options: --no-neural (skip Real-ESRGAN), --no-sharpen, --web + --web-width 1600 + --web-format webp|jpeg + --max-bytes N (fits the web copy under N bytes by stepping quality down), --quality 82.

1. Read the JSON report. It includes input/output sharpness (Laplacian variance), the backend used, the web export size, and any warnings.

1. Respect the stop check. The pipeline warns when the output is barely sharper than a plain resize, meaning the upscale invented nothing worth keeping. That is the signal to stop: a bigger image that gained nothing is just a heavier file. See references/when-to-stop.md.

Output Contract

• A cleaned, upscaled raster file at the requested scale (2x or 4x).
• Optionally, a web copy sized to a max width, saved as WebP (default) or progressive JPEG, under the byte budget.
• A JSON report: sizes, sharpness before/after, backend, warnings. If the report carries the stop warning, prefer the source or a lower scale.

Operating Rules

1. Never upscale and sharpen in the wrong order. Despeckle before the resize, unsharp mask after.
2. JPEG inputs always get a light median despeckle first; do not skip it on artifacted sources.
3. Do not upscale a source below ~200px on its long side and expect magic; the model needs something to work with.
4. AI upscalers invent plausible detail, they never recover real detail. Faces and text are the two places fakes are most visible; zoom to 100% and look.
5. Prefer the RealESRGAN_x4plus model for photos, RealESRGAN_x4plus_anime_6B for illustrations. Real-ESRGAN is in maintenance mode but remains the default free option. See references/models.md.
6. Strip EXIF on web exports (the pipeline does this). Size web copies to at most 2x the display width; anything larger wastes bytes.