Skip to content

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 wrap blend and the seam bridge read together — `--wrap-blend off` leaves a loop that is not a walk to the bridge, and the bridge runs after the blend

Soohong Kim49c0fa48dbaa
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index c631a58..11a567c 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -722,7 +722,7 @@ the gate are as with it on; `--repair off` turns it off with the rest.
A user expects an idle loop, jump, attack, or generic in-place action to be smoothed at its wrap like a walk. A walk's flow repair reads every frame against the line between its neighbours. An idle's own motion (a blink, an eye half shut, a mouth that opens) leaves that line too, so flow repair would remake those frames and take out the motion. A loop that is not a walk is therefore not read for its flow; its wrap alone is read, leaving the walk path unchanged.
-The seam bridge (`repair.seam_bridge`, driven from `loop.run_loop`) runs under `--repair auto` (the default) or `on` for any state that is not a gait (not walk or run). It runs on a cut that plays as a loop, and skips cuts played once (`--cycle once`, `once-return`, or an effect's lifetime), which retain `"why": "not a gait state (...)"`. A pinned clip (`--cycle pinned`) whose pin the gate refuses is skipped (`skipped`: "the pin does not close: the clip is refused on it"), because the clip is refused on its pin whatever its wrap shows. It runs after the anchor (`--anchor`), before `cycle/`, the strip, the GIF, and the WebP are written.
+The seam bridge (`repair.seam_bridge`, driven from `loop.run_loop`) runs under `--repair auto` (the default) or `on` for any state that is not a gait (not walk or run). It runs on a cut that plays as a loop, and skips cuts played once (`--cycle once`, `once-return`, or an effect's lifetime), which retain `"why": "not a gait state (...)"`. A pinned clip (`--cycle pinned`) whose pin the gate refuses is skipped (`skipped`: "the pin does not close: the clip is refused on it"), because the clip is refused on its pin whatever its wrap shows. It runs after the anchor (`--anchor`) and the wrap blend (section 6), reads the wrap as blended, and runs before `cycle/`, the strip, the GIF and the WebP are written.
| Rule | Value | Why |
|---|---|---|
@@ -1708,7 +1708,7 @@ scripts that made them are kept with the experiment's material in the maintainer
When `video-loop --cycle pinned` cuts a clip generated with its first frame given to the video model as the last frame too, the cut retains every frame except the last. The pin gate checks that the last frame lands near the first on a small thumbnail and passes, because the pinned last frame holds the first frame's pose. The video model draws that frame again: softer or sharper, in another tone, or with hair strands a pixel over. Because the redraw remains, the wrap from the last cell back to the first shows this redraw as a single jump in sharpness, whereas every other step in the loop shows motion.
-The wrap blend (`video-loop --wrap-blend auto`, the default) takes the first frame's drawing back over the cut's last half second, applying only where the two ends differ by a redraw. Passing `--wrap-blend off` cuts as before with identical bytes. The step is implemented in `sprite_gen/video/wrap_blend.py` (`measure`, `gate`, `blend`, `apply`) and called from `loop.run_loop`. It runs on the frames as filmed after the anchor and after `source_projection`, before any repair reads the wrap, and before `cycle/`, the strip, the GIF and the WebP are written.
+The wrap blend (`video-loop --wrap-blend auto`, the default) takes the first frame's drawing back over the cut's last half second, applying only where the two ends differ by a redraw. Passing `--wrap-blend off` cuts as filmed, but the seam bridge (section 2) can still make frames round the wrap of a loop that is not a walk or run; for such a loop, pass `--repair off --wrap-blend off` for the earlier bytes. The step is implemented in `sprite_gen/video/wrap_blend.py` (`measure`, `gate`, `blend`, `apply`) and called from `loop.run_loop`. It runs on the frames as filmed after the anchor and after `source_projection`, before any repair reads the wrap, and before `cycle/`, the strip, the GIF and the WebP are written.
| Rule | Value | Why |
|---|---|---|
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index ea34880..b347c54 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -1099,7 +1099,7 @@ last frame has to land within `max(seam_max x the mean step, PIN_NOISE_MAX)` of
the analysis thumbnail. A near-still clip moves so little per frame that the ratio reads the
re-render noise of the pinned frame as a jump; a clip that ends in another pose still fails,
with its own message (`the pinned clip does not end on its first frame`). The report says
-`kind = "pinned"` and records `pin_error` and `pin_tolerance`. Where the pinned frame redraws the first, `--wrap-blend auto` (the default) takes the first frame's drawing back over the last half second, a redraw only, recorded as `wrap_blend`. Passing `--wrap-blend off` cuts as before with identical bytes. See [loop repair](loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again) for the gating and blending rules.
+`kind = "pinned"` and records `pin_error` and `pin_tolerance`. Where the pinned frame redraws the first, `--wrap-blend auto` (the default) takes the first frame's drawing back over the last half second, a redraw only, recorded as `wrap_blend`. Passing `--wrap-blend off` cuts as filmed, but [the seam bridge](loop-repair.md#the-seam-bridge-a-loop-that-is-not-a-walk-whose-wrap-jumps) can still make frames round the wrap of a loop that is not a walk or run; for such a loop, pass `--repair off --wrap-blend off` for the earlier bytes. See [loop repair](loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again) for the gating and blending rules.
`--cycle once-return` is for a clip pinned to end on its first frame that plays once (`video-set
--play once-return`, [play modes](#play-modes)). It keeps every frame, the last too, so the strip