# Sprite sheets from one reference, with a coding agent

These are the scripts behind the DreamLayer blog post "AI Sprite Sheet Generator: 12-frame animations
from one character reference". Paste this folder into a project and tell your agent (Claude Code,
Codex, Cursor) to follow README.md. Everything runs with Python 3.11+, Pillow, NumPy and SciPy. The key is read from the environment (`DREAMLAYER_API_KEY`) and never printed.

## The workflow

1. Approve one reference image of the character: side view, plain white background. Fix everything
   you dislike here; every later frame inherits it.
2. Write a pose list, one line per frame. Say where each foot, arm and the body sit.
3. Generate the frames from the reference (`seq_gen.py`), one job at a time.
4. Review a contact sheet. Reject and regenerate the misses; change the reference when a pose family
   keeps failing (a rearing horse from the standing horse produced gallops; from the peak-rear frame it
   produced the descent).
5. Cut out every frame (`seq_gen.py` with `background_remove`), clean the cut-outs
   (`clean_cutout.py`), assemble the sheet and atlas (`assemble_sheet.py`).

## Files

| Script | What it does |
|---|---|
| `seq_gen.py` | Runs a JSON spec of jobs against the DreamLayer Agent API: one job in flight, 75 s apart by default (`SEQ_MIN_GAP_S`), resumable, idempotency keys, provenance log. Operations: `text_to_image`, `image_to_image` (with `input_asset_id` or `upload_from`), `background_remove`. |
| `finish_set.py` | One call per set: cut out what is missing, clean, assemble, write a preview GIF. |
| `clean_cutout.py` | Local cleanup of cut-outs: keep the largest alpha blob, drop flat grey floor shadows, peel white halos (`DEFRINGE_WHITE=1`), optional mauve-shadow rule (`SHADOW_MAUVE=1`, off by default because it eats red shoes). |
| `assemble_sheet.py` | Grid sheet + atlas JSON. One shared scale per set; each cell anchored horizontally on the head-and-chest centre of mass (thin columns such as a raised blade ignored) and vertically on the feet, so the body does not sway between frames. |

## Spec format for `seq_gen.py`

```json
{"frames": [
  {"name": "walk_01", "idem": "myproject-walk-01-v1", "operation": "image_to_image", "aspect": "1:1",
   "input_asset_id": "<id from POST /v1/input-assets>",
   "prompt": "<identity clause> Walk cycle frame 1 of 8 (contact): right foot forward ..."}
]}
```

```
python3 seq_gen.py spec.json out_dir 1          # generate
python3 finish_set.py out_dir my-sheet 4 512 bottom "the character" walk_01 walk_02 ...   # cut out, clean, assemble
```

## What to expect

Identity holds well from one reference. Poses are approximate: wide strides come easily, passing
poses rarely, sword length and horse size drift. Budget one credit per frame and one per cut-out,
plus a few rejects. The post shows the real counts.