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(loop): preserve both phase occurrences in ambiguous gaits

Soohong Kim99b29ca587e8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d30a04..381e982 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,9 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- `video-loop` automatic cuts now score the transition actually played from the last displayed frame back to the first. The chooser prefers a step comparable to the cycle's ordinary motion rather than the smallest distance, which could repeat a pose and pause at the wrap. Reports retain `next_frame_distance` as a separate diagnostic.
- `video-frames --spill full` now lowers the tint threshold as well as lifting the cluster-size limit, so faint key-colour reflections are corrected. `--spill auto` examines the reference at the same threshold before selecting full correction, preserving the character's own key-coloured material. The conservative `small` mode and the default 3-second video-set duration are unchanged.
+- Gait auto-detection now considers an ambiguous double-period candidate even when the short candidate exceeds the duration floor. It preserves both phase occurrences at source speed when the longer local minimum is similarly credible and passes the periodicity gate; near-exact short repeats, worse doubles, non-gait states and caller window bounds are preserved. Reports identify this conservative choice with `half_period_guard.reason = "ambiguous-harmonic"` and `cycle.review_recommended`, rather than claiming anatomical stride certainty.
+- Added a [loop review guide](docs/loop-review.md) defining what numeric gates establish, when sequential visual review is needed, and how to record explicit cut/alignment choices without presenting them as automatic decisions.
+
## v2.4.1 - A visible hop is no longer refused as "never leaves its rest pose"
- `video-loop` one-shot detection no longer refuses a visible hop because the rest pose is not one pose. The excursion is admitted by either the peak's height in MADs of the rest noise (as before) or the fraction of the subject's pixel mass the peak moves (new, ≥ 0.4); the report records `excursion_moved` and `excursion_rule`. A body that walked a few steps, hopped 42 px and froze scored 1.8 MADs because the walking preamble and the frozen tail inflate the "rest noise"; by moved mass it scores 1.07. A jittering stand still fails both rules, and clips the MAD rule already accepted are cut exactly as before.
diff --git a/docs/README.md b/docs/README.md
index 89e954a..0ffa212 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -76,6 +76,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution, transparency strategy per provider, row usage |
| [video.md](video.md) | `sprite-gen video` / `video-extend` / `video-edit`: stills and clips to mp4 through Grok Imagine (image-to-video, last-frame pin, references, extension, editing) with the user's own credential |
| [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch |
+| [loop-review.md](loop-review.md) | Automatic loop decisions, ambiguous gait review, visual evidence and explicit cut/alignment overrides |
| [frame-interpolation.md](frame-interpolation.md) | Generative in-betweens for sprite frames, recorded as a take |
| [seamless-video-loop.md](seamless-video-loop.md) | Making a non-looping ambient clip loop forever (RIFE seam bridge) — a different job from pipeline B |
diff --git a/docs/loop-review.md b/docs/loop-review.md
new file mode 100644
index 0000000..3017c7b
--- /dev/null
+++ b/docs/loop-review.md
@@ -0,0 +1,86 @@
+# Loop automation and visual review
+
+Use the normal pipeline first. No model needs to choose every cut:
+
+```bash
+sprite-gen video-loop --frames-dir keyed/ --out-dir loop/ --state run --fps 24
+```
+
+The caller must pass the **measured source fps**, not always 24. `video-set` obtains it
+from `video-frames`. The default anchor is `none` in both commands. The default clip
+request remains 3 seconds; it does not determine the playback speed.
+
+## What the script decides
+
+- It measures repeat candidates from the keyed frames and the state's time window.
+- It scores the last displayed frame -> first frame against ordinary adjacent motion,
+ reducing repeated-pose stalls at a loop boundary.
+- Gaits below the duration floor may use a double period, as before. Above that floor,
+ similarly credible non-exact candidates at P and approximately 2P now retain 2P once
+ when it fits the window and passes the periodicity gate. Keeping two real repetitions
+ is preferable to discarding a potentially distinct phase. This may produce a two-cycle
+ loop of a genuine short gait; frames keep their original timing.
+- Near-exact short repeats, implausible longer repeats, and non-gait states are not
+ extended by that ambiguity policy. There is no character-specific frame count.
+- Alpha, frame counts and seam metrics are checked before the output is accepted.
+
+A numeric pass establishes those facts. It does **not** establish correct foot contact,
+anatomical left/right alternation, a believable gait, or that the source was drawn well.
+`cycle.review_recommended = true` marks an ambiguous-harmonic choice; `false` means
+that this particular heuristic did not flag ambiguity, not that visual quality is certified.
+The direct CLI summary preserves that flag and the guard evidence. `video-set` also
+propagates them in its item report and marks the table row `OK (review gait)`.
+
+## Material for a vision-capable reviewer
+
+Provide the original clip, the generated loop played at source speed for at least three
+repeats, the JSON report, and an ordered contact sheet with original frame indices. For
+an ambiguous harmonic include both P and 2P candidates using the same size and fps.
+A single still cannot establish a gait cycle. If the model cannot consume video, provide
+ordered frames spanning at least two candidate cycles, including several frames on both
+sides of the wrap. Do not ask it to judge motion from an unordered image collage.
+
+A human or a vision-capable model should check:
+
+1. Do the limbs alternate, or does one phase restart before its counterpart appears?
+2. At the wrap, does motion stall, snap, or reverse compared with nearby frames?
+3. Does the torso translate across the canvas, or are only the limbs/clothing moving?
+4. Are deformation or contact errors already present in the source clip?
+
+Return the evidence frame indices, chosen mode/start/length, anchor, reason and any
+uncertainty. Keep that decision separate from the unmodified automatic report. A model
+without the required visual input must not claim it reviewed the gait. Ambiguous or
+contradictory visual evidence should remain unresolved rather than inventing a precise cut.
+
+## Explicit adjustments
+
+If the visible full cycle is clear but the automatic candidate is wrong, make the choice
+explicit and keep the report's `kind = fixed`:
+
+```bash
+sprite-gen video-loop --frames-dir keyed/ --out-dir reviewed/ --state run \
+ --fps 24 --cycle fixed --start <zero-based-index> --length <frame-count>
+```
+
+Do not double a frame count unconditionally or duplicate existing frames. Choose a
+continuous interval in the original sequence. `--min-len/--max-len` can instead narrow
+an evidenced search interval while leaving the exact cut to the detector.
+
+Use `--anchor feet` only when the source shows slow in-canvas translation. It removes a
+linear horizontal trend; it is not a universal stabilizer, does not pin each planted foot,
+and can alter an already stationary subject. Start with the default `none`. Compare with
+`feet` on identical frames before selecting it. Normal body bounce, clothing motion and
+a model's changing anatomy are not position drift.
+
+Do not raise `--seam-max` merely to make a failed result pass. A source lacking a complete
+usable cycle may require a longer/new clip. Regeneration is a new generation request,
+not a hidden fallback inside loop extraction.
+
+## Reproducibility
+
+Store the source identity, engine version, exact CLI arguments, selected report and
+whether a person/model overrode the automatic choice. Keep the same fps for comparisons.
+Render comparison videos from PNG strips or lossless frame outputs, not palette GIFs.
+A reviewed example is not evidence that all future inputs will automatically attain its
+quality. Consumers can route `review_recommended` to review while retaining the automatic
+result as an explicitly labelled candidate.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index b96a48c..dfc749e 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -196,6 +196,16 @@ periodicity gate measures the period's dip against the profile mean over the who
window, and a ceiling that grows with the clip inflates that mean until a single hop
in a jittering stand passes as a walk.
+For gait states, a duration above the floor is not proof that both phases are present.
+If a local minimum near twice the chosen period is within the existing 25 % repeat-error
+tolerance and still passes the periodicity gate, the detector retains the longer candidate
+once, inside the requested window. Near-exact repeats (repeat error at most 10 % of an
+ordinary adjacent step) stay short. This is a conservative response to ambiguous harmonics:
+a genuine short gait may be shown twice, at the same source speed. It does not identify
+anatomical left/right contacts. The report records `half_period_guard.reason =
+"ambiguous-harmonic"` and `cycle.review_recommended = true`. See [loop review](loop-review.md)
+for the visual review contract and manual overrides.
+
Gates, all fail-loud: no period (profile flat, `periodicity < 0.15`), loop seam ratio
above `--seam-max` (2.0), GIF/WebP re-opened and checked (frame count, `loop=0`,
transparent corners, no RGB under alpha 0 in the WebP).
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 711bb8e..88c8194 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -134,6 +134,8 @@ def run_item(
result["frames"]["spill"] = fr.get("spill", {}).get("mode")
lp = loop_mod.run_loop(Path(fr["keyed_dir"]), item_dir / "loop", fps=float(fr["fps"]), state=state, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX, name=item, report_path=item_dir / "loop.report.json", anchor=anchor)
result["loop"] = {"kind": lp["cycle"].get("kind", "periodic"), "cycle": lp["cycle"]["length"], "period": lp["cycle"]["period_global"], "cycle_ratio": round(lp["cycle"]["ratio"], 3), "seam_ratio": lp["resampled_seam_ratio"], "n_out": lp["n_out"], "drift_px": lp["strip"].get("drift_px", 0), "gif": lp["gif"]["file"], "webp": lp["webp"]["file"], "strip": lp["strip"]["path"]}
+ result["loop"]["review_recommended"] = lp["cycle"].get("review_recommended", False)
+ result["loop"]["half_period_guard"] = lp["cycle"].get("half_period_guard")
result["ok"] = True
except SystemExit as exc:
result["ok"] = False
@@ -146,7 +148,8 @@ def write_table(results: list[dict[str, Any]], path: Path) -> str:
for r in results:
if r.get("ok"):
lp = r["loop"]
- lines.append(f"| {r['direction']} | {r['state']} | {lp.get('kind', 'periodic')} | {lp['cycle']} | {lp['period'] if lp['period'] is not None else '-'} | {lp['seam_ratio']:.2f} | {lp['n_out']} | OK |")
+ status = "OK (review gait)" if lp.get("review_recommended") else "OK"
+ lines.append(f"| {r['direction']} | {r['state']} | {lp.get('kind', 'periodic')} | {lp['cycle']} | {lp['period'] if lp['period'] is not None else '-'} | {lp['seam_ratio']:.2f} | {lp['n_out']} | {status} |")
else:
lines.append(f"| {r['direction']} | {r['state']} | - | - | - | - | - | FAIL: {r.get('error', '')[:80]} |")
text = "\n".join(lines) + "\n"
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 391b829..14ea31e 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -69,6 +69,7 @@ ONE_SHOT_MIN_LEN = 4 # a one-shot's length is the clip's own fact; only a degen
# taken when it repeats about as well. The cost is asymmetric — a wrongly doubled cycle
# is still a clean two-cycle loop, a halved one walks on one leg.
GAIT_DOUBLE_TOL = 0.25
+GAIT_NEAR_EXACT_STEP_FRACTION = 0.10 # no ambiguity extension when repeat error is tiny compared with a playback step
ANCHOR_MODES = ("none", "feet")
FOOT_BAND = 0.08 # fraction of the frame's own height, measured up from its lowest opaque row
@@ -157,7 +158,8 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
`gait_floor` (frames) turns on the half-period guard: a period below it is one step
of a two-step gait, so the doubled period is taken when it repeats about as well
- (see GAIT_DOUBLE_TOL)."""
+ (see GAIT_DOUBLE_TOL). Above the floor, ambiguous non-exact harmonics may also
+ retain two phase occurrences; the report flags that decision for visual review."""
n = D.shape[0]
max_len = min(max_len, n - 2)
if min_len < 2 or max_len < min_len:
@@ -184,7 +186,32 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
period = L2
else:
guard = {"applied": False, "below_floor": period, "gait_floor": gait_floor, "why": "the doubled period repeats too much worse to be the same gait"}
+ # A plausible duration does not prove that a gait contains both phases. If a
+ # second local minimum at twice the period is similarly good, retain both
+ # occurrences at the original fps. This is a conservative ambiguity policy,
+ # not an anatomical inference: a true short cycle may be shown twice.
+ # Do it only once, inside the requested window, and leave near-exact repeats
+ # alone. The duration-floor guard above still owns implausibly short beats.
profile_mean = float(np.mean([prof[L] for L in prof]))
+ review_recommended = False
+ if gait_floor is not None and period >= gait_floor and not guard["applied"]:
+ ordinary_step = float(adjacent.mean())
+ repeat_fraction = prof[period] / ordinary_step if ordinary_step > 0 else math.inf
+ doubles = [L for L in cands if abs(L - 2 * period) <= 1]
+ if doubles and repeat_fraction > GAIT_NEAR_EXACT_STEP_FRACTION:
+ L2 = min(doubles, key=lambda L: prof[L])
+ if (prof[L2] <= prof[period] * (1 + GAIT_DOUBLE_TOL) + 1e-4
+ and profile_mean > 0
+ and (profile_mean - prof[L2]) / profile_mean >= PERIODICITY_MIN):
+ guard = {
+ "applied": True, "from": period, "to": L2,
+ "gait_floor": gait_floor, "reason": "ambiguous-harmonic",
+ "depth_ratio": round(prof[L2] / prof[period], 3),
+ "repeat_error_over_step": round(repeat_fraction, 3),
+ "why": "both periods are plausible; retain two phase occurrences at source speed",
+ }
+ period = L2
+ review_recommended = True
periodicity = (profile_mean - prof[period]) / profile_mean if profile_mean > 0 else 0.0
# Score the last displayed frame -> first frame transition against an ordinary
# playback step. Minimising distance alone rewards a repeated pose (a stall).
@@ -206,6 +233,7 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
best.pop("wrap_score")
best["period_global"] = period
best["half_period_guard"] = guard
+ best["review_recommended"] = review_recommended
best["periodicity"] = round(periodicity, 4) # how far below the profile mean the period dips (0 = flat = no period)
best["profile_minima"] = [[L, round(prof[L], 5)] for L in sorted(cands, key=lambda L: prof[L])[:6]]
return best
@@ -716,7 +744,7 @@ def run(**kwargs: object) -> int:
anchor=str(kwargs.get("anchor") or "none"),
)
summary = {k: payload[k] for k in ("state", "frames_total", "window", "cycle_seconds", "n_out", "delay_ms", "resampled_seam_ratio", "specks_dropped", "report")}
- summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio")}
+ summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio", "review_recommended", "half_period_guard")}
if payload["periodic_attempt"]:
summary["periodic_attempt"] = payload["periodic_attempt"]["why_rejected"]
summary["strip"] = {k: payload["strip"][k] for k in ("path", "frames", "w", "h", "body_h", "delay_ms")}
diff --git a/tests/video/test_gait_harmonic_ambiguity.py b/tests/video/test_gait_harmonic_ambiguity.py
new file mode 100644
index 0000000..010ed7f
--- /dev/null
+++ b/tests/video/test_gait_harmonic_ambiguity.py
@@ -0,0 +1,56 @@
+"""Ambiguous gaits retain both phases without a fixed cut or a slower frame rate."""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from sprite_gen.video import loop
+
+
+def _repeat_distances(period=13, *, noise=0.0, drift=0.0):
+ t = np.arange(period * 12)
+ angle = t * 2 * np.pi / period
+ points = np.column_stack([np.cos(angle), np.sin(angle), drift * t])
+ rng = np.random.default_rng(31)
+ nuisance = rng.normal(0, noise, (len(t), 12))
+ points = np.column_stack([points, nuisance])
+ return np.abs(points[:, None] - points[None, :]).mean(axis=2).astype(np.float32)
+
+
+def test_noisy_harmonic_above_duration_floor_retains_both_occurrences():
+ D = _repeat_distances(noise=0.02)
+ plain = loop.detect_cycle(D, min_len=7, max_len=29)
+ gait = loop.detect_cycle(D, min_len=7, max_len=29, gait_floor=8)
+ assert plain['period_global'] == 13
+ assert gait['period_global'] == 26
+ assert gait['length'] in (25, 26, 27)
+ assert gait['half_period_guard']['reason'] == 'ambiguous-harmonic'
+ assert gait['half_period_guard']['from'] == 13
+ assert gait['review_recommended'] is True
+
+
[email protected]('noise', [0, 0.0001])
+def test_exact_or_near_exact_fast_repeat_is_not_doubled(noise):
+ cycle = loop.detect_cycle(_repeat_distances(noise=noise), min_len=7, max_len=29, gait_floor=8)
+ assert cycle['period_global'] == 13
+ assert cycle['half_period_guard']['applied'] is False
+ assert cycle['review_recommended'] is False
+
+
+def test_ambiguity_policy_never_expands_the_callers_window():
+ cycle = loop.detect_cycle(_repeat_distances(noise=0.02), min_len=7, max_len=20, gait_floor=8)
+ assert cycle['period_global'] == 13
+ assert cycle['length'] <= 20
+ assert cycle['half_period_guard']['applied'] is False
+
+
+def test_worsening_repeat_does_not_trigger_harmonic_extension():
+ cycle = loop.detect_cycle(_repeat_distances(noise=0.02, drift=0.08), min_len=7, max_len=29, gait_floor=8)
+ assert cycle['period_global'] == 13
+ assert cycle['half_period_guard']['applied'] is False
+
+
+def test_non_gait_keeps_the_shortest_credible_repeat():
+ cycle = loop.detect_cycle(_repeat_distances(noise=0.02), min_len=7, max_len=29)
+ assert cycle['period_global'] == 13
+ assert cycle['review_recommended'] is False
diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.py
index 7abdf7d..98438ad 100644
--- a/tests/video/test_video_pipeline.py
+++ b/tests/video/test_video_pipeline.py
@@ -461,7 +461,7 @@ def test_run_set_staggers_retries_429_and_tables_failures(tmp_path: Path, monkey
monkeypatch.setattr(batch_mod.time, "sleep", lambda s: None) # no real backoff waits
monkeypatch.setattr(frames_mod, "run_frames", lambda clip, out_dir, **kw: {"fps": 24.0, "frames": 10, "alpha_zero_pct_min": 60.0, "alpha_zero_pct_max": 70.0, "keyed_dir": str(out_dir / "keyed")})
monkeypatch.setattr(batch_mod.frames_mod, "run_frames", frames_mod.run_frames)
- monkeypatch.setattr(batch_mod.loop_mod, "run_loop", lambda frames_dir, out_dir, **kw: {"cycle": {"length": 12, "period_global": 12, "ratio": 0.3}, "resampled_seam_ratio": 0.5, "n_out": 12, "gif": {"file": "x.gif"}, "webp": {"file": "x.webp"}, "strip": {"path": "x.png"}})
+ monkeypatch.setattr(batch_mod.loop_mod, "run_loop", lambda frames_dir, out_dir, **kw: {"cycle": {"length": 12, "period_global": 12, "ratio": 0.3, "review_recommended": kw["state"] == "run"}, "resampled_seam_ratio": 0.5, "n_out": 12, "gif": {"file": "x.gif"}, "webp": {"file": "x.webp"}, "strip": {"path": "x.png"}})
payload = batch_mod.run_set(bases={"side": base}, states=["walk", "run", "jump"], root=tmp_path / "set", character=None, duration=6, resolution="720p", key="green", concurrency=3, force=False, gap=0.0, video_runner=fake_video)
@@ -469,8 +469,11 @@ def test_run_set_staggers_retries_429_and_tables_failures(tmp_path: Path, monkey
assert by["side-walk"]["ok"] and by["side-walk"]["clip"]["attempts"] == [0]
assert by["side-run"]["ok"] and by["side-run"]["clip"]["attempts"] == [1, 0] # one 429 retry
assert not by["side-jump"]["ok"] and "clip generation failed" in by["side-jump"]["error"]
+ assert by["side-run"]["loop"]["review_recommended"] is True
+ assert by["side-walk"]["loop"]["review_recommended"] is False
assert payload["failed"] == ["side-jump"]
table = (tmp_path / "set" / "table.md").read_text()
assert "| side | jump | - | - | - | - | - | FAIL" in table and "| side | walk | periodic | 12 | 12 | 0.50 | 12 | OK |" in table
+ assert "| side | run | periodic | 12 | 12 | 0.50 | 12 | OK (review gait) |" in table
assert (tmp_path / "set" / "set.report.json").is_file()
assert (tmp_path / "set" / "side-walk" / "canvas.png").is_file() # canvas ran for real