Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(video-loop): the same picture read on the thumbnail and on the frames as cut, in loop-repair section 7 and the CHANGELOG's Unreleased
Soohong Kim34d8945df8cb
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cddf8e7..0bccc9a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,13 +6,13 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the**Upgrading from 3.7.0: `video-loop` (and so `video-set`) now finds neighbour cells of a cut that show the same picture and, by default, makes them again with RIFE's frames between. A cut with no such cell comes out byte for byte as before. A cut with them comes out with its held cells made, its length, beat, first and last cells and wrap unchanged. `--fill-held off` cuts as before. Every cut's report and strip metadata gain `held_fill`.**-- **New: held cells found on every cut.** A frame shown twice or three times in a row (a model that stalls, a rate carried to another by repeating frames, a cut mapped to a higher rate by taking the nearer frame) is read on the analysis thumbnail the cut is chosen by. A step where no pixel changes by more than 0.1, but for at most 0.5 % of the subject's pixels, is the same picture. The report and the strip metadata record `held_fill`: the cells, the poses (the cells less those showing the picture before them again), and the held runs (first cell, how many), before and after. `video-loop` prints `poses/cells` in its summary and `video-set` puts `loop.poses` on each item.+- **New: held cells found on every cut.** A frame shown twice or three times in a row (a model that stalls, a rate carried to another by repeating frames, a cut mapped to a higher rate by taking the nearer frame) is read on the analysis thumbnail used to choose the cut and on the frames as cut. A step where at most 0.5 % of the subject's pixels change by more than 0.1 in both readings is the same picture. The report and the strip metadata record `held_fill`: the cells, the poses (the cells less those showing the picture before them again), and the held runs (first cell, how many), before and after. `video-loop` prints `poses/cells` in its summary and `video-set` puts `loop.poses` on each item.- **New: held cells filled by default (`--fill-held auto`).** Each run's cells are made between the run's first cell and the next pose at their own times (a run of three a third and two thirds of the way), judged as `video-cycle-align`'s frames are (smear, outline, ghost, hole, doubled) and for a part standing still on both sides (a foot planted, a hand on a ledge: its outline must stand where it stood, the fault `contact`). A frame refused is made again at a nearby fraction, else the run stays as filmed with a warning. Kept as filmed: a run longer than three cells (a hold the motion means), the opening and closing pose of a cut played once, a loop's last cells (their next pose is across the wrap), and every run of a cut drawn on twos or threes. In that case, its held-drawings reading (`cycle_drawings`, as `video-cycle-align` reads it) holds 2 or 3 and every run is that long (`held_fill.drawn`): limited animation, as filmed. A clip carried to a higher rate by repeating frames reads a hold too, but its runs are two and three cells by turns, and it is filled. With no RIFE the cells are delivered as filmed, never a failure, and a warning names the motion and `sprite-gen rife install`.- **New: `video-loop --out-fps F` and `video-set --out-fps F`.** A cut given above its clip's rate is made of frames between at each cell's own time, never frames shown again: a loop keeps its cycle's seconds, a cut played once runs from its first frame to its last. The strip metadata says `out_fps` and `source_fps`, and `source_cut.times` in place of `samples`. With no RIFE the cut is delivered at its own rate with a warning. `video-cycle-align` and `video-stop` refuse such a loop; `video-set` refuses it with the cycle alignment on (pass `--align-cycles off`).- A cut whose cells were made is read by the seam gate on its rendered cells, is not restored from its source frames (`video-loop-repair`: `source-processing-unsupported`), and `video-cycle-align` reads its drawings on its own cells.- Python callers: `sprite_gen.video.held_fill` (`same_steps`, `runs`, `reading`, `fill`, `upsample`, `times`, `still_kept`, `judge`, `public`, `said`); `loop.run_loop(..., fill_held=, out_fps=)`; `batch.run_set(..., fill_held=, out_fps=)`.- **Docs**: [loop-repair.md](docs/loop-repair.md) section 7 (the reading, the fill, the higher rate, the paths that give frames at a higher rate, what it takes from sprite-gen); [video-pipeline.md](docs/video-pipeline.md) section 4 (the default step: find, fill, read again; poses over cells in one line); `SKILL.md`.-- **Tests**: `tests/video/test_held_fill.py` (synthetic clips and a stand-in interpolator that draws the clip again at the time asked: six cuts with no held cell pinned to their bytes on the engine before the fill; a stalled walk filled at a half, a third and two thirds, every other cell as filmed; `--fill-held off` byte for byte as before; no RIFE delivered as filmed with the motion named; a hold of five kept; a walk drawn on twos kept as filmed, byte for byte as `--fill-held off`; a walk carried from 24 to 60 fps by repeating frames filled to 60 poses in 60 cells; a once and a one-shot cut filled; a planted foot kept still and a dragged one refused; the ends of a cut played once and a loop's last cells kept; codec-like copies the same picture and a pixel's move not; a walk at 60 fps made of 60 poses in 60 cells; a one-shot at 60 fps keeping its first and last frames; no RIFE at its own rate; a rate under the clip's refused; the switches through `video-loop` and `video-set`; restoration, the alignment and a stop refusing what they cannot read).+- **Tests**: `tests/video/test_held_fill.py` (synthetic clips and a stand-in interpolator that draws the clip again at the time asked: six cuts with no held cell pinned to their bytes on the engine before the fill; a stalled walk filled at a half, a third and two thirds, every other cell as filmed; `--fill-held off` byte for byte as before; no RIFE delivered as filmed with the motion named; a hold of five kept; a walk drawn on twos kept as filmed, byte for byte as `--fill-held off`; a walk carried from 24 to 60 fps by repeating frames filled to 60 poses in 60 cells; a once and a one-shot cut filled; a planted foot kept still, and a frame between that drags it or cross-fades two poses refused; the ends of a cut played once and a loop's last cells kept; codec-like copies are the same picture and a pixel's move is not; a whole figure moving under a thumbnail pixel is not the same picture; a walk at 60 fps made of 60 poses in 60 cells; a one-shot at 60 fps keeping its first and last frames; no RIFE at its own rate; a rate under the clip's refused; the switches through `video-loop` and `video-set`; restoration, the alignment and a stop refusing what they cannot read).## v3.7.0 - Breathe row width and height minimum and maximum sizing, and curator breathe editor range inputsdiff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex 8fd5510..9bee1c5 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -2761,11 +2761,11 @@ over its cells.| Rule | Value | Why ||---|---|---|-| The same picture | A step no pixel of which, on the analysis thumbnail the cut is chosen by (96 px on the longer side, premultiplied RGBA), changes by more than `PIXEL_SAME` 0.1, but for at most `CHANGED_MAX` 0.5 % of the subject's pixels | A textured synthetic figure, each pose shown three times, encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`: a frame shown again changes no pixel by more than 0.008, 0.020 and 0.051 (no pixel over 0.1). An arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the subject's pixels over 0.1. |+| The same picture | A step where at most `CHANGED_MAX` 0.5 % of the subject's pixels change by more than `PIXEL_SAME` 0.1 (premultiplied RGBA). This is read twice: on the analysis thumbnail used to choose the cut (96 px on the longer side) and on the frames as cut. It is the same picture only where both readings say so. | A textured synthetic figure, each pose shown three times, is encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`. A frame shown again changes no thumbnail pixel by more than 0.008, 0.020 and 0.051, and changes 0.012 %, 0.049 % and 0.11 % of the frame's subject pixels by more than 0.1. An arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the thumbnail's subject pixels over 0.1 and 0.38 % of the frame's: the thumbnail separates it. || Not a distance over the mass | `nonloop.STABLE_MAX` (0.025), the once cut's settled end, is not the rule | The arm's pixel reads 0.003 of the subject's mass: under it, so the rule would call it held. || Where read | On the cut's frames as loaded, before an anchor moves each frame apart, and again on the cells delivered | An anchor shifts each frame of a pair by its own amount: a picture shown again would no longer read as one. || Not read across the wrap | A loop's last cell and its first are not a run | The wrap is the seam gate's, not a hold. |-| A sub-thumbnail move | A small part moved a fraction of a thumbnail pixel reads as the same picture | Two or three pixels of a hand on a large frame play as a hold; made again between its neighbours it plays the same. |+| A move under a thumbnail pixel | A whole figure that moves less than a thumbnail pixel is read on the frame as cut. It is not the same picture. A small part moved a pixel or so reads as the same picture on both. | A synthetic walker moving away in a frame 280 px wide changes 4.9 % of the frame's subject pixels over 0.1 in a step that changes none of the thumbnail's. Two or three pixels of a hand on a large frame play as a hold. Made again between its neighbours, it plays the same. |The record, `held_fill` in the loop report and in the strip metadata (the strip's without each try): `cells`,`poses` (the cells less the ones showing the picture before them) and `held_runs` (each run's first cell and how