Skip to content

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.py
index 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 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/
+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 cut
as filmed in `cycle.source/`; every later alignment reads from there, so running it again — or
with another length — never resamples a resampled loop.
@@ -50,6 +56,7 @@ from sprite_gen._deps import np
from sprite_gen.gen import handedness as handed_mod
from sprite_gen.spec.runio import atomic_write_text
from sprite_gen.util.gif_utils import save_clean_gif
+from sprite_gen.video import held as held_mod
from sprite_gen.video import legs as legs_mod
from sprite_gen.video import loop as loop_mod
from 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 exc
start = 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"]] + warnings
if 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 exc
for 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 0
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 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, *, interpo
out[state] = {"ok": False, "error": str(exc)}
continue
out[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 out
diff --git a/sprite_gen/video/held.py b/sprite_gen/video/held.py
new file mode 100644
index 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.py
index 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_text
from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.util.resample import resize_cell
from sprite_gen.video import motion_anchor, auto_motion, local_cycle, gait_fallback
+from sprite_gen.video import held as held_mod
from sprite_gen.video import legs as legs_mod
from sprite_gen.video import period as period_mod
from 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 = None
try:
@@ -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"] = anchor
strip_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.py
new file mode 100644
index 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