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 step gate's noise floor in the reference, the pipeline's gates and the CHANGELOG

Soohong Kimf45dc703444e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d0fead..7b8fa8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,13 +4,13 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased - The loop check inspects steps between drawings, checks fixed cut step counts, warns on unfixed repair frames, and explains seam failures
-**Upgrading from 2.45.3: Every cut 2.45.3 passed that neither new reading refuses gives the same loop files byte for byte.** Strip, sidecar, frames, GIF and WebP bytes match with the same stderr save new warning lines, measured on a batch of walk clips cut with caller arguments (the automatic walk cut, cuts by hand, forced cuts). The report gains `step_gate` on walk or run loops and `cycle.step_count` on fixed walk or run cuts, `producer` names the new version, and the CLI summary gains `step_gate` and `jump_repair.unfixed`. Refusals outside the new readings keep their lines word for word, except the seam line's end where warning lines name a part on a beat of its own. Callers matching failure lines by first words need rules for `video-loop: loop step ratio` (the clip jumps inside: film again), `video-loop: loop step count refutes the fixed cut` (cutting again by hand failed), and `video-loop: loop frames left off the flow` only if passing `--unfixed refuse`; failure reasons can also be read from `seam_refusal`. Any `--seam-max` past 2.5 lifts the step gate and count refusal, so forced delivery keeps passing `--seam-max 1000`. Reading feet on a fixed walk or run cut costs less than the distance matrix read by every cut. As a known limit, the seam gate and the body anchor's rule from 2.45.3 still read frames, not drawings, so a walk held on twos or threes whose cut wraps between two drawings is still refused where it closes between its drawings.
+**Upgrading from 2.45.3: Every cut 2.45.3 passed that neither new reading refuses gives the same loop files byte for byte.** Strip, sidecar, frames, GIF and WebP bytes match with the same stderr save new warning lines, measured on a batch of walk clips cut with caller arguments (the automatic walk cut, cuts by hand, forced cuts). The report gains `step_gate` on walk or run loops and `cycle.step_count` on fixed walk or run cuts, `producer` names the new version, and the CLI summary gains `step_gate` with `under_noise` set to true when a loop passes because its largest step is under the step gate's noise floor `STEP_NOISE_MAX` (0.03), along with `jump_repair.unfixed`. Refusals outside the new readings keep their lines word for word, except the seam line's end where warning lines name a part on a beat of its own. Callers matching failure lines by first words need rules for `video-loop: loop step ratio` (the clip jumps inside: film again), `video-loop: loop step count refutes the fixed cut` (cutting again by hand failed), and `video-loop: loop frames left off the flow` only if passing `--unfixed refuse`; failure reasons can also be read from `seam_refusal`. Any `--seam-max` past 2.5 lifts the step gate and count refusal, so forced delivery keeps passing `--seam-max 1000`. Reading feet on a fixed walk or run cut costs less than the distance matrix read by every cut. As a known limit, the seam gate and the body anchor's rule from 2.45.3 still read frames, not drawings, so a walk held on twos or threes whose cut wraps between two drawings is still refused where it closes between its drawings.
-- **Behavior change: Walk and run loops that play round now pass a step gate that inspects spacing between drawings.** After the seam gate, cells are read between drawings rather than frame by frame, so held animation on twos or threes does not appear uneven when drawings span multiple frames. The largest step from one drawing to the next, the wrap included, over the mean of the others, must be at most `STEP_RATIO_MAX` (2.5), else the loop fails with `video-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip`, with jump repair reason `: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmed` before ` — regenerate the clip` where present. The report records `step_gate` on every walk or run loop (`drawings`, `hold`, `mean_step`, `largest_ratio`, `largest_from`, `largest_into`, `wrap_ratio`, `max`, `lifted`, `kept`; `skipped` under three drawings). The bound is the larger of 2.5 and `--seam-max`, so any `--seam-max` past 2.5 lifts it; a scan or forced delivery with `--seam-max 1000` keeps a loop whose largest step is over 2.5 with warning `video-loop: warning: the loop's largest step between drawings is <ratio>x their mean (into frame <frame>), over 2.5: it jumps inside — kept, as --seam-max <seam-max> lifts the step gate` and `step_gate.kept`.
+- **Behavior change: Walk and run loops that play round now pass a step gate that inspects spacing between drawings.** After the seam gate, cells are read between drawings rather than frame by frame, so held animation on twos or threes does not appear uneven when drawings span multiple frames. The largest step from one drawing to the next, the wrap included, over the mean of the others, must be at most `STEP_RATIO_MAX` (2.5), else the loop fails with `video-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip`, with jump repair reason `: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmed` before ` — regenerate the clip` where present. The gate also uses `STEP_NOISE_MAX` (0.03) as a floor for the largest step on the analysis thumbnail. A loop passes without a warning line when that step is at most the floor, even if its ratio exceeds 2.5: whole row foot rises in a walk going away from the camera measured 2.69 times the mean but only 0.018. One frame of a 400 px tall walk cut moved 6 px and back, read 0.057, and the gate still refuses the loop. The report records `step_gate` on every walk or run loop (`drawings`, `hold`, `mean_step`, `largest_step`, `largest_ratio`, `largest_from`, `largest_into`, `wrap_ratio`, `max`, `noise_max`, `under_noise`, `lifted`, `kept`; `skipped` under three drawings). The bound is the larger of 2.5 and `--seam-max`, so any `--seam-max` past 2.5 lifts it; a scan or forced delivery with `--seam-max 1000` keeps a loop whose largest step is over 2.5 with warning `video-loop: warning: the loop's largest step between drawings is <ratio>x their mean (into frame <frame>), over 2.5: it jumps inside — kept, as --seam-max <seam-max> lifts the step gate` and `step_gate.kept`.
- **Behavior change: Fixed cuts fail when foot crossings count an odd number of steps.** Manual walk or run cuts using `--cycle fixed` now read the clip's foot crossings and evaluate the cut, matching `--anchor motion-auto`. The report records `cycle.step_count` with `chosen_by: caller`. A cut counted an odd number of steps fails with `video-loop: loop step count refutes the fixed cut <start>/<L> — the clip's crossings count one step, each seen where a walk loops on two, and an odd count swaps the legs at the wrap; cut it again two steps long (about <2 steps> frames)`. An even count is not refused by the count check, and the exemption `--anchor motion-auto` makes for a pass hidden among feet held together (the clip a cut on the same picture) applies identically through shared `local_cycle.same_picture_count`. The strip is unchanged, and there is no `steps` field. Any `--seam-max` past 2.5 lifts this refusal; a scan or forced delivery with `--seam-max 1000` keeps an odd step cut with warning `video-loop: warning: the clip's crossings count the fixed cut <start>/<L> one step, each seen: a walk loops on two steps, and an odd count swaps the legs at the wrap — kept, as --seam-max <seam-max> lifts the step gate` and records `cycle.step_count.lifted`.
- **New: Refused jump repair drawings are listed in `jump_repair.unfixed` and can fail the command.** When jump repair refuses a frame group, its frames remain as filmed; where the playing loop still reads a drawing of it 3.0 or more of its window's usual steps off the flow, that drawing is recorded in `jump_repair.unfixed` alongside `refused` (the faults). Every `unfixed` drawing prints warning line `video-loop: warning: frame <frame> of the loop lies <off>x its window's usual step off the walk's flow after the jump repair: the group that would bring it back was refused (<faults>), so it plays as filmed — a jump played as filmed; --unfixed refuse refuses such a loop (docs/loop-repair.md section 2)`. A new flag `--unfixed warn|refuse` (default `warn`) controls handling: `refuse` fails such a loop with an error line starting `video-loop: loop frames left off the flow — `. This failure is not lifted by `--seam-max`.
- **Fix: The seam gate failure line explains the cause where warning lines know it.** The first words of the failure line stay the same up to `the cycle does not close — `; where warning lines name a part on a beat of its own (an `--anchor motion-auto` cut two steps long by the clip's crossings whose wrap the gate refuses), the rest says so and names what became of the overlapped wrap, for example `video-loop: loop seam ratio <ratio> exceeds 2.0 (periodic length <L> frames from <start>); the cycle does not close — the cut covers two steps by the clip's crossings, and a part on a beat of its own (a tail, a held prop) closes on no cut of two steps: the overlapped wrap was not made (turned off (--overlap-wrap off)) — regenerate with that part moving on the walk's beat`. Elsewhere the line is word for word as before. Every refusal by the wrap, steps, or count records `seam_refusal` in the report (`reading`: `wrap`, `steps` or `count`). For `wrap`, it records `ratio`, `max`, `reason` (`own-beat` or null), and `overlap_wrap`. For `steps`, it records `ratio`, `max`, `into`, `reason` (`repair-refused`, `unfixed` or null), plus `frames` and `refused` where a reason was found. For `count`, it records `cut`, `verdict`, `k`, `why`, and `two_steps`.
-- **Tests** — `tests/video/test_loop_silent_pass.py`: a side walk in place with a middle frame moved 10 px fails the step gate while its wrap passes, recording `step_gate` and `seam_refusal`, kept by `--seam-max 1000` with a warning line; an eight drawing walk on threes passes when frame by frame steps exceed 2.5; melted ponytail outlines and smeared stand in RIFE frames stay `unfixed` with faults, cite the refused frame in step gate lines, and fail under `--unfixed refuse`; CLI tests confirm `--unfixed` defaults to `warn` and rejects other words; hand cuts fail on one step, pass at two, keep one step cuts under `--seam-max 1000`, and exempt hidden far feet on twos; a walker whose tail swings on its own beat fails seam checks with the reason in its line and `seam_refusal`; and a sideways wrap shift keeps its line word for word with `seam_refusal.reason` null. In `tests/video/test_body_anchor_gate.py`, the sliding side walk with its first frame moved 3 px used to pass because its wrap passes the seam gate on the source frames; now the step gate refuses the step into frame 1 because those 3 px take up the walk's sideways slide at the wrap and put the jump inside the loop, while the seam is still read on the source frames and not read again. In `tests/video/test_gait_fallback.py`, the held loop of the walk going away from the camera now has its feet rise by sub pixels (`walking_away(..., sub_pixel=True)`): whole crop rows made them jump a pixel every three or four frames, a step the step gate reads at 2.7 times this slow loop's mean and refuses.
+- **Tests** — `tests/video/test_loop_silent_pass.py`: a side walk in place with a middle frame moved 10 px fails the step gate while its wrap passes, recording `step_gate` and `seam_refusal`, kept by `--seam-max 1000` with a warning line; an eight drawing walk on threes passes when frame by frame steps exceed 2.5; melted ponytail outlines and smeared stand in RIFE frames stay `unfixed` with faults, cite the refused frame in step gate lines, and fail under `--unfixed refuse`; CLI tests confirm `--unfixed` defaults to `warn` and rejects other words. Hand cuts fail on one step, pass at two, keep one step cuts under `--seam-max 1000`, and exempt hidden far feet on twos. A walker whose tail swings on its own beat fails seam checks with the reason in its line and `seam_refusal`; a sideways wrap shift keeps its line word for word with `seam_refusal.reason` null. The walk going away from the camera passes with whole crop row foot rises: its largest step exceeds 2.5 times the mean but is under the floor, recorded as `step_gate.under_noise`. A standing side walk with a frame moved 2 px and back still fails on a step over the floor. In `tests/video/test_body_anchor_gate.py`, the sliding side walk with its first frame moved 3 px is refused on the step into frame 1: those 3 px take up the sideways slide at the wrap and put the jump inside the loop. The seam still reads the source frames and is not read again.
## v2.45.3 - The seam check reads the frames that play when the body anchor spreads a sideways slide; such a cut passes again, as it did in 2.44.0
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index 740c0fc..eb3c9af 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -1035,7 +1035,7 @@ settles it. Four-legged gaits are read as one foot band (`legs.strike_signals`),
### The step gate: every step between drawings, and a fixed cut's count
-On every walk or run loop that plays round (not a single play cut), after the seam gate passes, the strip cells are read between their drawings: a loop drawn on twos or threes shows each drawing for two or three frames (`repair.flow_drawings` finds them), so read frame by frame it steps nothing and then two or three steps at each drawing, making its largest step two or three times its mean even when playing evenly. Each drawing first cell is read on analysis features the seam gate reads (`loop._small_features`), taking the step from each drawing to the next and from the last drawing into the first across the wrap. The largest of these steps, wrap included, over the mean of the others must be at most `STEP_RATIO_MAX` (2.5) (`loop.drawing_steps`). Otherwise the loop fails with `video-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip`. Where jump repair says why the step jumps, the line says it before ` — regenerate the clip`: `: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmed`, or `: frame <frame> lies off the walk's flow, and no group of up to 2 drawings brings it back`. The report records `step_gate` on every walk or run loop, passed or failed: `read` (`drawings`), `drawings`, `hold`, `mean_step`, `largest_ratio`, `largest_from` and `largest_into` (the cut frames the largest step goes from and into, each the first frame of its drawing), `wrap_ratio`, `max` (the bound used), `lifted`, and `kept` where a lifted gate kept a loop over 2.5; a loop of fewer than three drawings records `skipped` instead.
+On every walk or run loop that plays round (not a single play cut), after the seam gate passes, the strip cells are read between their drawings: a loop drawn on twos or threes shows each drawing for two or three frames (`repair.flow_drawings` finds them), so read frame by frame it steps nothing and then two or three steps at each drawing, making its largest step two or three times its mean even when playing evenly. Each drawing first cell is read on analysis features the seam gate reads (`loop._small_features`), taking the step from each drawing to the next and from the last drawing into the first across the wrap. The largest of these steps, wrap included, over the mean of the others must be at most `STEP_RATIO_MAX` (2.5) (`loop.drawing_steps`). The gate also uses `STEP_NOISE_MAX` (0.03) on the same analysis thumbnail: a ratio over 2.5 passes without warning when `largest_step` is at most the floor, because a pixel of jitter can look large against a tiny mean step. On synthetic frames, a still pose 41 to 120 px tall moved one whole row reads 0.015 to 0.019, a slow walk with that row reads 0.018 to 0.020, and a frame of a walk cut 400 px tall moved 6 px and back reads 0.057 and fails. Otherwise the loop fails with `video-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip`. Where jump repair says why the step jumps, the line says it before ` — regenerate the clip`: `: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmed`, or `: frame <frame> lies off the walk's flow, and no group of up to 2 drawings brings it back`. The report records `step_gate` on every walk or run loop, passed or failed: `read` (`drawings`), `drawings`, `hold`, `mean_step`, `largest_step`, `largest_ratio`, `largest_from` and `largest_into` (the cut frames the largest step goes from and into, each the first frame of its drawing), `wrap_ratio`, `max` (the bound used), `noise_max` (the floor used), `under_noise` (true where the ratio is over 2.5 and the largest step is at most the floor), `lifted`, and `kept` where a lifted gate kept a loop over 2.5; a loop of fewer than three drawings records `skipped` instead.
`--cycle fixed --start S --length L` of a walk or run now reads clip foot crossings (`crossings.read`) and judges the cut (`Reading.judge`), as `--anchor motion-auto` already does for the cut it takes. The report records this as `cycle.step_count` (the reading record, `chosen_by: caller`, and `cut` with `verdict`, `code`, `k`, `phase`, `ring`). A walk loops on two steps; a cut whose crossings count an odd number of steps (one, three) swaps legs at the wrap however close frames look, failing with `video-loop: loop step count refutes the fixed cut <start>/<L> — the clip's crossings count one step, each seen where a walk loops on two, and an odd count swaps the legs at the wrap; cut it again two steps long (about <2 steps> frames)`. An even count of four steps is not refused. The exemption from `--anchor motion-auto` applies (`local_cycle.same_picture_count`, shared by both now): where feet are seen together over half a step at a pass (`crossings.HIDE_SHARE`) and the clip one cut on is the same picture (at most `local_cycle.SAME_PICTURE_MAX`, 1.0 playback steps along the cut), the count missed a crossing; verdict reads `uncertain`, code `same-picture`, recorded with `same_picture`, and the cut is not refused. A fixed cut gets no `steps` field and leaves its strip unchanged.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index d70b948..0fe6b54 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -924,7 +924,7 @@ the last bit on every machine. With np.polyfit, whose last bit differs between L
that stand on the frame's bottom edge read a hair past it or short of it, and whether the frames
got 2 px of room below — and so the frames the cut is searched on — turned on that bit.
-Gates, all fail loud: no period (profile flat, below the recorded `periodicity_min`), loop seam ratio above `--seam-max` (2.0), GIF/WebP reopened and checked (frame count, `loop=0`, transparent corners, no RGB under alpha 0 in the WebP). On every walk or run loop that plays round, the step gate reads cells between drawings and requires the largest step over the mean of the others to be at most `STEP_RATIO_MAX` (2.5). A fixed cut of a walk or run reads clip foot crossings to judge the cut, refusing an odd step count that would swap legs at the wrap. Both checks are lifted by `--seam-max` past 2.5; see `docs/loop-repair.md` section 3, "The step gate".
+Gates, all fail loud: no period (profile flat, below the recorded `periodicity_min`), loop seam ratio above `--seam-max` (2.0), GIF/WebP reopened and checked (frame count, `loop=0`, transparent corners, no RGB under alpha 0 in the WebP). On every walk or run loop that plays round, the step gate reads cells between drawings and refuses the loop only when the largest step over the mean of the others exceeds `STEP_RATIO_MAX` (2.5) and the largest step itself exceeds `STEP_NOISE_MAX` (0.03). A fixed cut of a walk or run reads clip foot crossings to judge the cut, refusing an odd step count that would swap legs at the wrap. Both checks are lifted by `--seam-max` past 2.5; see `docs/loop-repair.md` section 3, "The step gate".
A walk or run loop then has its jump frames repaired before the strip is built: one or two
drawings in a row that leave the loop's flow — 3× their region's usual step off the line between