Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video-loop): a body cut whose source frames refuse a wrap the ramp closed is gated on the cells that play, its wrap and every step
Soohong Kim563b88793976
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3e904c9..2d5c617 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,11 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased++- **Fix: `video-loop --anchor body` no longer refuses an evenly sliding walk whose wrap the ramp closed when flow repair makes no frame.** Up to 2.44.0 jump repair remade any frame after a step 1.4 times the median, reading rendered cells. Since 2.45.0 flow repair makes no frame for an evenly sliding walk, so the gate read source frames and refused a wrap the ramp closed: on the tests' synthetic walk (0.1 px right a frame, 2.4 px over 24 frames), 3.08 on source frames, 1.33 on cells that play. Now, where source frames refuse the wrap, `wrap_dx_px` is not 0, no frame was made, and the cut is seam-gated, the gate reads the cells that play again (`seam_as_filmed`). It passes the cut on them (`seam_measurement: rendered-cells`, `resampled_seam_ratio`) when the wrap and largest step against the mean step are both within `--seam-max`. Every step is checked because the ramp moves wrap jumps inward. The report gains `seam_after_anchor` (`source_seam_ratio`, `seam_ratio`, `largest_step_ratio`, `largest_step_into`). Passed cuts remain the same bytes, including `--seam-max 1000`; `--anchor motion`, `motion-auto`, `none` and `feet` do not change, nor do pinned clips, flags, or restoration schemas. The reading is only as fine as the limit: half a stride with swapped legs reads 1.93 on cells that play and passes; without slide it reads 2.19 and is refused. [loop review](docs/loop-review.md#the-body-anchor-and-the-seam-gate)+- **Tests** — `tests/video/test_body_anchor_gate.py` (the sliding walk cut by hand from four starts with the repair off passes on the cells that play, and so does the walk cut by hand with the repair on and the stride the search finds, the repair making no frame; the source frames' refusal is the one `--anchor none` gives the same cut; a wrap the ramp does not close is refused with the same error line as `--anchor none` gives for one, two, three or four frames at the wrap moved 4 or 10 px sideways, a frame torn across, holed, or moved 8 px down, and cuts of 18 and 28 frames off the stride; a cut the source frames pass is not read again for the walk without the slide, the sliding walk under `--seam-max 1000`, and a first frame moved 3 px; a pinned clip of the sliding walk is gated by its pin and read on its source frames).+## v2.45.2 - The new `video-loop --overlap-wrap off` turns the overlapped wrap off on its own; the motion anchor's fine search is faster and gives the same values**Upgrading from 2.45.1: By default a run delivers the same bytes as 2.45.1, sooner, and only `--overlap-wrap off` changes what is delivered.** With the default `--overlap-wrap on`, the loop files, the frames and the report are the same bytes as 2.45.1 (the report's `producer` field names the new version), and `video-loop --anchor motion-auto` finishes sooner. With `--overlap-wrap off`, the overlapped wrap is not tried (the report's `wrap_overlap.skipped` reads `turned off (--overlap-wrap off)`, no RIFE calls), a `warning:` line is printed, and the seam gate refuses the cut as filmed, so the run fails on its seam instead of spending minutes of CPU on RIFE. No restoration schemas change: `source-restoration-v5`, repair report `schema_version` 4, comparison `schema_version` 6.diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex b21f006..5b903d2 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -316,6 +316,12 @@ step of nothing as one that closes whatever the cut. On the source frames the cefilmed; on the rendered cells, the cell of the strip the cut makes with that frame as filmed. A loopthat only gave its ghosts way to the frames beside them is gated on its source frames, as filmed.`--anchor body` reads its `seam_ratio_after_anchor` the same way.+Where the source frames refuse the wrap, the body anchor moved the cells (`wrap_dx_px` not 0), and+no frame was made, the gate reads the cells that play again. Where the repair made a frame, the gate+reads the wrap alone, but here the cut passes on them (`seam_measurement: rendered-cells`) when the+wrap and the largest step of the loop, each against the mean step, are both within `--seam-max`+(default 2.0); otherwise the refusal is the source frames' own. See+[loop review](loop-review.md#the-body-anchor-and-the-seam-gate).To compare an active result with a final candidate after all processing, use[`video-loop-compare`](loop-comparison.md); a seam pass alone is not an improvement.diff --git a/docs/loop-review.md b/docs/loop-review.mdindex 7bd65cd..bb4d72d 100644--- a/docs/loop-review.md+++ b/docs/loop-review.md@@ -36,6 +36,36 @@ that this particular heuristic did not flag ambiguity, not that visual quality iThe direct CLI summary preserves that flag and the guard evidence. `video-set` alsopropagates them in its item report and marks the table row `OK (review gait)`.+### The body anchor and the seam gate++`--anchor body` is `video-loop`'s default for `walk` and `run`. It measures the cut's+last frame's head and torso offset against its first once (strip sidecar `wrap_dx_px`)+and ramps frame k by that offset times k/L; the loop plays cells that are not the source+frames. The seam gate (`--seam-max`, default 2.0: wrap against mean step) reads source+frames (`seam_measurement: source-frames`) unless RIFE made a frame+([loop repair](loop-repair.md) section 2) or anchor is `motion` or `motion-auto`+(`rendered-cells`). Where source frames refuse, `wrap_dx_px` moved cells, no frame was+made, and the cut is gated by its seam (neither pinned nor played once), the gate reads+the cells that play again; a cell given way to the frame beside it is read as filmed+(`seam_as_filmed`). The cut passes (`seam_measurement: rendered-cells`,+`resampled_seam_ratio`) when wrap and largest step against mean step both meet the+limit; otherwise source refusal stands. Passing cuts, `--seam-max 1000` included, are+not read again, keeping identical bytes.++Only where read again, `seam_after_anchor` records `source_seam_ratio`, `seam_ratio`,+`largest_step_ratio`, and `largest_step_into` (pass or fail). The ramp closes the wrap+of a cut whose frames at the wrap jump sideways and moves the jump a few frames into the+loop; read at the wrap alone, every such cut of the test walk passed (one or two frames+moved 2 to 10 px); a window of steps beside the wrap misses a jump one frame longer than+the window; every step catches a jump of any length. A test walk sliding 0.1 px/frame+(2.4 px over 24 frames) failed at 3.08 on source frames but passes on the cells that+play at 1.33 (steps within 2.0). The slide widens the mean step, so a swapped-leg+half-stride passes at 1.93 on the cells that play while the walk without the slide is+refused at 2.19 on source frames; the reading does not promise to refuse every wrap that+does not close. Repaired frames check the wrap alone, a walk whose ordinary steps are+uneven can read a step over the limit on the cells that play and is refused as before,+and `--anchor feet` reads source frames.+## Material for a vision-capable reviewerProvide the original clip, the generated loop played at source speed for at least threediff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 499ad3c..93df3cc 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -266,6 +266,13 @@ def distance_matrix(files: list[Path]) -> np.ndarray:return _distances(np.stack([_load_small(f) for f in files]))+def _seam_on_cells(cells: list[Image.Image]) -> tuple[float, float, np.ndarray]:+ """Cells as they play, on their analysis features: the mean step, the wrap (last -> first) and each step."""+ flat = np.stack([_small_features(im) for im in cells])+ steps = np.abs(flat[1:] - flat[:-1])+ return float(steps.mean()), float(np.abs(flat[-1] - flat[0]).mean()), steps.mean(axis=1)++def _distances(flat: np.ndarray) -> np.ndarray:"""The distance between every two frames of their analysis features (`_small_features`)."""n = len(flat)@@ -1863,12 +1870,32 @@ def run_loop(seam_idx = [i + j for j in idx]resampled_adjacent = float(np.mean([D[seam_idx[k], seam_idx[k + 1]] for k in range(len(seam_idx) - 1)]))resampled_seam = float(D[seam_idx[-1], seam_idx[0]])- if report_base["seam_measurement"] == "rendered-cells":- # Gate the actual corrected/repaired/resampled strip cells, with the same limit — a cell given way to the frame+ on_cells = report_base["seam_measurement"] == "rendered-cells"+ source_ratio = resampled_seam / resampled_adjacent if resampled_adjacent > 0 else math.inf+ # The body anchor moved the cells to close a wrap the source frames refuse: the cells that play are read again. Where+ # the seam ratio gates the cut, not a pin or a cut played once.+ ramped = (not on_cells and anchor == "body" and wrap_dx != 0 and cycle["kind"] not in ("pinned", *nonloop.KINDS)+ and source_ratio > seam_max)+ if on_cells or ramped:+ # The actual corrected/repaired/resampled strip cells, with the same limit — a cell given way to the frame# beside it as filmed (`seam_as_filmed`), on the strip the cut makes with those frames.- flat = np.stack([_small_features(im) for im in (resampled_cells(*strip_of(seam_frames), idx, L) if as_filmed else pick)])- resampled_adjacent = float(np.abs(flat[1:] - flat[:-1]).mean())- resampled_seam = float(np.abs(flat[-1] - flat[0]).mean())+ adjacent, wrap, steps = _seam_on_cells(resampled_cells(*strip_of(seam_frames), idx, L) if as_filmed else pick)+ if ramped:+ # The ramp spreads whatever offset the wrap shows over the loop: a jump of a few frames comes out moved into the+ # loop, not closed. So the cells overrule the source frames only where their wrap and every step of the loop are+ # within the same limit; otherwise the refusal is the source frames'.+ largest = int(np.argmax(steps))+ report_base["seam_after_anchor"] = {+ "source_seam_ratio": round(source_ratio, 4) if math.isfinite(source_ratio) else None,+ "seam_ratio": round(wrap / adjacent, 4) if adjacent > 0 else None,+ "largest_step_ratio": round(float(steps[largest]) / adjacent, 4) if adjacent > 0 else None,+ "largest_step_into": idx[largest + 1],+ }+ if adjacent > 0 and wrap / adjacent <= seam_max and float(steps[largest]) / adjacent <= seam_max:+ report_base["seam_measurement"] = "rendered-cells"+ on_cells = True+ if on_cells:+ resampled_adjacent, resampled_seam = adjacent, wrapseam_ratio = resampled_seam / resampled_adjacent if resampled_adjacent > 0 else math.infdelay_ms = max(20, round(1000 * cycle_seconds / n_out))gif_path = out_dir / f"{name}.gif"