Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(cycle-source): video-loop keeps a filled loop's cut with the fill off as cycle.source/ and the alignment aligns from it without the clip's frames, its cycle_source record and stderr lines, what to carry when aligning elsewhere, and CHANGELOG Unreleased (v4.2.0)
Soohong Kim1c8ef55ab047
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a944e5b..d137fa0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,17 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased (v4.2.0)++**Upgrading from 4.1.0: loops with no held cell made and cuts with `--fill-held off` give the same files byte for byte as 4.1.0 except the report's `producer.implementation_sha256` (four of seven cuts measured before and after: a synthetic walk with a held frame cut with `--fill-held off`, a synthetic walk with nothing held, and the application's walk flags on a synthetic strider with the fill off and with the fill on where its fill made no cell); cuts that are not loops (played once or an effect's lifetime) and cuts with `--out-fps` were not measured and are unchanged because the new step does not run for them. For a loop at the clip's rate whose held cells were made again, the delivered `cycle/`, `<name>.strip.png`, `<name>.strip.json`, `<name>.gif`, and `<name>.webp` are byte for byte as in 4.1.0 and the report differs only in `cycle_source` and `producer.implementation_sha256` (the other three measured cuts: the held walk, the same with jump repair on, and a walk whose last cells were held), while `video-loop` now cuts the clip's frames a second time with `--fill-held off` to keep `cycle.source/` beside it (0.31 to 0.40 times the loop's output size on test walks, 19.0 to 19.8 KB beside 48 to 64 KB; cut time 0.41 s to 0.75 s on the synthetic walk and 0.83 s to 1.63 s with jump repair on; 14 RIFE binary calls instead of 12 on an Apple GPU on rife-v4.25 and rife-v4.6 where the second cut repairs a ghost), adds `cycle_source` to the loop report and summary JSON, and writes stderr lines around the second cut. An app that cuts in one place and runs `video-cycle-align` in another must carry `cycle.source/` with each loop's cycle frames, strip, strip record, and report so alignment needs no clip frames; loops cut by 4.1.0 or earlier have no `cycle.source/` and align as before.**++- **New: `video-loop` keeps the cut with `--fill-held off` beside a filled loop as `cycle.source/`.** When a cut is a loop at the clip's rate (no `--out-fps`) and its held cells were made again (`held_fill.made` or `held_fill.again.made`), once the filled cut has passed every gate and its GIF and WebP are written `video-loop` cuts the clip's frames again with `--fill-held off` from the report's `cut_args` and `frames_dir` through `loop.cut_again`. It builds the cut in `.cycle.source.cut/` beside the loop; if it takes the same clip frames (`cycle_drawings` start and length), its frames, `<name>.strip.png`, and `<name>.strip.json` are put in place as `cycle.source/` by one rename and `.cycle.source.cut/` is removed. Stderr prints `video-loop: <name>: its held cells were made again, so it is cut again with the fill off and that cut is kept as cycle.source/ for video-cycle-align; the lines below until it is kept are that cut's` before the second cut's lines and `video-loop: <name>: the cut with the fill off is kept as cycle.source/` after; if the second cut fails or takes other frames, stderr prints `video-loop: warning: <name>: its held cells were made again and no cut with the fill off is kept beside it (<reason>): video-cycle-align cuts it again from the clip's frames, or stops on it without them` and the filled loop is still delivered.+- **Fix: `video-cycle-align` aligns filled loops from `cycle.source/` without needing the clip's frames.** Up to 4.1.0, aligning a loop whose held cells `video-loop` made again always re-cut the clip's frames with `--fill-held off`, stopping when a set was aligned away from those frames. Where `cycle.source/` beside a loop holds a strip record showing no cell was made, `video-cycle-align` now aligns from it directly and cuts nothing, giving byte for byte the same cycle frames, strip, GIF, WebP, and `cycle.source/` as aligning from the clip's frames, and the same strip record except `cycle_align.cut_again` (written only when the alignment itself cuts again). Only where `cycle.source/` is absent (a 4.1.0 or earlier loop, a failed second cut, or a folder not carried along) does it cut again from the clip's frames or stop without them, saying to carry the `cycle.source/` `video-loop` kept beside it (its cut with the fill off) or cut it again with `video-loop --fill-held off` and align that.+- The loop report and printed summary JSON record `cycle_source` when a loop's held cells were made again at the clip's rate: `kept` (`true`), `dir` (`"cycle.source"`), `fill_held` (`"off"`), `cells` (cells of the cut with the fill off), and `made_before` (`held_fill.made`), or `kept` (`false`) and `why` when no cut with the fill off is kept. Loops with no cell made and cuts with `--fill-held off` record no `cycle_source`.+- Python callers: `sprite_gen.video.loop`: new `keep_unfilled(report, out_dir, name, cut, **asked)` (the cut again with the fill off kept as `cycle.source/`; ValueError naming why it is not), new `filled(meta)` and `CUT_AGAIN_DIR` (both moved from `align`); `sprite_gen.video.align.filled` and `align.CUT_AGAIN_DIR` keep their names and refer to those; `align.unfilled_source` aligns from a kept cut and otherwise calls `keep_unfilled`.+- **Docs**: [loop-repair.md](docs/loop-repair.md) section 7 ("An alignment: aligned as filmed, filled at the end") and section 4 ("The cut as filmed is kept"); [video-pipeline.md](docs/video-pipeline.md) section 4 (held cells, and what a refusal removes); `--fill-held` help of `video-loop` and `video-cycle-align`.+- **Tests**: `tests/video/test_no_repeat_default.py` adds `test_a_set_with_a_filled_direction_is_aligned_without_the_clip_s_frames_as_it_is_with_them`, `test_video_loop_keeps_a_filled_loop_s_cut_with_the_fill_off_beside_it_and_an_unfilled_one_s_as_it_was`, and `test_a_filled_loop_whose_cut_with_the_fill_off_fails_is_delivered_and_says_why_nothing_is_kept`, and removes `cycle.source/` first in two existing alignment tests (covering 4.1.0 loops and the updated stop message); `tests/video/test_loop_prop_seam_held.py` checks `cycle_source` on the loop report and no `cycle_align.cut_again` on the aligned strip record; `tests/video/test_ghost_given_way.py` moves the RIFE binary call pin on the synthetic strider from rife-v4.25 10 to 12 and rife-v4.6 12 to rife-v4.25 12 to 14 and rife-v4.6 14 (the test's pin per model holds on every machine, including the Linux llvmpipe lane; its new values were measured on an Apple GPU, where the app walk ran the binary 12 times at 4.1.0 and 14 times now on both rife-v4.25 and rife-v4.6; 17 call-pin tests run, none of the others moved).+## v4.1.0 - Prop plate tracked and erased per frame across camera pans, with palette exclusion and contact warnings (video-frames --prop-plate)**Upgrading from 4.0.0: runs without `--prop-plate` take the same code path as 4.0.0 (every new argument is `None`) and give the same keyed frames, frames report, stdout, and stderr byte for byte as 4.0.0, with `--decontam palette` and `--spill auto` as well as by default. Runs with `--prop-plate`: keyed frames and every cut from them change (the plate is erased in each frame where it is found, and the 3.12.0 median rule no longer erases anything), the frames report's `prop_plate` records per-frame tracking instead of a fixed box, and the edge pass learns the subject palette without the plate. The canvas side (`video-canvas --prop-plate`) is unchanged. No new dependency, no model call.**diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex 9a56672..f6121c0 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -3220,9 +3220,7 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-`{"source": i}` — frame i of `cycle.source/`, taken as filmed (a turn, a snap, or the nearerframe), as many times as it is taken — or `{"between": [i, j], "t": t}`, a frame made betweentwo. The report's loop rows carry it too.-- **The cut as filmed is kept** in `cycle.source/` on the first alignment, and every later- alignment reads from there: running it again, or at another length, never resamples a- resampled loop. Every loop of the set is resampled before any is rewritten, so a loop that+- **The cut as filmed is kept** in `cycle.source/` by `video-loop` when a loop's held cells were made again at the clip's rate (its cut with `--fill-held off`) and otherwise on the first alignment, so the first alignment of a filled loop (without the clip's frames) and every later alignment read from there: aligning a filled loop, running the alignment again, or running it at another length never resamples frames the fill made or a resampled loop. Every loop of the set is resampled before any is rewritten, so a loop thatcannot be made leaves the set as it was. The first alignment also records the strip as cut,before anything is rewritten (`cycle_align.origin`: its file's sha256 — `follow.source.png`'swhere a follow-through moved it —, cell size, scale, crop origin, `sample_indices`, each cell's@@ -3451,7 +3449,9 @@ Measured on the tests' synthetic walker without a staff: its repairs left four r### An alignment: aligned as filmed, filled at the end-`video-cycle-align` (and `video-set --align-cycles auto`) makes its frames between from frames as filmed, never from frames the fill made. A loop never aligned whose held cells `video-loop` made again (`held_fill.made`, or `held_fill.again.made`) is cut again from its frames with `--fill-held off`, using its report's `cut_args` (no provider call). That cut is kept as `cycle.source/` (its frames, strip and strip record) and aligned. `cycle_align.cut_again` records it: `report`, `fill_held` (`off`), `cells`, `made_before`. Where it cannot be cut again (no report beside it, a report from before cuts recorded their arguments, frames moved, the cut again took another window of frames), the alignment stops, names the loop and why, and says: cut it again with `video-loop --fill-held off` and align that.+`video-cycle-align` (and `video-set --align-cycles auto`) makes its frames between from frames as filmed, never from frames the fill made. When `video-loop` cuts a loop (not a cut played once, not an effect's lifetime) at the clip's rate (no `--out-fps`) and its held cells were made again (`held_fill.made`, or `held_fill.again.made`), once the filled cut has passed every gate and its GIF and WebP are written `video-loop` cuts the clip's frames a second time with `--fill-held off`, using its report's `cut_args` and `frames_dir` through `loop.cut_again` (no provider call). That cut is built in `.cycle.source.cut/` beside the loop; if it takes the same frames of the clip as the first (`cycle_drawings` start and length), its frames, strip (`<name>.strip.png`) and strip record (`<name>.strip.json`) are put in place as `cycle.source/` by one rename and `.cycle.source.cut/` is removed, while the delivered loop (`cycle/`, strip, strip record, GIF, WebP) stays the filled one. Stderr announces the second cut before its lines and notes when `cycle.source/` is kept. The loop report and printed summary JSON record `cycle_source`: `kept` (`true`), `dir` (`cycle.source`), `fill_held` (`off`), `cells` (cells of the cut with the fill off), `made_before` (`held_fill.made`), or `kept` (`false`) and `why` with a warning on stderr when the second cut fails or takes other frames (the filled loop is still delivered).++Where `cycle.source/` beside a loop holds a strip record showing no cell was made, `video-cycle-align` aligns from it and cuts nothing, so the clip's frames are not needed where the set is aligned (an app that cuts in one place and aligns in another carries `cycle.source/` with the loop's cycle frames, strip, strip record and report). Only where `cycle.source/` is not there (a loop cut by 4.1.0 or earlier, one whose second cut failed, or a folder not carried along) is a loop never aligned whose held cells `video-loop` made again cut again from the clip's frames with `--fill-held off`, using its report's `cut_args` and `frames_dir` (no provider call), kept as `cycle.source/` (its frames, strip and strip record) and aligned. `cycle_align.cut_again` records it only when the alignment itself cut again: `report`, `fill_held` (`off`), `cells`, `made_before`. Where it cannot be cut again (no report beside it, a report from before cuts recorded their arguments, frames moved, the cut again took another window of frames), the alignment stops, names the loop and why, and says: carry the `cycle.source/` `video-loop` kept beside it (its cut with the fill off), or cut it again with `video-loop --fill-held off` and align that.Then each loop as aligned is read for held cells and filled at the end (`--fill-held auto`, the default), as `video-loop` fills a loop: its first cell kept, a loop drawn on twos or threes and a hold longer than three cells kept, each frame made judged with the `held` fault among the others. This also catches a frame the alignment's own resampling took twice (`--between nearest`, or a frame made refused and the nearer source frame taken). The fill at the end can also ask for a frame between that the loop's own resampling already made for that loop and gave way, under `--between auto`. That frame is taken from what the resampling made, and RIFE is not run for it again. With `--between-cache`, such a frame is not asked of the directory a second time, so the report's `between_cache` counts each frame once. The strip record's and the report row's `held_fill` say what was done; `holds` lists what was kept. `--fill-held off` delivers the aligned loops as they come out of the alignment. A set whose loops show no held cell is aligned as before, pinned by a picture digest measured on the engine before this change (commit 4f5ccd5).diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 541a822..578df14 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -439,7 +439,7 @@ them fails rather than being written.See [loop review](loop-review.md)for the visual review contract and manual overrides.-**Held cells: found, filled, repaired, read again: the default step of every cut.** A cut whose neighbour cells show the same picture (a frame shown twice or three times: a model that stalls, a rate carried to another by repeating frames) stops on it as it plays. `video-loop` reads each cut it makes for them (loop, one-shot, once, once-return, so every cut of `video-set` and of a clip from `video`) and by default makes each run of them again with RIFE's frames between the pose before and the pose after (`--fill-held auto`), the cut's length, beat and first cell kept, a part standing still in both kept still. A loop is read as a ring: a run that ends on its last cell is made again toward its first cell, and a last cell that shows the first cell's picture (a cut one cell too long) is made again too, the first cell never changed. A run longer than three cells, a run joined across the wrap longer than three cells, the ends of a cut played once and a cut drawn on twos or threes (limited animation, `held_fill.drawn`) stay as filmed, and so does a run no frame between is taken for (a fault, or a frame that shows the picture beside it again), named in a warning; a hold the motion means is listed in the strip's `holds` (`{from, to, kind, reason}`). Then the repairs run and the cut is read again for a run they left, made again the same way (`held_fill.again`). The report and the strip metadata record the held runs (first cell, how many, `keep` on a kept one) and the poses over the cells (`held_fill`); tell the person that one line: `poses/cells`, e.g. `24/27` before and `27/27` after. With no RIFE the cells are delivered as filmed and a warning names the motion and the install line; `--fill-held off` cuts as before, with no read again. The walks and runs a set aligns (`video-set --align-cycles auto`, `video-cycle-align`) are cut as filmed, aligned from frames as filmed, and filled at the end, each loop as aligned read and filled as `video-loop` fills a loop, the cut as filmed kept as `cycle.source/`. A cut asked for above its clip's rate (`--out-fps 60` on a 24 fps clip; `video-cycle-align --out-fps` for an aligned set) is made of frames between, never frames shown again ([loop repair](loop-repair.md) section 7).+**Held cells: found, filled, repaired, read again: the default step of every cut.** A cut whose neighbour cells show the same picture (a frame shown twice or three times: a model that stalls, a rate carried to another by repeating frames) stops on it as it plays. `video-loop` reads each cut it makes for them (loop, one-shot, once, once-return, so every cut of `video-set` and of a clip from `video`) and by default makes each run of them again with RIFE's frames between the pose before and the pose after (`--fill-held auto`), the cut's length, beat and first cell kept, a part standing still in both kept still. A loop is read as a ring: a run that ends on its last cell is made again toward its first cell, and a last cell that shows the first cell's picture (a cut one cell too long) is made again too, the first cell never changed. A run longer than three cells, a run joined across the wrap longer than three cells, the ends of a cut played once and a cut drawn on twos or threes (limited animation, `held_fill.drawn`) stay as filmed, and so does a run no frame between is taken for (a fault, or a frame that shows the picture beside it again), named in a warning; a hold the motion means is listed in the strip's `holds` (`{from, to, kind, reason}`). Then the repairs run and the cut is read again for a run they left, made again the same way (`held_fill.again`). The report and the strip metadata record the held runs (first cell, how many, `keep` on a kept one) and the poses over the cells (`held_fill`); tell the person that one line: `poses/cells`, e.g. `24/27` before and `27/27` after. With no RIFE the cells are delivered as filmed and a warning names the motion and the install line; `--fill-held off` cuts as before, with no read again. The walks and runs a set aligns (`video-set --align-cycles auto`, `video-cycle-align`) are aligned from frames as filmed, never from frames the fill made, and filled at the end, each loop as aligned read and filled as `video-loop` fills a loop, the cut as filmed kept as `cycle.source/`. In `video-set --align-cycles auto`, the walks and runs it aligns are cut as filmed (`--fill-held off`), so its loops are never filled before the alignment; when someone instead runs `video-loop` with its default fill and aligns the loops afterwards with `video-cycle-align` (not through `video-set`), `video-loop` has already filled those loops. When `video-loop` makes held cells again in a loop at the clip's rate (no `--out-fps`), once the filled cut has passed every gate and its GIF and WebP are written it cuts the clip's frames a second time with `--fill-held off` and keeps that cut beside it as `cycle.source/` (`cycle_source` in the report), so `video-cycle-align` aligns from `cycle.source/` without needing the clip's frames (carry `cycle.source/` when aligning elsewhere; only where it is missing does `video-cycle-align` cut again from the clip's frames). A cut asked for above its clip's rate (`--out-fps 60` on a 24 fps clip; `video-cycle-align --out-fps` for an aligned set) is made of frames between, never frames shown again ([loop repair](loop-repair.md) section 7).**The fundamental period: recorded, never cut on the pixels' word.** A motion that repeats everyP frames repeats every 2P as well, and 2P can be the better repeat: a clip drawn on twos (a new@@ -570,8 +570,7 @@ Every `video-loop` refusal that writes `status = "failed"` (selection, the motiojump repair, the jolt gate, the pin gate, the seam gate, a strip with no body to crop, and aGIF or WebP that could not be written or failed its verification) now removes what an earliercut handed over in the output folder: `cycle/`, `<name>.strip.png`, `<name>.strip.json`,-`<name>.gif`, `<name>.webp`, and `cycle.source/` and `follow.source.png`, which a later-alignment and follow-through keep beside them. A cut the+`<name>.gif`, `<name>.webp`, `cycle.source/` (kept beside them by `video-loop` for a filled loop, or by a later alignment), and `follow.source.png` (kept beside them by a later follow-through). A cut therefused run had already written (a strip with no body, the pin and seam gates, the GIF andWebP) is kept as `cycle.refused/`, to look at. The next cut that passes removes it; a refusal that comes beforethe cut removes an earlier one. An argument error touches nothing.