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(cycle-align): a held loop is judged on the cycle cut out of its clip, not on the whole clip (held-drawings)

Soohong Kimc8a6ca2fc140
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index cd76902..c10bc63 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -15,7 +15,7 @@ the frame's top edge, which a long ear owns. docs/loop-repair.md section 4.
Every frame between two source frames softens a little, so the length is the median (the one
that needs the fewest made frames across the set), and a loop already that long is not touched.
-A loop whose clip holds each drawing for two or three frames (`held_drawings`, sprite_gen/video/
+A loop whose cut holds each drawing for two or three frames (`held_drawings`, sprite_gen/video/
held.py), that the length leaves at under RETAKE_DRAWINGS_MIN drawings a second, with frames
between them that could not be made, is aligned all the same — and named in the report's `retake`
(reason `held-drawings`, with its numbers) and in a warning: the gap is wider than any interpolator
@@ -104,18 +104,28 @@ RETAKE_UNMADE_MIN = 1
RETAKE_REASON = "held-drawings"
-def held_drawings(frames: list[Image.Image], *, fps: float, clip: dict[str, Any] | None = None) -> dict[str, Any]:
+def held_drawings(frames: list[Image.Image], *, fps: float, clip: dict[str, Any] | None = None,
+ cut: dict[str, Any] | None = None) -> dict[str, Any]:
"""Whether a loop's drawings are held, and how many its cycle holds (`held.measure`).
- `clip` is the record `video-loop` wrote in the strip metadata (`drawings`), read over the whole
- clip as keyed: its hold, and its drawings a second over the cycle's frames (`source` clip). The cut
- cycle is the fallback for a loop cut before that record (`source` cycle, read as a ring): it is
- short, and `--anchor motion-auto` shifts each cut frame, so a pair's repeat may no longer read as one."""
+ `cut` and `clip` are the records `video-loop` wrote in the strip metadata, both read on the clip's
+ steps as keyed: `cycle_drawings` over the cut (`source` span) and `drawings` over the whole clip
+ (`source` clip) — the hold and the drawings a second, over the cycle's frames. The cut's is the
+ loop's: a clip held for part of its length is held where it was cut. The clip's stands where the
+ cut was too short to read, or was cut before that record (`span_why` says which). The cut cycle
+ is the fallback for a loop cut before either record (`source` cycle, read as a ring): it is short,
+ and `--anchor motion-auto` shifts each cut frame, so a pair's repeat may no longer read as one."""
n = len(frames)
if clip and clip.get("hold"):
+ whole = {"hold": clip["hold"], "drawings_per_second": clip["drawings_per_second"], "contrast": clip.get("contrast")}
+ if cut and cut.get("hold"):
+ per_second = float(cut["drawings_per_second"])
+ return {"source": "span", "hold": cut["hold"], "contrast": cut.get("contrast"), "start": cut["start"], "length": cut["length"],
+ "frames": n, "fps": fps, "drawings_per_second": per_second, "drawings": round(per_second * n / fps, 2), "clip": whole}
per_second = float(clip["drawings_per_second"])
return {"source": "clip", "hold": clip["hold"], "contrast": clip.get("contrast"), "frames": n, "fps": fps,
- "drawings_per_second": per_second, "drawings": round(per_second * n / fps, 2)}
+ "drawings_per_second": per_second, "drawings": round(per_second * n / fps, 2),
+ "span_why": cut.get("why", "the cut was not read") if cut else "no record of the cut's own steps (cut before it was kept)"}
D = _ring(frames)
return {"source": "cycle", **held_mod.measure([float(D[k, (k + 1) % n]) for k in range(n)], fps=fps, cyclic=True)}
@@ -140,7 +150,7 @@ def retake(drawings: dict[str, Any], facts: dict[str, Any], *, fps: float) -> di
def _retake_line(name: str, r: dict[str, Any]) -> str:
"""A loop to film again, in words."""
- return (f"{name}: film this direction again ({r['reason']}) — its clip shows each drawing for {r['hold']} frames "
+ return (f"{name}: film this direction again ({r['reason']}) — its {'clip' if r['source'] == 'clip' else 'cut'} shows each drawing for {r['hold']} frames "
f"({r['drawings']:g} drawings in the cycle, {r['drawings_per_second_filmed']:g} a second as filmed); at the set's length "
f"that is {r['drawings_per_second']:g} drawings a second, {r['frames_per_drawing']:g} frames apart, and {r['unmade']} "
"frame(s) between them could not be made, so the loop halts there. A new take that draws every frame "
@@ -628,7 +638,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
except (ValueError, rife_mod.RifeUnavailable) as exc:
raise SystemExit(f"video-cycle-align: {d}: {exc}; frames between source frames are made by RIFE (docs/loop-repair.md)") from exc
start = strike["start"]
- drawings = held_drawings(frames, fps=fps, clip=loops[i][2].get("drawings"))
+ drawings = held_drawings(frames, fps=fps, clip=loops[i][2].get("drawings"), cut=loops[i][2].get("cycle_drawings"))
again = retake(drawings, facts, fps=fps)
record = {**facts, "drawings": drawings, "retake": again, "turned_by": start, "turned_on": strike["by"], "view": view, "start_foot": strike["start_foot"],
**({"foot": strike["foot"]} if "foot" in strike else {}), **({"foot_why": strike["foot_why"]} if "foot_why" in strike else {}),
diff --git a/sprite_gen/video/held.py b/sprite_gen/video/held.py
index 0af696f..3751275 100644
--- a/sprite_gen/video/held.py
+++ b/sprite_gen/video/held.py
@@ -22,6 +22,10 @@ a frame repeated now and then, as a 20 fps clip carried at 24 repeats one in six
not at all), the median over the windows. A hold whose contrast is under CONTRAST_MAX is the clip's
hold; each step is then held when it is nearer the held steps than the change steps (under the
geometric midpoint of their means), and the drawings are the frames that begin one.
+
+A clip may hold its drawings for only part of its length. `measure_cycle` reads the cycle cut out of
+it on the clip's own steps over the cut (one window's worth at least, SPAN_MIN_STEPS), so a loop is
+held where it was cut, not where most of its clip was.
"""
from __future__ import annotations
@@ -39,6 +43,9 @@ WINDOW = 12 # steps per window: six drawings on twos, four on threes; a phase t
# every frame whose steps alternate long and short stays above a third (docs/loop-repair.md section 4).
CONTRAST_MAX = 0.3
MIN_STEPS = 6 # fewer steps than this say nothing about a rhythm of two or three
+# A cut cycle is read on its own steps when it has at least one window of them: the same evidence the
+# clip's reading weighs in each window. Under it the clip's reading stands, and the record says why.
+SPAN_MIN_STEPS = WINDOW
def _contrast(steps: np.ndarray, hold: int) -> tuple[float, list[np.ndarray], list[np.ndarray]] | None:
@@ -71,15 +78,17 @@ def _contrast(steps: np.ndarray, hold: int) -> tuple[float, list[np.ndarray], li
return float(np.median(scores)), held, change
-def measure(steps: Sequence[float], *, fps: float, cyclic: bool = False) -> dict[str, Any]:
+def measure(steps: Sequence[float], *, fps: float, cyclic: bool = False, span: bool = False) -> dict[str, Any]:
"""Whether a run of frames holds its drawings, and how many drawings it shows a second.
`steps` are the distances between neighbouring frames: n - 1 of them for n frames, or n read as a
- ring (`cyclic`, the last step from the last frame back to the first). The rhythm is read on the
- steps in order (a ring's closing step is left out of it: a cut may close mid-pair), the drawings
- are counted on all of them. `hold` is 1 (every frame a drawing), 2 or 3."""
+ ring (`cyclic`, the last step from the last frame back to the first), or n read in the clip
+ (`span`, the last step from the last frame into the frame after it: a cut cycle, `measure_cycle`).
+ The rhythm is read on the steps in order (a ring's closing step is left out of it: a cut may close
+ mid-pair; a span's last step is the clip's own and is read), the drawings are counted on all of
+ them. `hold` is 1 (every frame a drawing), 2 or 3."""
s = np.asarray(steps, dtype=np.float64)
- frames = len(s) if cyclic else len(s) + 1
+ frames = len(s) if cyclic or span else len(s) + 1
inner = s[:-1] if cyclic else s
seconds = frames / fps
base: dict[str, Any] = {"frames": frames, "fps": fps, "steps": len(s), "contrast": {}}
@@ -99,6 +108,23 @@ def measure(steps: Sequence[float], *, fps: float, cyclic: bool = False) -> dict
mid = math.sqrt(max(float(np.concatenate(held).mean()), change_mean * 1e-3) * change_mean)
held_steps = int((s < mid).sum())
changes = len(s) - held_steps
- drawings = max(1, changes) if cyclic else changes + 1
+ drawings = max(1, changes) if cyclic or span else changes + 1
return {**base, "hold": hold, "held_steps": held_steps, "drawings": drawings,
"drawings_per_second": round(drawings / seconds, 3), "held_below": round(mid, 6)}
+
+
+def measure_cycle(clip_steps: Sequence[float], *, start: int, length: int, fps: float) -> dict[str, Any]:
+ """The hold of the cycle cut out of a clip, read on the clip's own steps over the cut: the steps
+ from frame k to the next, k in [start, start + length) — the last into the frame after the cut,
+ which a cycle returns to — or one fewer where the cut ends the clip. A clip held for part of its
+ length and drawn every frame for the rest is held where the cut is held, whatever the whole clip
+ reads as. `clip_steps` are the clip's n - 1 neighbouring steps, as keyed and before any anchor
+ moves a frame. A cut of fewer than SPAN_MIN_STEPS steps is not read (`hold` None, `why`)."""
+ end = min(start + length, len(clip_steps))
+ whole = end - start == length
+ span = list(clip_steps[start:end])
+ if len(span) < SPAN_MIN_STEPS:
+ return {"start": start, "length": length, "frames": length, "fps": fps, "steps": len(span), "contrast": {}, "hold": None,
+ "held_steps": None, "drawings": None, "drawings_per_second": None,
+ "why": f"{len(span)} steps, under {SPAN_MIN_STEPS}: too few to read the cut's rhythm on its own"}
+ return {"start": start, "length": length, **measure(span, fps=fps, span=whole)}
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 6720d24..8ee58b5 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -913,6 +913,9 @@ def run_loop(
lo = min_len if min_len is not None else lo_default
hi = max_len if max_len is not None else max(lo + 2, hi_default)
D = distance_matrix(files)
+ # The clip's steps as keyed, before `--anchor motion-auto` reads its own distance or moves a frame:
+ # the hold is read on them, over the clip and over the cut (sprite_gen/video/held.py).
+ clip_steps = [float(D[k, k + 1]) for k in range(n - 1)]
masses = frame_masses(files)
periodic_attempt: dict[str, Any] | None = None
target = (report_path or (out_dir / f"{name}.loop.report.json")).expanduser().resolve()
@@ -926,7 +929,7 @@ def run_loop(
# How many drawings the clip shows a second, and whether it shows each for two or three frames
# (sprite_gen/video/held.py) — over the whole clip as keyed, before any cut. A record for
# `video-cycle-align`, which says when a held clip stretched to the set's length must be filmed again.
- "drawings": held_mod.measure([float(D[k, k + 1]) for k in range(n - 1)], fps=fps),
+ "drawings": held_mod.measure(clip_steps, fps=fps),
}
cycle = None
try:
@@ -1019,6 +1022,8 @@ def run_loop(
raise SystemExit(f"video-loop: {exc}") from exc
raise
i, L = cycle["start"], cycle["length"]
+ # The same, over the cut alone: a clip held for part of its length is held where the cut is.
+ report_base["cycle_drawings"] = held_mod.measure_cycle(clip_steps, start=i, length=L, fps=fps)
# playback density, not a fixed count: a long cycle gets more frames so every state plays at
# ~gif_fps (a fixed 12 made a 2.5 s jump hold each frame 210 ms while a 1.1 s walk held 90 ms)
if n_out is None:
@@ -1118,9 +1123,12 @@ def run_loop(
if state:
# `video-cycle-align` reads the gait floor of this state when it screens a loop for two cycles.
strip_meta["state"] = str(state).strip().lower()
- # `video-cycle-align` reads the clip's hold here: a cut cycle is too short to read it on, and
- # `--anchor motion-auto` moves each frame of a pair apart (sprite_gen/video/held.py).
+ # `video-cycle-align` reads the hold here, over the cut (`cycle_drawings`) and over the clip
+ # (`drawings`, where the cut is too short to read): read on the keyed steps, since `--anchor
+ # motion-auto` moves each frame of a pair apart in the cut it writes (sprite_gen/video/held.py).
strip_meta["drawings"] = {k: report_base["drawings"][k] for k in ("hold", "drawings_per_second", "contrast", "frames")}
+ strip_meta["cycle_drawings"] = {k: report_base["cycle_drawings"][k] for k in ("start", "length", "steps", "hold", "drawings_per_second", "contrast")
+ } | ({"why": report_base["cycle_drawings"]["why"]} if "why" in report_base["cycle_drawings"] else {})
if motion is not None:
strip_meta["foot_anchor"] = anchor
strip_meta["motion_anchor"] = motion
diff --git a/tests/video/test_held_drawings.py b/tests/video/test_held_drawings.py
index 11afac9..ebda0cc 100644
--- a/tests/video/test_held_drawings.py
+++ b/tests/video/test_held_drawings.py
@@ -143,7 +143,7 @@ def test_a_held_loop_stretched_past_what_an_interpolator_bridges_is_named_for_a_
by = {Path(r["dir"]).name: r for r in report["loops"]}
assert by["NE"]["drawings"]["hold"] == 2 and by["SW"]["drawings"]["hold"] == 2 and by["E"]["drawings"]["hold"] == 1
retake = by["NE"]["retake"]
- assert retake["reason"] == "held-drawings" and retake["hold"] == 2 and retake["source"] == "clip" and retake["drawings"] == 8
+ assert retake["reason"] == "held-drawings" and retake["hold"] == 2 and retake["source"] == "span" and retake["drawings"] == 8
assert retake["drawings_per_second"] == pytest.approx(8.0) and retake["frames_per_drawing"] == pytest.approx(3.0)
assert retake["unmade"] == len(by["NE"]["nearest_at"]) > 0
# on twos at its own length nothing is made; drawn every frame, a replaced frame is no reason to film again
@@ -193,7 +193,7 @@ def test_the_clips_hold_is_read_from_the_strip_and_the_cycle_is_the_fallback(tmp
meta = json.loads((dirs[0] / "walk.strip.json").read_text())
assert meta["drawings"]["hold"] == 2 and meta["drawings"]["drawings_per_second"] == pytest.approx(12.0)
report = align.align_set(dirs, interpolate=_cross_fade, length=24)
- assert [r["drawings"]["source"] for r in report["loops"]] == ["clip", "clip"]
+ assert [r["drawings"]["source"] for r in report["loops"]] == ["span", "span"] # the cut's own steps, over the clip's
again = json.loads((dirs[0] / "walk.strip.json").read_text())
assert again["drawings"] == meta["drawings"] # an alignment keeps the clip's record for the next one
for d in dirs:
@@ -206,6 +206,71 @@ def test_the_clips_hold_is_read_from_the_strip_and_the_cycle_is_the_fallback(tmp
assert row["retake"]["reason"] == "held-drawings" and row["retake"]["source"] == "cycle"
+def _partly_held(frames: int, held_frames: int, *, held_first: bool, cycle: int = 16) -> list[Image.Image]:
+ """A clip on twos for `held_frames` frames (its first, or its last) and drawn every frame for the rest."""
+ def held_at(k: int) -> bool:
+ return k < held_frames if held_first else k >= frames - held_frames
+ return [_walker(2 * math.pi * (k - k % 2) / cycle, redraw=6 * (k % 2)) if held_at(k) else _walker(2 * math.pi * k / cycle)
+ for k in range(frames)]
+
+
+def _cut_at(tmp_path: Path, name: str, frames: list[Image.Image], start: int, length: int) -> Path:
+ keyed = _keyed(tmp_path, name, frames)
+ out = tmp_path / name
+ loop_mod.run_loop(keyed, out, fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=1000.0,
+ name="walk", report_path=None, cycle_mode="fixed", start=start, length=length, anchor="none", repair="off")
+ return out
+
+
[email protected]("held_frames, start, clip_hold, cut_hold, named", [
+ (48, 56, 2, 1, False), # held for most of the clip, the cut every frame: the clip reads as held, the cut is not
+ (24, 4, 1, 2, True), # every frame for most of the clip, the cut held: the clip reads as drawn every frame, the cut is held
+])
+def test_a_clip_held_for_part_of_its_length_is_read_where_it_was_cut(tmp_path, held_frames, start, clip_hold, cut_hold, named):
+ """A cycle of 16 cut out of an 88-frame clip on twos for its first `held_frames` frames, stretched to
+ 24. Whether it is filmed again follows the cut: the clip's reading, over both kinds, would name a
+ cycle drawn every frame and pass a held one."""
+ d = _cut_at(tmp_path, "NE", _partly_held(88, held_frames, held_first=True), start, 16)
+ meta = json.loads((d / "walk.strip.json").read_text())
+ assert meta["drawings"]["hold"] == clip_hold # the clip's reading is kept as it was
+ assert meta["cycle_drawings"]["hold"] == cut_hold and (meta["cycle_drawings"]["start"], meta["cycle_drawings"]["length"]) == (start, 16)
+ report = align.align_set([d, _cut(tmp_path, "S", 24, 1)], interpolate=_cross_fade, length=24)
+ row = next(r for r in report["loops"] if Path(r["dir"]).name == "NE")
+ assert row["drawings"]["source"] == "span" and row["drawings"]["hold"] == cut_hold and row["drawings"]["clip"]["hold"] == clip_hold
+ assert row["drawings"]["drawings"] == (8 if cut_hold == 2 else 16)
+ if named:
+ assert row["retake"]["reason"] == "held-drawings" and row["retake"]["source"] == "span"
+ assert row["retake"]["drawings"] == 8 and row["retake"]["drawings_per_second"] == pytest.approx(8.0)
+ else:
+ assert row["retake"] is None and report["retake"] == []
+
+
+def test_the_cut_is_read_on_the_clips_steps_into_the_frame_after_it():
+ """On twos from frame 1, a cut that starts mid-pair: its 16 steps in the clip, the last into the frame
+ after the cut, hold 8 drawings. A cut that ends the clip reads one step fewer."""
+ feats = np.stack([loop_mod._small_features(f) for f in [_walker(0.0)] + _clip(16, 40, 2)])
+ steps = [float(v) for v in np.abs(feats[1:] - feats[:-1]).mean(axis=1)]
+ m = held.measure_cycle(steps, start=1, length=16, fps=24.0)
+ assert (m["hold"], m["drawings"], m["frames"], m["steps"]) == (2, 8, 16, 16) and m["drawings_per_second"] == pytest.approx(12.0)
+ end = held.measure_cycle(steps, start=len(steps) + 1 - 16, length=16, fps=24.0)
+ assert end["steps"] == 15 and end["frames"] == 16 and end["hold"] == 2
+
+
+def test_a_cut_too_short_to_read_leaves_the_clips_reading_and_says_so(tmp_path):
+ """A cycle of fewer steps than one window (held.SPAN_MIN_STEPS) is not read on its own: the
+ alignment takes the clip's hold, and the record says why."""
+ short = held.SPAN_MIN_STEPS - 2
+ m = held.measure_cycle([1.0, 0.1] * 20, start=0, length=short, fps=24.0)
+ assert m["hold"] is None and "too few" in m["why"]
+ d = _cut_at(tmp_path, "NE", _clip(short, 72, 2), 0, short)
+ meta = json.loads((d / "walk.strip.json").read_text())
+ assert meta["cycle_drawings"]["hold"] is None and "too few" in meta["cycle_drawings"]["why"]
+ row = align.held_drawings([Image.new("RGBA", (4, 4))] * short, fps=24.0, clip=meta["drawings"], cut=meta["cycle_drawings"])
+ assert row["source"] == "clip" and row["hold"] == 2 and "too few" in row["span_why"]
+ before = align.held_drawings([Image.new("RGBA", (4, 4))] * short, fps=24.0, clip=meta["drawings"])
+ assert before["source"] == "clip" and "cut before" in before["span_why"] # a strip written before the cut's record
+
+
def test_video_cycle_align_warns_and_prints_the_retake_with_exit_zero(tmp_path, capsys, monkeypatch):
dirs = [_cut(tmp_path, "NE", 16, 2), _cut(tmp_path, "S", 24, 1)]
monkeypatch.setattr(align.rife_mod, "Rife", lambda: _Fade())