Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(cycle-align): a clip that shows each drawing for two or three frames is read by its rhythm, and a held loop the set left under 13 drawings a second with frames not made is named for a retake (held-drawings)
Soohong Kimdd901ec05bfa
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex a0b6ff1..cd76902 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -15,6 +15,12 @@ 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 onethat 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/+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+bridges, and only a new take fixes it.+The loop directories are `video-loop` output directories. Their first alignment keeps the cutas filmed in `cycle.source/`; every later alignment reads from there, so running it again — orwith another length — never resamples a resampled loop.@@ -50,6 +56,7 @@ from sprite_gen._deps import npfrom sprite_gen.gen import handedness as handed_modfrom sprite_gen.spec.runio import atomic_write_textfrom sprite_gen.util.gif_utils import save_clean_gif+from sprite_gen.video import held as held_modfrom sprite_gen.video import legs as legs_modfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import period as period_mod@@ -85,6 +92,59 @@ SMEAR_WARN = 0.001# shape of fill, or a limb a pale ghost. Outlined legs crossing too far melt at 32 %, a short step# the flow follows stays under 3 % (tests/video/test_rife.py; docs/loop-repair.md section 4).OUTLINE_WARN = 0.05+# A loop whose source holds its drawings (two or three frames each, sprite_gen/video/held.py) and that+# the set's length leaves at fewer than this many drawings a second, with at least UNMADE_MIN of the+# frames between them not made (taken from the nearer source frame, or kept with a fault), is a take+# to film again: the reason `held-drawings` in the report (`retake`). A clip on twos shows 12 a+# second; at that rate or slower, each frame that could not be made holds a drawing a frame longer+# where the legs cross, and the loop halts there. A loop squeezed well past it shows its drawings+# closer than on twos, and is not named (docs/loop-repair.md section 4).+RETAKE_DRAWINGS_MIN = 13.0+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]:+ """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."""+ n = len(frames)+ if clip and clip.get("hold"):+ 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)}+ D = _ring(frames)+ return {"source": "cycle", **held_mod.measure([float(D[k, (k + 1) % n]) for k in range(n)], fps=fps, cyclic=True)}+++def retake(drawings: dict[str, Any], facts: dict[str, Any], *, fps: float) -> dict[str, Any] | None:+ """The reason to film a loop again, with its numbers, or None. `drawings` is the source's+ `held_drawings`, `facts` its `resample` facts: a held source stretched to under+ RETAKE_DRAWINGS_MIN drawings a second, with RETAKE_UNMADE_MIN or more frames between them not made+ — taken from the nearer source frame (`nearest_at`), or made with a fault and kept (`--between rife`)."""+ if not drawings.get("hold") or drawings["hold"] < 2:+ return None+ seconds = facts["to"] / fps+ per_second = drawings["drawings"] / seconds+ unmade = len(facts.get("nearest_at", [])) + sum(1 for m in facts.get("smear", []) if m["method"] == "rife" and m["faults"])+ if per_second >= RETAKE_DRAWINGS_MIN or unmade < RETAKE_UNMADE_MIN:+ return None+ return {"reason": RETAKE_REASON, "hold": drawings["hold"], "source": drawings["source"], "drawings": drawings["drawings"],+ "drawings_per_second_filmed": drawings["drawings_per_second"], "drawings_per_second": round(per_second, 3),+ "frames_per_drawing": round(facts["to"] / drawings["drawings"], 3), "unmade": unmade,+ "limits": {"drawings_per_second_min": RETAKE_DRAWINGS_MIN, "unmade_min": RETAKE_UNMADE_MIN}}+++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 "+ 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 "+ "fixes it; no interpolator draws legs that swap places across a gap this wide (docs/loop-repair.md section 4)")def faults(measure: dict[str, float]) -> list[str]:@@ -568,7 +628,9 @@ 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 excstart = strike["start"]- record = {**facts, "turned_by": start, "turned_on": strike["by"], "view": view, "start_foot": strike["start_foot"],+ drawings = held_drawings(frames, fps=fps, clip=loops[i][2].get("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 {}),"stride_swing": strike["stride_swing"], "reach_swing": strike["reach_swing"],"fps": round(fps, 4), "source": SOURCE_DIR, "cycles_given": given.get(i), "cycle_screen": screens[i],@@ -585,7 +647,10 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:rows.append({"dir": str(d), "name": meta_path.name[: -len(".strip.json")], **{k: v for k, v in record.items() if k not in ("gif", "webp")},"strip": {k: merged[k] for k in ("frames", "w", "h", "body_h", "delay_ms")}})warnings = [_fault_line(r["name"], m) for r in rows for m in r.get("smear", []) if m["faults"]]- warnings = cycle_warnings + warnings+ retakes = [{"dir": r["dir"], "name": r["name"], **r["retake"]} for r in rows if r["retake"]]+ # A loop to film again is named by its directory where two loops share a strip name (each `walk`).+ shared = len({r["name"] for r in rows}) < len(rows)+ warnings = cycle_warnings + [_retake_line(r["dir"] if shared else r["name"], r["retake"]) for r in rows if r["retake"]] + warningsif len(rows) > 1 and views is None:warnings.append("no view given (--view): each loop starts on its larger strike, whichever foot that is")else:@@ -593,7 +658,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:if r["view"] is not None and r["start_foot"] is None]report = {"kind": "sprite-gen-video-cycle-align-report", "applied": True, "length": target,"length_rule": "requested" if length is not None else "median",- "between": between, "start_foot": start_foot, "warnings": warnings,+ "between": between, "start_foot": start_foot, "retake": retakes, "warnings": warnings,"lengths": lengths, "multi_cycle": multi_cycle, "suspects": suspects,"cycles_given": {str(loops[i][0]): k for i, k in given.items()},"fps": round(fps, 4), "cycle_seconds": round(target / fps, 4),@@ -657,7 +722,7 @@ def run(**kwargs: object) -> int:f"`{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)") from excfor line in report["warnings"]:print(f"video-cycle-align: warning: {line}", file=sys.stderr)- print(json.dumps({k: report[k] for k in ("length", "lengths", "cycles_given", "between", "made_by_rife", "replaced", "cycle_seconds")}+ print(json.dumps({k: report[k] for k in ("length", "lengths", "cycles_given", "between", "made_by_rife", "replaced", "retake", "cycle_seconds")}| {"loops": [{k: r[k] for k in ("name", "from", "to", "made_by_rife", "turned_by", "turned_on", "start_foot", "seam_ratio")} for r in report["loops"]]},ensure_ascii=False, indent=2))return 0diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex 88feddb..43c5126 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -701,11 +701,12 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpoout[state] = {"ok": False, "error": str(exc)}continueout[state] = {"ok": True, "applied": True, "length": report["length"], "lengths": report["lengths"], "between": report["between"],- "made_by_rife": report["made_by_rife"], "replaced": report["replaced"], "warnings": report["warnings"], "report": str(root / f"{state}.cycle-align.json")}+ "made_by_rife": report["made_by_rife"], "replaced": report["replaced"], "retake": report["retake"],+ "warnings": report["warnings"], "report": str(root / f"{state}.cycle-align.json")}for line in report["warnings"]:print(f"video-set: warning: {state}: {line}", file=sys.stderr)for r, row in zip(rows, report["loops"]):- r["loop"]["cycle_align"] = {k: row[k] for k in ("from", "to", "made_by_rife", "turned_by", "turned_on", "start_foot", "seam_ratio")}+ r["loop"]["cycle_align"] = {k: row[k] for k in ("from", "to", "made_by_rife", "turned_by", "turned_on", "start_foot", "seam_ratio", "retake")}r["loop"]["n_out"] = row["strip"]["frames"]return outdiff --git a/sprite_gen/video/held.py b/sprite_gen/video/held.pynew file mode 100644index 0000000..0af696f--- /dev/null+++ b/sprite_gen/video/held.py@@ -0,0 +1,104 @@+# SPDX-License-Identifier: Apache-2.0+"""Held drawings: a clip that shows each drawing for two or three frames, and how many it shows a second.++A video model may film a walk at 12 drawings a second inside a 24 fps clip: each drawing is shown+twice ("on twos"), or three times ("on threes"). Played at its own rate such a loop is ordinary+limited animation. Stretched to a longer cycle (`video-cycle-align`), the frames between are made+by an interpolator across a gap two or three times as wide as one frame of an every-frame clip, and+where the legs swap places in that gap no interpolator can draw them (docs/loop-repair.md section 4).++The second frame of a pair is rarely a byte copy: the model redraws it a little, so its step from+the first is small but not zero. A rule that calls a step held when it falls under a fraction of the+median step fails exactly there: with half the steps held, the median falls between the held and+the moving steps, and a fraction of it is smaller than many of the held steps. So the judgement+reads the rhythm, not one step at a time: in a clip on twos every second step is small, on threes two+of every three, and a motion filmed every frame has no such rhythm — its steps swell and shrink+with the stride, a dozen frames or more, never every second or third frame.++`measure` reads it off the steps between neighbouring frames (the distance `video-loop` cuts by):+for a hold h of 2 or 3, in windows of WINDOW steps, the phase whose every h-th step is the change+and the rest are held, scored by `contrast` — the held steps over the change steps (their medians:+a frame repeated now and then, as a 20 fps clip carried at 24 repeats one in six, moves a median+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.+"""++from __future__ import annotations++import math+from collections.abc import Sequence+from typing import Any++from sprite_gen._deps import np++HOLDS = (2, 3) # frames a drawing is shown for: on twos, on threes+WINDOW = 12 # steps per window: six drawings on twos, four on threes; a phase that slips spoils a window or two, not the clip+# The held steps over the change steps (medians) under which a hold is the clip's. A pair+# redrawn a little sits at a quarter of a change step or below, a byte copy near zero; a motion filmed+# 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+++def _contrast(steps: np.ndarray, hold: int) -> tuple[float, list[np.ndarray], list[np.ndarray]] | None:+ """(the median over windows of the best phase's contrast, the held steps and the change steps of+ each window's best phase), or None when no window has a step of each kind that moves."""+ n = len(steps)+ spans = [(0, n)] if n < 2 * WINDOW else [(a, a + WINDOW) for a in range(0, n - WINDOW + 1, WINDOW // 2)]+ if spans[-1][1] < n:+ spans.append((n - WINDOW, n))+ scores, held, change = [], [], []+ for a, b in spans:+ idx = np.arange(b - a)+ best = None+ for phase in range(hold):+ is_change = idx % hold == phase+ if not is_change.any() or is_change.all():+ continue+ top = float(np.median(steps[a:b][is_change]))+ if top <= 0:+ continue+ score = float(np.median(steps[a:b][~is_change])) / top+ if best is None or score < best[0]:+ best = (score, steps[a:b][~is_change], steps[a:b][is_change])+ if best is not None:+ scores.append(best[0])+ held.append(best[1])+ change.append(best[2])+ if not scores:+ return None+ return float(np.median(scores)), held, change+++def measure(steps: Sequence[float], *, fps: float, cyclic: 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."""+ s = np.asarray(steps, dtype=np.float64)+ frames = len(s) if cyclic 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": {}}+ if len(inner) < MIN_STEPS or float(inner.max(initial=0.0)) <= 0:+ why = "no motion between frames" if len(inner) >= MIN_STEPS else f"{len(inner)} steps, under {MIN_STEPS}: too few to read a rhythm"+ return {**base, "hold": None, "held_steps": None, "drawings": None, "drawings_per_second": None, "why": why}+ found = {h: _contrast(inner, h) for h in HOLDS}+ base["contrast"] = {str(h): (round(f[0], 4) if f else None) for h, f in found.items()}+ scored = [(f[0], h) for h, f in found.items() if f is not None and f[0] < CONTRAST_MAX]+ if not scored:+ return {**base, "hold": 1, "held_steps": 0, "drawings": frames, "drawings_per_second": round(frames / seconds, 3)}+ _, hold = min(scored)+ _, held, change = found[hold] # type: ignore[misc]+ # The boundary is the geometric midpoint of the two kinds' plain means: a byte copy (step 0) beside+ # a redrawn repeat would drag a geometric mean of the held steps under the redrawn ones.+ change_mean = float(np.concatenate(change).mean())+ 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+ return {**base, "hold": hold, "held_steps": held_steps, "drawings": drawings,+ "drawings_per_second": round(drawings / seconds, 3), "held_below": round(mid, 6)}diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 787a30b..6720d24 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -49,6 +49,7 @@ from sprite_gen.spec.runio import atomic_write_textfrom sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.util.resample import resize_cellfrom sprite_gen.video import motion_anchor, auto_motion, local_cycle, gait_fallback+from sprite_gen.video import held as held_modfrom sprite_gen.video import legs as legs_modfrom sprite_gen.video import period as period_modfrom sprite_gen.video import repair as repair_mod@@ -922,6 +923,10 @@ def run_loop("seam_max": seam_max,"anchor": anchor,"seam_measurement": "rendered-cells" if anchor in ("motion", "motion-auto") else "source-frames",+ # 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),}cycle = Nonetry:@@ -1113,6 +1118,9 @@ 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).+ strip_meta["drawings"] = {k: report_base["drawings"][k] for k in ("hold", "drawings_per_second", "contrast", "frames")}if motion is not None:strip_meta["foot_anchor"] = anchorstrip_meta["motion_anchor"] = motion@@ -1255,6 +1263,7 @@ def run(**kwargs: object) -> int:)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", "review_recommended", "half_period_guard", "fundamental")}+ summary["drawings"] = {k: payload["drawings"][k] for k in ("hold", "drawings_per_second")}if payload["periodic_attempt"]:summary["periodic_attempt"] = payload["periodic_attempt"]["why_rejected"]if payload.get("motion_anchor", {}).get("applied") is False:diff --git a/tests/video/test_held_drawings.py b/tests/video/test_held_drawings.pynew file mode 100644index 0000000..11afac9--- /dev/null+++ b/tests/video/test_held_drawings.py@@ -0,0 +1,238 @@+# SPDX-License-Identifier: Apache-2.0+"""Held drawings (docs/loop-repair.md section 4, sprite_gen/video/held.py): a clip that shows each+drawing for two or three frames is told from one drawn every frame by the rhythm of its steps, the+second frame of each pair redrawn a little as a video model does; `video-loop` records how many+drawings the clip shows a second, and `video-cycle-align` names a held loop it stretched past what an+interpolator bridges as a take to film again (`retake`, reason `held-drawings`).++Synthetic figures only: a body and a dark foot going round, as in test_cycle_align."""++from __future__ import annotations++import json+import math+from pathlib import Path++import numpy as np+import pytest+from PIL import Image++from sprite_gen.video import align, held+from sprite_gen.video import loop as loop_mod++W, H = 100, 120+++def _walker(phase: float, *, redraw: int = 0) -> Image.Image:+ """A body that bobs with the phase and a dark foot going round; `redraw` shifts the body's colour+ a little, as a model redraws the second frame of a pair."""+ a = np.zeros((H, W, 4), dtype=np.uint8)+ bob = round(4 * (1 + math.cos(2 * phase)) / 2)+ a[20 + bob:90, 40:60] = (90 + redraw, 90 + redraw, 200 + redraw, 255)+ fx, fy = 50 + round(20 * math.cos(phase)), 104 + round(8 * math.sin(phase))+ a[fy - 5:fy + 5, fx - 5:fx + 5] = (60, 60, 60, 255)+ return Image.fromarray(a, "RGBA")+++def _clip(cycle: int, frames: int, hold: int, *, redraw: int = 6) -> list[Image.Image]:+ """`frames` frames of a walk whose cycle is `cycle` frames, each drawing shown `hold` times — each+ repeat redrawn a little (`redraw` per repeat), never a byte copy."""+ return [_walker(2 * math.pi * (k - k % hold) / cycle, redraw=redraw * (k % hold)) for k in range(frames)]+++def _uneven(cycle: int, frames: int) -> list[Image.Image]:+ """Drawn every frame, but the steps alternate long and short (0.6 of each other): uneven timing, not a hold."""+ t, times = 0.0, []+ for k in range(frames):+ times.append(t)+ t += (1.25 if k % 2 == 0 else 0.75)+ return [_walker(2 * math.pi * x / cycle) for x in times]+++def _steps(frames: list[Image.Image]) -> list[float]:+ feats = np.stack([loop_mod._small_features(f) for f in frames])+ return [float(v) for v in np.abs(feats[1:] - feats[:-1]).mean(axis=1)]++[email protected]("hold, per_second", [(1, 24.0), (2, 12.0), (3, 8.0)])+def test_the_hold_and_the_drawings_a_second_are_read_off_the_rhythm(hold, per_second):+ m = held.measure(_steps(_clip(24, 72, hold)), fps=24.0)+ assert m["hold"] == hold and m["frames"] == 72+ assert m["drawings_per_second"] == pytest.approx(per_second, abs=0.5)+ if hold > 1:+ assert m["contrast"][str(hold)] < held.CONTRAST_MAX+++def test_a_pair_redrawn_a_little_is_missed_by_a_fraction_of_the_median_step_but_not_by_the_rhythm():+ """The rule this replaces: a step under a quarter of the median is held. With half the steps held+ the median falls between the two kinds, and a redrawn pair's step is above a quarter of it."""+ s = np.array(_steps(_clip(15, 73, 2, redraw=10)))+ assert (s < 0.25 * np.median(s)).sum() < 0.35 * len(s) # the old rule: not a paired clip+ m = held.measure(s, fps=24.0)+ assert m["hold"] == 2 and m["held_steps"] == 36 and m["drawings_per_second"] == pytest.approx(12.0, abs=0.5)+++def test_steps_that_alternate_long_and_short_are_not_a_hold():+ m = held.measure(_steps(_uneven(24, 72)), fps=24.0)+ assert m["hold"] == 1 and m["drawings"] == 72+ assert min(v for v in m["contrast"].values()) > held.CONTRAST_MAX+++def test_a_frame_repeated_now_and_then_is_not_a_hold():+ """A 20 fps clip carried at 24: one frame in six shown again (redrawn a little), the rest every frame."""+ times = [k - k // 6 for k in range(72)] # 0 1 2 3 4 5 5 6 7 8 9 10 10 ...+ frames = [_walker(2 * math.pi * x / 20, redraw=6 if k and times[k] == times[k - 1] else 0) for k, x in enumerate(times)]+ m = held.measure(_steps(frames), fps=24.0)+ assert m["hold"] == 1 and min(m["contrast"].values()) > held.CONTRAST_MAX+++def test_a_ring_counts_its_drawings_and_too_few_steps_say_nothing():+ ring = _clip(16, 16, 2)+ feats = np.stack([loop_mod._small_features(f) for f in ring])+ steps = [float(np.abs(feats[(k + 1) % 16] - feats[k]).mean()) for k in range(16)]+ m = held.measure(steps, fps=24.0, cyclic=True)+ assert m["hold"] == 2 and m["drawings"] == 8 and m["frames"] == 16 and m["drawings_per_second"] == pytest.approx(12.0)+ short = held.measure(steps[:4], fps=24.0)+ assert short["hold"] is None and "too few" in short["why"]+ still = held.measure([0.0] * 10, fps=24.0)+ assert still["hold"] is None and still["why"] == "no motion between frames"+++def _keyed(tmp_path: Path, name: str, frames: list[Image.Image]) -> Path:+ keyed = tmp_path / f"{name}-keyed"+ keyed.mkdir(parents=True)+ for k, f in enumerate(frames):+ f.save(keyed / f"{k:04d}.png")+ return keyed+++def _cut(tmp_path: Path, name: str, cycle: int, hold: int) -> Path:+ """A loop of one `cycle`-frame cycle cut out of a clip drawn with `hold`."""+ keyed = _keyed(tmp_path, name, _clip(cycle, cycle + 8, hold))+ 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=0, length=cycle, anchor="none", repair="off")+ return out++[email protected]("hold, per_second", [(1, 24.0), (2, 12.0), (3, 8.0)])+def test_video_loop_records_the_clips_drawings_a_second(tmp_path, hold, per_second):+ d = _cut(tmp_path, "S", 24, hold)+ report = json.loads((d / "walk.loop.report.json").read_text())+ assert report["drawings"]["hold"] == hold+ assert report["drawings"]["drawings_per_second"] == pytest.approx(per_second, abs=0.7)+ meta = json.loads((d / "walk.strip.json").read_text())+ assert meta["drawings"] == {k: report["drawings"][k] for k in ("hold", "drawings_per_second", "contrast", "frames")}+++def _cross_fade(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ """An interpolator that cannot follow the motion: two half-covered ghosts, the outline lost."""+ return Image.blend(a, b, t)+++def _follows(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ return a.copy() # a frame the interpolator drew whole, outlined as its neighbours+++def test_a_held_loop_stretched_past_what_an_interpolator_bridges_is_named_for_a_retake(tmp_path, capsys):+ """A cycle of 16 frames on twos (8 drawings) stretched to 24: 8 drawings a second, three frames+ apart, and the frames between them melt — a take to film again. The set is still aligned."""+ dirs = [_cut(tmp_path, "NE", 16, 2), _cut(tmp_path, "SW", 24, 2), _cut(tmp_path, "E", 26, 1)]+ report = align.align_set(dirs, interpolate=_cross_fade, length=24, report_path=tmp_path / "align.json")+ assert report["applied"] is True and report["replaced"] > 0+ 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["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+ assert by["SW"]["retake"] is None and by["SW"]["made_by_rife"] == 0+ assert by["E"]["retake"] is None and len(by["E"]["nearest_at"]) > 0+ assert [(r["name"], r["reason"]) for r in report["retake"]] == [("walk", "held-drawings")]+ assert Path(report["retake"][0]["dir"]) == dirs[0]+ lines = [w for w in report["warnings"] if "film this direction again (held-drawings)" in w]+ assert len(lines) == 1 and "8 drawings a second" in lines[0] and lines[0].startswith(f"{dirs[0]}: ") # every strip is `walk`+ written = json.loads((tmp_path / "align.json").read_text())+ assert written["retake"] == report["retake"]+ meta = json.loads((dirs[0] / "walk.strip.json").read_text())+ assert meta["cycle_align"]["retake"]["reason"] == "held-drawings"+++def test_a_held_loop_whose_frames_between_are_all_made_is_not_named(tmp_path):+ dirs = [_cut(tmp_path, "NE", 16, 2), _cut(tmp_path, "S", 24, 1)]+ report = align.align_set(dirs, interpolate=_follows, length=24)+ assert report["retake"] == [] and report["replaced"] == 0+ assert not any("film this direction again" in w for w in report["warnings"])+++def test_between_nearest_and_rife_name_the_frames_not_made(tmp_path):+ """nearest makes no frame, so every one between drawings is taken; rife keeps a melted frame, a fault."""+ nearest = align.align_set([_cut(tmp_path / "n", "NE", 16, 2), _cut(tmp_path / "n", "S", 24, 1)], length=24, between="nearest")+ row = next(r for r in nearest["loops"] if Path(r["dir"]).name == "NE")+ assert [r["reason"] for r in nearest["retake"]] == ["held-drawings"] and nearest["retake"][0]["unmade"] == len(row["nearest_at"]) == 16+ kept = align.align_set([_cut(tmp_path / "r", "NE", 16, 2), _cut(tmp_path / "r", "S", 24, 1)], length=24,+ interpolate=_cross_fade, between="rife")+ assert kept["replaced"] == 0 and kept["retake"] and kept["retake"][0]["unmade"] > 0+++def test_a_held_loop_squeezed_past_on_twos_is_not_named(tmp_path):+ """On twos, 32 frames to 24: sixteen drawings in a second, closer than on twos (12) and above+ RETAKE_DRAWINGS_MIN, so a melted frame there is no reason to film it again."""+ dirs = [_cut(tmp_path, "A", 32, 2), _cut(tmp_path, "B", 24, 1)]+ report = align.align_set(dirs, interpolate=_cross_fade, length=24, cycles={"A": 1}) # the bob reads as two cycles+ row = next(r for r in report["loops"] if Path(r["dir"]).name == "A")+ assert row["drawings"]["hold"] == 2 and row["drawings"]["drawings"] == pytest.approx(16, abs=0.5)+ assert len(row["nearest_at"]) > 0 and row["retake"] is None+++def test_the_clips_hold_is_read_from_the_strip_and_the_cycle_is_the_fallback(tmp_path):+ """`video-loop` writes the clip's hold into the strip metadata, and the alignment reads it there; a+ loop cut before that record is measured on its own cycle, read as a ring."""+ dirs = [_cut(tmp_path, "NE", 16, 2), _cut(tmp_path, "S", 24, 1)]+ 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"]+ 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:+ m = json.loads((d / "walk.strip.json").read_text())+ del m["drawings"]+ (d / "walk.strip.json").write_text(json.dumps(m))+ old = align.align_set(dirs, interpolate=_cross_fade, length=24)+ row = next(r for r in old["loops"] if Path(r["dir"]).name == "NE")+ assert row["drawings"]["source"] == "cycle" and row["drawings"]["hold"] == 2 and row["drawings"]["drawings"] == 8+ assert row["retake"]["reason"] == "held-drawings" and row["retake"]["source"] == "cycle"+++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())+ assert align.run(loop_dir=dirs, length=24, report=tmp_path / "align.json") == 0+ captured = capsys.readouterr()+ assert f"video-cycle-align: warning: {dirs[0]}: film this direction again (held-drawings)" in captured.err+ assert json.loads(captured.out)["retake"][0]["reason"] == "held-drawings"+++class _Fade:+ def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ return _cross_fade(a, b, t)++ def describe(self) -> dict[str, str]:+ return {"binary": "stand-in"}+++def test_video_set_carries_the_retake_into_its_record(tmp_path):+ from sprite_gen.video import batch++ rows = []+ for direction, cycle, hold in (("back", 16, 2), ("side", 24, 1)):+ item = tmp_path / f"{direction}-walk"+ item.mkdir()+ _cut(item, "loop", cycle, hold)+ rows.append({"item": f"{direction}-walk", "direction": direction, "state": "walk", "dir": str(item), "ok": True,+ "loop": {"n_out": cycle}})+ out = batch.align_gaits(rows, tmp_path, "auto", interpolate=_cross_fade)+ assert out["walk"]["applied"] and [r["reason"] for r in out["walk"]["retake"]] == ["held-drawings"]+ assert rows[0]["loop"]["cycle_align"]["retake"]["reason"] == "held-drawings" and rows[1]["loop"]["cycle_align"]["retake"] is None