Skip to content

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 search's cut stands against two-step cuts that do not close only where its own seam passes

Soohong Kim8fa2c225961d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 185bd03..4dc2a70 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
-- **Fix: `video-loop --anchor motion-auto` keeps the pixel search's cut where the clip's crossings miss a pass, and where no cut of two steps closes in its place.** Seen from behind on a diagonal, the far foot passes hidden behind the near one, so the feet are seen apart once a cycle and together through the other step, its pass among them; in a clip on twos or threes a pass can also fall between two drawings. The count then sees one crossing a cycle, calls the clip's own cycle one step, and cut two cycles with `steps: 2` — which the set alignment read as settling its two-cycle screen, so the loop walked twice as fast as the rest of the set. A cut the count calls an odd number of steps has the legs swapped a cut on; where a pass can hide — the feet seen together at a pass over more than half a step, the median of the runs the clip shows whole (`crossings.Reading.overlap`, `HIDE_SHARE`) — and the clip a cut on is the same picture instead — frame by frame along the cut, its frame a cut on at most 1.0 of the cut's playback steps off (`local_cycle.same_picture`, `SAME_PICTURE_MAX`) — no legs were swapped, the count missed a crossing, and the search's cut stands, its count `uncertain` (`same-picture`, `step_count.search.same_picture`), no `steps` written. Both are asked: from the side, legs drawn alike, a step on can draw as near as the next frame, and there the feet pass briefly and the count stands. A walk whose feet stand together through most of a step and whose two steps draw nearer than a frame apart is cut one step long, as the search cut it before the count. And a search's cut the count does not refute — a two out of phase, or uncertain — now gives way only to a two-step cut that passed the gates (in phase, its top calm, its wrap within the seam gate of its step, its seam under the flow limit) and whose seam the gate passes; where none does, the search's cut is kept (`step_count.declined`, a warning line), where before a cut whose seam the gate refuses replaced a loop it passed. A search's cut the count refutes — one step or three, each seen — still gives way to the two-step cut, closing or not. On the synthetic walkers the far foot hiding behind the near reads 0.03 and 0.27 playback steps a cut on (on twos and on threes), the feet together 0.60 and 0.63 of a step, and the half step drawn with a tail on its own beat 2.12; a side walker whose two steps are one silhouette, near and far a tone apart, reads 0.89 a step on — the picture alone kept its half step — and is cut two steps, its feet together briefly; a clip the search finds no cycle in and whose crossings miss a pass a cycle is still cut two cycles long ([loop-repair](docs/loop-repair.md) section 3, "The step count").
-- **Tests** — `tests/video/test_walk_steps.py` (a walker seen from behind on a diagonal, on twos and on threes, whose far foot passes hidden: the clip's one cycle, not two, no `steps`; a walker on threes whose big tail closes on no cut of two steps: the search's cut, which passes, where the two-step cut failed the seam gate; a side walker whose two steps are one silhouette, near and far a tone or four apart, cut one step by the search: two steps, its feet passing briefly, where asking the picture alone kept the half step; the half-step walker reads over the same-picture bound; on `by_steps` itself, a search's cut two steps out of phase stands where every two-step cut's seam fails the gate and gives way where one passes, a cut refuted one step gives way to a two-step cut whose seam fails, a one-step cut that is the same picture a cut on is kept where the feet stand together through a pass, and given up for two steps where they pass briefly).
+- **Fix: `video-loop --anchor motion-auto` keeps the pixel search's cut where the clip's crossings miss a pass, and where no cut of two steps closes in its place.** Seen from behind on a diagonal, the far foot passes hidden behind the near one, so the feet are seen apart once a cycle and together through the other step, its pass among them; in a clip on twos or threes a pass can also fall between two drawings. The count then sees one crossing a cycle, calls the clip's own cycle one step, and cut two cycles with `steps: 2` — which the set alignment read as settling its two-cycle screen, so the loop walked twice as fast as the rest of the set. A cut the count calls an odd number of steps has the legs swapped a cut on; where a pass can hide — the feet seen together at a pass over more than half a step, the median of the runs the clip shows whole (`crossings.Reading.overlap`, `HIDE_SHARE`) — and the clip a cut on is the same picture instead — frame by frame along the cut, its frame a cut on at most 1.0 of the cut's playback steps off (`local_cycle.same_picture`, `SAME_PICTURE_MAX`) — no legs were swapped, the count missed a crossing, and the search's cut stands, its count `uncertain` (`same-picture`, `step_count.search.same_picture`), no `steps` written. Both are asked: from the side, legs drawn alike, a step on can draw as near as the next frame, and there the feet pass briefly and the count stands. A walk whose feet stand together through most of a step and whose two steps draw nearer than a frame apart is cut one step long, as the search cut it before the count. And a search's cut the count does not refute — a two out of phase, or uncertain — whose own seam the gate passes now gives way only to a two-step cut that passed the gates (in phase, its top calm, its wrap within the seam gate of its step, its seam under the flow limit) and whose seam the gate passes; where none does, the search's cut is kept (`step_count.declined`, `step_count.search.seam`, a warning line), where before a cut whose seam the gate refuses replaced a loop it passed. A search's cut the gate refuses too, or one the count refutes — one step or three, each seen — still gives way to the two-step cut, closing or not: its wrap may yet be closed by the overlapped wrap. On the synthetic walkers the far foot hiding behind the near reads 0.03 and 0.27 playback steps a cut on (on twos and on threes), the feet together 0.60 and 0.63 of a step, and the half step drawn with a tail on its own beat 2.12; a side walker whose two steps are one silhouette, near and far a tone apart, reads 0.89 a step on — the picture alone kept its half step — and is cut two steps, its feet together briefly; a clip the search finds no cycle in and whose crossings miss a pass a cycle is still cut two cycles long ([loop-repair](docs/loop-repair.md) section 3, "The step count").
+- **Tests** — `tests/video/test_walk_steps.py` (a walker seen from behind on a diagonal, on twos and on threes, whose far foot passes hidden: the clip's one cycle, not two, no `steps`; a walker on threes whose big tail closes on no cut of two steps: the search's cut, which passes, where the two-step cut failed the seam gate; a side walker whose two steps are one silhouette, near and far a tone or four apart, cut one step by the search: two steps, its feet passing briefly, where asking the picture alone kept the half step; the half-step walker reads over the same-picture bound; on `by_steps` itself, a search's cut two steps out of phase whose own seam passes stands where every two-step cut's seam fails the gate and gives way where one passes or where its own seam fails too, a cut refuted one step gives way to a two-step cut whose seam fails, a one-step cut that is the same picture a cut on is kept where the feet stand together through a pass, and given up for two steps where they pass briefly).
- **New: `video-loop --anchor motion-auto` closes a two-step cut's wrap that a part on its own beat leaves open, with the clip's frames a cycle apart.** A walk cut two steps long by the clip's crossings closes for the legs; a tail swinging round on a beat of its own closes on no cut of two steps, so the seam gate refused every one — and the eased retime does not reach it, since the part turns back at the wrap, where its frames read off the flow against the way. The clip goes on past the cut, and its frame a cycle after one of the cut's shows the legs at the same point of the walk. Under `--repair auto` (and `on`), where such a cut's wrap reads over `--seam-max` on its frames as corrected (`loop.wrap_on_cells`), the frames beside the wrap are made again before the jump repair (`repair.overlap_wrap`): each by RIFE between its two frames of one time — the clip's frame a cycle apart, moved by the analysis translation between the two and corrected as the cut frame was (`loop.cycle_apart`), and the cut's own — so the wrap plays a step the clip filmed and the part goes over to the cut's way over those frames, each frame at its own time. The weights (`repair.overlap_weights`) are the ease in and out x²(3 − 2x), held off it only in the steps where the rest of the body or a body measure, read on the line between the two frames, would go past its bound; a weight of 0 or 1 shows a frame whole, with no call, and a frame at one weight is made once, whatever the run. Four frames, then six, eight, ten and twelve (`OVERLAP_WIDTHS`), on the side — after the wrap or before it — whose frames a cycle apart differ least, never past half the loop; a run is taken only where no made frame has an interpolation fault — a part torn among them, below — the gate passes it, the loop played round still covers two steps (`loop.ring_steps`), no body measure — the foot line, the torso, the ground — moves a pixel past the largest step of the stretch as the loop plays it (the eased retime's bound on the same torso, never the clip's frames a cycle apart: the part going over pulls the body's mass, which is reported, while a torso the clip's frame a cycle on shows elsewhere would slide) — the part steps no further than over the stretch, no new rush is read, no window of the rest of the body steps further than its own largest step over the stretch, and no frame is left further off the flow over its limit (`rejected_for`). The jump repair after it makes nothing from, beside or again over those frames (`jump_repair.overlapped`). A frame made between two frames a cycle apart bridges the part's whole move at once, and where the part swings over a smaller one — a tail across a hand — RIFE drags the small part apart with it, which on art painted without a line no other reading sees: each frame is also read with RIFE's sixteen single passes (`rife.Rife.read`: the binary's eight flips and transposes, both ways in time, run one at a time with no augmentation and turned back, `rife.passes`) and refused as `torn` where the forward passes' mean and the backward passes' mean put the colour and coverage more than 0.05 apart over more than 0.21 of a window a tenth of the body high (`rife.torn`, `interpolation_quality.TORN_WARN`); the frame delivered is still the binary's own. The frames are made the weight nearest a half first, and the first frame with a fault ends its run, the rest of it not made (`unmade`), so a clip whose part crosses another on every run is refused the overlapped wrap and kept as filmed for the gate to refuse. The report carries `wrap_overlap` (each try with the weights chosen, the frames made in play order and in the order made, and the run taken; the binary's calls), the summary names it, a warning line names the frame that ended each refused run, and without RIFE the wrap is cut as filmed with a warning line (`--repair on` refuses). Each frame made costs the binary 34 calls (its frame, and its sixteen passes in colour and coverage); at most forty frames, where every width is made whole and refused. On the test walker (front, 26 frames a cycle, the tail on a 41-frame beat) the cut 29/26 reads 6.23 at the gate as filmed and 3.17 after the jump repair alone; four frames after the wrap rush the tail and are refused, six are taken, and the loop passes at 1.04, two steps, in ten calls. On a second walker whose big tuft bobs on the loop and a cycle on is carried 8 px aside a frame, the walker in its place, four frames are taken at the ease (3.41 → 1.53 at the gate, four calls): the torso moves 0.05 px, the body's mass 3.95 px against the stretch's 0.71, reported; where the whole walker also stands 3 px aside a cycle on, its torso sliding, every run is held at 0.85 of the cut's own frame next to the wrap, the wrap stays open and the cut is kept as filmed for the gate to refuse. On a third walker, painted without a line and seen from behind, whose big tail swings from 48 to −8 degrees across its hand between two frames a cycle apart, the real RIFE's frames at weights 0.5 and 0.7 read torn 0.44 and 0.26 with no other fault; swung 10 degrees past no hand, its frames read 0.04 at most ([loop-repair](docs/loop-repair.md#the-overlapped-wrap--a-part-on-its-own-beat-that-no-cut-of-two-steps-closes)).
- **Tests** — `tests/video/test_loop_overlap.py` (a front walker whose tail swings round on its own beat, refused at the seam on every cut of two steps, is closed at the wrap: each frame beside it made between the clip's frame a cycle apart and the cut's own at its eased weight, once a frame and weight, four frames refused for a rush and six taken, two steps on the loop played round, the body within its drift, the rest of it no faster, every other frame the clip's own and nothing made by the jump repair; on a walker whose big tuft a cycle on is carried aside, every run's drift bound is the stretch's own as the loop plays it — the torso's, which stands still there, never the clip's frames a cycle apart — and the body's mass is reported beside it; with the tuft alone carried over the run is taken near the ease, the torso within its pixel while the mass moves 2 px and more past its own; with the whole walker also standing aside a cycle on, its torso sliding, no run moves it more than a pixel in a step on the frames shown, drawn again, the frame next to the wrap is held off the ease and the cut is kept as filmed; `--repair off` refused as before; without RIFE cut as filmed with a warning, and with `--repair on` refused asking for it; a made frame with a fault ends its run there — the frame nearest a half made first, the rest not made — every width refused and the cut kept as filmed; a stand-in whose passes disagree over a patch of the body ends every run at its first frame as torn, the warning naming it; the real RIFE (marked `real_rife`) drags the painted walker's hand apart between its frames a cycle apart and the frames are refused as torn, no other reading refusing them, while a swing past no hand reads nothing; a weighting search on lines drawn by hand: the ease where nothing binds, held off it in the one step a window of the rest of the body is bounded in, none where a body measure may not move); `tests/video/test_rife.py` (`Rife.read` makes the frame as every call does and then sixteen single passes with no augmentation, the pair flipped and transposed and run both ways in time: with a binary that hands back its first frame, turned back, they disagree by exactly how far the pair differs and only there; `rife.torn` reads a patch a window wide where the passes disagree and not lines a pixel or two wide, scattered pixels, a faint patch or a frame with no body).
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index 6fe23ae..a50b2ed 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -957,15 +957,16 @@ far the wrap is from joining the same point of the walk, in frames, the worst ov
The pixel search's repeat rule is not asked: a part off the legs' beat — a tail on its own beat —
repeats on its own, and its seam is the flow repair's (section 2). `step_count.repeat` records the
search's word on the cut, and a cut it would refuse, or one that passed no gate, is a warning line.
-- A search's cut the count does not refute — a two out of phase, or uncertain — gives way only to a
- two-step cut that closes: one of the cuts that passed the gates above (in phase, its top calm, its wrap
- within the seam gate of its step, its seam under the flow limit) whose seam the gate passes. Where none
- does, the search's cut is kept, every image as the search alone cuts it (`steps` written where it is a
- two), and `step_count.declined` names the best two-step cut, its phase, whether it passed the gates and its
- seam, with a warning line. A cut that plays a step a clip shows unevenly, or a part on its own beat that closes on
- no two steps, would otherwise trade a loop that passes for one the seam gate refuses. Only a search's
- cut the count refutes — one step or three, each seen — is given up for a two-step cut that does not
- close, and the seam gate says whether the loop passes.
+- A search's cut the count does not refute — a two out of phase, or uncertain — and whose own seam the
+ gate passes (`step_count.search.seam`) gives way only to a two-step cut that closes: one of the cuts that
+ passed the gates above (in phase, its top calm, its wrap within the seam gate of its step, its seam under
+ the flow limit) whose seam the gate passes. Where none does, the search's cut is kept, every image as the
+ search alone cuts it (`steps` written where it is a two), and `step_count.declined` names the best
+ two-step cut, its phase, whether it passed the gates and its seam, with a warning line. A cut that plays
+ a step a clip shows unevenly, or a part on its own beat that closes on no two steps, would otherwise
+ trade a loop that passes for one the seam gate refuses. A search's cut the gate refuses as well gives way
+ as before — the two-step cut's wrap may yet be closed by the overlapped wrap (section 2) — and so does
+ one the count refutes, one step or three, each seen; the seam gate says whether the loop passes.
- The clip shows its steps but no cut of two: the search's cut, unless the count refutes it — then the
search runs again refusing what the crossings refute, and a search that finds nothing lists each
refused window's count (`cycle.candidates[].step_count`), those the crossings refute last.
diff --git a/sprite_gen/video/local_cycle.py b/sprite_gen/video/local_cycle.py
index 31359ca..c2cdb16 100644
--- a/sprite_gen/video/local_cycle.py
+++ b/sprite_gen/video/local_cycle.py
@@ -484,9 +484,11 @@ def by_steps(distances, trajectory, reading, *, found, refused, min_len, max_len
where none the first, and the gate says whether it closes (`method: observed-two-steps-v1`). The pixel
search's own repeat rule is not asked: a part off the legs' beat (a tail) repeats on its own and its seam is
the flow repair's; `repeat` records it.
- - A search's cut the count does not refute (`two` out of phase, `uncertain`) is replaced only by a two-step cut
- that closes: one of the cuts that passed the gates (`_rank`) whose seam the seam gate passes. Where none does,
- the search's cut, as it chose it (`declined`: the best two-step cut and why it does not close).
+ - A search's cut the count does not refute (`two` out of phase, `uncertain`) whose own seam the seam gate passes
+ is replaced only by a two-step cut that closes: one of the cuts that passed the gates (`_rank`) whose seam the
+ seam gate passes. Where none does, the search's cut, as it chose it (`declined`: the best two-step cut and why
+ it does not close). A search's cut the gate refuses too gives way as before: the two-step cut's wrap may still
+ be closed by the overlapped wrap (repair.overlap_wrap), and the gate says whether it is.
A cut taken on two steps records `steps` (count 2, by crossings): `video-cycle-align` reads a return half way
as its step, and the step screen's pixel suspicion of one step (`step_screen`) is settled, kept as
@@ -545,11 +547,14 @@ def by_steps(distances, trajectory, reading, *, found, refused, min_len, max_len
record['seam_gate'] = {'max': seam_max, 'tried': tried}
start, length = picked['start'], picked['length']
if searched is not None and searched['verdict'] != 'refuted' and not (passed and ranked.index(picked) < band):
- # A cut the count does not refute stands until a two-step cut closes in its place.
- record.update(chosen_by='search', cut=searched, flow_limit=flow_limit, seam_max=seam_max, declined={
- 'cut': [start, length], 'phase': picked['phase'], 'gated': ranked.index(picked) < band,
- 'seam': next(t['seam'] for t in tried if (t['start'], t['length']) == (start, length))})
- return (_two_steps(found, record) if searched['verdict'] == 'two' else found), record
+ # A cut the count does not refute, and the seam gate passes, stands until a two-step cut closes in its place.
+ own = round(seam_gate(found['start'], found['length']), 3)
+ record['search']['seam'] = own
+ if own <= seam_max:
+ record.update(chosen_by='search', cut=searched, flow_limit=flow_limit, seam_max=seam_max, declined={
+ 'cut': [start, length], 'phase': picked['phase'], 'gated': ranked.index(picked) < band,
+ 'seam': next(t['seam'] for t in tried if (t['start'], t['length']) == (start, length))})
+ return (_two_steps(found, record) if searched['verdict'] == 'two' else found), record
record.update(chosen_by='two steps', cut=picked['counted'], gated=bool(band), flow_limit=flow_limit, seam_max=seam_max)
# The pixel search's own word on this cut: its repeat, read as `detect` reads a window it refused.
radius, js = _around(start, length)
diff --git a/tests/video/test_walk_steps.py b/tests/video/test_walk_steps.py
index 7b2fcf4..9562043 100644
--- a/tests/video/test_walk_steps.py
+++ b/tests/video/test_walk_steps.py
@@ -376,11 +376,11 @@ def test_the_search_refuses_what_the_crossings_refute_and_names_their_count(unce
assert "refute after the rest" in refused.value.diagnostics["order"]
-def _choose(found: dict, *, period: int, seam: float, run: int = 9) -> tuple[dict, dict]:
+def _choose(found: dict, *, period: int, seam: float, run: int = 9, search_seam: float = 1.0) -> tuple[dict, dict]:
"""`by_steps` on a clip whose picture goes round every `period` frames, its feet passing every 15 (crossings at 8,
23 … 68), seen together `run` frames at each pass (9: over half a step, a pass can hide there; 3: brief), with the
search's cut `found`: every two-step cut's seam reads `seam` at the gate, its top calm and its flow off 1.0 either
- side."""
+ side, and the search's own cut `search_seam`."""
D = _distances(period=period, frames=FRAMES)
middles = (8, 23, 38, 53, 68)
reading = crossings.Reading(FRAMES, "gap", [(float(c), float(c)) for c in middles],
@@ -388,16 +388,19 @@ def _choose(found: dict, *, period: int, seam: float, run: int = 9) -> tuple[dic
return local_cycle.by_steps(
D, np.zeros(FRAMES), reading, found=dict(found), refused=None, min_len=12, max_len=FRAMES,
seam_flow=lambda s, L: {"off": [1.0, 1.0], "turn": [0.0, 0.0], "window": [[0, 0, 1, 1], [0, 0, 1, 1]]},
- wrap_pop=lambda s, L: {"pops": False, "pop": 0.1}, seam_gate=lambda s, L: seam, flow_limit=3.0, seam_max=2.0,
+ wrap_pop=lambda s, L: {"pops": False, "pop": 0.1},
+ seam_gate=lambda s, L: search_seam if (s, L) == (found["start"], found["length"]) else seam, flow_limit=3.0, seam_max=2.0,
gait_floor=12, periodicity_min=loop.PERIODICITY_MIN, signals=None)
[email protected]("seam, kept", [(3.0, True), (1.0, False)])
-def test_a_cut_the_count_does_not_refute_gives_way_only_to_a_two_step_cut_that_closes(seam, kept):
- """The search's cut 10/33 covers two steps a fifth of a step off (out of phase, not refuted). A two-step cut in
- phase replaces it only where the seam gate passes it; where none passes, the search's cut stands and the record
- names the two-step cut it declined, with a warning line (the parent engine took the two-step cut either way)."""
- picked, record = _choose({"start": 10, "length": 33}, period=30, seam=seam)
[email protected]("seam, search_seam, kept", [(3.0, 1.0, True), (1.0, 1.0, False), (3.0, 3.0, False)])
+def test_a_cut_the_count_does_not_refute_gives_way_only_to_a_two_step_cut_that_closes(seam, search_seam, kept):
+ """The search's cut 10/33 covers two steps a fifth of a step off (out of phase, not refuted), and the seam gate
+ passes it. A two-step cut in phase replaces it only where the seam gate passes that too; where none passes, the
+ search's cut stands and the record names the two-step cut it declined, with a warning line (the parent engine took
+ the two-step cut either way). A search's cut the gate refuses as well gives way: the two-step cut's wrap may yet be
+ closed by the overlapped wrap."""
+ picked, record = _choose({"start": 10, "length": 33}, period=30, seam=seam, search_seam=search_seam)
assert record["search"]["verdict"] == "two" and abs(record["search"]["phase"]) > crossings.PHASE_TOLERANCE
if kept:
assert (picked["start"], picked["length"]) == (10, 33) and record["chosen_by"] == "search"