Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Merge origin/main (v3.5.0: the side walk canvas room and the measured background matte) into main, with the unreleased round chest breathe kept above it in the changelog
Soohong Kimffe06f6f0de8
diff --cc CHANGELOG.mdindex 1c7955a,900ce27..204eb09--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -2,15 -2,32 +2,41 @@@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased+- **Upgrading from 3.4.0: a pixel Breathe row can now breathe round from the chest, with the arms moving sideways (`chest_round`, `arms_x`), and `sprite-gen breathe` takes cells held still (`--hold-mask`), what the arms hold (`--props-mask`), pieces held behind the body (`--props-behind-mask`), and props grouping (`--props-groups`). All are off by default: every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar.**++**Upgrading from 3.5.0: a pixel Breathe row can now breathe round from the chest, with the arms moving sideways (`chest_round`, `arms_x`), and `sprite-gen breathe` takes cells held still (`--hold-mask`), what the arms hold (`--props-mask`), pieces held behind the body (`--props-behind-mask`), and props grouping (`--props-groups`). All are off by default: every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar.**++- **New: the round chest (pixel; `chest_round`, `arms_x`, flags `--chest-round`, `--arms-x`).** When either is above 0, a pixel row bakes the round chest instead of the envelope squash. Both are shares of the body below the neck (0 to 0.20). The rim of the chest ellipse (smooth's `chest_*` keys) moves out from its peak by `chest_round`. Inside the ellipse the body stretches evenly from the peak; outside it the body is pushed whole, so a 1 px outline stays 1 px. Above the peak the chest goes up and out; below the peak it goes sideways only, fading to nothing at the feet. The head above the rigid boundary keeps its place and bytes, as in smooth. Below the rigid boundary, the sideways share (the chest's sideways push and the arms) turns on over the longer of 0.15 of the neck band and 1.5 times the sideways px (`chest_round` plus `arms_x` in px), and the body's following of a held piece turns on over the longer of 0.15 of the neck band and 1.5 times the largest piece move in px (if it turns on over less, rows just below the head line slide more than one cell per row against each other and an outline crossing the head line breaks; with 1.5 times, no row slides more than about one cell against the next because the steepest slope of the smooth turn on is 1.5 over its length). The arms (the columns outside where appendage protection starts) are pushed whole by the chest and then sideways by `arms_x` on top, never stretched; the torso's sides take the stretch over 12 times that push. The breath is smooth's one-sided curve (`inhale`, `breaths`, `breath_peaks`, `loop_cells`, `start_cell`), so a cell at phase 0 is the source byte for byte. Every output cell is a cell of the source: no new colour, and no row or column is folded. A round row refuses `depth`, `depth_x`, `lag` and smooth-only shape keys; smooth refuses `chest_round` and `arms_x`. See [breathing](docs/breathing.md), "둥근 가슴".+- **New: held cells (`--hold-mask`), held props (`--props-mask`), props behind the body (`--props-behind-mask`), and props grouping (`--props-groups`).** All are PNGs the size of the frames; their light opaque pixels (lightness 128 or more, alpha 128 or more) are the cells. A cell may be in only one of the three masks; a cell in two is refused. Empty cells inside a props mask are not drawn; only the drawing's opaque cells of a piece move. A held cell keeps its bytes in every frame, because the field is 0 there (smooth and round rows; an envelope row refuses). Each piece of the props mask (8-connected, cells within 2 px of each other joined, as a hilt and blade parted by the hand) moves whole and sideways, as far as the hand holding it: the chest's sideways push where the piece touches the body, plus the full `arms_x` of the arm on its side. The body within 2 px of it moves the same whole cells, so no gap opens between hand and grip. A whole arm can move as one rigid block by masking it from the sleeve below the shoulder down to the hand together with what it holds as one `--props-mask` piece (one colour), starting below the sideways turn on rows. Where a piece moves onto held cells, held cells stay on top and those cells are not drawn; the engine counts them per piece and per frame in `props.pieces[i].hidden` and `hidden_max` of `breathe.json`, printing one warning line on stderr of the form `breathe: warning: --props-mask piece K of N (C cells) goes under held cells in F of T frames, up to M cells (frame X); those cells are not drawn` followed by `breathe.json props.pieces[K-1].hidden`. In each row, the engine looks at the first cell right behind the moved piece: when that cell is a held cell, it repeats over the cells the piece left (water fills where a blade left the water band; a held back fills where a sleeve moved away), and otherwise the body fills it; no empty cell is made up. The engine counts cells a piece fills by repeating a cell or left by the field where the body does not follow fully rather than moving them in `props.pieces[i].filled` and `filled_max` of `breathe.json` (held cells themselves are never counted), printing one warning line on stderr of the form `breathe: warning: --props-mask piece K of N (C cells) leaves cells it fills by repeating a cell in F of T frames, up to M cells (frame X); those cells are made up, not moved` followed by a space and `breathe.json props.pieces[K-1].filled`. Pieces held behind the body (`--props-behind-mask`, off by default) take the same sideways move, but the body stays in front, does not follow, and the piece is drawn under held cells, under the body, and under pieces held in front; all pieces behind the body are drawn first, then all pieces in front, including pieces that do not move in that frame (so a resting front piece is not covered by a behind piece), and held cells are always on top; where it pulls out from behind the body, the piece's cell touching the body in that row repeats over the cells it left (making the piece look wider by that many cells, as the shield's edge column repeats), while cells left where nothing was in front become empty; the cells it fills by repeating a cell are counted in `props_behind.pieces[i].filled` and `filled_max` with a warning line on stderr of the form `breathe: warning: --props-behind-mask piece K of N (C cells) leaves cells it fills by repeating a cell in F of T frames, up to M cells (frame X); those cells are made up, not moved` followed by a space and `breathe.json props_behind.pieces[K-1].filled`; its hidden cells (under held cells, the body, or a front piece) are counted in `props_behind.pieces[i].hidden` and `hidden_max` with a warning line reading `goes under held cells, the body or a piece held in front of it` and naming `--props-behind-mask`. A piece ledger maintains a source map of which source cell each output cell shows, reading all counts off this map in every frame. Before drawing, each piece is checked at its whole-cell destination and refused if pushed off the cell (naming the mask flag, piece as i/n with its cell count, opaque cells leaving, side crossed with its count like `왼쪽 변 밖 3`, cell size, and move, advising to widen the cell margin or lower `chest_round` or `arms_x`; covering behind pieces, rows above the head line, and rounding edges); the body's own off-cell refusal now counts body cells only and names the side crossed with its count. Two pieces of one layer landing on one cell are refused (advising `--props-groups colour` or moving one to the other mask); a behind piece and the body in front moving apart to leave empty cells is refused (advising to mask only the part showing outside the body as `--props-behind-mask` or give it as `--props-mask`); and in every frame the cells shown at destination plus hidden cells must equal the piece's opaque cells in the still, refusing as an engine defect if not. With `--props-groups colour` (default `piece`; refused without a props mask), both props masks are read by colour: light opaque cells of one colour form one group moving by the whole cells read where the group touches the body, allowing unheld elements like reflections to follow a prop. `breathe.json` records `hold`, `props`, and `props_behind` (path, sha256, cells, each piece's `shift_px`, `hidden`, `hidden_max`, `filled`, `filled_max`), with each piece carrying `colour` and the mask carrying `groups: "colour"` and `colours` when grouped by colour. `sprite-gen breathe` also takes `--axis-x` and `--torso-half`, the sidecar's existing overrides, so a figure whose arms lie inside the measured torso can name them.+- **Curator**: a round row is kept as written and its preview and video export are refused, as for smooth rows; the mirrored key lists are checked against the bake's.+- **Tests**: `tests/effects/test_breathe_round.py` (on a synthetic figure: the rest is the source and the head never moves; the chest swells round from one point, the line above the peak rises and the line below it does not; no new colour, no fold, a 1 px outline; the arms move sideways whole; a bar held in the hand moves with it and no gap opens; held cells keep their bytes under the round chest and under smooth; a bar going under a held water band is counted per frame in `breathe.json` and warned on stderr, held cells keep their bytes and the cells it left in the water rows are water (no gap); a reflection painted the bar's colour with `--props-groups colour` follows the bar by the same cells in every frame, the cells it left show the still's water, and no new colour appears; a shield given as `--props-behind-mask` slides out from behind a held arm with its rim cell filling the space and no gap, while given as `--props-mask` the held arm's outline fills that space instead; `--props-groups` without a props mask is refused; the new keys off keep every byte; wrong keys are refused; the CLI bakes what the library bakes and records both masks; a piece pushed off the canvas, behind the body or in front, is refused with its name and the side, and no folder is left; a piece above the head line pushed off the canvas is refused; the body pushed off the canvas names the side; the cells a piece fills (a shield sliding out from behind an arm, a bar leaving a held water band) are recorded per frame in `breathe.json` and warned, and match a count made independently from a tag picture (every cell carries its own index); in eight scenes every cell of every piece is drawn at its destination or counted as hidden in every frame, and the filled count matches the independent count; two pieces of one layer landing on one cell are refused; a piece in front stays over a piece behind, whether it moves over it or the behind piece moves under it; a piece behind the body moving apart from it is refused; the ledger changes no byte of seven scenes baked before it (no masks, held legs only, the held bar, the bar in the water, the colour group reflection, the shield behind and in front); a row with only held cells records no piece ledger) and `tests/effects/test_breathe_round_curator.py` (the mirror refuses a round row; the round trip keeps a round sidecar as written and keeps a refused one with a notice; the mirrored key lists).++ ## v3.5.0 - Widened square canvas framing for side walk and run stride and trailing parts, measured background matte cutout for flat backgrounds of any colour, and failure when a cutout removes nothing++ **Upgrading from 3.4.0: `video-set` now frames a walk or run filmed from the side on a square widened by the room its still lacks, and a background the chroma engine did not recognise, which used to come out with nothing removed, is now cut out.** A still that leaves less than `GAIT_ROOM` clear in front of its silhouette (0.15 of the silhouette's height) or behind it (0.25) gains the columns it lacks on that side; the square gains the same number of rows above the still. A still that leaves the room keeps its canvas to the byte. Every other state, a front, back or diagonal view, `--shape` and `--fit tight` are framed as before. Each side walk or run's `canvas.report.json`, and its item in `set.report.json`, gains `room`. `video-canvas` gains `--view` and reads the room only with `--view side`. Backgrounds the chroma engine already recognised key byte for byte as before. A pure or recognised magenta/green background still goes to the chroma engine and a bright achromatic one to the white matte, with the same bytes.++ - **New: the walk's room (`canvas.gait_room`, `GAIT_ROOM`, `ROOM_VIEWS`).** Filmed from the side, a walk's stride reaches in front of the standing silhouette, and behind it the stride and a part that trails behind the body (a big tail, a long coat) swing past it. Where either met the left or right edge, `video-frames` refused the clip, and the walk had to be filmed again with `--shape wide`. The `walk` and `run` rows now read the still's room: the empty columns between the silhouette and the left and right edges of the square the row makes of the still, in front and behind, as a fraction of the silhouette's height. A side under its `GAIT_ROOM` (more behind than in front) gains what it lacks, and the frame stays square: the clip keeps the 1:1 a walk is filmed at, and the still is never scaled. The report's `room` records the view, the silhouette, the room on each side, the bound, `short`, `added_px` (columns per side) and `added_rows`, and a widened canvas's `why` says why. `--shape square` keeps the still's own square. `--shape wide` is still the walk's 16:9 row (`GAIT_WIDE`). See [video-pipeline](docs/video-pipeline.md) section 1.+ - **Changed: `canvas.subject_rows` is now `canvas.subject_box`**, which reads the columns as well as the rows. `--fit tight` reads its rows from it, byte for byte.+ - **New: the measured background matte (`sprite_gen/frames/measured_matte.py`, rule in docs/chroma-alpha.md "The measured background").** It reads the background's colour and spread from a ring inside the image's edges, keys that colour and its hue in shade (a drop shadow, a gradient), thin dark strips along the edges, and enclosed pockets of a saturated background, then unmixes a 2 px edge between the local background and the nearest solid subject colour. No colour needs a route of its own: a muted yellow-green, an off-cyan, a grey or an off-white key the same way.+ - **Fixed: `cutout --key green|magenta` and `extract_route` on a background the engine does not recognise as that key.** Such a background was keyed against the pure key and nothing came off, and `cutout` exited 0; a green behind dark edge strips was routed to the white matte. It is now measured (`route: measured`, `chroma_key_painted` the measured colour), so `video-canvas` repaints such a still to the exact key, and `cutout` keys the frames of such a clip one by one. `video-frames` keeps keying a clip from one exact key: it still refuses such a clip, with the same bytes and report, and its guidance to normalise the still with `video-canvas` now works on these backgrounds.+ - **Fixed: `cutout` fails when it made nothing transparent**, like `gen/chroma.py`, instead of reporting success.+ - CLI: `cutout --key measured` forces the measured matte; `auto` sends a corner that is neither a key nor bright and achromatic to it.+ - Report fields (`route: measured`): `background`, `background_spread`, `background_ring_share`, `shade`, `tolerance`, `edge_strips`, `keyed_pixels`, `pocket_pixels`, `edge_pixels`, `band`, `key_residue_px`.+ - Python callers: `extract_route(..., measure_unrecognised=True)` and `cutout(..., measure_unrecognised=True, refuse_empty=True)` (`video-frames` passes both False); new `cutout.key_recognised(image, kind)`, `measured_matte.measured_matte(image, band=2)`, `measured_matte.measure_background(rgb)`, `measured_matte.background_like(rgb, colour, tolerance, shade)`.+ - **Tests**: new `tests/frames/test_measured_matte.py`, synthetic only: a subject with a dark outline, skin and hair colours on muted green, deep green, off-cyan and yellowish backgrounds with noise, a gradient, a darker shade round the subject, dark strips on two edges and a pocket of background inside; an off-white background measured on request; the routing of a green request on a muted green through `extract_route`, `cutout` and `video-canvas`; a cutout that keys nothing fails.+ - **Tests**: `tests/video/test_walk_canvas_room.py` covers these cases:+ - a side walk whose tail reaches 6 px of the edge behind, facing either way, gets a square widened behind and above by what it lacks, the still unscaled, through `video-set`'s item and report;+ - a person with room keeps the default row's canvas byte for byte;+ - front, back, diagonal and unnamed views are not read;+ - each bound flips one pixel either side of its `GAIT_ROOM`, the one behind larger than the one in front, and both short sides each gain their own lack;+ - a still taller than it is wide is read in its square;+ - a white base is read on its corner colour;+ - a run is read at the walk's bounds;+ - `--shape square`, `--shape wide`, `--fit tight` and another state are not read;+ - `--view` works from the command line.++ Four `video-set` tests' canvas stubs now take `view`, and `test_edge_speck_lead_in.py` reads the walk's own row.+## v3.4.0 - Loop part pop retakes, cycle alignment walk beat repair and broken beats, ghost limb faults, and same foot, filmed jump, and seam jump retakes**Upgrading from 3.3.0: A walk or run loop in `video-loop` is cut to the same bytes, whether a part pops in it or not, and `video-cycle-align` changes only alignment outputs whose beat broke or where a made frame has a limb seen through under `--between auto`.** For `video-loop`, every walk and run report gains `part_pop` and `retake`; `--unfixed refuse` also refuses a loop recorded `retake` reason `part-pop`, whatever `--repair`; no flags are added, no frames are made and no other cut is taken. `video-cycle-align` now reads ghost bands in windows of the body to catch limbs seen through, keeps frames given way on the beat under `--between auto` by making them again at clean fractions or widening jolts across neighbouring frames, changing only alignment outputs whose beat broke (a jolt of 0.25 beat or more) or where a made frame has a limb seen through (ghost window over 1.4 %); loops keeping the beat, loops with no frame given way, and `video-loop` (and `video-set`) keep their bytes for strip PNG, GIF, WebP, and cycle frames, while gaining `beat`, `ghost_window`, (on back and back_diagonal views) `same_foot`, and `retake` reasons (`broken-beat`, `same-foot`) in alignment `strip.json` and reports; every aligned loop's `strip.json` and report gain `screen`, and loops whose cut jumps gain the reasons `filmed-jump` and `seam-jump`, frames unchanged; and `clip_feet` in `video-loop`'s `strip.json` and reports for every walk or run cut; all outputs from `video-loop-compare` and `video-loop-repair` are unchanged, bytes included, and `--same-foot` defaults to `warn` so nothing is refused by default.