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 set with a loop that may hold two cycles stops until --cycles counts it; video-loop records the shorter repeat and cuts as 2.25

Soohong Kim7b411d8205a7
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index 5300f08..e16cb88 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -18,6 +18,17 @@ The loop directories are `video-loop` output directories. Their first alignment
as filmed in `cycle.source/`; every later alignment reads from there, so running it again — or
with another length — never resamples a resampled loop.
+Resampling to one length assumes every loop holds one cycle. A loop that holds two (a cut that
+took two strides as one) would come out walking twice as fast as the rest, and pixels cannot tell
+it from a loop of one stride whose two steps look alike. So each loop is screened first
+(`cycle_screen`, sprite_gen/video/period.py): a half or a third of it that returns to a pose on
+the motion's path makes it a suspect. A set with a suspect is stopped before anything is rewritten
+(`--multi-cycle warn` aligns it as it is and says so), the report naming each suspect
+(`suspects`). The count comes back from whoever looked: `--cycles <loop>=1` aligns that loop as
+it is, `--cycles <loop>=k` takes one cycle — a k-th of it, from the start whose frame one cycle on
+is the most like it — out of the loop as filmed (`take_cycle`) and aligns that. Nothing changes the
+number of cycles in a loop but `--cycles`.
+
A set that needs a made frame where no RIFE is installed raises `rife.RifeNotInstalled` with
nothing rewritten: this command fails on it, `video-set` skips the alignment with a warning.
"""
@@ -38,20 +49,18 @@ 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 legs as legs_mod
from sprite_gen.video import loop as loop_mod
+from sprite_gen.video import period as period_mod
from sprite_gen.video import rife as rife_mod
SNAP = 0.03 # a sample time within this of a source frame takes that frame
SOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop again
RATE_TOLERANCE = 0.002 # frame rates read back from the strip metadata agree within this
-LOW_ALPHA = 128 # the foot-strike turn reads solid pixels only
-# The foot-strike turn (docs/loop-repair.md section 4). A walk seen from the side or a diagonal opens
-# its feet by a good part of its height each step; from the front or back its foot band hardly
-# changes width, but the foot nearer the viewer is drawn lower by a few hundredths of it. With a
-# view the view picks the signal and these only say whether there are legs to read (`foot_strike`).
-STRIDE_MIN = 0.15 # the foot band's swing (of the body's height) that says the feet open along the picture
-REACH_MIN = 0.015 # the lowest row's swing (of the body's height) that says a foot steps toward the viewer
-BODY_RUN = 0.5 # the body's top line: the first row at least half as wide as the frame's widest
+# The foot-strike turn (docs/loop-repair.md section 4) reads the legs as the two-cycle screen
+# records them (sprite_gen/video/legs.py). With a view the view picks the signal and the swings only
+# say whether there are legs to read (`foot_strike`).
+LOW_ALPHA, STRIDE_MIN, REACH_MIN, BODY_RUN = legs_mod.LOW_ALPHA, legs_mod.STRIDE_MIN, legs_mod.REACH_MIN, legs_mod.BODY_RUN
START_FOOT = "right" # every loop of a set starts as this own foot lands, where its view can tell
SHADE_BAND = 0.15 # the shade cue reads the feet and lower legs: the lowest 15 % of the body
# The two strikes must differ by this to name a foot (`strike_foot`): shade in luma (0..1), depth in
@@ -62,6 +71,10 @@ FOOT_MARGIN = 0.01
# harmonic) must be at least this share of its spread over the cycle.
CUE_RHYTHM = 0.25
BETWEEN = ("rife", "nearest") # how a time between two source frames is filled (resample)
+# A set with a loop the two-cycle screen suspects and no --cycles for it: fail (default) stops the
+# set before anything is rewritten, warn aligns it as it is and names the loop in the warnings.
+MULTI_CYCLE = ("fail", "warn")
+CYCLES = (1, 2, 3) # what --cycles <loop>=k may say a loop holds
# A made frame whose dark pixels inside the body exceed both neighbours' by this fraction of its
# solid pixels is named in the report's warnings: a smear, not a dark part that moved.
SMEAR_WARN = 0.001
@@ -110,37 +123,7 @@ def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Inter
return out, facts
-def _longest_runs(solid: np.ndarray) -> np.ndarray:
- """The longest horizontal run of solid pixels in each row."""
- edges = np.diff(np.pad(solid.astype(np.int8), ((0, 0), (1, 1))), axis=1)
- runs = np.zeros(solid.shape[0], dtype=int)
- for y in np.nonzero(solid.any(axis=1))[0]:
- starts, ends = np.nonzero(edges[y] == 1)[0], np.nonzero(edges[y] == -1)[0]
- runs[y] = int((ends - starts).max())
- return runs
-
-
-def strike_signals(frames: list[Image.Image]) -> dict[str, list[float]]:
- """Per frame, from the solid pixels: `stride`, the width of the foot band (the lowest FOOT_BAND
- of the frame's own height) as a fraction of that height; `reach`, the lowest solid row; `top`,
- the body's top line — the first row whose longest solid run is at least BODY_RUN of the
- frame's widest, so an ear, a hat's point or an antenna (a narrow run) is passed over."""
- out: dict[str, list[float]] = {"stride": [], "reach": [], "top": [], "height": []}
- for f in frames:
- solid = np.asarray(f.getchannel("A")) >= LOW_ALPHA
- rows = np.nonzero(solid.any(axis=1))[0]
- if rows.size == 0:
- raise ValueError("a loop frame has no solid body")
- y0, y1 = int(rows[0]), int(rows[-1])
- height = y1 - y0 + 1
- band = solid[y1 + 1 - max(1, round(height * loop_mod.FOOT_BAND)) : y1 + 1]
- xs = np.nonzero(band.any(axis=0))[0]
- runs = _longest_runs(solid)
- out["stride"].append((xs[-1] - xs[0] + 1) / height)
- out["reach"].append(float(y1))
- out["top"].append(float(np.nonzero(runs >= BODY_RUN * runs.max())[0][0]))
- out["height"].append(float(height))
- return out
+strike_signals = legs_mod.strike_signals
def _feet(frame: Image.Image) -> tuple[np.ndarray, np.ndarray, int]:
@@ -149,7 +132,7 @@ def _feet(frame: Image.Image) -> tuple[np.ndarray, np.ndarray, int]:
solid = np.asarray(frame.getchannel("A")) >= LOW_ALPHA
rows = np.nonzero(solid.any(axis=1))[0]
y1, height = int(rows[-1]), int(rows[-1] - rows[0] + 1)
- xs = np.nonzero(solid[y1 + 1 - max(1, round(height * loop_mod.FOOT_BAND)) : y1 + 1].any(axis=0))[0]
+ xs = np.nonzero(solid[y1 + 1 - max(1, round(height * legs_mod.FOOT_BAND)) : y1 + 1].any(axis=0))[0]
return solid, np.arange(solid.shape[1]) >= (xs[0] + xs[-1]) / 2, height
@@ -247,10 +230,8 @@ def foot_strike(frames: list[Image.Image], *, view: str | None = None, foot: str
if foot not in handed_mod.SIDES:
raise ValueError(f"foot must be left or right, not {foot!r}")
sig = strike_signals(frames)
- height = float(np.median(sig["height"]))
- swing = {k: float(max(sig[k]) - min(sig[k])) / (1.0 if k == "stride" else height) for k in ("stride", "reach")}
- least = {"stride": STRIDE_MIN, "reach": REACH_MIN}
- legs = [k for k in least if swing[k] >= least[k]]
+ swing = legs_mod.swings(sig)
+ legs = legs_mod.legs_by(sig)
name, _, facing = (view or "").partition("@")
if view is None:
by = legs[0] if legs else "body_low"
@@ -276,6 +257,97 @@ def foot_strike(frames: list[Image.Image], *, view: str | None = None, foot: str
return {**out, "start": start, "start_foot": foot, "foot": found}
+def _ring(frames: list[Image.Image]) -> np.ndarray:
+ """The distances between every two frames of a loop, on the analysis thumbnail `video-loop` cuts by."""
+ flat = np.stack([loop_mod._small_features(f) for f in frames])
+ return np.stack([np.abs(flat - row).mean(axis=1) for row in flat])
+
+
+def cycle_screen(frames: list[Image.Image], *, fps: float, state: str | None = None) -> dict[str, Any]:
+ """Whether a loop may hold two or three cycles (`period.screen`, the loop read as a ring).
+
+ A half or a third of it that is a repeat, no shorter than the state's gait floor (under it two
+ look-alike halves are the two steps of one stride, which the half-period guard owns), and that
+ is not another pose is a suspect. `state` is the loop's motion state (`video-loop` writes it in
+ the strip metadata): without one there is no floor beyond four frames and no steps to record."""
+ n = len(frames)
+ profile = loop_mod.profile_for(state)
+ floor = round(profile.min_seconds * fps) if profile.gait else 0
+ base = {"state": state, "gait_floor": floor or None}
+ if n < 8: # no half of it is four frames long: nothing shorter could be a cycle
+ return {**base, "period": n, "legs": {"by": None, "why": "too short to halve"}, "checked": [], "suspects": []}
+ D = _ring(frames)
+ ring = np.arange(n)
+ prof = {lag: float(D[ring, (ring + lag) % n].mean()) for lag in range(1, n)}
+ minima = [lag for lag in range(2, n - 1) if prof[lag] <= prof[lag - 1] and prof[lag] <= prof[lag + 1]]
+ return {**base, **period_mod.screen(
+ n, D=D, prof=prof, minima=minima, mean=float(np.mean(list(prof.values()))), lowest=max(4, floor),
+ periodicity_min=loop_mod.PERIODICITY_MIN, signals=loop_mod.leg_signals(frames), gait=profile.gait, cyclic=True,
+ floor_why="the gait floor" if floor >= 4 else "a cycle", fps=fps)}
+
+
+def take_cycle(frames: list[Image.Image], cycles: int) -> tuple[list[Image.Image], dict[str, Any]]:
+ """One cycle out of a loop that holds `cycles`: the run of round(n / cycles) frames, read as a
+ ring, whose frame one cycle on is the most like its first (the earliest on a tie) — so it wraps
+ as the loop played on."""
+ n = len(frames)
+ length = round(n / cycles)
+ if length < 2:
+ raise ValueError(f"{n} frames cannot hold {cycles} cycles")
+ D = _ring(frames)
+ step = float(np.mean([D[k, (k + 1) % n] for k in range(n)]))
+ start = min(range(n), key=lambda k: (float(D[k, (k + length) % n]), k))
+ out = [frames[(start + k) % n] for k in range(length)]
+ inner = float(np.mean([D[(start + k) % n, (start + k + 1) % n] for k in range(length - 1)])) if length > 1 else 0.0
+ seam = float(D[(start + length - 1) % n, start])
+ return out, {"from": n, "cycles": cycles, "start": start, "length": length, "exact": n % cycles == 0,
+ "repeat_over_step": round(float(D[start, (start + length) % n]) / step, 4) if step > 0 else None,
+ "seam_ratio": round(seam / inner, 4) if inner > 0 else None}
+
+
+class CycleSuspects(SystemExit):
+ """A set stopped, nothing rewritten, on loops that may hold more than one cycle. `suspects` is
+ the report's typed list: each loop, its candidates and the arguments that settle it; `command`
+ the alignment to run once they are counted (each `--cycles <loop>=<…>` filled in)."""
+
+ def __init__(self, message: str, suspects: list[dict[str, Any]], command: str = ""):
+ super().__init__(message)
+ self.suspects = suspects
+ self.command = command
+
+
+def _suspect_line(entry: dict[str, Any]) -> str:
+ """One loop's suspects, in words: where it returns, how, and what that would make it."""
+ parts = []
+ for row in entry["candidates"]:
+ evidence = [f"pose {row['pose']:.2f}" if row.get("pose") is not None else None,
+ f"steps {row['steps']:.2f}" if row.get("steps") is not None else None]
+ parts.append(f"{row['cycles']} cycles of {row['period']} frames ({row['seconds']:.3f} s) — {row['why']}"
+ + (f" [{', '.join(e for e in evidence if e)}]" if any(evidence) else ""))
+ return f"{entry['dir']}: may hold " + "; or ".join(parts)
+
+
+def _resolve_cycles(cycles: dict[str, int] | None, loops: list[tuple[Path, Path, dict[str, Any], float]]) -> dict[int, int]:
+ """`--cycles` keys to loop positions: a key names a loop by its directory, its strip's name, its
+ directory's name or — for a directory named `loop` (a video-set item) — its parent's name, and
+ must name exactly one."""
+ out: dict[int, int] = {}
+ for key, k in (cycles or {}).items():
+ if k not in CYCLES:
+ raise SystemExit(f"video-cycle-align: --cycles {key}={k}: a loop holds {', '.join(map(str, CYCLES))} cycles here")
+ path = Path(key).expanduser()
+ hits = [i for i, (d, meta_path, _, _) in enumerate(loops)
+ if (path.exists() and path.resolve() == d)
+ or key in (meta_path.name[: -len(".strip.json")], d.name) or (d.name == "loop" and key == d.parent.name)]
+ hits = sorted(set(hits))
+ if len(hits) != 1:
+ raise SystemExit(f"video-cycle-align: --cycles {key}={k} names {len(hits)} of the --loop-dir given; name one by its directory")
+ if hits[0] in out:
+ raise SystemExit(f"video-cycle-align: --cycles names {loops[hits[0]][0]} twice")
+ out[hits[0]] = k
+ return out
+
+
def _loop_files(loop_dir: Path) -> tuple[Path, dict[str, Any]]:
metas = sorted(loop_dir.glob("*.strip.json"))
if len(metas) != 1:
@@ -350,16 +422,26 @@ def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: list
def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate: rife_mod.Interpolate | None = None,
report_path: Path | None = None, between: str = "rife", views: list[str | None] | None = None,
- start_foot: str = START_FOOT) -> dict[str, Any]:
+ start_foot: str = START_FOOT, multi_cycle: str = "fail", cycles: dict[str, int] | None = None,
+ state: str | None = None) -> dict[str, Any]:
"""Resample every loop of a set to one length (default: the median), turned to a foot strike —
where `views` (one per loop: `front`, `back`, `side@right`, `front_diagonal@left`, …) lets it,
- the strike of the same own foot (`start_foot`) in every loop."""
+ the strike of the same own foot (`start_foot`) in every loop.
+
+ Each loop is screened for two or three cycles first (`cycle_screen`; `state` is the set's motion
+ state, for loops whose strip metadata does not carry one). `cycles` maps a loop (`_resolve_cycles`)
+ to the number of cycles it holds, as someone who looked counted them: 1 aligns it as it is, more
+ takes one cycle out of it (`take_cycle`). A suspect with no count stops the set before anything
+ is rewritten (`multi_cycle` fail: `CycleSuspects`, the report written with `applied` false) or is
+ aligned as it is with a warning (warn)."""
if len(loop_dirs) < 1:
raise SystemExit("video-cycle-align: at least one --loop-dir")
if views is not None and len(views) != len(loop_dirs):
raise SystemExit(f"video-cycle-align: {len(views)} --view for {len(loop_dirs)} --loop-dir; give one per loop, in the same order")
if start_foot not in handed_mod.SIDES:
raise SystemExit(f"video-cycle-align: --start-foot must be left or right, not {start_foot!r}")
+ if multi_cycle not in MULTI_CYCLE:
+ raise SystemExit(f"video-cycle-align: --multi-cycle must be one of {', '.join(MULTI_CYCLE)}, not {multi_cycle!r}")
for v in views or []:
if v is not None:
name, _, facing = v.partition("@")
@@ -384,6 +466,51 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
sources.append(_source_frames(d))
except ValueError as exc:
raise SystemExit(f"video-cycle-align: {exc}") from exc
+ given = _resolve_cycles(cycles, loops)
+ screens = [cycle_screen(frames, fps=fps, state=state or meta.get("state")) for (_, _, meta, _), frames in zip(loops, sources)]
+ suspects: list[dict[str, Any]] = []
+ taken: dict[int, dict[str, Any]] = {}
+ cycle_warnings: list[str] = []
+ for i, ((d, meta_path, _, _), screen) in enumerate(zip(loops, screens)):
+ k = given.get(i)
+ if screen["suspects"]:
+ status = "stopped" if k is None and multi_cycle == "fail" else "warned" if k is None else "counted"
+ suspects.append({"dir": str(d), "name": meta_path.name[: -len(".strip.json")], "length": len(sources[i]),
+ "status": status, "cycles_given": k,
+ "candidates": [{key: row[key] for key in ("period", "seconds", "divisor", "cycles", "periodicity", "pose",
+ "off_path", "distance", "steps", "follow", "why") if key in row}
+ for row in screen["suspects"]],
+ "settle": [f"--cycles {d}={c}" for c in sorted({1, *(row["cycles"] for row in screen["suspects"])})]})
+ if k is not None and k > 1:
+ if not any(row["cycles"] == k for row in screen["suspects"]):
+ cycle_warnings.append(f"{d}: --cycles {k} given, but the screen found no return at 1/{k} of it; "
+ f"one cycle is taken out of it as asked")
+ sources[i], taken[i] = take_cycle(sources[i], k)
+ stopped = [e for e in suspects if e["status"] == "stopped"]
+ if stopped:
+ # The command that settles it, as given plus a count for each stopped loop: K is 1 where it
+ # holds one cycle, or the number it holds (each loop's `settle` lists the choices).
+ rerun = ["sprite-gen video-cycle-align", *(f"--loop-dir {d}" for d, *_ in loops),
+ *(f"--view {v}" for v in (views or []) if v is not None), *([f"--length {length}"] if length is not None else []),
+ *([f"--between {between}"] if between != "rife" else []), *([f"--start-foot {start_foot}"] if start_foot != START_FOOT else []),
+ *([f"--state {state}"] if state else []), *([f"--report {report_path}"] if report_path is not None else []),
+ *(f"--cycles {loops[i][0]}={k}" for i, k in sorted(given.items())),
+ *(f"--cycles {e['dir']}=<{'|'.join(s.rpartition('=')[2] for s in e['settle'])}>" for e in stopped)]
+ command = " ".join(rerun)
+ message = ("video-cycle-align: " + "; ".join(_suspect_line(e) for e in stopped)
+ + ". Stopped before anything was rewritten: pixels cannot tell two cycles from one cycle whose steps look alike. "
+ "Count the cycles in each (look at it, or ask a vision model how often each foot lands), then run, with each count "
+ f"filled in (1: it holds one, aligned as it is; more: one cycle is taken out of it): {command}"
+ " — or add --multi-cycle warn to align the set as it is (docs/loop-repair.md section 4)")
+ if report_path is not None:
+ loop_mod.write_loop_report(report_path.expanduser().resolve(), {
+ "kind": "sprite-gen-video-cycle-align-report", "applied": False, "refused": "cycle-suspects", "why": message, "command": command,
+ "multi_cycle": multi_cycle, "lengths": [len(f) for f in sources], "fps": round(fps, 4), "suspects": suspects,
+ "cycles_given": {str(loops[i][0]): k for i, k in given.items()}})
+ raise CycleSuspects(message, suspects, command)
+ cycle_warnings += [f"{_suspect_line(e)}; aligned as it is (--multi-cycle warn) — at the set's length it plays "
+ f"{max(row['cycles'] for row in e['candidates'])} times as fast as the rest if it does"
+ for e in suspects if e["status"] == "warned"]
lengths = [len(f) for f in sources]
target = length if length is not None else round(statistics.median(lengths))
located: list[dict[str, str]] = []
@@ -398,7 +525,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
# Every loop is resampled before any is rewritten: a loop that cannot be made leaves the set as it was.
aligned = []
- for (d, *_), frames, view in zip(loops, sources, views or [None] * len(loops)):
+ for i, ((d, *_), frames, view) in enumerate(zip(loops, sources, views or [None] * len(loops))):
try:
out, facts = resample(frames, target, lazy, between=between)
strike = foot_strike(out, view=view, foot=start_foot)
@@ -410,7 +537,8 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
record = {**facts, "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,
+ "fps": round(fps, 4), "source": SOURCE_DIR, "cycles_given": given.get(i), "cycle_screen": screens[i],
+ **({"cycle_taken": taken[i]} if i in taken else {}),
"made_at": [(k - start) % target for k in facts["made_at"]]}
if "nearest_at" in facts:
record["nearest_at"] = sorted((k - start) % target for k in facts["nearest_at"])
@@ -425,14 +553,18 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
warnings = [f"{r['name']}: frame {m['at']} (made by RIFE) has {100 * m['dark_excess']:.2f} % more dark pixels inside the body "
f"than either source frame beside it — a smear; see it in cycle/, or align with --between nearest"
for r in rows for m in r.get("smear", []) if m["dark_excess"] > SMEAR_WARN]
+ warnings = cycle_warnings + 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:
warnings += [f"{r['name']}: starts on its larger strike, foot not named — {r['foot_why']}" for r in rows
if r["view"] is not None and r["start_foot"] is None]
- report = {"kind": "sprite-gen-video-cycle-align-report", "length": target, "length_rule": "requested" if length is not None else "median",
+ 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,
- "lengths": lengths, "fps": round(fps, 4), "cycle_seconds": round(target / fps, 4),
+ "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),
"interpolator": ({"kind": "rife-ncnn-vulkan", **located[0]} if located else
{"kind": "injected"} if any(r["made_by_rife"] for r in rows) else None),
"made_by_rife": sum(r["made_by_rife"] for r in rows), "loops": rows}
@@ -449,23 +581,48 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
help="the view of each --loop-dir, in the same order: front, back, or side|front_diagonal|back_diagonal@right|left "
"(the way it faces); with it every loop starts as the same own foot lands (--start-foot)")
parser.add_argument("--start-foot", choices=handed_mod.SIDES, default=START_FOOT, help="the own foot every loop starts on (default right; needs --view)")
+ parser.add_argument("--cycles", action="append", default=[], metavar="LOOP=K",
+ help="how many cycles a loop holds, as counted by whoever looked at it (repeatable; LOOP is its --loop-dir, its "
+ "strip's name or its directory's name): 1 aligns it as it is; 2 or 3 takes one cycle out of it as filmed "
+ "(cycle.source/) and aligns that. Only this changes the number of cycles in a loop")
+ parser.add_argument("--multi-cycle", choices=MULTI_CYCLE, default="fail",
+ help="a loop that may hold two or three cycles (a half or a third of it returns to a pose on the motion's path) "
+ "and has no --cycles: fail (default) stops the set before anything is rewritten, the report naming it under "
+ "`suspects`; warn aligns it as it is and names it in the warnings")
+ parser.add_argument("--state", help="the set's motion state (walk, run), for loops cut before video-loop wrote it in the strip metadata: "
+ "its gait floor is the shortest cycle the screen looks for")
parser.add_argument("--between", choices=BETWEEN, default="rife",
help="a time between two source frames: rife (default) makes that frame, its smear measured per frame in the report; "
"nearest takes the nearer source frame — nothing made, no RIFE needed, the motion up to half a frame off its time")
+def parse_cycles(values: list[str]) -> dict[str, int]:
+ """`--cycles LOOP=K` values as {LOOP: K}."""
+ out: dict[str, int] = {}
+ for v in values:
+ key, sep, k = v.rpartition("=")
+ if not sep or not key or not k.strip().isdigit():
+ raise SystemExit(f"video-cycle-align: --cycles expects LOOP=K (K one of {', '.join(map(str, CYCLES))}), got {v!r}")
+ if key in out:
+ raise SystemExit(f"video-cycle-align: --cycles names {key} twice")
+ out[key] = int(k)
+ return out
+
+
def run(**kwargs: object) -> int:
try:
report = align_set(list(kwargs["loop_dir"]), length=kwargs.get("length"), report_path=kwargs.get("report"), # type: ignore[arg-type]
between=str(kwargs.get("between") or "rife"), views=kwargs.get("view"), # type: ignore[arg-type]
- start_foot=str(kwargs.get("start_foot") or START_FOOT))
+ start_foot=str(kwargs.get("start_foot") or START_FOOT),
+ multi_cycle=str(kwargs.get("multi_cycle") or "fail"), cycles=parse_cycles(list(kwargs.get("cycles") or [])), # type: ignore[arg-type]
+ state=kwargs.get("state")) # type: ignore[arg-type]
except rife_mod.RifeNotInstalled as exc:
# Asked for by name, so no RIFE is a failure, never a quiet skip (video-set skips with a warning).
raise SystemExit(f"video-cycle-align: {exc}; frames between source frames are made by RIFE — "
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", "between", "made_by_rife", "cycle_seconds")}
+ print(json.dumps({k: report[k] for k in ("length", "lengths", "cycles_given", "between", "made_by_rife", "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 c3551af..5617a6d 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -585,6 +585,11 @@ def run_item(
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")
+ if (lp["cycle"].get("fundamental") or {}).get("suspects"):
+ # a half or a third of the cut repeats: it may hold that many cycles (recorded, not cut)
+ result["loop"]["fundamental"] = {"period": lp["cycle"]["fundamental"]["period"],
+ "suspects": [{k: row.get(k) for k in ("period", "cycles", "pose", "steps")}
+ for row in lp["cycle"]["fundamental"]["suspects"]]}
if lp.get("motion_anchor", {}).get("applied") is False:
result["loop"]["motion_anchor"] = lp["motion_anchor"]
if "rife" in (lp.get("jump_repair") or {}):
@@ -659,8 +664,10 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpo
"""One cycle length per gait state across the set's directions (`video-cycle-align`,
docs/loop-repair.md section 4). A state filmed in fewer than two directions has nothing to
match. A failure is recorded under its state and the batch reports it; the loops stay as cut.
- Where a frame is to be made and no RIFE is installed the state is skipped, not failed: each
- loop keeps its own length, the record says why, and a warning line names the install."""
+ Two cases skip the state instead of failing it, each loop keeping its own length, the record
+ saying why (`reason`) and a warning line naming what settles it: a frame is to be made and no
+ RIFE is installed (`rife-not-installed`), or a loop may hold two or three cycles and nobody has
+ counted them (`cycle-suspects`, the loops under `suspects`; `video-cycle-align --cycles`)."""
out: dict[str, Any] = {}
if mode == "off":
return out
@@ -674,14 +681,22 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpo
try:
report = align_mod.align_set([Path(r["dir"]) / "loop" for r in rows], interpolate=interpolate,
report_path=root / f"{state}.cycle-align.json", between=between,
- views=[_align_view(r) for r in rows])
+ views=[_align_view(r) for r in rows], state=state)
except rife_mod.RifeNotInstalled as exc:
- out[state] = {"ok": True, "applied": False, "why": "RIFE not installed — each loop keeps its own length",
+ out[state] = {"ok": True, "applied": False, "reason": "rife-not-installed", "why": "RIFE not installed — each loop keeps its own length",
"rife": str(exc), "install": rife_mod.INSTALL_COMMAND}
print(f"video-set: warning: {state}: cycles not aligned — RIFE is not installed, so each loop keeps its own "
f"length; run `{rife_mod.INSTALL_COMMAND}`, then `sprite-gen video-cycle-align` (docs/loop-repair.md)",
file=sys.stderr)
continue
+ except align_mod.CycleSuspects as exc:
+ names = ", ".join(Path(e["dir"]).parent.name if Path(e["dir"]).name == "loop" else e["name"] for e in exc.suspects if e["status"] == "stopped")
+ out[state] = {"ok": True, "applied": False, "reason": "cycle-suspects",
+ "why": f"{names} may hold more than one cycle — each loop keeps its own length until its cycles are counted",
+ "suspects": exc.suspects, "command": exc.command, "report": str(root / f"{state}.cycle-align.json")}
+ print(f"video-set: warning: {state}: cycles not aligned — {out[state]['why']}; count them and run "
+ f"`sprite-gen video-cycle-align --cycles <loop>=<k>` ({exc}) (docs/loop-repair.md section 4)", file=sys.stderr)
+ continue
except SystemExit as exc:
out[state] = {"ok": False, "error": str(exc)}
continue
@@ -800,9 +815,13 @@ def run_set(
failed = [r["item"] for r in results if not r.get("ok")] + [f"cycle-align:{st}" for st, a in aligned.items() if not a.get("ok")]
# What the set left undone for want of RIFE — never a failure, never silent.
warnings = ([f"{r['item']}: jump frame not repaired — {r['loop']['jump_repair']['why']}" for r in results if r.get("ok") and "jump_repair" in r["loop"]]
- + [f"cycle-align:{st}: not aligned — {a['why']}" for st, a in aligned.items() if a.get("applied") is False])
+ + [f"cycle-align:{st}: not aligned — {a['why']}" for st, a in aligned.items() if a.get("reason") == "rife-not-installed"])
if warnings:
warnings.append(f"install RIFE with `{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)")
+ # What the set left for someone to count — never a failure, never silent.
+ warnings += [f"cycle-align:{st}: not aligned — {a['why']}; count them, then `sprite-gen video-cycle-align --cycles <loop>=<k>` "
+ f"(the loops under `suspects` in {a['report']}, docs/loop-repair.md section 4)"
+ for st, a in aligned.items() if a.get("reason") == "cycle-suspects"]
warnings += [f"cycle-align:{st}: {line}" for st, a in aligned.items() for line in a.get("warnings", [])]
payload = {"kind": "sprite-gen-video-set-report", "root": str(root), "states": states, "facing": facing, "facing_fix": facing_fix, "directions": list(bases), **({"handed": [vars(h) for h in handed]} if handed else {}), "body_height": body_height, "ok": sum(1 for r in results if r.get("ok")), "failed": failed, "warnings": warnings, "items": results, "cycle_align": aligned}
atomic_write_text(root / "set.report.json", json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
diff --git a/sprite_gen/video/legs.py b/sprite_gen/video/legs.py
new file mode 100644
index 0000000..56547fe
--- /dev/null
+++ b/sprite_gen/video/legs.py
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+"""What a walk's legs say, read off the solid pixels of each frame.
+
+Two stages read them. `video-cycle-align` turns each loop to start as a heel lands
+(`align.foot_strike`), and the two-cycle screen (sprite_gen/video/period.py) records how a gait's
+steps fall in a shorter return it found — evidence for whoever looks at it, never what decides.
+Both read the same per-frame signals (`strike_signals`) and choose between them by the same swings
+(`legs_by`):
+
+- `stride`: the width of the foot band (the lowest FOOT_BAND of the frame's own height) as a
+ fraction of that height. Seen from the side or a diagonal the feet open and close once a step.
+- `reach`: the lowest solid row. Seen from the front or back the foot nearer the viewer is drawn
+ lower, once a step.
+- `top`: the body's top line, for a body with no legs to read.
+- `gap`: the widest empty run between the foot band's two ends, of the frame's height — two feet
+ seen apart.
+
+The swing of the stride or the lowest row says there is something to read, not that it is legs:
+a legless body that squashes as it bounces widens its foot band once a cycle, where a walker's
+widens once a step. Counting steps therefore also asks for two feet seen apart (`feet_apart`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from PIL import Image
+
+from sprite_gen._deps import np
+
+FOOT_BAND = 0.08 # fraction of the frame's own height, measured up from its lowest opaque row
+LOW_ALPHA = 128 # the legs are read off solid pixels only
+BODY_RUN = 0.5 # the body's top line: the first row at least half as wide as the frame's widest
+# A walk seen from the side or a diagonal opens its feet by a good part of its height each step;
+# from the front or back its foot band hardly changes width, but the foot nearer the viewer is
+# drawn lower by a few hundredths of it.
+STRIDE_MIN = 0.15 # the foot band's swing (of the body's height) that says the feet open along the picture
+REACH_MIN = 0.015 # the lowest row's swing (of the body's height) that says a foot steps toward the viewer
+# Two feet seen apart: an empty run at least this wide (of the body's height) between the foot
+# band's ends, in at least FEET_APART_SHARE of the frames. A walker's feet part for a good share of
+# each step, from any view; a legless body's foot band is one run.
+FEET_APART = 0.02
+FEET_APART_SHARE = 0.2
+
+
+def _longest_runs(solid: np.ndarray) -> np.ndarray:
+ """The longest horizontal run of solid pixels in each row."""
+ edges = np.diff(np.pad(solid.astype(np.int8), ((0, 0), (1, 1))), axis=1)
+ runs = np.zeros(solid.shape[0], dtype=int)
+ for y in np.nonzero(solid.any(axis=1))[0]:
+ starts, ends = np.nonzero(edges[y] == 1)[0], np.nonzero(edges[y] == -1)[0]
+ runs[y] = int((ends - starts).max())
+ return runs
+
+
+def _widest_gap(cols: np.ndarray) -> int:
+ """The longest run of False between the first and the last True of `cols`."""
+ xs = np.nonzero(cols)[0]
+ inner = ~cols[xs[0] : xs[-1] + 1]
+ if not inner.any():
+ return 0
+ edges = np.diff(np.pad(inner.astype(np.int8), 1))
+ return int((np.nonzero(edges == -1)[0] - np.nonzero(edges == 1)[0]).max())
+
+
+def strike_signals(frames: list[Image.Image]) -> dict[str, list[float]]:
+ """Per frame, from the solid pixels: `stride`, `reach`, `top`, `gap` (see the module) and
+ `height`, the frame's own body height in pixels. `top` passes over an ear, a hat's point or an
+ antenna: the first row whose longest solid run is at least BODY_RUN of the frame's widest."""
+ out: dict[str, list[float]] = {"stride": [], "reach": [], "top": [], "gap": [], "height": []}
+ for f in frames:
+ solid = np.asarray(f.getchannel("A")) >= LOW_ALPHA
+ rows = np.nonzero(solid.any(axis=1))[0]
+ if rows.size == 0:
+ raise ValueError("a loop frame has no solid body")
+ y0, y1 = int(rows[0]), int(rows[-1])
+ height = y1 - y0 + 1
+ cols = solid[y1 + 1 - max(1, round(height * FOOT_BAND)) : y1 + 1].any(axis=0)
+ xs = np.nonzero(cols)[0]
+ runs = _longest_runs(solid)
+ out["stride"].append((xs[-1] - xs[0] + 1) / height)
+ out["reach"].append(float(y1))
+ out["top"].append(float(np.nonzero(runs >= BODY_RUN * runs.max())[0][0]))
+ out["gap"].append(_widest_gap(cols) / height)
+ out["height"].append(float(height))
+ return out
+
+
+def swings(sig: dict[str, list[float]]) -> dict[str, float]:
+ """How far the stride and the lowest row swing over the frames, of the median body height."""
+ height = float(np.median(sig["height"]))
+ return {k: float(max(sig[k]) - min(sig[k])) / (1.0 if k == "stride" else height) for k in ("stride", "reach")}
+
+
+def legs_by(sig: dict[str, list[float]]) -> list[str]:
+ """The signals that swing enough to read legs by, the stride first."""
+ swing = swings(sig)
+ return [k for k, least in (("stride", STRIDE_MIN), ("reach", REACH_MIN)) if swing[k] >= least]
+
+
+def feet_apart(sig: dict[str, list[float]]) -> float:
+ """The share of the frames that show two feet apart (a gap of FEET_APART or more)."""
+ return float(np.mean([g >= FEET_APART for g in sig["gap"]])) if sig["gap"] else 0.0
+
+
+def step_signal(sig: dict[str, list[float]]) -> dict[str, Any]:
+ """The signal a gait's steps are counted on, or why there is none: the stride where it swings
+ by STRIDE_MIN, else the lowest row where it swings by REACH_MIN — the turn's rule without a
+ view — and only where two feet are seen apart."""
+ by = legs_by(sig)
+ apart = feet_apart(sig)
+ record: dict[str, Any] = {"feet_apart": round(apart, 3), **{f"{k}_swing": round(v, 4) for k, v in swings(sig).items()}}
+ if not by:
+ return {**record, "by": None, "why": f"no legs to read: the foot band swings under {STRIDE_MIN} of the body's height "
+ f"and the lowest row under {REACH_MIN}"}
+ if apart < FEET_APART_SHARE:
+ return {**record, "by": None, "why": f"no two feet seen apart ({apart:.0%} of the frames, legs from {FEET_APART_SHARE:.0%})"}
+ return {**record, "by": by[0], "values": [float(v) for v in sig[by[0]]]}
diff --git a/sprite_gen/video/local_cycle.py b/sprite_gen/video/local_cycle.py
index 9656572..ca2bebb 100644
--- a/sprite_gen/video/local_cycle.py
+++ b/sprite_gen/video/local_cycle.py
@@ -4,14 +4,34 @@
A changing cadence can contain a good cycle without one period fitting the
whole clip. Require a local lag minimum, repeat depth, motion context, and the
same two-step duration prior; an isolated matching endpoint is insufficient.
+The local period taken is screened for two or three cycles and the finding
+recorded (`fundamental`, sprite_gen/video/period.py), never cut shorter; the
+legs are read off `signals` (`legs.strike_signals` of the analysed frames).
"""
from __future__ import annotations
import math
from sprite_gen._deps import np
+from sprite_gen.video import period as period_mod
+
+
+def _around(start, length):
+ """The frames whose repeats are compared for a cut at `start`: a quarter of the cut either side."""
+ radius = max(2, length//4)
+ return radius, np.arange(max(0, start-radius), start+radius+1)
+
+
+def _profile(distances, js, radius, lo, hi):
+ n = len(distances)
+ profile = {}
+ for lag in range(max(2, lo//2), hi+2):
+ observed = js[js+lag < n]
+ if len(observed) >= radius+1:
+ profile[lag] = float(distances[observed, observed+lag].mean())
+ return profile
def detect(distances, trajectory, *, min_len, max_len, gait_floor,
- periodicity_min, double_tolerance, double_search, max_fraction=.5):
+ periodicity_min, double_tolerance, double_search, max_fraction=.5, signals=None):
n = len(distances)
# A cycle has to be seen repeating: half the clip by default, more for the gait fallback.
lo, hi = max(6, min_len), min(max_len, int(n*max_fraction))
@@ -21,12 +41,8 @@ def detect(distances, trajectory, *, min_len, max_len, gait_floor,
for length in range(max(lo, gait_floor), hi+1):
radius = max(2, length//4)
for start in range(n-length-radius-1):
- js = np.arange(max(0, start-radius), start+radius+1)
- profile = {}
- for lag in range(max(2, lo//2), hi+2):
- observed = js[js+lag < n]
- if len(observed) >= radius+1:
- profile[lag] = float(distances[observed, observed+lag].mean())
+ _, js = _around(start, length)
+ profile = _profile(distances, js, radius, lo, hi)
minima = [lag for lag in profile if lag-1 in profile and lag+1 in profile
and profile[lag] <= min(profile[lag-1], profile[lag+1]) and lag <= hi]
if not minima:
@@ -77,8 +93,14 @@ def detect(distances, trajectory, *, min_len, max_len, gait_floor,
cutoff = candidates[0]['score']*1.15+1e-8
chosen = min((r for r in candidates if r['score'] <= cutoff),
key=lambda row: (row['start'], row['score'], row['length']))
+ radius, js = _around(chosen['start'], chosen['length'])
+ profile = _profile(distances, js, radius, lo, hi)
+ fundamental = period_mod.screen(
+ chosen['period_local'], D=distances, prof=profile, minima=period_mod.local_minima(profile),
+ mean=float(np.mean(list(profile.values()))), lowest=max(lo, gait_floor), periodicity_min=periodicity_min,
+ signals=signals, gait=True, js=js, floor_why='the gait floor')
return {
- **chosen, 'kind': 'periodic', 'method': 'local-repeat-drift-v1',
+ **chosen, 'fundamental': fundamental, 'kind': 'periodic', 'method': 'local-repeat-drift-v1',
'period_global': None, 'periodicity_min': periodicity_min,
'review_recommended': True, 'candidate_count': len(candidates),
'best_score': candidates[0]['score'], 'equivalent_score_tolerance': .15,
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index db85215..787a30b 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -13,6 +13,13 @@ accidental single-frame seam cannot outrank a coherent repeat. Idle motion is
tiny and not strictly periodic: its window is opened to
most of the clip, where the seam is lowest.
+The deepest repeat can hold two cycles (a clip drawn on twos whose cycle is an odd number of
+frames repeats better two cycles on than one), but nothing here cuts shorter than it on the
+pixels' word: a gait's half step with the legs drawn alike is the same picture as a true cycle
+half a drawing late. The half and the third of the period are screened and recorded
+(`cycle.fundamental`, sprite_gen/video/period.py); `video-cycle-align` stops a set on a loop the
+screen suspects, and only a count given to it (`--cycles`) takes one cycle out of that loop.
+
Everything downstream is measured, never assumed: the seam ratio (wrap distance
over the mean adjacent-frame distance inside the cycle) gates the run, the GIF and
WebP are re-opened and verified (frame count, loop flag, transparent corners,
@@ -42,6 +49,8 @@ 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 legs as legs_mod
+from sprite_gen.video import period as period_mod
from sprite_gen.video import repair as repair_mod
from sprite_gen.video import rife as rife_mod
@@ -83,7 +92,7 @@ GAIT_NEAR_EXACT_STEP_FRACTION = 0.10 # no ambiguity extension when repeat error
ANCHOR_MODES = ("none", "feet", "body", "motion", "motion-auto")
BODY_ANCHOR_BAND = 0.6 # --anchor body reads the wrap offset from the top 60 % of the first frame's box: head and torso, not the legs
BODY_ANCHOR_SEARCH = 24 # px either side searched for the last frame's horizontal offset against the first
-FOOT_BAND = 0.08 # fraction of the frame's own height, measured up from its lowest opaque row
+FOOT_BAND = legs_mod.FOOT_BAND # fraction of the frame's own height, measured up from its lowest opaque row
# Jump-frame repair (docs/loop-repair.md section 2). auto: walk and run loops get a RIFE frame in
# place of each frame that follows a jump, and a loop that needs one where no RIFE is installed is
# cut as filmed with a warning (a walk that cut before RIFE existed still cuts); on: the same, but
@@ -181,6 +190,15 @@ def frame_masses(files: list[Path]) -> np.ndarray:
return np.array([float(np.abs(_load_small(f)).mean()) for f in files], dtype=np.float32)
+def leg_signals(frames: list[Image.Image]) -> dict[str, list[float]] | None:
+ """The legs' per-frame signals for the two-cycle screen's record (`legs.strike_signals`), or
+ None where a frame has no solid body to read them from."""
+ try:
+ return legs_mod.strike_signals(frames)
+ except ValueError:
+ return None
+
+
def distance_matrix(files: list[Path]) -> np.ndarray:
flat = np.stack([_load_small(f) for f in files])
n = len(files)
@@ -210,7 +228,8 @@ def _repeat_context(D: np.ndarray, start: int, length: int, step: float) -> dict
}
-def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int | None = None) -> dict[str, Any]:
+def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int | None = None,
+ signals: dict[str, list[float]] | None = None) -> dict[str, Any]:
"""Global period, then a wrap-compatible start with coherent gait context.
`gait_floor` (frames) turns on the half-period guard: a period below it is one step
@@ -218,7 +237,10 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
(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.
Gait starts balance the wrap step with observed repetition around the cut;
- other states keep their wrap-only ranking."""
+ other states keep their wrap-only ranking. The period taken is then screened for
+ two or three cycles (`fundamental`, `period.screen`; `signals` are the frames'
+ `legs.strike_signals`, for the record): what is found is recorded, nothing is
+ cut shorter."""
n = D.shape[0]
max_len = min(max_len, n - 2)
if min_len < 2 or max_len < min_len:
@@ -293,6 +315,12 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
period = L2
review_recommended = True
periodicity = (profile_mean - prof[period]) / profile_mean if profile_mean > 0 else 0.0
+ # A half or a third of the period that returns to a pose on the motion's path may be the
+ # cycle, or one step of it with the legs alike: recorded, never taken (sprite_gen/video/period.py).
+ fundamental = period_mod.screen(
+ period, D=D, prof=prof, minima=period_mod.local_minima(prof), mean=profile_mean,
+ lowest=max(min_len, gait_floor or 0), periodicity_min=PERIODICITY_MIN, signals=signals, gait=gait_floor is not None,
+ floor_why="the gait floor" if gait_floor is not None and gait_floor >= min_len else "the window")
# Score the last displayed frame -> first frame transition against an ordinary
# playback step. Minimising distance alone rewards a repeated pose (a stall).
# Log distance penalises steps that are too short or too long symmetrically.
@@ -328,6 +356,7 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
best["profile_sample_pairs"] = len(range(0, n - period, 2))
best["period_global"] = period
best["half_period_guard"] = guard
+ best["fundamental"] = fundamental
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]]
@@ -922,7 +951,7 @@ def run_loop(
detect = dict(gait_floor=round(prof.min_seconds*fps), periodicity_min=PERIODICITY_MIN,
double_tolerance=GAIT_DOUBLE_TOL, double_search=GAIT_DOUBLE_SEARCH)
try:
- cycle = local_cycle.detect(D, trajectory, min_len=lo, max_len=hi, **detect)
+ cycle = local_cycle.detect(D, trajectory, min_len=lo, max_len=hi, signals=leg_signals(source_frames), **detect)
except ValueError as first:
# A front or back gait that walked toward the camera, or a slow one: one more
# search, recorded (`gait_fallback`), and only after the first found nothing.
@@ -943,7 +972,7 @@ def run_loop(
try:
cycle = local_cycle.detect(D, trajectory, min_len=lo, max_len=hi_long,
max_fraction=gait_fallback.LONG_CYCLE_FRACTION if max_len is None else .5,
- **detect)
+ signals=leg_signals(source_frames), **detect)
except ValueError as second:
raise ValueError(f"{second} (also with the gait fallback: window [{lo}, {hi_long}], "
f"scale drift {drift['drift']:+.1%}{', undone' if fallback['scale_undone'] else ''})") from first
@@ -957,7 +986,8 @@ def run_loop(
cycle = pinned_cycle(D, seam_max=seam_max)
else:
gait_floor = round(prof.min_seconds * fps) if prof.gait and prof.min_seconds > 0 else None
- cycle = detect_cycle(D, min_len=lo, max_len=hi, gait_floor=gait_floor)
+ cycle = detect_cycle(D, min_len=lo, max_len=hi, gait_floor=gait_floor,
+ signals=leg_signals([Image.open(f).convert("RGBA") for f in files]))
cycle["kind"] = "periodic"
floor = periodicity_floor(n, cycle["period_global"], partial_repeat=prof.action_seconds is not None)
cycle["periodicity_min"] = floor
@@ -1080,6 +1110,9 @@ def run_loop(
standing_src=first_frame_height(files[0]) if body_height is not None else None)
# The scaled-back frames are read for the last time above; the cycle cells keep them.
shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)
+ 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()
if motion is not None:
strip_meta["foot_anchor"] = anchor
strip_meta["motion_anchor"] = motion
@@ -1221,7 +1254,7 @@ def run(**kwargs: object) -> int:
size_hold=str(kwargs.get("size_hold") or "auto"),
)
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")}
+ summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio", "review_recommended", "half_period_guard", "fundamental")}
if payload["periodic_attempt"]:
summary["periodic_attempt"] = payload["periodic_attempt"]["why_rejected"]
if payload.get("motion_anchor", {}).get("applied") is False:
diff --git a/sprite_gen/video/period.py b/sprite_gen/video/period.py
new file mode 100644
index 0000000..e608e48
--- /dev/null
+++ b/sprite_gen/video/period.py
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Two cycles in one loop: a screen that suspects a shorter cycle, never takes or refuses one.
+
+A motion that repeats every P frames also repeats every 2P, and the longer lag can read as the
+better repeat: a clip drawn on twos whose cycle is an odd number of frames shows each cycle half a
+drawing off the one before, so the profile dips deeper two cycles on than one. A loop cut at 2P
+plays clean on its own. Resampled to the length of a set whose other loops hold one cycle
+(`video-cycle-align`), it walks at twice their speed.
+
+Pixels cannot tell that loop from a good one. Half a gait cycle on, the legs are back in place
+with near and far swapped; where the two legs are drawn alike (one colour of trousers, white fur)
+that one step and a true cycle half a drawing late are the same picture. Every rule that took the
+half as a cycle took a gait's half step somewhere (docs/video-pipeline.md, "The fundamental
+period"), and the leg signal fails both ways: a heel kick swings the stride twice a step, a
+diagonal view's two steps open the feet unequally. So nothing here says "this is a cycle", and
+nothing says "this is not one" either: a second cycle drawn a little differently (moved a pixel, a
+few per cent lighter) is, in pixels, off the motion's path just as a step with the legs swapped
+is, so a rule that refused one refused the other. The screen only says whether a loop may hold
+more than one cycle, for someone who can count them to settle.
+
+`screen` looks at a half and a third of a period. A candidate there is the lowest local minimum
+of the lag profile within NEAR frames, no shorter than the floor (under a gait's floor a repeat is
+one step, which the half-period guard owns). It is measured (`measure`: how far the frame one
+candidate on lies off the motion's path, `pose`, and the legs' step signal, `steps` and `follow`,
+sprite_gen/video/legs.py) and judged by one rule, `verdict` — the only place that decides: a
+candidate that repeats (dips `periodicity_min` below the profile's mean) makes the loop a
+**suspect**. It may hold two (or three) cycles, and only someone who counts them — by eye, or a
+vision call — can say; `--cycles <loop>=k` on `video-cycle-align` is how that count comes back.
+The measurements go in the record as the evidence for whoever looks, never into the decision.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from sprite_gen._deps import np
+from sprite_gen.video import legs as legs_mod
+
+# The spans (a, b) around a frame j that a returned frame may lie between: j and a neighbour, or
+# two frames across j. Two frames wide, so a clip that holds each drawing for two frames (a span
+# of one frame is then no span at all) still has a span around every frame.
+SPANS = ((-1, 0), (0, 1), (-2, 0), (-1, 1), (0, 2))
+DIVISORS = (2, 3) # a half and a third of the period: two or three cycles in it
+NEAR = 1.0 # frames either side of period / divisor where the shorter cycle's own minimum may sit
+EXACT = 0.05 # a lag closer than this (in playback steps) returns the same picture: `pose` is 0
+
+
+def _returns(D: np.ndarray, lag: int, js: np.ndarray | None, cyclic: bool) -> tuple[float, float] | None:
+ """(off the path, the lag's own distance), both in playback steps, or None (see `off_path`)."""
+ n = len(D)
+ reach = max(abs(v) for span in SPANS for v in span)
+ if cyclic:
+ js = np.arange(n) if js is None else np.asarray(js)
+ at = lambda v: v % n # noqa: E731
+ else:
+ every = np.arange(reach, n - lag) if js is None else np.asarray(js)
+ js = every[(every >= reach) & (every + lag < n)]
+ at = lambda v: v # noqa: E731
+ if js.size == 0:
+ return None
+ x = at(js + lag)
+ extra = np.minimum.reduce([D[at(js + a), x] + D[x, at(js + b)] - D[at(js + a), at(js + b)] for a, b in SPANS])
+ step = float(D[js, at(js + 1)].mean())
+ return (float(extra.mean()) / step, float(D[js, x].mean()) / step) if step > 0 else None
+
+
+def off_path(D: np.ndarray, lag: int, *, js: np.ndarray | None = None, cyclic: bool = False) -> float | None:
+ """How far off the motion's path the frames one `lag` on lie, in playback steps.
+
+ For a frame j and the frame x one lag on, over the short spans (a, b) of the clip around j, the
+ least `D[a, x] + D[x, b] - D[a, b]`: a frame between a and b adds nothing (the distance is a sum
+ of absolute differences, so it adds up along a path), a frame off the path adds twice its own
+ distance. `js` are the frames compared (default: every frame with room for the spans and the
+ lag); `cyclic` reads `D` as one loop, the lag and the spans wrapping. None when no frame has
+ room or the frames do not move."""
+ found = _returns(D, lag, js, cyclic)
+ return None if found is None else found[0]
+
+
+def steps(values: list[float], lag: int, *, js: np.ndarray | None = None, cyclic: bool = False) -> tuple[float, float] | None:
+ """(`steps`, `follow`) of the step signal `values` for a candidate of `lag` frames, each over the
+ signal's mean difference a quarter of the lag on: `steps`, its difference half the lag on (two
+ equal steps put it back where it was half way: near 0); `follow`, its difference one lag on (how
+ far the signal is from repeating where the picture does). Recorded, never decided by. None when
+ there is no room or the signal does not move."""
+ s = np.asarray(values, dtype=float)
+ n = len(s)
+ starts = np.arange(n) if js is None else np.asarray(js)
+
+ def apart(h: int) -> float | None:
+ if h <= 0:
+ return None
+ if cyclic:
+ return float(np.abs(s[starts] - s[(starts + h) % n]).mean())
+ t = starts[starts + h < n]
+ return float(np.abs(s[t] - s[t + h]).mean()) if t.size else None
+
+ half = [d for d in (apart(math.floor(lag / 2)), apart(math.ceil(lag / 2))) if d is not None]
+ quarter = [d for d in (apart(math.floor(lag / 4)), apart(math.ceil(lag / 4))) if d is not None]
+ whole = apart(lag)
+ if not half or not quarter or whole is None or max(quarter) <= 0:
+ return None
+ return min(half) / max(quarter), whole / max(quarter)
+
+
+def measure(D: np.ndarray, lag: int, *, legs: dict[str, Any], js: np.ndarray | None = None, cyclic: bool = False) -> dict[str, Any]:
+ """What the return one `lag` on looks like: its `pose` (`off_path` over the lag's own
+ `distance`, 0 where the distance is under EXACT; absent where too few frames measure it) and
+ the legs' `steps` and `follow` where they are read."""
+ row: dict[str, Any] = {}
+ if legs.get("by") is not None:
+ found_steps = steps(legs["values"], lag, js=js, cyclic=cyclic)
+ if found_steps is not None:
+ row = {"steps": round(found_steps[0], 3), "follow": round(found_steps[1], 3)}
+ found = _returns(D, lag, js, cyclic)
+ if found is not None:
+ off, dist = found
+ row.update(off_path=round(off, 3), distance=round(dist, 3), pose=round(0.0 if dist < EXACT else off / dist, 3))
+ return row
+
+
+def verdict(row: dict[str, Any], *, periodicity_min: float) -> tuple[str | None, str]:
+ """The screen's one rule, read off a candidate's measurements: (None — not a repeat, |
+ "suspect", why). A candidate that dips `periodicity_min` or more below the profile's mean is a
+ suspect; that is all. The pose and the legs are not consulted: a second cycle redrawn a pixel
+ aside or a few per cent lighter reads in pixels as another pose, just as a step with the legs
+ swapped does, so nothing measured here refuses a repeat. Everything that decides whether a loop
+ is suspected is here; the rest of the module only measures."""
+ depth = row["periodicity"]
+ if depth < periodicity_min:
+ return None, f"dips {depth:.2f} below the profile mean, under {periodicity_min:.2f}: not a repeat"
+ return "suspect", (f"repeats {depth:.2f} below the profile mean (a repeat from {periodicity_min:.2f}): one cycle of a loop that holds "
+ f"{row['cycles']}, or one step of a stride whose two steps look alike — pixels cannot tell")
+
+
+def screen(period: int, *, D: np.ndarray, prof: dict[int, float], minima: list[int], mean: float, lowest: int,
+ periodicity_min: float, signals: dict[str, list[float]] | None, gait: bool, js: np.ndarray | None = None,
+ cyclic: bool = False, floor_why: str = "the window", fps: float | None = None) -> dict[str, Any]:
+ """Whether `period` may hold two or three cycles: the record of each candidate at a half and a
+ third of it (`checked`), and those `verdict` suspects (`suspects`, each with the `cycles` it
+ would make the period). Nothing is chosen.
+
+ `D` is the distance matrix the profile `prof` was measured on (read as a ring with `cyclic`;
+ `js` the frames compared), `minima` the profile's local minima, `mean` its mean, `lowest` the
+ shortest lag a cycle may be (`floor_why` names it), `signals` the frames' `legs.strike_signals`
+ (or None) and `gait` whether there are steps to read in them; with `fps` each candidate also
+ says how long it is."""
+ if signals is None:
+ legs: dict[str, Any] = {"by": None, "why": "no frames to read the legs from"}
+ elif not gait:
+ legs = {"by": None, "why": "not a gait: no steps to read"}
+ else:
+ legs = legs_mod.step_signal(signals)
+ record: dict[str, Any] = {"period": period, "legs": {k: v for k, v in legs.items() if k != "values"},
+ "checked": [], "suspects": []}
+ for k in DIVISORS:
+ near = [q for q in minima if abs(q - period / k) <= NEAR and q < period]
+ if not near:
+ continue # nothing repeats there: not a candidate, nothing to record
+ q = min(near, key=lambda lag: prof[lag])
+ row: dict[str, Any] = {"period": q, "of": period, "divisor": k, "cycles": k}
+ if fps:
+ row["seconds"] = round(q / fps, 3)
+ record["checked"].append(row)
+ if q < lowest:
+ row.update(verdict=None, why=f"shorter than {floor_why} ({lowest} frames)")
+ continue
+ row["periodicity"] = round((mean - prof[q]) / mean if mean > 0 else 0.0, 4)
+ row.update(measure(D, q, legs=legs, js=js, cyclic=cyclic))
+ row["verdict"], row["why"] = verdict(row, periodicity_min=periodicity_min)
+ if row["verdict"] == "suspect":
+ record["suspects"].append(row)
+ return record
+
+
+def local_minima(prof: dict[int, float]) -> list[int]:
+ """The lags of `prof` no deeper than either neighbour."""
+ return [lag for lag in prof if lag - 1 in prof and lag + 1 in prof and prof[lag] <= prof[lag - 1] and prof[lag] <= prof[lag + 1]]
diff --git a/tests/video/test_cycle_suspects.py b/tests/video/test_cycle_suspects.py
new file mode 100644
index 0000000..c7bbc6a
--- /dev/null
+++ b/tests/video/test_cycle_suspects.py
@@ -0,0 +1,439 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Two cycles in one loop are suspected, never cut on the pixels' word (docs/video-pipeline.md,
+"The fundamental period"; docs/loop-repair.md section 4).
+
+`video-loop` cuts the period it always cut and records a half or a third of it that no pose
+refused (`cycle.fundamental`). `video-cycle-align` screens each loop the same way, stops a set on a
+suspect before anything is rewritten, and changes the number of cycles in a loop only when told it
+(`--cycles <loop>=k`). The figures are drawn here: a walker whose far leg is shaded `far` against
+the near leg's 200, a runner whose rear foot kicks up by `lift` px at the back of its stride, a
+legless bounce, and a far arm shaded `arm`. The screen's rule (`period.verdict`): a half or a
+third that repeats, no shorter than the gait floor, is a suspect; the pose and the legs are
+evidence for whoever looks, never a reason to refuse."""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image, ImageChops, ImageDraw, ImageEnhance
+
+from sprite_gen.video import align, batch, legs, local_cycle
+from sprite_gen.video import loop as loop_mod
+from sprite_gen.video import period as period_mod
+
+W = H = 192
+FPS = 24.0
+
+
+def _figure(phase: float, *, fam: str = "shade", far: int = 110, lift: float = 0.0, arm: int = 0) -> Image.Image:
+ """One frame at `phase` (radians, one stride = 2 pi), seen from the side. Half a stride on the
+ legs are back in the same places with their shades swapped; the body bobs and the head sways
+ twice a stride, a quarter apart, so no two frames in a row are the same picture."""
+ im = Image.new("RGBA", (W, H), (0, 0, 0, 0))
+ d = ImageDraw.Draw(im)
+ if fam == "bounce":
+ squash, lean = 10 * math.cos(phase), 8 * math.sin(phase)
+ d.ellipse((60 - squash + lean, 70 + squash, 132 + squash + lean, 170), fill=(90, 160, 220, 255))
+ return im
+ amp, half_width = (16, 12) if fam == "shade" else (20, 8)
+ bob, sway = 4 * math.cos(2 * phase), 5 * math.sin(2 * phase)
+ for sign, shade in ((-1, far), (1, 200)):
+ s = sign * math.sin(phase)
+ x = 96 + amp * s
+ kick = max(0.0, -s - 0.6) / 0.4 * lift if lift else 0.0 # the rear foot up at the back of the stride
+ d.rectangle((x - half_width, 110 + bob, x + half_width, 170 - kick), fill=(shade, shade, shade, 255))
+ d.rectangle((66, 60 + bob, 126, 120 + bob), fill=(200, 80, 80, 255))
+ d.rectangle((76 + sway, 24 + bob, 116 + sway, 60 + bob), fill=(230, 200, 170, 255))
+ if arm: # arms swing against the legs, the far one shaded `arm`
+ for sign, shade in ((1, arm), (-1, 230)):
+ ax = 96 + 14 * sign * math.sin(phase)
+ d.rectangle((ax - 5, 66 + bob, ax + 5, 104 + bob), fill=(shade, shade, shade, 255))
+ return im
+
+
+def _clip(root: Path, n: int, stride: int, *, twos: bool = False, **kw) -> list[Path]:
+ """`n` frames of a motion whose cycle is `stride` frames. On twos a new drawing comes every other
+ frame and the frame between moves a fifth of the way on: an odd `stride` then shows each cycle
+ half a drawing off the one before, and the profile dips deeper two cycles on than one."""
+ root.mkdir(parents=True, exist_ok=True)
+ files = []
+ for j in range(n):
+ t = (j - j % 2) + 0.4 * (j % 2) if twos else j
+ files.append(root / f"frame-{j:04d}.png")
+ _figure(2 * math.pi * t / stride, **kw).save(files[-1])
+ return files
+
+
+def _frames(files: list[Path]) -> list[Image.Image]:
+ return [Image.open(f).convert("RGBA") for f in files]
+
+
+def _detect(files: list[Path], state: str = "walk") -> dict:
+ profile = loop_mod.profile_for(state)
+ lo, hi = profile.window(len(files), FPS)
+ return loop_mod.detect_cycle(loop_mod.distance_matrix(files), min_len=lo, max_len=hi, gait_floor=round(profile.min_seconds * FPS),
+ signals=legs.strike_signals(_frames(files)))
+
+
+def _ring(stride: int, cycles: int, *, twos: bool = False, drift: tuple[str, float] | None = None, **kw) -> list[Image.Image]:
+ """A loop cut at exactly `cycles` strides, from frame 5 of a filmed clip. `drift` draws every
+ cycle after the first again, a little differently, as a generated clip does: ("shift", px) or
+ ("shift_y", px) moved, ("bright", %) lighter, ("lift", px) the rear foot kicked higher, ("phase",
+ frames) late."""
+ frames = []
+ for j in range(5, 5 + cycles * stride):
+ t = (j - j % 2) + 0.4 * (j % 2) if twos else j
+ again = drift is not None and j >= 5 + stride
+ kind, size = drift if again else ("", 0)
+ if kind == "phase":
+ t -= size
+ im = _figure(2 * math.pi * t / stride, **({**kw, "lift": kw.get("lift", 0) + size} if kind == "lift" else kw))
+ if kind == "shift":
+ im = ImageChops.offset(im, int(size), 0)
+ elif kind == "shift_y":
+ im = ImageChops.offset(im, 0, int(size))
+ elif kind == "bright":
+ im = ImageEnhance.Brightness(im).enhance(1 + size / 100)
+ frames.append(im)
+ return frames
+
+
+# --- video-loop: the period it always cut, the shorter one recorded ---------------------------
+
+def test_a_walk_filmed_through_two_cycles_is_cut_as_before_and_its_half_recorded_as_a_suspect(tmp_path):
+ """Stride 15 on twos: the frame 15 on is half a drawing off, the frame 30 on the same drawing, so
+ the deepest repeat is 30. It is cut there, as 2.25 cut it; the 15 is recorded as a suspect — two
+ cycles, the pose returning on the motion's path — with the legs' reading beside it."""
+ cycle = _detect(_clip(tmp_path / "keyed", 73, 15, twos=True))
+ assert cycle["period_global"] == 30 and cycle["review_recommended"] is False
+ found = cycle["fundamental"]
+ assert found["period"] == 30 and found["legs"]["by"] == "stride"
+ assert [(row["period"], row["cycles"], row["verdict"]) for row in found["suspects"]] == [(15, 2, "suspect")]
+ row = found["suspects"][0]
+ assert row["pose"] < 0.5 and "steps" in row and "follow" in row
+
+
+# The counter-examples of the two rejected rounds: one stride each, the half one step with the
+# legs swapped. 2.25 cut each at its stride; so does this one. The half repeats, so it is recorded
+# as a suspect — its pose, another pose, beside it for whoever looks — and nothing is cut.
+COUNTER = [
+ ("run", 18, dict(far=170)), # the far leg shaded nearly like the near one
+ ("run", 16, dict(fam="kick", lift=20)), # a heel kick: the stride swings twice a step
+ ("run", 20, dict(fam="kick", lift=20)),
+ ("run", 16, dict(fam="kick", lift=20, twos=True)),
+]
+
+
[email protected]("state, stride, kw", COUNTER)
+def test_a_half_stride_with_the_legs_swapped_is_never_cut(tmp_path, state, stride, kw):
+ keyed = tmp_path / "keyed"
+ _clip(keyed, 73, stride, **kw)
+ rep = loop_mod.run_loop(keyed, tmp_path / "out", fps=FPS, state=state, min_len=None, max_len=None, n_out=None, seam_max=2.0,
+ name=state, report_path=None, anchor="none", repair="off")
+ cycle = rep["cycle"]
+ assert cycle["period_global"] == stride and cycle["length"] == stride
+ half = [row for row in cycle["fundamental"]["checked"] if row["divisor"] == 2]
+ assert half and half[0]["verdict"] == "suspect" and half[0]["pose"] >= 0.8 and half[0]["period"] in (stride // 2, stride // 2 + 1)
+
+
+# A representative slice of the design grid (A shade, C heel kick, X arms), each one stride long.
+# The whole grid — 442 clips — is the release check in docs/loop-repair.md section 4.
+SLICE = [("run", 16, dict(far=197)), ("run", 20, dict(far=200, twos=True)), ("walk", 31, dict(far=190)),
+ ("run", 18, dict(fam="kick", far=190, lift=30, twos=True)), ("walk", 32, dict(fam="kick", far=140, lift=10)),
+ ("run", 18, dict(far=200, arm=150)), ("walk", 30, dict(fam="kick", far=197, lift=20, arm=150, twos=True))]
+
+
[email protected]("state, stride, kw", SLICE)
+def test_video_loop_cuts_the_period_the_deepest_repeat_gives(tmp_path, state, stride, kw):
+ """Nothing is cut shorter than the period the profile gives (2.25's rule): whatever the screen
+ finds at a half or a third goes in the record only."""
+ files = _clip(tmp_path / "keyed", 73, stride, **kw)
+ profile = loop_mod.profile_for(state)
+ lo, hi = profile.window(len(files), FPS)
+ D = loop_mod.distance_matrix(files)
+ floor = round(profile.min_seconds * FPS)
+ with_legs = loop_mod.detect_cycle(D, min_len=lo, max_len=hi, gait_floor=floor, signals=legs.strike_signals(_frames(files)))
+ without = loop_mod.detect_cycle(D, min_len=lo, max_len=hi, gait_floor=floor)
+ assert {k: with_legs[k] for k in ("period_global", "length", "start", "review_recommended")} == \
+ {k: without[k] for k in ("period_global", "length", "start", "review_recommended")}
+ assert all(row["cycles"] * row["period"] in range(with_legs["period_global"] - 3, with_legs["period_global"] + 3)
+ for row in with_legs["fundamental"]["suspects"])
+
+
+def test_the_local_repeat_search_records_the_screen_too(tmp_path):
+ """`--anchor motion-auto` reads a local profile (sprite_gen/video/local_cycle.py): the same
+ record, nothing cut shorter."""
+ files = _clip(tmp_path / "keyed", 73, 15, twos=True)
+ D = loop_mod.distance_matrix(files)
+ lo, hi = loop_mod.profile_for("walk").window(len(files), FPS)
+ kw = dict(min_len=lo, max_len=hi, gait_floor=14, periodicity_min=loop_mod.PERIODICITY_MIN,
+ double_tolerance=loop_mod.GAIT_DOUBLE_TOL, double_search=loop_mod.GAIT_DOUBLE_SEARCH)
+ cycle = local_cycle.detect(D, np.zeros(len(files)), signals=legs.strike_signals(_frames(files)), **kw)
+ plain = local_cycle.detect(D, np.zeros(len(files)), **kw)
+ assert {k: cycle[k] for k in ("start", "length", "period_local")} == {k: plain[k] for k in ("start", "length", "period_local")}
+ assert cycle["fundamental"]["period"] == cycle["period_local"] and "suspects" in cycle["fundamental"]
+
+
+def test_video_loop_writes_the_state_and_the_record(tmp_path):
+ keyed = tmp_path / "keyed"
+ _clip(keyed, 73, 15, twos=True)
+ rep = loop_mod.run_loop(keyed, tmp_path / "out", fps=FPS, state="walk", min_len=None, max_len=None, n_out=None, seam_max=2.0,
+ name="walk", report_path=None, anchor="none", repair="off")
+ saved = json.loads(Path(rep["report"]).read_text())["cycle"]["fundamental"]
+ assert saved["period"] == rep["cycle"]["period_global"] == 30 and saved["suspects"][0]["period"] == 15
+ meta = json.loads((tmp_path / "out" / "walk.strip.json").read_text())
+ assert meta["state"] == "walk" and meta["cycle_frames"] == 30
+
+
+# --- the screen ----------------------------------------------------------------------------
+
+TWO = [("walk", 15, dict(twos=True)), ("walk", 17, dict(twos=True, far=200)), ("run", 13, {}), ("run", 15, dict(fam="kick", lift=20, far=170)),
+ ("run", 16, dict(far=110)), ("run", 20, dict(fam="kick", lift=30, far=110, twos=True)), ("walk", 30, dict(far=200, arm=150)),
+ ("walk", 15, dict(fam="bounce", twos=True))]
+
+
[email protected]("state, stride, kw", TWO)
+def test_a_loop_of_two_cycles_is_a_suspect(state, stride, kw):
+ """However the legs are drawn: the true cycle at half the loop is a pose on the motion's path,
+ which the screen never refuses."""
+ screen = align.cycle_screen(_ring(stride, 2, **kw), fps=FPS, state=state)
+ assert [row["cycles"] for row in screen["suspects"]] == [2] and screen["suspects"][0]["period"] == stride
+ assert screen["suspects"][0]["seconds"] == round(stride / FPS, 3)
+
+
+# Two cycles whose second is drawn again a little differently (a generated clip redraws it): moved,
+# lighter, kicking higher, late. A rule that refused "another pose" missed most of these — in pixels
+# a redrawn second cycle is off the motion's path just as a swapped step is — so the screen refuses
+# nothing it finds repeating.
+DRIFT = [pytest.param(state, stride, kw, drift, id=f"{state}{stride}-{drift[0]}{drift[1]:g}")
+ for state, stride, kw, drift in (
+ ("run", 18, dict(far=110), ("shift", 1)),
+ ("run", 18, dict(far=110), ("shift", 3)),
+ ("run", 18, dict(far=110), ("bright", 5)),
+ ("run", 18, dict(far=110), ("shift_y", 2)),
+ ("run", 18, dict(far=110), ("lift", 5)),
+ ("run", 18, dict(far=110), ("phase", 0.2)),
+ ("run", 16, dict(fam="kick", far=110, lift=20), ("shift", 1)),
+ ("run", 16, dict(fam="kick", far=110, lift=20), ("bright", 10)),
+ ("run", 16, dict(fam="kick", far=110, lift=20), ("shift_y", 4)),
+ ("walk", 30, dict(far=140), ("lift", 5)),
+ ("walk", 30, dict(far=140), ("shift_y", 4)),
+ ("walk", 30, dict(far=140), ("bright", 20)),
+ ("walk", 30, dict(far=140), ("phase", 0.5)))]
+
+
[email protected]("state, stride, kw, drift", DRIFT)
+def test_a_loop_of_two_cycles_drawn_again_is_a_suspect(state, stride, kw, drift):
+ screen = align.cycle_screen(_ring(stride, 2, drift=drift, **kw), fps=FPS, state=state)
+ assert [row["cycles"] for row in screen["suspects"]] == [2], screen["checked"]
+
+
[email protected]("state, stride, kw", COUNTER)
+def test_a_stride_whose_half_repeats_is_a_suspect_with_its_pose_as_evidence(state, stride, kw):
+ """One stride whose half is a step with the legs swapped: it repeats, so it is suspected (a
+ false alarm costs one look); its pose, another pose, is in the record for that look."""
+ screen = align.cycle_screen(_ring(stride, 1, **kw), fps=FPS, state=state)
+ [row] = screen["suspects"]
+ assert row["cycles"] == 2 and row["pose"] >= 0.8 and row["periodicity"] >= loop_mod.PERIODICITY_MIN
+
+
+def test_two_steps_under_the_gait_floor_are_not_a_suspect():
+ """A loop the half-period guard doubled (two look-alike bounces of 12 frames, under the walk's
+ floor) holds one stride, as `video-loop` cut it."""
+ screen = align.cycle_screen(_ring(12, 2, fam="bounce"), fps=FPS, state="walk")
+ assert screen["suspects"] == [] and "gait floor" in screen["checked"][0]["why"]
+
+
+def test_a_loop_too_short_to_halve_is_not_screened():
+ screen = align.cycle_screen(_ring(6, 1), fps=FPS, state="walk")
+ assert screen["checked"] == [] and screen["suspects"] == []
+
+
+def test_the_screen_decides_by_the_repeat_alone():
+ """No verdict says "a cycle" or "another pose": a candidate is a suspect or not a repeat, and
+ the pose and the legs do not move it."""
+ frames = _ring(15, 2, twos=True) + _ring(16, 1, fam="kick", lift=20)
+ D = align._ring(frames)
+ for lag in range(4, len(frames) - 4):
+ row = {"periodicity": 1.0, "cycles": 2, **period_mod.measure(D, lag, legs={"by": None}, cyclic=True)}
+ assert period_mod.verdict(row, periodicity_min=loop_mod.PERIODICITY_MIN)[0] == "suspect"
+ assert period_mod.verdict({**row, "pose": 9.0}, periodicity_min=loop_mod.PERIODICITY_MIN)[0] == "suspect"
+ assert period_mod.verdict({**row, "periodicity": 0.1}, periodicity_min=loop_mod.PERIODICITY_MIN)[0] is None
+
+
+def test_off_path_is_zero_between_two_frames_and_large_for_another_pose(tmp_path):
+ D = loop_mod.distance_matrix(_clip(tmp_path / "twos", 73, 15, twos=True))
+ assert period_mod.off_path(D, 15) < 0.2 and period_mod.off_path(D, 30) < 0.05
+ D = loop_mod.distance_matrix(_clip(tmp_path / "ones", 73, 30))
+ assert period_mod.off_path(D, 15) > 1.0 and period_mod.off_path(D, 30) < 0.05
+ assert period_mod.off_path(D, 71) is None # no frame has room for the lag and the spans around it
+
+
+def test_steps_read_two_steps_and_one():
+ """For the record: a walk's stride opens and closes once a step (twice a stride of 20 frames)."""
+ stride = [abs(math.sin(2 * math.pi * t / 20)) for t in range(80)]
+ assert period_mod.steps(stride, 20)[0] < 0.1 and period_mod.steps(stride, 10)[0] > 1.0
+ assert period_mod.steps(stride, 20, cyclic=True, js=np.arange(20))[0] < 0.1
+ assert period_mod.steps([1.0] * 40, 20) is None
+
+
+# --- video-cycle-align --------------------------------------------------------------------
+
+class _Blend:
+ def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:
+ return Image.blend(a, b, t)
+
+
+def _cut(root: Path, name: str, stride: int, length: int, state: str = "walk", **kw) -> Path:
+ """A loop of `length` frames cut from a walk (or `state`) whose stride is `stride` frames."""
+ keyed = root / f"{name}-keyed"
+ _clip(keyed, length + 6, stride, **kw)
+ out = root / name
+ loop_mod.run_loop(keyed, out, fps=FPS, state=state, min_len=None, max_len=None, n_out=None, seam_max=1000.0,
+ name=state, report_path=None, cycle_mode="fixed", start=0, length=length, anchor="none", repair="off")
+ return out
+
+
+def _set(tmp_path: Path) -> list[Path]:
+ """S and E one stride each; NE two strides of 15 (30 frames), as a two-cycle cut leaves it."""
+ return [_cut(tmp_path, "S", 24, 24), _cut(tmp_path, "E", 24, 24), _cut(tmp_path, "NE", 15, 30, twos=True)]
+
+
+def test_a_set_with_a_suspect_is_stopped_before_anything_is_rewritten(tmp_path):
+ dirs = _set(tmp_path)
+ before = [(d / "walk.strip.png").read_bytes() for d in dirs]
+ with pytest.raises(align.CycleSuspects, match=r"NE: may hold 2 cycles of 15 frames \(0\.625 s\)") as stopped:
+ align.align_set(dirs, interpolate=_Blend(), report_path=tmp_path / "align.json")
+ message = str(stopped.value)
+ command = " ".join(["sprite-gen video-cycle-align", *(f"--loop-dir {d}" for d in dirs), f"--report {tmp_path / 'align.json'}",
+ f"--cycles {dirs[2]}=<1|2>"])
+ assert stopped.value.command == command and command in message and "--multi-cycle warn" in message
+ assert "video-loop" not in message
+ assert [(d / "walk.strip.png").read_bytes() for d in dirs] == before
+ assert all(not (d / "cycle.json").exists() and "cycle_align" not in json.loads((d / "walk.strip.json").read_text()) for d in dirs)
+ report = json.loads((tmp_path / "align.json").read_text())
+ assert report["applied"] is False and report["refused"] == "cycle-suspects" and report["command"] == command
+ [entry] = report["suspects"]
+ assert entry["dir"] == str(dirs[2]) and entry["status"] == "stopped" and entry["length"] == 30
+ assert [(c["period"], c["cycles"]) for c in entry["candidates"]] == [(15, 2)]
+ assert entry["settle"] == [f"--cycles {dirs[2]}=1", f"--cycles {dirs[2]}=2"]
+ assert stopped.value.suspects == report["suspects"]
+
+
+def test_cycles_two_takes_one_cycle_out_of_the_loop_as_filmed(tmp_path):
+ """`--cycles NE=2`: 15 frames out of NE's 30 — from where the frame 15 on is most like the first
+ — and the set aligned to its median, 24. Run again, it reads the same 30 filmed frames."""
+ dirs = _set(tmp_path)
+ report = align.align_set(dirs, interpolate=_Blend(), cycles={"NE": 2})
+ by = {Path(r["dir"]).name: r for r in report["loops"]}
+ assert report["applied"] is True and report["lengths"] == [24, 24, 15] and report["length"] == 24
+ assert by["NE"]["cycles_given"] == 2 and by["NE"]["from"] == 15 and by["NE"]["to"] == 24
+ taken = by["NE"]["cycle_taken"]
+ assert taken["from"] == 30 and taken["length"] == 15 and taken["exact"] is True and taken["repeat_over_step"] < 0.5
+ assert report["suspects"][0]["status"] == "counted" and report["cycles_given"] == {str(dirs[2]): 2}
+ assert len(list((dirs[2] / "cycle.source").glob("frame-*.png"))) == 30
+ again = align.align_set(dirs, interpolate=_Blend(), cycles={str(dirs[2]): 2})
+ assert {Path(r["dir"]).name: r["cycle_taken"]["start"] for r in again["loops"] if "cycle_taken" in r} == {"NE": taken["start"]}
+
+
+def test_cycles_one_aligns_the_loop_as_it_is(tmp_path):
+ dirs = _set(tmp_path)
+ report = align.align_set(dirs, interpolate=_Blend(), cycles={"NE": 1})
+ by = {Path(r["dir"]).name: r for r in report["loops"]}
+ assert by["NE"]["from"] == 30 and "cycle_taken" not in by["NE"] and report["suspects"][0]["status"] == "counted"
+ assert report["length"] == 24
+
+
+def test_multi_cycle_warn_aligns_the_set_as_it_is_and_names_the_loop(tmp_path):
+ dirs = _set(tmp_path)
+ report = align.align_set(dirs, interpolate=_Blend(), multi_cycle="warn")
+ assert [r["from"] for r in report["loops"]] == [24, 24, 30]
+ assert any(w.startswith(f"{dirs[2]}: may hold 2 cycles") and "--multi-cycle warn" in w for w in report["warnings"])
+ assert report["suspects"][0]["status"] == "warned"
+
+
+def test_the_number_of_cycles_in_a_loop_changes_only_with_cycles(tmp_path, monkeypatch):
+ """Every way of aligning a set but `--cycles k>1` resamples each loop from all of its filmed
+ frames: take_cycle is never reached."""
+ dirs = _set(tmp_path)
+ plain = [_cut(tmp_path, "P1", 20, 20), _cut(tmp_path, "P2", 24, 24)]
+
+ def never(*_a, **_k):
+ raise AssertionError("a loop's cycles changed without --cycles")
+
+ monkeypatch.setattr(align, "take_cycle", never)
+ for kwargs in (dict(dirs=plain), dict(dirs=dirs, multi_cycle="warn"), dict(dirs=dirs, cycles={"NE": 1})):
+ report = align.align_set(kwargs.pop("dirs"), interpolate=_Blend(), **kwargs)
+ assert all(r["from"] == len(list((Path(r["dir"]) / "cycle.source").glob("frame-*.png"))) for r in report["loops"])
+ with pytest.raises(align.CycleSuspects):
+ align.align_set(dirs, interpolate=_Blend())
+ with pytest.raises(AssertionError, match="without --cycles"):
+ align.align_set(dirs, interpolate=_Blend(), cycles={"NE": 2})
+
+
[email protected]("strides, odd, state, kw", [
+ ((18, 18, 20), 0, "run", dict(far=170)), # rejected round 1's set: one loop's far leg shaded like the near one
+ ((16, 16, 18), 0, "run", dict(fam="kick", lift=20)), # rejected round 2's set: one loop a heel kick
+])
+def test_the_counter_example_sets_stop_and_align_as_before_once_counted(tmp_path, strides, odd, state, kw):
+ """A run's half repeats in every one of these loops: the set stops, naming each loop, its
+ evidence and the command that settles it. Counted one cycle each, it is aligned as 2.25 aligned
+ it, each loop resampled from its own cut."""
+ dirs = [_cut(tmp_path, f"L{i}", s, s, state, **(kw if i == odd else {})) for i, s in enumerate(strides)]
+ with pytest.raises(align.CycleSuspects) as stopped:
+ align.align_set(dirs, interpolate=_Blend())
+ assert [e["dir"] for e in stopped.value.suspects] == [str(d) for d in dirs]
+ assert all(f"--cycles {d}=<1|2>" in str(stopped.value) and f"--loop-dir {d}" in stopped.value.command for d in dirs)
+ assert all("pose" in e["candidates"][0] for e in stopped.value.suspects)
+ report = align.align_set(dirs, interpolate=_Blend(), cycles={str(d): 1 for d in dirs})
+ assert report["length"] == strides[1] and [r["from"] for r in report["loops"]] == list(strides)
+ assert all(e["status"] == "counted" for e in report["suspects"]) and not any("may hold" in w for w in report["warnings"])
+
+
+def test_cycles_names_one_loop_or_is_refused(tmp_path):
+ dirs = [_cut(tmp_path / "a", "loop", 24, 24), _cut(tmp_path / "b", "loop", 20, 20)]
+ with pytest.raises(SystemExit, match="names 2 of the --loop-dir"):
+ align.align_set(dirs, interpolate=_Blend(), cycles={"loop": 2})
+ with pytest.raises(SystemExit, match="names 0 of the --loop-dir"):
+ align.align_set(dirs, interpolate=_Blend(), cycles={"NE": 2})
+ with pytest.raises(SystemExit, match="holds 1, 2, 3 cycles"):
+ align.align_set(dirs, interpolate=_Blend(), cycles={"a": 4})
+ report = align.align_set(dirs, interpolate=_Blend(), cycles={"a": 1}) # a video-set item: its directory's parent
+ assert report["cycles_given"] == {str(dirs[0]): 1}
+ assert align.parse_cycles(["x/NE=2", "a=b=1"]) == {"x/NE": 2, "a=b": 1}
+ with pytest.raises(SystemExit, match="LOOP=K"):
+ align.parse_cycles(["NE"])
+
+
+def test_the_command_takes_cycles(tmp_path, monkeypatch, capsys):
+ dirs = _set(tmp_path)
+ monkeypatch.setattr(align.rife_mod, "Rife", _Blend)
+ _Blend.describe = lambda self: {"binary": "blend"} # type: ignore[attr-defined]
+ with pytest.raises(SystemExit, match="may hold 2 cycles"):
+ align.main([*sum((["--loop-dir", str(d)] for d in dirs), []), "--between", "nearest"])
+ assert align.main([*sum((["--loop-dir", str(d)] for d in dirs), []), "--between", "nearest", "--cycles", "NE=2"]) == 0
+ out = json.loads(capsys.readouterr().out)
+ assert out["lengths"] == [24, 24, 15] and out["cycles_given"] == {str(dirs[2]): 2}
+
+
+# --- video-set ----------------------------------------------------------------------------
+
+def test_video_set_skips_a_suspect_state_with_a_warning(tmp_path, capsys):
+ rows = []
+ for direction, stride, length, twos in (("front", 24, 24, False), ("side", 24, 24, False), ("back", 15, 30, True)):
+ item = tmp_path / f"{direction}-walk"
+ item.mkdir()
+ _cut(item, "loop", stride, length, twos=twos)
+ rows.append({"item": f"{direction}-walk", "direction": direction, "state": "walk", "dir": str(item), "ok": True,
+ "loop": {"n_out": length}})
+ out = batch.align_gaits(rows, tmp_path, "auto", interpolate=_Blend())
+ walk = out["walk"]
+ assert walk["ok"] is True and walk["applied"] is False and walk["reason"] == "cycle-suspects"
+ assert "back-walk may hold more than one cycle" in walk["why"] and walk["suspects"][0]["dir"] == str(tmp_path / "back-walk" / "loop")
+ assert [r["loop"]["n_out"] for r in rows] == [24, 24, 30]
+ assert json.loads((tmp_path / "walk.cycle-align.json").read_text())["refused"] == "cycle-suspects"
+ assert "cycles not aligned" in capsys.readouterr().err
diff --git a/tests/video/test_duration_window_oneshot.py b/tests/video/test_duration_window_oneshot.py
index ab3a126..641ef3b 100644
--- a/tests/video/test_duration_window_oneshot.py
+++ b/tests/video/test_duration_window_oneshot.py
@@ -75,7 +75,7 @@ def test_run_loop_reports_the_gait_window_from_the_profile(tmp_path: Path, monke
_gait_frames(tmp_path, period=12, n=72)
seen: dict = {}
- def fake_detect(D, *, min_len, max_len, gait_floor=None):
+ def fake_detect(D, *, min_len, max_len, gait_floor=None, signals=None):
seen.update(lo=min_len, hi=max_len)
raise SystemExit("stop here")