---
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.

2. **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`.

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

4. **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.