Batch Restoration

---
name: batch-restoration
description: "Run and troubleshoot SUPIR folder-based restoration with
  test.py-style flags, prompt choices, Q/F checkpoints, CUDA device planning,
  and safe dry-run validation."
metadata:
  disco-role: operating
disable-model-invocation: true
license: NOASSERTION
---

# Batch Restoration

Use this sub-skill when the user wants a command-line or scripted folder
restoration workflow: input images in a directory, output PNGs in a save
directory, `SUPIR_sign` selection, quality/fidelity flags, manual prompts,
`--no_llava`, or a `test.py`-style run.

For API-only questions, route to
[../python-api-and-config/SKILL.md](../python-api-and-config/SKILL.md). For
Gradio/browser, tiled local-prompt, or face workflows, route to
[../interactive-demos/SKILL.md](../interactive-demos/SKILL.md).

## Read these bundled files

- [references/workflow-and-cli.md](references/workflow-and-cli.md) for the
  adapted batch workflow, options, device assignment, and troubleshooting.
- [scripts/supir_batch_restore.py](scripts/supir_batch_restore.py) for a safe
  dry-run wrapper that mirrors the repo batch workflow and only loads models
  when `--run` is explicitly passed.
- [../../references/checkpoints-and-environment.md](../../references/checkpoints-and-environment.md)
  for checkpoint and backend requirements.
- [../../references/configuration-reference.md](../../references/configuration-reference.md)
  for shared sampler, dtype, and prompt settings.

## Workflow summary

1. Validate CUDA and dependencies with the API probe.
2. Validate checkpoint/config paths with the root asset checker.
3. Choose `Q` for default high-quality restoration or `F` for fidelity under
   light degradation.
4. Choose whether LLaVA captioning is available. Use `--no_llava` for manual
   or empty prompts when LLaVA checkpoints are absent.
5. Run a dry run first:

```bash
python sub-skills/batch-restoration/scripts/supir_batch_restore.py \
  --img_dir inputs --save_dir outputs --SUPIR_sign Q --upscale 2 --dry-run
```

6. Only add `--run` after the dry run shows the intended config, devices,
   prompts, and output path.

## Inputs and outputs

- Input directory: image files readable by Pillow.
- Output directory: created if missing; each input image produces
  `<input_stem>_<sample_index>.png`.
- Internal image tensors: RGB, normalized to `[-1, 1]`, working sizes rounded to
  multiples of 64.
- Captions: generated by LLaVA from a denoised 512-side preview unless
  `--no_llava` is used.

## Key decisions

| Decision | Preferred route |
| --- | --- |
| Missing LLaVA or second GPU | Use `--no_llava` or `--load_8bit_llava`; provide manual context in prompts when possible. |
| Large images / memory pressure | Use `--use_tile_vae` and consider the interactive tiled route for local prompts. |
| Better visual appeal | Try higher `s_cfg`, larger `spt_linear_CFG`, and `s_stage2` slightly below 1.0 after validating seed/config. |
| Better fidelity | Use `SUPIR_sign F` for light degradation, lower guidance, and `s_stage2=1.0`. |
| Reproducibility | Set `--seed` and record checkpoint variants, prompt suffixes, and color-fix mode. |

## Guardrails

- The source batch workflow aborts without CUDA. Do not run it on CPU.
- Do not recursively process huge folders without a user-approved budget.
- Do not assume non-image files are safely ignored; validate inputs before long
  runs.
- Keep checkpoint paths out of public reports.