Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

Merge branch 'aldegad/edge-speck-zoom-lead-in' — video-frames erases a speck far from the body before the edge check and reads a key-tinted rim joined to the subject as the subject; video-loop leaves a walk's lead-in out of the search and reads the standing height on the cut where the cut is filmed at another size than the clip's first frame; video-canvas --shape wide gives a walk or run no head-room (a jump keeps its own)

Soohong Kim623fe8001868
diff --cc CHANGELOG.md
index d9e9698,38b0711..f982938
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -4,9 -4,19 +4,22 @@@ All notable public changes to `sprite-g
## Unreleased
+- **Output change: a diagonal still turns its chest or back and its legs, not only its head** (`STILL_VIEW_TEXT["front_diagonal"]`, `["back_diagonal"]`, read by `still_view_text` and `gen --direction`; an app that draws its own still takes it too). The sentences said the turn, the head and the feet, and a still that turns only its head and shoes, the chest (back) and the legs standing as from the front (straight behind), meets those words. They now say what that angle shows: not a front (back) view with only the head turned, the middle of the chest (back) and of the waist about three quarters of the way across the body toward its far edge, the near shoulder and side seen broad, the far shoulder and arm partly hidden, the legs at the same angle with the far foot set a little higher and partly behind the near leg, and not to follow a reference picture's angle. `STILL_VIEW_TEXT` takes `{other}`, the side opposite `{facing}` (the near side of a front diagonal, the far side of a back one); facing left is the same sentence with the sides swapped. The clip's view sentences (`VIEW_TEXT`, `VIEW_MOTION_TEXT`, `GAIT_HOLD_TEXT`) and the body plan's (`STILL_VIEW_TEXT_ANY_BODY`) are unchanged. The words were chosen by a before-and-after comparison on the still model; its measurements are kept in private evidence and none is recorded here ([video-pipeline](docs/video-pipeline.md#2-clip--sprite-gen-video)).
+- **`tests/video/test_video_pipeline.py`** holds both diagonal still sentences, facing right and left: the chest (back) and hips turn with the head, where the middle of the body sits, the near side broad, the far shoulder, arm and foot on the far side, the reference picture not followed, and facing left the same sentence with the sides swapped. **`tests/gen/test_prompt_freeze.py`** lists the two 2.22.0 sentences and the words measured in their place (`MEASURED`): the still prompts that hold the old words are compared with the measured ones, those prompts and no others differ from 2.22.0, and a measured sentence reworded again fails as any other prompt would.
+
+ - **Fix: a key-tinted rim joined to the subject at the edge is the subject.** The edge check split its contact pixels by their raw colour alone: the key's hue was leftover background. A body that reaches an edge band brings its antialiased rim there first — hair tips, the crown's outline, the key blended into them — and on a frame where only that rim was in the band, `--allow-subject-edge-contact` refused the clip as leftover background. Each key-tinted contact pixel is now read with the piece of the keyed frame it is in (its opaque pixels, corners joining them, the pieces `drop_specks` reads): it is `residual` only when nothing in its piece is off the key's hue — background on its own — and `subject` when it is joined to the subject. A frame with such a rim in the band passes with `--allow-subject-edge-contact` and is recorded as the subject's contact; refused by default, it says the subject was framed too tight, and a mixed refusal no longer counts the rim's frames as carrying leftover background. Key-coloured background apart from the body is refused as before. A clip with no key-tinted pixel in a band, or none joined to the subject, keys and reports as before, byte for byte. [docs/video-pipeline.md](docs/video-pipeline.md#3-frames--extract-key-check-the-edges).
+ - **`tests/video/test_edge_speck_lead_in.py`**: a body that rises until only the key-tinted rim over its crown is in the top band was refused as leftover background with the subject allowed; now it passes as the subject's contact, and by default is refused as framed too tight. A strip of the key's colour against the edge, apart from the body, is still refused as leftover background. `tests/frames/test_chroma_key_relative.py`: Grok's magenta in the band is residual cut off from the rest, and the subject's when joined to it.
+
+ - **Output change: `video-canvas --shape wide` gives a walk or run no head-room.** A forced-wide canvas gave every state a jump's 35 % above the still, and above a square still that head-room set the width as well (2800 × 1575 for 1024 × 1024, 1216 columns in front of the still); a walker that small in its frame is one a video model may reframe. A walk or run forced wide now has a row of its own (`canvas.GAIT_WIDE`, read through `STATE_SHAPE_CANVAS`): 28 % in front, 20 % behind, nothing above — 1969 × 1108 for a 1024 × 1024 still. A jump, and every other state forced wide, keeps the forced-wide row (`WIDE_OVERRIDE`) and its canvas byte for byte; `--headroom` still sets the room above. [docs/video-pipeline.md](docs/video-pipeline.md#1-canvas--the-input-frame-decides-the-output-frame).
+ - **`tests/video/test_edge_speck_lead_in.py`**: a walk or run forced wide is 1969 × 1108 with nothing above, a jump still 2800 × 1575.
+
+ - **Fix: `video-loop` leaves a walk's lead-in out of the search.** A video model may reframe a small subject in a clip's first frames — the body grows or shrinks by a third or more in under half a second, then walks at its new size. Searched with those frames, the motion analysis read the reframing as the clip's motion and lost the walk's repeat, and the gait fallback, scaling back by a line through the clip, read the step as steady growth and shrank the walk. A walk or run's sizes are now read one cycle on (`gait_fallback.cycle_drift`, the size hold's model) and a clip whose first frame's height and size (the square root of the frame's coverage) are both off it by 10 % or more, the same way (`LEAD_IN_MIN`), opens on a lead-in (`gait_fallback.lead_in`) that runs while the height stays that far off — a reframing scales the whole body, a pose such as an item held up from the second frame on changes the height alone; `--cycle auto` and `periodic` — the size hold, the motion analysis, the cycle search and the gait fallback — read the clip after it as a clip of its own, window included. Every frame number the report gives is the clip's own: `cycle.start`, each candidate's `start` and `context_pair_range`, a refusal's windows too, so `--cycle fixed --start` taken from them cuts the frames they name. Every walk and run report gains `lead_in` (`frames`, `height_change`, `first_off`, `first_off_size`, `min`, `method`, `search_from`); a clip too short to read its size one cycle on has none (`why`). A cut the caller names (`fixed`, `pinned`) is the caller's frames. `cycle.coverage` counts the frames the search read. The gait fallback now scales back by the size read one cycle on, as the hold does, so a first pose settling into the walk no longer hides a body that grows from it (`gait_fallback.scale_drift` gains `method: one-cycle-on` in the report); a clip that reaches the fallback with 3 % or more of change is scaled by that model now, and its pixels and the drift its refusal quotes can differ in the last places. A walk or run with no lead-in that the first search cuts is cut as before, its strip, GIF, WebP, cycle frames and `strip.json` byte for byte. [docs/video-pipeline.md](docs/video-pipeline.md#4-loop--period-first-seam-second-then-the-gait-floor), [docs/loop-review.md](docs/loop-review.md#the-gait-fallback-a-slow-walk-or-a-walk-toward-the-camera).
+ - **Fix: `--body-height` reads the standing height on the cut's first frame where the cut is filmed at another size than the clip's first.** The clip's first frame is the still's pose as filmed, but a video model may reframe the subject after it, by a lead-in or by less, and then the walk is filmed at another size than that pose: read there, the standing height scaled a walk after a lead-in up into the cell cap, and delivered a walk reframed by 7 % over its first frames 7 % too large. A walk or run cut for a `--body-height` now has its size read against the first frame's (`gait_fallback.size_change`) on three lengths at once — the height, the mass (the square root of the summed coverage) and the breadth (the widest row of the upper half of the body), each the middle of the cut's frames over the first frame's. A pose moves them apart (a walk is shorter than its standing pose and broader; an item held up is taller and no heavier) and a reframing moves all three the same way, so the change is the least of the three when all go one way and none when they part. At 1 % or more (`SIZE_HOLD_MIN`) the standing height is read on the cut's own first frame, and `strip.json` says so (`body_ref: cut-first-frame`, `body_ref_frame`, the clip frame); `video-cycle-align` rebuilds such a strip at the same height. The report gains `cut_size` (`change`, `height`, `mass`, `breadth`, `min`, `method`) on every walk and run cut for a `--body-height`. A cut the size of its first frame reads the first frame as before, and its strip, GIF, WebP, cycle frames and `strip.json` are as before. [docs/video-pipeline.md](docs/video-pipeline.md#4-loop--period-first-seam-second-then-the-gait-floor).
+ - **`tests/video/test_edge_speck_lead_in.py`**: a walker filmed at 0.63 of its size and reframed over 9 frames: a lead-in of 5 frames, found no cycle before, now cuts its 24-frame walk after it, every frame number its own; one filmed at 1.3 of its size has a lead-in too, and one that holds an item up from its second frame on has none; too slow a walk after the same lead-in is refused with windows that all start after it; a fixed cut there reads its standing height on its own first frame, and `video-cycle-align` keeps it; a walker reframed from 0.93 of its size, or from 1.07, opens no lead-in, and a fixed cut after it read the first frame's height (7 % too large or small) and now reads its own first frame's; a first pose that settles into the walk, an item held up from the second frame on and an arm swung out are each read as a pose, on the first frame. A walker that settles from its first pose and grows 5 % reads 2.8 % on a line and was refused; read one cycle on it is scaled back and cut.
+
+ - **Fix: `video-frames` erases a speck far from the body before the edge check.** A fleck the model drew drifting across the background survives the matte as a few pale pixels; where it crossed an edge band in one frame, the edge check read it as the subject framed too tight and refused the clip, and `video-loop --anchor motion-auto`, which never cleans a frame, kept it in the loop and widened every cell to reach it. Now every keyed frame has its specks erased before anything reads it (`frames.drop_specks`): a piece of the frame — its opaque pixels, corners joining them — under 1 % of the body (`SPECK_MIN_FRACTION`, at least 8 px) and more than a tenth of the body's height from it (`SPECK_APART`). Small pieces near the body are the subject's own and stay: the outline's loose pixels, a shadow drawn under a shoe, a part of a shoe the matte cut loose. Each report row gains `specks`, how many its frame lost, and the report `specks` (`dropped`, `frames` and the rule's numbers); a frame with no speck is not written again, so its bytes are as before. `video-loop`'s own pass on a cut that is not motion-reviewed (`--anchor none|feet|body`) erases every island of solid pixels under the same 1 % as before, pixel for pixel, through the same function (a run-based labelling, about twenty times faster than the pixel-by-pixel search it replaces). [docs/video-pipeline.md](docs/video-pipeline.md#3-frames--extract-key-check-the-edges).
+ - **`tests/video/test_edge_speck_lead_in.py`** keys a body on magenta with five pale pixels in its right edge band in one frame: before this the frames were refused as framed too tight, now the fleck is erased (`specks: 1`) and no frame touches the edge; a shadow under the feet, a loose pixel by the outline and a far block too large to be a speck are kept; `video-loop`'s own reading still erases the loose pieces. A walker on magenta with a fleck drifting far from it, keyed and cut `--anchor motion-auto`, is cut 49 px wide, the walker alone (147 px before).
+
- **Fix: `video-follow` replaces the loop's files only once all of them are written.** The strip, the GIF and the WebP were written over the loop's before the record was, so a run that failed on the record — `follow.follow_loop` given numpy numbers, an int64 of which has no JSON form (`TypeError`) — or on an animation's check left a moved strip beside a record that did not say so. Now the strip, GIF, WebP and record are written and checked in a scratch directory beside the loop (`.follow.*`), each under its own name, and moved over the loop's files after the record is written; a run that fails on the way leaves all four as they were (the strip as cut is still kept as `follow.source.png`, as on a refusal). `follow_loop` reads its regions, `gain`, `freq` and `zeta` as the floats the command line gives, so numpy numbers, or plain ints, write the strip and record that the same numbers as floats write, byte for byte (a caller that passed plain ints finds them recorded as floats, `80.0` where it was `80`). `loop.verify_animation` closes the file it checks. The command's output, its strip, GIF, WebP and record, and `--help` are as before, byte for byte. [docs/video-pipeline.md](docs/video-pipeline.md#6-follow-through--video-follow).
- **`tests/video/test_follow.py`** moves a chest and a smaller head region given as int64, int32, float32, float64 and plain int coordinates, as the rows of an int64 array, and with a float32 `gain`: each writes the strip, GIF, WebP and record the float coordinates write, byte for byte (before this the int64 run failed on the record with the strip already moved). A run made to fail on its record or on its WebP's check, on a loop as cut and on one already followed, leaves the strip, GIF, WebP and record as they were, and nothing beside them but `follow.source.png`.