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(video-loop): held cells found on every cut and made again with RIFE's frames between by default, and a cut given above its clip's rate (--out-fps)

Soohong Kimea42ccbd82e5
diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.py
index df5c29a..b4a038c 100644
--- a/sprite_gen/frames/unpack_atlas.py
+++ b/sprite_gen/frames/unpack_atlas.py
@@ -273,6 +273,24 @@ def import_pngs(out_dir: Path, png_paths: list[Path], state_name: str, labels: l
return import_png_groups(out_dir, [{"name": state_name, "paths": png_paths, "labels": labels}], iso)
+def loop_marks(folder: Path, count: int) -> dict[int, str]:
+ """The cells of a video-loop `cycle/` folder (one `*.strip.json` beside it, holding `count` cycle frames) that the
+ held fill made between their neighbours (`made`) and that still show the picture before them (`held`), from the
+ strip metadata's `held_fill` (docs/loop-repair.md section 7); nothing for any other folder. A cut given at
+ `--out-fps` has every cell made at its own time: its held cells alone are marked."""
+ metas = sorted(folder.parent.glob("*.strip.json")) if folder.name == "cycle" else []
+ if len(metas) != 1:
+ return {}
+ meta = json.loads(metas[0].read_text(encoding="utf-8"))
+ held = meta.get("held_fill")
+ if not isinstance(held, dict) or meta.get("cycle_frames") != count:
+ return {}
+ marks = {} if "out_fps" in meta else {int(c): "made" for c in held.get("made", [])}
+ for run in held.get("held_runs", []):
+ marks.update({c: "held" for c in range(int(run["start"]) + 1, int(run["start"]) + int(run["length"]))})
+ return marks
+
+
def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str, Any] | None = None,
base_src: Path | None = None, run_dir: Path | None = None) -> dict[str, Any]:
"""Import separate PNGs as one or more curator rows (states).
@@ -562,6 +580,10 @@ def _run(args: argparse.Namespace):
"refs": _group_refs(sub)})
if not groups:
raise SystemExit(f"no PNGs in {src}")
+ for group in groups:
+ # a video-loop cut's cells: each made between its neighbours, or still the picture before it, says so on its card
+ marks = loop_marks(group["paths"][0].parent, len(group["paths"]))
+ group["labels"] = [f"{label} ({marks[k]})" if k in marks else label for k, label in enumerate(group["labels"])]
# imported ref roles are validated fail-loud (run-contract §4). A _refs file whose
# prefix isn't a known role (anchor/basis/guide) is malformed input — reject it
# loudly instead of silently relabeling it as guide (No Silent Fallback).
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index 1c085bf..a61e5dc 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -197,7 +197,8 @@ def held_drawings(frames: list[Image.Image], *, fps: float, clip: dict[str, Any]
loop's: a clip held for part of its length is held where it was cut. The clip's stands where the
cut was too short to read, or was cut before that record (`span_why` says which). The cut cycle
is the fallback for a loop cut before either record (`source` cycle, read as a ring): it is short,
- and `--anchor motion-auto` shifts each cut frame, so a pair's repeat may no longer read as one."""
+ and `--anchor motion-auto` shifts each cut frame, so a pair's repeat may no longer read as one. It is
+ also how a loop whose held cells `video-loop` made again (`held_fill`) is read: as it plays."""
n = len(frames)
if clip and clip.get("hold"):
whole = {"hold": clip["hold"], "drawings_per_second": clip["drawings_per_second"], "contrast": clip.get("contrast")}
@@ -977,6 +978,10 @@ def _loop_files(loop_dir: Path) -> tuple[Path, dict[str, Any]]:
for key in ("cycle_frames", "cycle_seconds", "cell_height_cap", "kind"):
if key not in meta:
raise ValueError(f"{metas[0]}: no `{key}` — cut the loop again with this sprite-gen (video-loop) before aligning it")
+ if "out_fps" in meta:
+ raise ValueError(f"{metas[0]}: cut at --out-fps {meta['out_fps']:g}, its cells each made at a time of their own — the "
+ "alignment makes its own frames between: align the loop cut at its clip's rate (video-loop without "
+ "--out-fps)")
strip = cut_strip(loop_dir, metas[0], meta)
if strip is not None and not strip.is_file():
raise ValueError(f"{loop_dir}: no {strip.name} — a first alignment reads the strip as cut to record where its cells are from "
@@ -1336,7 +1341,11 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
except (ValueError, rife_mod.RifeUnavailable) as exc:
raise SystemExit(f"video-cycle-align: {d}: {exc}; frames between source frames are made by RIFE (docs/loop-repair.md)") from exc
start = strike["start"]
- drawings = held_drawings(frames, fps=fps, clip=loops[i][2].get("drawings"), cut=loops[i][2].get("cycle_drawings"))
+ # A loop whose held cells video-loop made again (`held_fill`) shows a picture a cell where its clip held them: the
+ # clip's readings say how it was filmed, not how it plays, and its own cells are read.
+ filled = bool((loops[i][2].get("held_fill") or {}).get("made"))
+ drawings = held_drawings(frames, fps=fps, clip=None if filled else loops[i][2].get("drawings"),
+ cut=None if filled else loops[i][2].get("cycle_drawings"))
# the ghosts passed over or kept as frames of cycle.source/, each cell where it now stands
ghost_at = sorted(({**g, "at": (g["at"] - start) % target, "source": index[g["source"]], "taken": index[g["taken"]]}
for g in facts["ghost_at"]), key=lambda g: g["at"])
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 54ba644..0292388 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -37,6 +37,7 @@ from sprite_gen.video import facing as facing_mod
from sprite_gen.video import canvas as canvas_mod
from sprite_gen.video import frames as frames_mod
from sprite_gen.video import loop as loop_mod
+from sprite_gen.video import held_fill as held_fill_mod
from sprite_gen.video import align as align_mod
from sprite_gen.video import body_plan as body_mod
from sprite_gen.video.body_plan import Body
@@ -720,6 +721,8 @@ def run_item(
end_frame: Path | None = None,
play: str | None = None,
motion: str | None = None,
+ fill_held: str = "auto",
+ out_fps: float | None = None,
) -> dict[str, Any]:
"""One (direction, state) item, canvas to loop. `play` is the request's play mode for it (`play.MODES`; None, the
state's preset) and `motion` the caller's own motion text in place of the state's sentence."""
@@ -859,7 +862,8 @@ def run_item(
result["frames"]["decontam_warning"] = decontam_note
lp = loop_mod.run_loop(Path(fr["keyed_dir"]), item_dir / "loop", fps=float(fr["fps"]), state=state, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX, name=item, report_path=item_dir / "loop.report.json", anchor=anchor, body_height=body_height,
cycle_mode=cycle_for(state, direction, play, pinned=pins),
- facing=facing if direction in handed_mod.LATERAL_VIEWS else "right")
+ facing=facing if direction in handed_mod.LATERAL_VIEWS else "right",
+ fill_held=fill_held, out_fps=out_fps)
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")
@@ -876,6 +880,12 @@ def run_item(
result["loop"]["step_screen"] = {k: lp["cycle"]["step_screen"][k] for k in ("lag", "ratio", "depth", "coverage")}
if lp.get("motion_anchor", {}).get("applied") is False:
result["loop"]["motion_anchor"] = lp["motion_anchor"]
+ # The cut's poses over its cells, its held runs as delivered, and what became of them (docs/loop-repair.md section 7).
+ held = lp["held_fill"]
+ result["loop"]["poses"] = held_fill_mod.said(held)
+ result["loop"]["held_fill"] = {"before": held_fill_mod.said(held["before"]), "held_runs": held["held_runs"],
+ "made": held["made"], **({"unmade": held["unmade"]} if "unmade" in held else {}),
+ **({"out_fps": held["out_fps"]} if "out_fps" in held else {})}
if "rife" in (lp.get("jump_repair") or {}):
# cut as filmed for want of RIFE: the set report lists it under `warnings` (a wrap the seam bridge read carries
# its `seam`, not the flow's `off_max_before`)
@@ -1091,6 +1101,8 @@ def run_set(
end_frames: dict[str, Path] | None = None,
play: dict[str, str] | None = None,
motion: dict[str, str] | None = None,
+ fill_held: str = "auto",
+ out_fps: float | None = None,
) -> dict[str, Any]:
"""`bases` maps a view to its still; `facing` is right, left or `right,left` (`facings_of`), and a view filmed
both ways is keyed `view@right` and `view@left` (`resolve_bases`). `handed` (`handedness.parse`) puts each
@@ -1132,6 +1144,9 @@ def run_set(
raise SystemExit("video-set: non-loop states need --fit state and --anchor none")
aligned_items = [i for i, _, s, _, _ in items if align_cycles == "auto" and loop_mod.profile_for(s).gait
and sum(1 for _, _, s2, _, _ in items if s2 == s) >= 2]
+ if out_fps is not None and aligned_items:
+ raise SystemExit(f"video-set: --out-fps gives each cut at a higher rate, and the cycle alignment of {', '.join(aligned_items)} "
+ "makes its own frames between to one length — pass --align-cycles off with it")
for item, foot in (align_feet or {}).items():
if item not in aligned_items:
raise SystemExit(f"video-set: --align-foot {item}={foot}: {item} is not an item the set aligns (a walk or run filmed in two or "
@@ -1153,7 +1168,7 @@ def run_set(
return prepare_side
with ThreadPoolExecutor(max_workers=max(1, concurrency)) as ex:
- futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan, **({"end_frame": end_frames[i]} if end_frames and i in end_frames else {}), **({"play": plays[i]} if i in plays else {}), **({"motion": motions[i]} if i in motions else {})): i for i, d, s, f, b in items}
+ futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan, **({"end_frame": end_frames[i]} if end_frames and i in end_frames else {}), **({"play": plays[i]} if i in plays else {}), **({"motion": motions[i]} if i in motions else {}), fill_held=fill_held, out_fps=out_fps): i for i, d, s, f, b in items}
for fut in as_completed(futures):
r = fut.result()
results.append(r)
@@ -1164,6 +1179,10 @@ 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"{r['item']}: held cells {r['loop']['held_fill']['unmade']['cells']} shown as filmed — RIFE is not installed"
+ for r in results if r.get("ok") and "unmade" in r["loop"]["held_fill"]]
+ + [f"{r['item']}: --out-fps {r['loop']['held_fill']['out_fps']['asked']:g} not met — {r['loop']['held_fill']['out_fps']['why']}"
+ for r in results if r.get("ok") and not r["loop"]["held_fill"].get("out_fps", {"applied": True})["applied"]]
+ [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)")
@@ -1280,6 +1299,13 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
help="which own foot lands on the first strike of an item's loop (e.g. front-walk=left), for a loop the "
"alignment report lists under `unnamed_feet` (video-cycle-align --foot; repeatable): that loop starts as "
"the set's start foot lands, recorded start_foot_source given")
+ parser.add_argument("--fill-held", choices=held_fill_mod.MODES, default="auto",
+ help="each cut's neighbour cells showing the same picture (video-loop --fill-held): auto (default) makes "
+ "them again with RIFE's frames between, off cuts them as filmed; each item's `loop.poses` says its poses "
+ "over its cells")
+ parser.add_argument("--out-fps", type=float, default=None,
+ help="give each cut at this rate, above its clip's, made of frames between (video-loop --out-fps); with "
+ "a walk or run filmed in two or more directions, pass --align-cycles off")
parser.add_argument("--force", action="store_true", help="regenerate clips that already exist")
@@ -1302,6 +1328,7 @@ def run(**kwargs: object) -> int:
body_plan=body_mod.parse_all(list(kwargs.get("body_plan") or [])) or None, # type: ignore[arg-type]
play=_parse_keyed(list(kwargs.get("play") or []), "--play") or None, # type: ignore[arg-type]
motion=_parse_keyed(list(kwargs.get("motion") or []), "--motion") or None, # type: ignore[arg-type]
+ fill_held=str(kwargs.get("fill_held") or "auto"), out_fps=kwargs.get("out_fps"), # type: ignore[arg-type]
)
return 0 if not payload["failed"] else 1
diff --git a/sprite_gen/video/held_fill.py b/sprite_gen/video/held_fill.py
new file mode 100644
index 0000000..ad73d00
--- /dev/null
+++ b/sprite_gen/video/held_fill.py
@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Held cells: neighbour cells of a cut that show the same picture, found, made again as the frames between the poses
+beside them, and read again (docs/loop-repair.md section 7).
+
+A clip may show a frame twice or three times in a row: a video model that stalls, a rate carried to another by
+repeating frames (20 fps in 24 repeats one in six), a cut mapped to a higher rate by taking the nearer frame. Played,
+the motion stops on that picture and jumps on: one pose, two or three cells. Each cut `video-loop` makes is read for
+them (`same_steps`, `reading`): the cells, the poses (the cells less the ones that show their neighbour's picture
+again) and each run of cells showing one picture (`held_runs`, its first cell and how many). The cells are read as
+filmed, before an anchor moves each frame of a pair apart.
+
+The same picture is a step no thumbnail pixel of which (the analysis thumbnail `video-loop` cuts by, premultiplied)
+changes by more than PIXEL_SAME, but for at most CHANGED_MAX of the subject's pixels. A textured figure shown three
+times, encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`, changes no pixel of a frame shown again by
+more than 0.008, 0.020 and 0.051; an arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the
+subject's pixels by more than PIXEL_SAME. A distance over the subject's mass (`nonloop.STABLE_MAX`, which reads a once
+cut's settled end) does not part them: the arm's pixel reads under it. Read on a thumbnail 96 px on its longer side, a
+small part's move of a fraction of one of its pixels reads as the same picture, as a hold plays.
+
+`fill` makes each run's cells again, between the run's first cell and the next pose, at their own times — the cells of a
+run of three a third and two thirds of the way — so the cut keeps its length, its beat, its first and last cells and
+its wrap: a made cell stands where a held cell stood. A run is kept as filmed where filling it would change what the
+cut means: longer than HOLD_MAX cells (a drawing held on threes is three: longer is a hold the motion means), the opening
+or the closing pose of a cut played once, the last cells of a loop (their next pose is across its wrap). A cut drawn on
+twos or threes keeps every run (`drawn`): limited animation, each drawing shown as long as the next. It is drawn so where
+its held-drawings reading (`held.measure_cycle`, which `video-cycle-align` reads) gives a hold of 2 or 3 and every run is
+that long, but a run cut short at the cut's first or last cell: a clip carried to a higher rate by repeating frames
+reads a hold too (24 fps carried to 60 shows each frame two or three times), its runs two and three cells by turns, and
+a clip that stalls now and then reads none. A frame made
+is judged as the frames the alignment makes are (`align.measure_made`, `faults`), and for a part standing still on
+both sides of it (`still_kept`: a foot planted, a hand on a ledge), which must stand where it stood; a frame refused is
+made again at another fraction of RETIME_T within half a cell of its own time, else the run is kept as filmed and says
+why. A run is made whole or kept whole: half made it would step back.
+
+`upsample` gives a cut at a rate above its own (`--out-fps`) its frames between, at their own times, never a frame
+shown again; a cell where both frames beside its time show one picture (a hold kept) is that picture."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from typing import Any
+
+from PIL import Image, ImageFilter
+
+from sprite_gen._deps import np
+from sprite_gen.video import held as held_mod
+from sprite_gen.video import legs as legs_mod
+from sprite_gen.video import rife as rife_mod
+from sprite_gen.video.interpolation_quality import faults, ghost_screen, looks
+
+MODES = ("auto", "off")
+PIXEL_SAME = 0.1 # a thumbnail pixel (premultiplied, 0..1) that changes by more than this has changed
+CHANGED_MAX = 0.005 # the same picture: at most this share of the subject's thumbnail pixels changed
+HOLD_MAX = max(held_mod.HOLDS) # a run of cells longer than a drawing on threes is a hold the motion means: kept
+# A part standing still on both sides of a frame made (`still_kept`): its outline pixels, solid (legs.LOW_ALPHA) and
+# within STILL_RGB of each other in both frames, must be solid and within STILL_RGB in the frame made, within a pixel,
+# for at least STILL_KEPT_MIN of them in every window of rife.GHOST_BAND of the body high holding STILL_MIN_PX or more.
+STILL_RGB = 24
+STILL_KEPT_MIN = 0.8
+STILL_MIN_PX = 12
+SNAP = 0.03 # a time within this of a frame takes that frame (align.SNAP)
+
+
+def _thumbs(frames: Sequence[Image.Image]) -> np.ndarray:
+ from sprite_gen.video.loop import _small_features # the thumbnail video-loop cuts by (loop imports this module)
+
+ return np.stack([_small_features(f).reshape(-1, 4) for f in frames])
+
+
+def same_steps(frames: Sequence[Image.Image]) -> list[bool]:
+ """For each step of `frames` (cell k to k + 1), whether the two show the same picture."""
+ t = _thumbs(frames)
+ out = []
+ for a, b in zip(t, t[1:]):
+ subject = int((np.maximum(a[:, 3], b[:, 3]) > 0.5).sum())
+ changed = int((np.abs(a - b).max(axis=1) > PIXEL_SAME).sum())
+ out.append(changed <= CHANGED_MAX * subject)
+ return out
+
+
+def runs(same: Sequence[bool]) -> list[dict[str, int]]:
+ """Each run of cells showing one picture: its first cell and how many (two or more). Not read across a wrap."""
+ found, k = [], 0
+ while k < len(same):
+ if not same[k]:
+ k += 1
+ continue
+ start = k
+ while k < len(same) and same[k]:
+ k += 1
+ found.append({"start": start, "length": k - start + 1})
+ return found
+
+
+def reading(same: Sequence[bool]) -> dict[str, Any]:
+ """The cells, the poses and the held runs of a cut whose steps are `same`."""
+ held = runs(same)
+ cells = len(same) + 1
+ return {"cells": cells, "poses": cells - sum(r["length"] - 1 for r in held), "held_runs": held}
+
+
+def said(record: dict[str, Any]) -> str:
+ """The poses over the cells, as a person is told them: `poses/cells`."""
+ return f"{record['poses']}/{record['cells']}"
+
+
+def _edge(solid: np.ndarray) -> np.ndarray:
+ inner = np.asarray(Image.fromarray(np.uint8(solid) * 255).filter(ImageFilter.MinFilter(3))) > 0
+ return solid & ~inner
+
+
+def still_kept(frame: Image.Image, a: Image.Image, b: Image.Image) -> dict[str, Any]:
+ """Whether a part standing still in `a` and `b` stands where it stood in `frame`, made between them: the outline
+ pixels both draw in one place in one colour (`still`), and the share of them `frame` draws there too, within a
+ pixel (`kept`), the least over windows of rife.GHOST_BAND of the body high that hold STILL_MIN_PX of them (`reads`
+ false where none does)."""
+ A, B, F = (np.asarray(im.convert("RGBA"), dtype=np.int16) for im in (a, b, frame))
+ sa, sb, sf = (x[..., 3] >= legs_mod.LOW_ALPHA for x in (A, B, F))
+ still = _edge(sa) & _edge(sb) & (np.abs(A[..., :3] - B[..., :3]).max(axis=-1) <= STILL_RGB)
+ drawn = sf & (np.abs(F[..., :3] - A[..., :3]).max(axis=-1) <= STILL_RGB)
+ near = np.asarray(Image.fromarray(np.uint8(drawn) * 255).filter(ImageFilter.MaxFilter(3))) > 0
+ rows = np.nonzero((sa | sb).any(axis=1))[0]
+ if not rows.size:
+ return {"reads": False, "still_px": 0}
+ top, bottom = int(rows[0]), int(rows[-1])
+ win = max(8, round((bottom - top + 1) * rife_mod.GHOST_BAND))
+ still_rows, kept_rows = still.sum(axis=1), (still & near).sum(axis=1)
+ least, at = None, None
+ for y in range(top, max(top, bottom - win + 1) + 1, max(1, win // 4)):
+ n = int(still_rows[y:y + win].sum())
+ if n >= STILL_MIN_PX:
+ share = float(kept_rows[y:y + win].sum()) / n
+ if least is None or share < least:
+ least, at = share, y
+ if least is None:
+ return {"reads": False, "still_px": int(still.sum())}
+ return {"reads": True, "still_px": int(still.sum()), "kept": round(least, 4), "at_row": at, "window_px": win}
+
+
+def judge(frame: Image.Image, a: Image.Image, b: Image.Image, t: float, *, reads: bool) -> tuple[dict[str, Any], list[str]]:
+ """A frame made between `a` and `b` at `t`: the alignment's measure and faults (`align.measure_made`, `faults`),
+ and `contact` where a part standing still on both sides does not stand where it stood (`still_kept`)."""
+ from sprite_gen.video.align import measure_made # align imports loop, which imports this module
+
+ measure = measure_made(frame, a, b, t, reads=reads)
+ contact = still_kept(frame, a, b)
+ wrong = faults(measure) + (["contact"] if contact["reads"] and contact["kept"] < STILL_KEPT_MIN else [])
+ return {**measure, "contact": contact}, wrong
+
+
+def _made(interpolate: rife_mod.Interpolate, a: Image.Image, b: Image.Image, t: float, window: tuple[float, float], *,
+ reads: bool) -> tuple[Image.Image | None, dict[str, Any]]:
+ """The frame between `a` and `b` at `t`, or at the fraction of RETIME_T nearest it inside `window` that is made
+ with no fault and, made only off its time, with its ghost band under RETIME_WINDOW_MAX in every window (align's
+ bar for a frame made again at another fraction); None and what each try was refused for, where none is."""
+ from sprite_gen.video.align import RETIME_T, RETIME_WINDOW_MAX
+
+ tries = []
+ for at in [t] + sorted((r for r in RETIME_T if window[0] < r < window[1] and abs(r - t) > 1e-3), key=lambda r: (abs(r - t), r)):
+ frame = interpolate(a, b, at)
+ measure, wrong = judge(frame, a, b, at, reads=reads)
+ seen = at != t and (measure.get("ghost_window") or 0.0) >= RETIME_WINDOW_MAX
+ tries.append({"t": round(at, 4), "faults": wrong, **({"window_over": RETIME_WINDOW_MAX} if seen and not wrong else {})})
+ if not wrong and not seen:
+ return frame, {"t": round(at, 4), **({"from_t": round(t, 4)} if at != t else {}),
+ "contact": measure["contact"], "look": looks(measure), "tries": tries}
+ return None, {"t": round(t, 4), "tries": tries}
+
+
+def drawn(found: Sequence[dict[str, int]], n: int, hold: int | None) -> int | None:
+ """The hold of a cut of `n` cells drawn on twos or threes, or None: the held-drawings reading's `hold` 2 or 3, and
+ every held run `found` that many cells long, but one cut short at the cut's first or last cell (see the module)."""
+ if hold not in held_mod.HOLDS or not found:
+ return None
+ edge = lambda r: r["start"] == 0 or r["start"] + r["length"] == n # noqa: E731
+ return hold if all(r["length"] == hold or (r["length"] < hold and edge(r)) for r in found) else None
+
+
+def _fillable(run: dict[str, int], n: int, *, ring: bool, on: int | None = None) -> str | None:
+ """Why a held run is kept as filmed, or None where it is made again. `on` is the hold of a cut drawn on twos or
+ threes (`drawn`)."""
+ if on is not None:
+ return (f"the cut is drawn on {'twos' if on == 2 else 'threes'} (its held-drawings reading holds {on}, and so does "
+ "every run): limited animation, kept as filmed")
+ if run["length"] > HOLD_MAX:
+ return (f"held {run['length']} cells, longer than a drawing on threes ({HOLD_MAX}): a hold the motion means, "
+ "kept as filmed")
+ if run["start"] + run["length"] == n:
+ return ("the loop's last cells: their next pose is across its wrap, and the wrap stays as cut" if ring else
+ "the cut's closing pose, kept as filmed")
+ if run["start"] == 0 and not ring:
+ return "the cut's opening pose, kept as filmed"
+ return None
+
+
+def fill(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool,
+ same: Sequence[bool] | None = None, mode: str = "auto", reads: bool | None = None,
+ hold: int | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`frames` with each held run's cells made again between the run's first cell and the next pose (see the module),
+ and the record: the reading before (`before`, each run `filled` or why not), the cells made (`made`, and how each
+ was, `frames`), the cells left for want of an interpolator (`unmade`, `interpolate` None), the hold of a cut drawn
+ on twos or threes (`drawn`), and the reading of the frames returned (`cells`, `poses`, `held_runs`). `same` is the
+ steps' reading as filmed (`same_steps` of `frames` where None); `reads` whether the ghost screen reads the cut (read
+ on `frames` where None); `hold` the cut's held-drawings reading (`held.measure_cycle`)."""
+ if mode not in MODES:
+ raise ValueError(f"fill mode {mode!r}: one of {', '.join(MODES)}")
+ same = list(same_steps(frames) if same is None else same)
+ n = len(frames)
+ on = drawn(runs(same), n, hold)
+ out = list(frames)
+ before = []
+ made: list[int] = []
+ unmade: list[int] = []
+ rows: list[dict[str, Any]] = []
+ for run in runs(same):
+ row: dict[str, Any] = dict(run)
+ cells = list(range(run["start"] + 1, run["start"] + run["length"]))
+ why = "--fill-held off" if mode == "off" else _fillable(run, n, ring=ring, on=on)
+ if why is None and interpolate is None:
+ unmade += cells
+ why = "no interpolator"
+ if why is not None:
+ before.append({**row, "filled": False, "why": why})
+ continue
+ if reads is None:
+ reads = bool(ghost_screen(frames)["reads"])
+ a, b = run["start"], run["start"] + run["length"]
+ taken, tried = [], []
+ for c in cells:
+ t = (c - a) / (b - a)
+ half = 0.5 / (b - a)
+ frame, how = _made(interpolate, frames[a], frames[b % n], t, (t - half, t + half), reads=reads)
+ tried.append({"cell": c, "between": [a, b % n], **how})
+ if frame is None:
+ break
+ taken.append((c, frame))
+ if len(taken) < len(cells):
+ refused = sorted({f for row_ in tried for t_ in row_["tries"] for f in t_["faults"]})
+ before.append({**row, "filled": False, "faults": refused, "tries": tried,
+ "why": f"a frame between was refused ({', '.join(refused) or 'ghost band over the retime bar'}): kept as filmed"})
+ continue
+ for c, frame in taken:
+ out[c] = frame
+ made += cells
+ rows += tried
+ before.append({**row, "filled": True, "made": cells})
+ record: dict[str, Any] = {
+ "mode": mode, "pixel_same": PIXEL_SAME, "changed_max": CHANGED_MAX, "hold_max": HOLD_MAX,
+ "before": {**reading(same), "held_runs": before},
+ "made": made, "frames": rows,
+ "contact": [{"cell": r["cell"], **r["contact"]} for r in rows if r["contact"]["reads"]],
+ }
+ if on is not None:
+ record["drawn"] = on
+ if unmade:
+ record["unmade"] = {"cells": unmade}
+ record.update(reading(same_steps(out)) if made else reading(same))
+ return out, record
+
+
+def times(n: int, fps: float, out_fps: float, *, ring: bool) -> list[float]:
+ """The times, in frames of the cut, of the cells of a cut of `n` frames at `fps` given at `out_fps`: a loop's
+ round(n·out_fps/fps) cells over its cycle, a cut played once from its first frame to its last."""
+ if ring:
+ count = round(n * out_fps / fps)
+ return [k * n / count for k in range(count)]
+ count = round((n - 1) * out_fps / fps) + 1
+ return [k * (n - 1) / (count - 1) for k in range(count)]
+
+
+def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ring: bool, fps: float, out_fps: float,
+ reads: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`frames` given at `out_fps` (`times`): a cell on a frame's time is that frame, one between two frames showing
+ one picture is that picture, any other is made between the two at its own time (`_made`, within half a cell of
+ it), and one no frame made is taken for is the nearer frame and named (`shown_again`)."""
+ n = len(frames)
+ at = times(n, fps, out_fps, ring=ring)
+ same = same_steps(frames + ([frames[0]] if ring else []))
+ if reads is None:
+ reads = bool(ghost_screen(frames)["reads"])
+ spacing = fps / out_fps
+ out: list[Image.Image] = []
+ made: list[dict[str, Any]] = []
+ shown_again: list[int] = []
+ for k, tau in enumerate(at):
+ near = round(tau)
+ if abs(tau - near) <= SNAP:
+ out.append(frames[near % n])
+ continue
+ a = math.floor(tau)
+ if same[a]:
+ out.append(frames[a])
+ continue
+ t = tau - a
+ frame, how = _made(interpolate, frames[a], frames[(a + 1) % n], t, (t - spacing / 2, t + spacing / 2), reads=reads)
+ if frame is None:
+ out.append(frames[near % n])
+ shown_again.append(k)
+ made.append({"cell": k, "between": [a, (a + 1) % n], "taken": near % n, **how})
+ continue
+ out.append(frame)
+ made.append({"cell": k, "between": [a, (a + 1) % n], **how})
+ return out, {"asked": out_fps, "fps": fps, "applied": True, "cells": len(out), "times": [round(x, 4) for x in at],
+ "made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made}
+
+
+def public(record: dict[str, Any]) -> dict[str, Any]:
+ """The record as the strip metadata carries it: the reading as delivered (`cells`, `poses`, `held_runs`), before
+ (each run `filled` or why not, with its faults), the cells made and left, and the rate asked — not each try."""
+ out: dict[str, Any] = {k: record[k] for k in ("mode", "why", "drawn", "cells", "poses", "held_runs", "made") if k in record}
+ before = record["before"]
+ out["before"] = {"cells": before["cells"], "poses": before["poses"],
+ "held_runs": [{k: v for k, v in r.items() if k != "tries"} for r in before["held_runs"]]}
+ if "unmade" in record:
+ out["unmade"] = {k: record["unmade"][k] for k in ("cells", "why", "install") if k in record["unmade"]}
+ if "out_fps" in record:
+ out["out_fps"] = {k: record["out_fps"][k] for k in ("asked", "fps", "applied", "cells", "made", "shown_again", "why", "install")
+ if k in record["out_fps"]}
+ return out
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 0c6b674..5f6191a 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -53,6 +53,7 @@ from sprite_gen.video import part_pop as part_pop_mod
from sprite_gen.video import cadence as cadence_mod
from sprite_gen.video import crossings as crossings_mod
from sprite_gen.video import held as held_mod
+from sprite_gen.video import held_fill as held_fill_mod
from sprite_gen.video import body_turn as body_turn_mod
from sprite_gen.video import legs as legs_mod
from sprite_gen.video import period as period_mod
@@ -1315,6 +1316,91 @@ def _bridge_lines(bridge: dict[str, Any]) -> list[str]:
return [f"{said}, and no frames made round it close it ({refused}): cut as filmed (docs/loop-repair.md section 2)"]
+def _located(interpolate: rife_mod.Interpolate | None, made_by: list[dict[str, str]]) -> Any:
+ """`interpolate`, or RIFE located the first time a frame is asked for (`made_by` then names it)."""
+ def lazy(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
+ nonlocal interpolate
+ if interpolate is None:
+ found = rife_mod.Rife()
+ made_by.append(found.describe())
+ interpolate = found
+ return interpolate(a, b, t)
+
+ lazy.counts = lambda: interpolate.counts() if made_by else {} # type: ignore[attr-defined]
+ return lazy
+
+
+def _fill_held(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, same: list[bool],
+ mode: str, hold: int | None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`held_fill.fill` on the cut, with RIFE located only once a frame is to be made: a cut with no held cell, or only
+ runs kept as filmed, needs no binary. The record names the interpolator that made the frames. A frame to make and no
+ RIFE installed: the held cells are delivered as filmed, and the record says which and how to install it (`unmade`)."""
+ made_by: list[dict[str, str]] = []
+ lazy = _located(interpolate, made_by)
+ asked = partial(held_fill_mod.fill, ring=ring, same=same, mode=mode, hold=hold)
+ try:
+ frames, record = asked(frames, lazy)
+ except rife_mod.RifeNotInstalled as exc:
+ # RIFE is located before the first frame is made, so nothing was made yet: read again with no interpolator.
+ frames, record = asked(frames, None)
+ record["unmade"].update(why="RIFE is not installed", rife=str(exc), install=rife_mod.install_command())
+ return frames, record
+ if record["made"]:
+ record["interpolator"] = {**made_by[0], **lazy.counts()} if made_by else {"kind": "injected"}
+ return frames, record
+
+
+def _upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, fps: float,
+ out_fps: float) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`held_fill.upsample` on the cut, with RIFE located only once a frame is to be made. No RIFE installed: the cut is
+ delivered at its own rate, never with a frame shown again for each cell between, and the record says so."""
+ made_by: list[dict[str, str]] = []
+ lazy = _located(interpolate, made_by)
+ try:
+ out, record = held_fill_mod.upsample(frames, lazy, ring=ring, fps=fps, out_fps=out_fps)
+ except rife_mod.RifeNotInstalled as exc:
+ return frames, {"asked": out_fps, "fps": fps, "applied": False, "cells": len(frames),
+ "why": "RIFE is not installed", "rife": str(exc), "install": rife_mod.install_command()}
+ if record["made"]:
+ record["interpolator"] = {**made_by[0], **lazy.counts()} if made_by else {"kind": "injected"}
+ return out, record
+
+
+def _fill_lines(record: dict[str, Any]) -> list[str]:
+ """What became of the cut's held cells, in words (`video-loop: warning:` lines): the cells left for want of RIFE, the
+ runs a frame between was refused for, the frames made to look at. A run kept as the motion's own says nothing."""
+ lines = []
+ if "unmade" in record:
+ cells = record["unmade"]["cells"]
+ lines.append(f"{len(cells)} held cell{'s' if len(cells) > 1 else ''} ({', '.join(map(str, cells))}) shown as filmed — "
+ f"RIFE is not installed, so no frame between was made ({held_fill_mod.said(record['before'])} poses/cells); "
+ f"run `{record['unmade']['install']}` and cut it again (docs/loop-repair.md section 7)")
+ for run in record["before"]["held_runs"]:
+ if run.get("faults") is not None:
+ last = run["start"] + run["length"] - 1
+ lines.append(f"held cells {run['start']}-{last} kept as filmed: {run['why']} — look at them in the loop, or film "
+ "it again (docs/loop-repair.md section 7)")
+ for made in record.get("frames", []):
+ if made["look"]:
+ a, b = made["between"]
+ lines.append(f"cell {made['cell']} was made between cells {a} and {b}, which may cross-fade two drawings inside "
+ "its outline; kept, a reading to look at (docs/loop-repair.md section 4)")
+ return lines
+
+
+def _out_fps_lines(record: dict[str, Any]) -> list[str]:
+ """What became of a rate asked above the clip's (`--out-fps`), in words: not met for want of RIFE, or cells where no
+ frame between was made and the frame beside them is shown again."""
+ if not record["applied"]:
+ return [f"--out-fps {record['asked']:g} was not met — RIFE is not installed, so the cut is delivered at its own "
+ f"{record['fps']:g} fps; run `{record['install']}` and cut it again (docs/loop-repair.md section 7)"]
+ again = record["shown_again"]
+ if not again:
+ return []
+ return [f"{len(again)} cell{'s' if len(again) > 1 else ''} of --out-fps {record['asked']:g} ({', '.join(map(str, again))}) "
+ "show the frame beside them again: no frame between was made there without a fault (docs/loop-repair.md section 7)"]
+
+
def _shifts(analysis: dict[str, Any]) -> tuple[np.ndarray, int]:
"""The analysis translation `auto_motion.analyse` measured, whole pixels a frame, and the room it needs."""
shifts = np.rint(np.asarray(analysis["analysis_only_translation_xy"], dtype=np.float64)).astype(int)
@@ -2115,6 +2201,8 @@ def _cut_loop(
unfixed: str = "warn",
seam_pop_max: float | None = repair_mod.SEAM_POP_REFERENCE,
body_turn: str = "warn",
+ fill_held: str = "auto",
+ out_fps: float | None = None,
) -> dict[str, Any]:
state = state.strip().lower() if state else state
if state == effect.STATE:
@@ -2154,6 +2242,14 @@ def _cut_loop(
raise SystemExit(f"video-loop: --seam-pop-max {seam_pop_max}: a bound over 0, or off")
if body_turn not in body_turn_mod.MODES:
raise SystemExit(f"video-loop: unknown --body-turn {body_turn!r}; expected one of {', '.join(body_turn_mod.MODES)}")
+ if fill_held not in held_fill_mod.MODES:
+ raise SystemExit(f"video-loop: unknown --fill-held {fill_held!r}; expected one of {', '.join(held_fill_mod.MODES)}")
+ if out_fps is not None:
+ if not (math.isfinite(out_fps) and out_fps > fps):
+ raise SystemExit(f"video-loop: --out-fps {out_fps:g} is not above the clip's {fps:g} fps: a cut is given at a higher "
+ "rate than it was filmed (its frames between made), a lower one is its preview's (--gif-fps)")
+ if cycle_mode == "lifetime":
+ raise SystemExit("video-loop: --out-fps: an effect's lifetime plays as filmed")
if anchor is None:
# gaits drift a few pixels over a cycle and the wrap shows it; in-place states do not
anchor = "body" if profile_for(state).gait else "none"
@@ -2422,6 +2518,7 @@ def _cut_loop(
# ~gif_fps (a fixed 12 made a 2.5 s jump hold each frame 210 ms while a 1.1 s walk held 90 ms)
if n_out is None:
n_out = max(GIF_FRAMES_MIN, round(L / fps * gif_fps))
+ n_asked = n_out
n_out = min(n_out, L) # never ask for more distinct frames than the cycle holds
out_dir = out_dir.expanduser().resolve()
@@ -2443,6 +2540,9 @@ def _cut_loop(
im, d = drop_specks(im, alpha_over=16, diagonal=False, apart=0)
specks += d
frames.append(im)
+ # Each step of the cut as filmed, read for a picture shown again (held_fill.same_steps): before an anchor moves each
+ # frame of a pair apart.
+ same = held_fill_mod.same_steps(frames)
if prof.gait:
report_base["gait"] = evidence_mod.gait_observation(frames, cycle)
@@ -2474,6 +2574,28 @@ def _cut_loop(
"recipe": RECIPE, "wrap_dx_px": wrap_dx,
"before_repair_pixels_sha256": [evidence_mod.digest(f.tobytes()) for f in frames],
}
+ # A loop closes on its first cell again; a cut played once runs from its first to its last.
+ ring = cycle["kind"] not in ("one-shot", "lifetime", *nonloop.KINDS)
+ if cycle["kind"] == "lifetime":
+ report_base["held_fill"] = {"mode": fill_held, "why": "an effect's lifetime is played as filmed", "made": [],
+ "before": held_fill_mod.reading(same), **held_fill_mod.reading(same)}
+ else:
+ # The cells that show the picture before them again, made between the poses beside them (docs/loop-repair.md
+ # section 7), on the cut as anchored, before anything reads its flow or its wrap. A cut drawn on twos or threes
+ # keeps them: its hold as video-cycle-align reads it, over the cut, else over the clip.
+ cut_drawings = report_base["cycle_drawings"]
+ hold = cut_drawings["hold"] if cut_drawings["hold"] is not None else report_base["drawings"]["hold"]
+ try:
+ frames, report_base["held_fill"] = _fill_held(frames, interpolate, ring=ring, same=same, mode=fill_held, hold=hold)
+ except (ValueError, rife_mod.RifeUnavailable) as exc:
+ error = (f"video-loop: {exc}; the cut shows a picture again and the frames between are to be made — fix RIFE, "
+ "or pass --fill-held off to cut it as filmed (docs/loop-repair.md section 7)")
+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})
+ raise SystemExit(error) from exc
+ if report_base["held_fill"]["made"]:
+ report_base["seam_measurement"] = "rendered-cells"
+ for line in _fill_lines(report_base["held_fill"]):
+ print(f"video-loop: warning: {name}: {line}", file=sys.stderr)
if prof.gait:
# The ghost screen of the cut as filmed (docs/loop-repair.md section 4), read before the jump repair: each
# filmed ghost it names is a target of that repair, which gives it way to a clean frame where there is one.
@@ -2649,6 +2771,29 @@ def _cut_loop(
if not report_base["ghost_screen"]["reads"]:
print(f"video-loop: warning: the ghost screen does not read this cut — {report_base['ghost_screen']['why']}; no frame "
"of it is named a ghost, here or in video-cycle-align, so look at cycle/ (docs/loop-repair.md)", file=sys.stderr)
+ held_record = report_base["held_fill"]
+ upsampled = None
+ if out_fps is not None:
+ # A rate above the clip's: every cell at its own time, made between the frames beside it (held_fill.upsample).
+ try:
+ frames, held_record["out_fps"] = _upsample(frames, interpolate, ring=ring, fps=fps, out_fps=out_fps)
+ except (ValueError, rife_mod.RifeUnavailable) as exc:
+ error = (f"video-loop: {exc}; --out-fps {out_fps:g} makes the frames between the clip's — fix RIFE, or cut it "
+ "without --out-fps (docs/loop-repair.md section 7)")
+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})
+ raise SystemExit(error) from exc
+ for line in _out_fps_lines(held_record["out_fps"]):
+ print(f"video-loop: warning: {name}: {line}", file=sys.stderr)
+ if held_record["out_fps"]["applied"]:
+ upsampled = held_record["out_fps"]["times"]
+ report_base["seam_measurement"] = "rendered-cells"
+ as_filmed = {} # the cells are each made at a time of their own: read as they play
+ if not ring:
+ cycle_seconds = len(frames) / out_fps # first to last frame as filmed, each cell 1/out_fps
+ n_out = min(n_asked, len(frames))
+ # The cut as delivered, read again: its poses over its cells.
+ held_record.update(held_fill_mod.reading(held_fill_mod.same_steps(frames)))
+ C = len(frames) # the cells delivered: the cut's frames, or more at --out-fps
cycle_dir.mkdir(parents=True, exist_ok=True)
for old in cycle_dir.glob("frame-*.png"):
old.unlink()
@@ -2680,9 +2825,14 @@ def _cut_loop(
# The cut as its seam is read: each cell given way to the frame beside it as filmed (`seam_as_filmed`).
seam_frames = [as_filmed.get(k, f) for k, f in enumerate(frames)]
strip_meta["source_cut"] = {"source": report_base["source"], "start": i, "length": L,
- "samples": [i + k for k in strip_meta["sample_indices"]]}
+ **({"samples": [i + k for k in strip_meta["sample_indices"]]} if upsampled is None else
+ {"times": [round(i + upsampled[k], 4) for k in strip_meta["sample_indices"]]})}
+ if upsampled is not None:
+ # Each cell is a time of its own, at a rate above the clip's: the cells are not the clip's frames.
+ strip_meta.update(out_fps=out_fps, source_fps=fps)
if cycle["kind"] in nonloop.KINDS:
- strip_meta.update(nonloop.metadata(cycle, strip_meta["sample_indices"]))
+ strip_meta.update(nonloop.metadata(cycle, strip_meta["sample_indices"] if upsampled is None else
+ [upsampled[k] for k in strip_meta["sample_indices"]]))
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()
@@ -2698,6 +2848,8 @@ def _cut_loop(
} | ({"why": report_base["cycle_drawings"]["why"]} if "why" in report_base["cycle_drawings"] else {})
if "clip_feet" in report_base:
strip_meta["clip_feet"] = report_base["clip_feet"]
+ # The cut's held cells, what became of them, and its poses over its cells (docs/loop-repair.md section 7).
+ strip_meta["held_fill"] = held_fill_mod.public(held_record)
# A cut frame that is no longer the frame as filmed for a filmed ghost, and one kept with no clean frame beside
# it: `cycle/` is the alignment's material (`cycle.source/`), whose screen no longer sees a ghost given way, so the
# strip says it, and an alignment carries it over (frames of the cut).
@@ -2734,9 +2886,10 @@ def _cut_loop(
idx = [strip_meta["sample_indices"][k] for k in preview_indices]
pick = [strip.crop((k * strip_meta["w"], 0, (k + 1) * strip_meta["w"], strip_meta["h"])) for k in preview_indices]
else:
- idx = [min(L - 1, i2) for i2 in (round(k * L / n_out) for k in range(n_out))]
- pick = resampled_cells(strip, strip_meta, idx, L)
- seam_idx = [i + j for j in idx]
+ idx = [min(C - 1, i2) for i2 in (round(k * C / n_out) for k in range(n_out))]
+ pick = resampled_cells(strip, strip_meta, idx, C)
+ # The source frames the distances were read on: a cell made at --out-fps reads as the frame at or before its time.
+ seam_idx = [i + (j if upsampled is None else min(L - 1, math.floor(upsampled[j]))) for j in idx]
on_cells = report_base["seam_measurement"] == "rendered-cells"
# A walk's or run's seam is read between its drawings, as its steps are (`seam_drawings`), where the seam ratio gates
# the cut: not a pin or a cut played once. Any other loop's, and a walk drawn a frame each, on every frame.
@@ -2757,7 +2910,7 @@ def _cut_loop(
if on_cells or ramped:
# The actual corrected/repaired/resampled strip cells, with the same limit — a cell given way to the frame
# beside it as filmed (`seam_as_filmed`), on the strip the cut makes with those frames; a walk's between its drawings.
- cells = resampled_cells(*strip_of(seam_frames), idx, L) if as_filmed else pick
+ cells = resampled_cells(*strip_of(seam_frames), idx, C) if as_filmed else pick
on, cells_read = seam_drawings(cells) if by_drawing else (list(range(len(cells))), None)
adjacent, wrap, steps = _seam_on_cells([cells[k] for k in on])
if ramped:
@@ -2979,6 +3132,19 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
"another holds a cycle. Where none does: warn (default), the cut the search takes with the turn in, "
"and a warning line; refuse, the clip is refused in a line of its own (`video-loop: the body turns "
"in the walk`), to be filmed again at the still's angle")
+ parser.add_argument("--fill-held", choices=held_fill_mod.MODES, default="auto",
+ help="neighbour cells of the cut that show the same picture (a frame shown twice or three times): auto "
+ "(default) makes each run of them again with RIFE's frames between the pose before and the pose "
+ f"after, the cut's length, beat, first and last cells and wrap kept, and a run longer than "
+ f"{held_fill_mod.HOLD_MAX} cells, the opening or closing pose of a cut played once, a loop's last "
+ "cells and a cut drawn on twos or threes kept as filmed; off cuts them as filmed. Either way the report and the strip metadata record "
+ "the held runs and the poses over the cells (`held_fill`, docs/loop-repair.md section 7); with no "
+ "RIFE installed the cells are shown as filmed, with a warning")
+ parser.add_argument("--out-fps", type=float, default=None,
+ help="give the cut at this rate, above the clip's (--fps): every cell at its own time, made by RIFE "
+ "between the frames beside it — never a frame shown again. A loop keeps its cycle's seconds, a "
+ "cut played once runs from its first frame to its last; the strip metadata says `out_fps`. With no "
+ "RIFE installed the cut is delivered at its own rate, with a warning (docs/loop-repair.md section 7)")
parser.add_argument("--name", default="loop", help="basename for strip/gif/webp outputs")
parser.add_argument("--report", type=Path)
@@ -3001,6 +3167,7 @@ def run(**kwargs: object) -> int:
unfixed=str(kwargs.get("unfixed") or "warn"),
seam_pop_max=kwargs.get("seam_pop_max", repair_mod.SEAM_POP_REFERENCE), # type: ignore[arg-type]
body_turn=str(kwargs.get("body_turn") or "warn"),
+ fill_held=str(kwargs.get("fill_held") or "auto"), out_fps=kwargs.get("out_fps"), # type: ignore[arg-type]
)
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")}
@@ -3068,6 +3235,11 @@ def run(**kwargs: object) -> int:
if payload.get("retake"):
summary["retake"] = {k: payload["retake"][k] for k in ("reason", "remedy")}
summary["strip"] = {k: payload["strip"][k] for k in ("path", "frames", "w", "h", "body_h", "delay_ms")}
+ held = payload["held_fill"]
+ summary["held_fill"] = {"poses_cells": held_fill_mod.said(held), "before": held_fill_mod.said(held["before"]),
+ "held_runs": held["held_runs"], "made": held["made"],
+ **({"unmade": held["unmade"]["cells"]} if "unmade" in held else {}),
+ **({"out_fps": {k: held["out_fps"][k] for k in ("asked", "applied", "cells")}} if "out_fps" in held else {})}
print(json.dumps(summary, ensure_ascii=False, indent=2))
return 0
diff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.py
index d51107c..959e8a8 100644
--- a/sprite_gen/video/source.py
+++ b/sprite_gen/video/source.py
@@ -207,7 +207,9 @@ def project(baseline: Any, source: Source) -> tuple[Projection | None, str | Non
# A held cut is read again only where its report records each frame's move, and the cut's frames before repair to
# prove every one of them on (`source_projection`, the moves of the cells the repair replaced included).
held = bool(hold.get("applied"))
- if (any(k in m for k in ("cycle_align", "motion_anchor", "wrap_blend"))
+ # A cut whose held cells were made again (`held_fill`), or whose cells are times of their own (`out_fps`), shows
+ # frames the source does not hold.
+ if (any(k in m for k in ("cycle_align", "motion_anchor", "wrap_blend", "out_fps")) or (m.get("held_fill") or {}).get("made")
or held and ("cut_frames" not in hold or report.get("source_projection") is None)):
return None, "source-processing-unsupported"
moves, pad = _cut_moves(hold, n) if held else (None, None)
diff --git a/sprite_gen/video/stop.py b/sprite_gen/video/stop.py
index 9029105..113c8c1 100644
--- a/sprite_gen/video/stop.py
+++ b/sprite_gen/video/stop.py
@@ -68,6 +68,7 @@ from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.util.resample import resize_cell
from sprite_gen.video import evidence as evidence_mod
from sprite_gen.video import gait_fallback
+from sprite_gen.video import held_fill as held_fill_mod
from sprite_gen.video import loop as loop_mod
from sprite_gen.video import nonloop
from sprite_gen.video.interpolation_quality import ghost_screen
@@ -132,6 +133,9 @@ def read_loop(meta_path: Path) -> tuple[dict[str, Any], list[Image.Image], str]:
raise SystemExit(f"{PROG}: {strip_path.name} is {strip.size[0]}x{strip.size[1]}, its sidecar says {n * w}x{h}")
if meta.get("loop") is False:
raise SystemExit(f"{PROG}: {meta_path.name} plays once (loop false); a stop leaves a loop")
+ if "out_fps" in meta:
+ raise SystemExit(f"{PROG}: {meta_path.name} was cut at --out-fps {meta['out_fps']:g}, its cells each a time of their own; "
+ "a stop is cut from a loop at its clip's rate (video-loop without --out-fps)")
state = str(meta.get("state") or "")
if not loop_mod.profile_for(state).gait:
raise SystemExit(f"{PROG}: {meta_path.name} is a {state or 'state-less'} loop; a stop is cut from a walk or run loop")
@@ -422,7 +426,13 @@ def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = "
last = _box(stop_cells[-1])
# Read as filmed, at the keyed frames' own size, as video-loop reads its cut: a part-covered band is a
# number of pixels thick, and scaled down a ghost's band falls under it.
- screen = ghost_screen([Image.open(files[j]).convert("RGBA") for j in shown])
+ filmed = [Image.open(files[j]).convert("RGBA") for j in shown]
+ screen = ghost_screen(filmed)
+ # The stop's frames shown again (docs/loop-repair.md section 7): named, never made between — a stop plays the clip's
+ # filmed frames, none made between two others.
+ reading = held_fill_mod.reading(held_fill_mod.same_steps(filmed))
+ held = {"mode": "off", "why": "a stop plays the clip's filmed frames, none made between two others", "made": [],
+ "before": reading, **reading}
for g in screen.get("ghosts", []):
g["clip_frame"] = shown[g["frame"]]
delay = round(1000 / fps, 2)
@@ -435,7 +445,7 @@ def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = "
"from_loop": {"strip_sha256": strip_sha, "state": meta.get("state"), "frames": len(cells), "w": w, "h": h,
"from_cell": found["entry"]["from_cell"]},
"source_cut": {"source": identity, "frames": shown, "entry": found["entry"]["frame"], "rest_end": found["rest"]["end"]},
- "speed": speed, "seam_steps": found["seam"]["steps"],
+ "speed": speed, "seam_steps": found["seam"]["steps"], "held_fill": held,
}
out_dir.mkdir(parents=True, exist_ok=True)
strip = Image.new("RGBA", (cw * len(stop_cells), ch), (0, 0, 0, 0))
@@ -469,6 +479,9 @@ def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = "
f"{100 * g['ghost']:.2f} % of its body — a filmed ghost, kept as filmed", file=sys.stderr)
if not screen["reads"]:
print(f"{PROG}: warning: the ghost screen does not read this stop — {screen['why']}", file=sys.stderr)
+ for run in held["held_runs"]:
+ print(f"{PROG}: warning: cells {run['start']}-{run['start'] + run['length'] - 1} show one picture "
+ f"({held_fill_mod.said(held)} poses/cells): the clip stalls there, played as filmed", file=sys.stderr)
payload["report"] = str(target)
return payload
diff --git a/tests/frames/test_chroma_decontam.py b/tests/frames/test_chroma_decontam.py
index e582983..4199823 100644
--- a/tests/frames/test_chroma_decontam.py
+++ b/tests/frames/test_chroma_decontam.py
@@ -680,7 +680,7 @@ def test_video_set_hands_its_decontam_to_video_frames_and_lists_the_warning(tmp_
monkeypatch.setattr(batch.frames_mod, "run_frames", frames_stub)
monkeypatch.setattr(batch.loop_mod, "run_loop", lambda *a, **kw: {
"cycle": {"length": 10, "period_global": 10, "ratio": 0.2},
- "resampled_seam_ratio": 0.2, "n_out": 10, "gif": {"file": "loop.gif"},
+ "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10, "gif": {"file": "loop.gif"},
"webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}})
monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
still = Path(__file__).parents[1] / "fixtures" / "facing" / "left.png"
diff --git a/tests/video/held_fill_inputs.py b/tests/video/held_fill_inputs.py
new file mode 100644
index 0000000..b594f14
--- /dev/null
+++ b/tests/video/held_fill_inputs.py
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Synthetic clips for the held-cell tests (tests/video/test_held_fill.py): figures that move every frame, and the same
+figures with frames shown again. No real footage."""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+W, H = 120, 140
+N = 24 # a walk's cycle, frames
+
+
+def walker(phase: float) -> Image.Image:
+ """A torso and head that bob a pixel with the step, and a dark foot going round a circle at an even speed, far enough
+ a frame that a third of one moves it a pixel or more: every frame moves, and every time between two frames."""
+ a = np.zeros((H, W, 4), dtype=np.uint8)
+ bob = round(2 * (1 + math.cos(2 * phase)) / 2)
+ a[30 + bob:100, 50:70] = (90, 90, 200, 255)
+ a[10 + bob:30 + bob, 48:72] = (230, 190, 160, 255)
+ fx, fy = 60 + round(28 * math.cos(phase)), 105 + round(28 * math.sin(phase))
+ a[fy - 6:fy + 6, fx - 6:fx + 6] = (60, 60, 60, 255)
+ return Image.fromarray(a, "RGBA")
+
+
+def walk(frames: int = N + 6) -> list[Image.Image]:
+ return [walker(2 * math.pi * k / N) for k in range(frames)]
+
+
+def hopper(y: int, *, x: int = 52) -> Image.Image:
+ """A block body standing `y` px off the floor, with an arm across it."""
+ a = np.zeros((H, W, 4), dtype=np.uint8)
+ top = 40 - y
+ a[top:top + 80, x:x + 18] = (200, 80, 30, 255)
+ a[top + 20:top + 26, x - 10:x + 28] = (60, 60, 60, 255)
+ return Image.fromarray(a, "RGBA")
+
+
+def hop(rest: int = 12, air: int = 14) -> list[Image.Image]:
+ """Standing still, one hop up and down over `air` frames (a different height every frame), standing still again."""
+ heights = [round(36 * math.sin(math.pi * (k + 1) / (air + 1))) + k % 2 for k in range(air)]
+ return [hopper(0)] * rest + [hopper(h) for h in heights] + [hopper(0)] * rest
+
+
+def swing(frames: int = 25) -> list[Image.Image]:
+ """An arm swung out and back once, the last frame drawing the first again (a clip pinned to end on its start)."""
+ out = []
+ for k in range(frames):
+ a = np.zeros((H, W, 4), dtype=np.uint8)
+ a[30:110, 50:70] = (90, 90, 200, 255)
+ # even reaches, an odd pixel more every other frame: no two neighbours alike, the last the first again
+ reach = 2 * round(15 * math.sin(math.pi * k / (frames - 1))) + (k % 2 if 0 < k < frames - 1 else 0)
+ a[50:58, 70:76 + reach] = (60, 60, 60, 255)
+ out.append(Image.fromarray(a, "RGBA"))
+ return out
+
+
+def topple(count: int = 60) -> list[Image.Image]:
+ """A body that stands still, sinks to the ground a pixel or more every frame, then lies still (a once cut's end)."""
+ out = []
+ for k in range(count):
+ t = min(1.0, max(0.0, (k - 6) / 30))
+ a = np.zeros((96, 128, 4), dtype=np.uint8)
+ height = round(64 - 40 * t)
+ width = round(16 + 36 * t)
+ a[86 - height:86, 40:40 + width] = (200, 80, 30, 255)
+ out.append(Image.fromarray(a, "RGBA"))
+ return out
+
+
+def save(frames: list[Image.Image], d: Path) -> Path:
+ d.mkdir(parents=True)
+ for k, f in enumerate(frames):
+ f.save(d / f"{k:04d}.png")
+ return d
+
+
+def shown_again(frames: list[Image.Image], at: dict[int, int]) -> list[Image.Image]:
+ """`frames` with frame k shown `at[k]` times (its copies byte for byte the same), the rest once: a clip that stalls."""
+ out = []
+ for k, f in enumerate(frames):
+ out.extend([f] * at.get(k, 1))
+ return out
+
+
+def planter(reach: float) -> Image.Image:
+ """A body standing on a foot planted on the floor (a light block, the same in every frame), an arm reaching out
+ `reach` px."""
+ a = np.zeros((H, W, 4), dtype=np.uint8)
+ a[30:110, 50:70] = (90, 90, 200, 255)
+ a[110:H - 8, 52:68] = (200, 160, 40, 255)
+ a[50:58, 70:76 + round(reach)] = (60, 60, 60, 255)
+ return Image.fromarray(a, "RGBA")
+
+
+def slid(image: Image.Image, dx: int = 3) -> Image.Image:
+ """`image` with its planted foot moved `dx` px along the floor: an in-between that drags a contact."""
+ a = np.asarray(image).copy()
+ foot = a[110:H - 8].copy() # under the body: the foot alone
+ a[110:H - 8] = 0
+ a[110:H - 8, dx:] = foot[:, : W - dx]
+ return Image.fromarray(a, "RGBA")
+
+
+class Between:
+ """Stand-in interpolator: the true frame of a synthetic clip between two of its frames, drawn again at its own
+ time. Each frame is known by its pixels — `draw` at each of `times`, and every frame it makes — so a frame made
+ from a frame made is known too. With a `period`, a later frame drawn at an earlier time is the next cycle's
+ (a loop's wrap). `calls` lists (time of a, time of b, t) of each frame asked for."""
+
+ def __init__(self, draw, times, *, period: float | None = None, after=None):
+ self.draw, self.period, self.after = draw, period, after
+ self.known: dict[bytes, float] = {}
+ for t in times:
+ self.known.setdefault(draw(t).tobytes(), float(t) % period if period else float(t))
+ self.calls: list[tuple[float, float, float]] = []
+
+ def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:
+ ta, tb = self.known[a.tobytes()], self.known[b.tobytes()]
+ if self.period and tb <= ta:
+ tb += self.period
+ at = ta + t * (tb - ta)
+ im = self.draw(at % self.period if self.period else at)
+ self.known.setdefault(im.tobytes(), at % self.period if self.period else at)
+ self.calls.append((ta, tb, round(t, 4)))
+ return self.after(im) if self.after else im
+
+
+def walk_at(time: float) -> Image.Image:
+ """The walker `time` frames into its cycle."""
+ return walker(2 * math.pi * time / N)
diff --git a/tests/video/test_attack_motion.py b/tests/video/test_attack_motion.py
index 6e0ceb4..3c7807d 100644
--- a/tests/video/test_attack_motion.py
+++ b/tests/video/test_attack_motion.py
@@ -109,7 +109,7 @@ def test_video_set_gives_every_state_the_same_body_height(tmp_path: Path, monkey
def fake_loop(frames_dir, out_dir, **kw):
seen.append((kw["state"], kw.get("body_height")))
cycles[kw["state"]] = kw.get("cycle_mode")
- return {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3,
+ return {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}},
"n_out": 8, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}
def video(image, prompt, out, report, **kw):
diff --git a/tests/video/test_batch_facing.py b/tests/video/test_batch_facing.py
index 0074d6d..e24a3a6 100644
--- a/tests/video/test_batch_facing.py
+++ b/tests/video/test_batch_facing.py
@@ -18,7 +18,7 @@ def offline(monkeypatch):
"keyed_dir": str(out)})
monkeypatch.setattr(batch.loop_mod, "run_loop", lambda *a, **kw: {
"cycle": {"length": 10, "period_global": 10, "ratio": 0.2},
- "resampled_seam_ratio": 0.2, "n_out": 10, "gif": {"file": "loop.gif"},
+ "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10, "gif": {"file": "loop.gif"},
"webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}})
monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
diff --git a/tests/video/test_batch_handed.py b/tests/video/test_batch_handed.py
index afbfdf6..da7405b 100644
--- a/tests/video/test_batch_handed.py
+++ b/tests/video/test_batch_handed.py
@@ -24,7 +24,7 @@ def offline(monkeypatch):
def run_loop(*a, **kw):
loops.append((kw["name"], kw["facing"]))
- return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,
+ return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10,
"gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}}
monkeypatch.setattr(batch.loop_mod, "run_loop", run_loop)
monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
diff --git a/tests/video/test_body_plan.py b/tests/video/test_body_plan.py
index ebb1c2e..c020c2b 100644
--- a/tests/video/test_body_plan.py
+++ b/tests/video/test_body_plan.py
@@ -258,7 +258,7 @@ def test_video_set_says_the_body_plan_in_the_redraw_and_the_clip(tmp_path, monke
monkeypatch.setattr(batch.frames_mod, "run_frames", lambda clip, out, **kw: {
"fps": 24, "frames": 10, "alpha_zero_pct_min": 50, "alpha_zero_pct_max": 60, "keyed_dir": str(out)})
monkeypatch.setattr(batch.loop_mod, "run_loop", lambda *a, **kw: {
- "cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,
+ "cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10,
"gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}})
monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
redraws: list[str] = []
diff --git a/tests/video/test_gait_guard_anchor_wide.py b/tests/video/test_gait_guard_anchor_wide.py
index ec2e7ad..3a00759 100644
--- a/tests/video/test_gait_guard_anchor_wide.py
+++ b/tests/video/test_gait_guard_anchor_wide.py
@@ -218,7 +218,7 @@ def test_video_set_passes_shape_and_anchor_through(tmp_path: Path, monkeypatch,
def fake_loop(frames_dir, out_dir, **kw):
seen["anchor"] = kw.get("anchor")
- report = {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3, "n_out": 8, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}
+ report = {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 8, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}
if anchor == "motion-auto":
report["motion_anchor"] = {"applied": False, "reason": "fine-match-at-search-boundary"}
return report
diff --git a/tests/video/test_held_fill.py b/tests/video/test_held_fill.py
new file mode 100644
index 0000000..a93566f
--- /dev/null
+++ b/tests/video/test_held_fill.py
@@ -0,0 +1,470 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Held cells (sprite_gen/video/held_fill.py, docs/loop-repair.md section 7): neighbour cells of a cut that show the
+same picture are found on every cut `video-loop` makes, recorded (`held_fill`: the held runs, the poses and the cells)
+and, by default, made again as the frames between the pose before them and the pose after; the cut's first and last
+cells, its length, its beat and its wrap stay as they were, and a part standing still in both stays where it stood.
+A clip asked for at a higher rate than it was filmed (`--out-fps`) is given frames between, not frames shown again.
+With no RIFE the cut is delivered as filmed with a warning naming the motion and the install line; `--fill-held off`
+cuts it as before. A cut with no held cell comes out byte for byte as before (the six inputs below, pinned on the
+engine before the fill).
+
+The interpolator is a stand-in that draws the synthetic clip again at the time asked for (`Between`), so the tests
+need no binary and say which frame comes back."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from sprite_gen.video import held_fill
+from sprite_gen.video import loop as loop_mod
+from tests.video.held_fill_inputs import (N, Between, hop, planter, save, shown_again, slid, swing, topple, walk,
+ walk_at)
+
+
+def _no_rife(monkeypatch, tmp_path: Path) -> None:
+ """No RIFE anywhere the engine looks: no SPRITE_GEN_RIFE, no directory on PATH holding one, an empty data
+ directory."""
+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
+ path = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not (Path(d) / "rife-ncnn-vulkan").exists()]
+ monkeypatch.setenv("PATH", os.pathsep.join(path))
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))
+
+
+def _run(tmp_path: Path, frames: list[Image.Image], name: str = "m", **kw) -> dict:
+ keyed = save(frames, tmp_path / f"{name}-keyed")
+ return loop_mod.run_loop(keyed, tmp_path / f"{name}-out", fps=24.0, min_len=None, max_len=None, n_out=None,
+ seam_max=loop_mod.SEAM_RATIO_MAX, name=name, report_path=None, **kw)
+
+
+def _sha(path: Path) -> str:
+ return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _bytes(out: Path, name: str) -> dict[str, str]:
+ cycle = hashlib.sha256(b"".join(p.read_bytes() for p in sorted((out / "cycle").glob("frame-*.png")))).hexdigest()
+ return {"strip": _sha(out / f"{name}.strip.png"), "gif": _sha(out / f"{name}.gif"), "webp": _sha(out / f"{name}.webp"),
+ "cycle": cycle}
+
+
+def _meta(rep: dict) -> dict:
+ return json.loads(Path(rep["strip"]["path"]).with_suffix("").with_suffix(".strip.json").read_text())
+
+
+def _cycle(rep: dict) -> list[Image.Image]:
+ return [Image.open(p).convert("RGBA") for p in sorted((Path(rep["out_dir"]) / "cycle").glob("frame-*.png"))]
+
+
+# Pinned on the engine before the fill (886936e): a cut with no held cell is delivered as it was, byte for byte.
+UNHELD = {
+ "walk-fixed": (lambda: walk(), dict(state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off"), {
+ "strip": "2335f3f5da57e08074113d6d30b89a672a3ff1f969ff645c667e07f3d08eaba1",
+ "gif": "27f05c499a83e66621c9853efdb61fb591bfa386fbceb159c0a09822f79989c9",
+ "webp": "4c9922b16ff73385a87f363d7aac567b5f1885df667fafce91702935fb8451b7",
+ "cycle": "26be9c07e34ad0976013e7f5ce5b40af10c071ef78fb6b749ac389deb01e4a8d"}),
+ "walk-auto": (lambda: walk(N * 3 + 4), dict(state="walk", repair="off"), {
+ "strip": "d9c2143deb3cb3f90d932a4cd47132dcc196a2c83227eea85588c58b3cbc2ca3",
+ "gif": "1b53603c32cd6bcca445374eb9403a68d9e1914c6bdf126c49b5312fadd9d62e",
+ "webp": "6ae3c4465ef484691deb63883cee6439f8e401ae6d9fc121fd4233a9d8c2215a",
+ "cycle": "73de53310593c2792d4ef3b957e4f303befaeb2db5dc79c2e39649a66c0d108a"}),
+ "hop-one-shot": (lambda: hop(), dict(state="jump", cycle_mode="one-shot"), {
+ "strip": "4c2317151d8ac0f78b2cf05fd00f90d77ec6a84adb418e076693675b92155032",
+ "gif": "084867009d141d032adea38edaec5e7277f9f7cc03d59e1498b926c5e4146546",
+ "webp": "5d6b8b67c7e515096c002da2f715088b12e1b1f2174de865bda35dd4d2ab8a6f",
+ "cycle": "9ccfbada05cf1b964bebea30c67cb92170713f6950dfa348a9d54afb20ddf43a"}),
+ "swing-pinned": (lambda: swing(), dict(state="attack", cycle_mode="pinned", anchor="none"), {
+ "strip": "74ea7ee259b254744c76ab3d2b5ca3a2a0ee8baa04d7f7beafd1ecf39966d76d",
+ "gif": "3944bc371f1b167707a06c069411960d7043f40d784108cb4c231adcfee77fcd",
+ "webp": "feea1f26d5dcb5eceb49706440db1c0037b5a95c692ca4ddfa58072c28e3ec70",
+ "cycle": "fee8b88afd0ccbbde09c6e14411514bedf030a47dde290a9218fe9c00bbe7457"}),
+ "topple-once": (lambda: topple(), dict(state="death", cycle_mode="once"), {
+ "strip": "59629dc0b1ba7796e5a7650fc99696e22d84b958012e9d898bb321860118ed0e",
+ "gif": "0f71d5df9da9ca3645193481c042dde32cfe6d9d344018835ee09715a08a7809",
+ "webp": "6adb35ceaa211abb535e46998df6b513bfd58fa57340d47af652fd28f784a24d",
+ "cycle": "6d15da447a24801ec6f4618328e18c7e75dc15a871649d47dd1889db301a8570"}),
+ "swing-once-return": (lambda: swing(), dict(state="leap", cycle_mode="once-return", anchor="none"), {
+ "strip": "67c113649569ee63f704ba0f4fc9c70a9c26ec50e0e5f25937ebb8c8db3d4638",
+ "gif": "af0b2a32648ee4316edbabd5392ea652519a51939e67407c80650859c5fa21da",
+ "webp": "ba0ad2de4a5b264ebfc61cd0657f22864340629e842abd2e1ec3929c39362ada",
+ "cycle": "c0a3d63b81c139f83566e658959214f965efd136b85e810c86d78bb57551375e"}),
+}
+
+
[email protected]("case", sorted(UNHELD))
+def test_a_cut_with_no_held_cell_is_delivered_byte_for_byte_as_before(case, tmp_path, monkeypatch):
+ _no_rife(monkeypatch, tmp_path) # nothing is made, so nothing looks for RIFE
+ frames, kw, pinned = UNHELD[case]
+ rep = _run(tmp_path, frames(), case, **kw)
+ assert _bytes(Path(rep["out_dir"]), case) == pinned
+ record = _meta(rep)["held_fill"]
+ assert record == held_fill.public(rep["held_fill"])
+ assert record["mode"] == "auto" and record["made"] == [] and "unmade" not in record
+ cells = rep["cycle"]["length"]
+ assert record["cells"] == cells
+ if case == "topple-once":
+ # It lies still for its last five cells: the cut's closing pose, kept.
+ assert record["held_runs"] == [{"start": cells - 5, "length": 5}]
+ assert record["before"]["held_runs"][0]["filled"] is False
+ assert record["poses"] == cells - 4
+ else:
+ assert record["held_runs"] == [] and record["poses"] == cells
+
+
+STALLED = {5: 2, 13: 3} # the walk's frame 5 shown twice, frame 13 three times
+STALLED_OFF = { # the stalled walk cut on the engine before the fill (886936e)
+ "strip": "f208b850b2265fd6ce10ce4993998895f70a065f5cea118ef71230581f02ad15",
+ "gif": "c25a5d96b123e0237045774d689b9d2205ca51f16e67745e8ea9d290b285e3fb",
+ "webp": "117d7b8b18b2e2ff42434890ca58efd0f0855c1db2f9b55515174ac481c749c7",
+ "cycle": "5753f68c10942635e9518220423301f04805cbb845abaea7300ba01fb4e1c8cb",
+}
+STALLED_CUT = dict(state="walk", cycle_mode="fixed", start=0, length=N + 3, anchor="none", repair="off")
+
+
+def test_a_stalled_walk_has_its_held_cells_made_between_the_poses_beside_them(tmp_path):
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, shown_again(walk(), STALLED), interpolate=between, **STALLED_CUT)
+ record = rep["held_fill"]
+ assert record["before"]["cells"] == N + 3 and record["before"]["poses"] == N
+ assert [(r["start"], r["length"], r["filled"]) for r in record["before"]["held_runs"]] == [(5, 2, True), (14, 3, True)]
+ assert record["made"] == [6, 15, 16]
+ # Each made at its own time between the pose before the run and the pose after it: half way, a third and two thirds.
+ assert sorted(between.calls) == [(5.0, 6.0, 0.5), (13.0, 14.0, 0.3333), (13.0, 14.0, 0.6667)]
+ assert (record["cells"], record["poses"], record["held_runs"]) == (N + 3, N + 3, [])
+ cells = _cycle(rep)
+ assert cells[6].tobytes() == walk_at(5.5).tobytes()
+ assert cells[15].tobytes() == walk_at(13 + 1 / 3).tobytes()
+ # Every other cell is the cut's as filmed: the first and the last, the length, the beat.
+ filmed = shown_again(walk(), STALLED)[: N + 3]
+ assert len(cells) == N + 3
+ assert all(cells[k].tobytes() == filmed[k].tobytes() for k in range(N + 3) if k not in (6, 15, 16))
+ assert _meta(rep)["held_fill"] == held_fill.public(record)
+ assert rep["seam_measurement"] == "rendered-cells"
+
+
+def test_fill_held_off_cuts_the_stalled_walk_as_before_and_still_names_its_runs(tmp_path):
+ rep = _run(tmp_path, shown_again(walk(), STALLED), fill_held="off", **STALLED_CUT)
+ assert _bytes(Path(rep["out_dir"]), "m") == STALLED_OFF
+ record = rep["held_fill"]
+ assert record["mode"] == "off" and record["made"] == []
+ assert [(r["start"], r["length"], r["filled"], r["why"]) for r in record["before"]["held_runs"]] == [
+ (5, 2, False, "--fill-held off"), (14, 3, False, "--fill-held off")]
+ assert (record["cells"], record["poses"]) == (N + 3, N)
+
+
+def test_no_rife_delivers_the_held_cells_as_filmed_and_says_which_motion(tmp_path, monkeypatch, capsys):
+ _no_rife(monkeypatch, tmp_path)
+ rep = _run(tmp_path, shown_again(walk(), STALLED), name="stalled-walk", **STALLED_CUT)
+ assert rep["status"] == "passed"
+ out = Path(rep["out_dir"])
+ # The images are the cut as filmed: what --fill-held off delivers.
+ off = _run(tmp_path, shown_again(walk(), STALLED), name="off", fill_held="off", **STALLED_CUT)
+ assert {k: v for k, v in _bytes(out, "stalled-walk").items()} == _bytes(Path(off["out_dir"]), "off")
+ record = rep["held_fill"]
+ assert record["made"] == [] and record["unmade"]["cells"] == [6, 15, 16]
+ assert record["unmade"]["install"] == loop_mod.rife_mod.install_command()
+ assert (record["cells"], record["poses"]) == (N + 3, N)
+ err = capsys.readouterr().err
+ assert "stalled-walk" in err and "RIFE is not installed" in err and loop_mod.rife_mod.install_command() in err
+
+
+def test_a_hold_longer_than_three_cells_is_the_motion_s_own_and_kept(tmp_path):
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, shown_again(walk(), {9: 5}), interpolate=between,
+ **{**STALLED_CUT, "length": N + 4})
+ run = rep["held_fill"]["before"]["held_runs"]
+ assert [(r["start"], r["length"], r["filled"]) for r in run] == [(9, 5, False)]
+ assert "longer than" in run[0]["why"]
+ assert between.calls == [] and rep["held_fill"]["held_runs"] == [{"start": 9, "length": 5}]
+
+
+def test_a_walk_drawn_on_twos_is_limited_animation_and_kept(tmp_path):
+ # Each drawing shown twice, as a clip of 12 drawings a second at 24 fps is (sprite_gen/video/held.py).
+ twos = shown_again(walk(), {k: 2 for k in range(N + 6)})
+ cut = {**STALLED_CUT, "length": 2 * N}
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, twos, interpolate=between, **cut)
+ record = rep["held_fill"]
+ assert rep["cycle_drawings"]["hold"] == 2 and record["drawn"] == 2
+ assert between.calls == [] and record["made"] == []
+ assert all(not r["filled"] and "drawn on twos" in r["why"] for r in record["before"]["held_runs"])
+ assert (record["cells"], record["poses"]) == (2 * N, N)
+ off = _run(tmp_path, twos, name="off", fill_held="off", **cut)
+ assert _bytes(Path(rep["out_dir"]), "m") == _bytes(Path(off["out_dir"]), "off")
+
+
+def test_a_walk_carried_to_60_fps_by_repeating_frames_reads_a_hold_and_is_filled_to_a_pose_a_cell(tmp_path):
+ # 24 fps carried to 60 by the frame under each time: each frame shown three and two times by turns. Its rhythm
+ # reads a hold of 2, but its runs are not each two cells: the frames between are made.
+ filmed = walk(2 * N + 2)
+ carried = [filmed[k * 24 // 60] for k in range(len(filmed) * 60 // 24)]
+ between = Between(walk_at, range(2 * N + 2), period=N)
+ keyed = save(carried, tmp_path / "carried-keyed")
+ rep = loop_mod.run_loop(keyed, tmp_path / "carried-out", fps=60.0, min_len=None, max_len=None, n_out=None,
+ seam_max=loop_mod.SEAM_RATIO_MAX, name="m", report_path=None, interpolate=between,
+ state="walk", anchor="none", repair="off")
+ record = rep["held_fill"]
+ assert rep["cycle_drawings"]["hold"] == 2 and "drawn" not in record
+ assert {r["length"] for r in record["before"]["held_runs"]} == {2, 3}
+ assert record["before"]["poses"] < record["before"]["cells"] == rep["cycle"]["length"] == 60
+ assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])
+ cells, start = _cycle(rep), rep["cycle"]["start"]
+ assert cells[0].tobytes() == carried[start].tobytes() and cells[-1].tobytes() == carried[start + 59].tobytes()
+
+
+def test_a_once_cut_and_a_one_shot_have_their_held_cells_made_too(tmp_path):
+ frames = topple()
+ stalled = shown_again(frames, {20: 2})
+ times = {f.tobytes(): float(k) for k, f in enumerate(frames)}
+ between = Between(lambda t: _topple_at(t), [])
+ between.known.update(times)
+ rep = _run(tmp_path, stalled, "fall", interpolate=between, state="death", cycle_mode="once")
+ record = rep["held_fill"]
+ start = rep["cycle"]["start"]
+ assert [(r["start"], r["filled"]) for r in record["before"]["held_runs"] if r["filled"]] == [(20 - start, True)]
+ assert between.calls == [(20.0, 21.0, 0.5)]
+ hopped = shown_again(hop(), {18: 2})
+ rep = _run(tmp_path, hopped, "hop", interpolate=lambda a, b, t: Image.blend(a, b, t), state="jump", cycle_mode="one-shot")
+ assert any(r["start"] + rep["cycle"]["start"] == 18 for r in rep["held_fill"]["before"]["held_runs"])
+
+
+def _topple_at(time: float) -> Image.Image:
+ """`topple`'s body `time` frames in, between its frames as well."""
+ t = min(1.0, max(0.0, (time - 6) / 30))
+ a = np.zeros((96, 128, 4), dtype=np.uint8)
+ height, width = round(64 - 40 * t), round(16 + 36 * t)
+ a[86 - height:86, 40:40 + width] = (200, 80, 30, 255)
+ return Image.fromarray(a, "RGBA")
+
+
+# The fill on a cut's frames, as `video-loop` calls it: which runs it makes, which it keeps and why.
+
+
+def _reach(time: float) -> Image.Image:
+ return planter(4 * time)
+
+
+def _planted(times: list[float]) -> list[Image.Image]:
+ return [_reach(t) for t in times]
+
+
+def test_a_part_standing_still_on_both_sides_stays_where_it_stood():
+ frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])
+ out, record = held_fill.fill(frames, Between(_reach, range(7)), ring=False)
+ assert record["made"] == [4]
+ assert out[4].tobytes() == _reach(3.5).tobytes()
+ assert record["before"]["held_runs"][0]["filled"] is True
+ assert record["contact"][0]["kept"] == 1.0
+
+
+def test_a_frame_between_that_drags_a_planted_foot_is_not_taken():
+ frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])
+ out, record = held_fill.fill(frames, Between(_reach, range(7), after=slid), ring=False)
+ assert record["made"] == []
+ assert out[4].tobytes() == frames[4].tobytes() # the held cell, as filmed
+ run = record["before"]["held_runs"][0]
+ assert run["filled"] is False and "contact" in run["faults"]
+ assert record["held_runs"] == [{"start": 3, "length": 2}]
+
+
+def test_the_opening_and_the_closing_pose_of_a_cut_played_once_are_kept():
+ frames = _planted([0, 0, 1, 2, 3, 4, 4])
+ calls: list = []
+ out, record = held_fill.fill(frames, lambda a, b, t: calls.append(t) or a, ring=False)
+ whys = [r["why"] for r in record["before"]["held_runs"]]
+ assert calls == [] and record["made"] == []
+ assert "opening" in whys[0] and "closing" in whys[1]
+
+
+def test_a_loop_s_held_cells_at_its_wrap_are_kept_and_at_its_start_made():
+ frames = _planted([0, 0, 1, 2, 3, 4, 5, 5])
+ between = Between(_reach, range(7), period=None)
+ # The wrap closes on cell 0 again: a frame between the last pose and the first is the wrap's, not the hold's.
+ out, record = held_fill.fill(frames, between, ring=True)
+ runs = record["before"]["held_runs"]
+ assert (runs[0]["start"], runs[0]["filled"]) == (0, True)
+ assert (runs[1]["start"], runs[1]["filled"]) == (6, False) and "wrap" in runs[1]["why"]
+ assert record["made"] == [1] and out[0].tobytes() == frames[0].tobytes() and out[7].tobytes() == frames[7].tobytes()
+
+
+def test_codec_copies_read_as_the_same_picture_and_the_slowest_motion_does_not():
+ still = planter(10)
+ noisy = np.asarray(still).astype(np.int16)
+ noisy[..., :3] += np.random.default_rng(0).integers(-3, 4, size=noisy[..., :3].shape).astype(np.int16)
+ noisy = Image.fromarray(np.clip(noisy, 0, 255).astype(np.uint8), "RGBA")
+ assert held_fill.same_steps([still, noisy, planter(11)]) == [True, False]
+
+
+# A higher rate than the clip's: frames between, never frames shown again.
+
+
+def test_a_walk_asked_for_at_60_fps_is_made_of_frames_between(tmp_path):
+ between = Between(walk_at, range(N + 6), period=N)
+ rep = _run(tmp_path, walk(), "walk60", interpolate=between, out_fps=60.0,
+ state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")
+ meta = _meta(rep)
+ record = rep["held_fill"]
+ assert record["out_fps"]["applied"] is True and record["out_fps"]["cells"] == 60
+ assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])
+ assert meta["frames"] == 60 and meta["cycle_seconds"] == 1.0 and meta["delay_ms"] == pytest.approx(16.67)
+ assert meta["out_fps"] == 60.0
+ cells = _cycle(rep)
+ assert len(cells) == 60
+ assert cells[0].tobytes() == walk_at(0).tobytes() and cells[5].tobytes() == walk_at(2).tobytes()
+ assert cells[1].tobytes() == walk_at(0.4).tobytes()
+ assert len({c.tobytes() for c in cells}) == 60
+
+
+def test_a_one_shot_asked_for_at_60_fps_keeps_its_first_and_last_frame(tmp_path):
+ frames = hop()
+ times = {f.tobytes(): float(k) for k, f in enumerate(frames)}
+ made: list = []
+
+ def between(a, b, t):
+ made.append((times[a.tobytes()], times[b.tobytes()], round(t, 4)))
+ return Image.blend(a, b, t)
+
+ rep = _run(tmp_path, frames, "hop60", interpolate=between, out_fps=60.0, state="jump", cycle_mode="one-shot")
+ L = rep["cycle"]["length"]
+ record = rep["held_fill"]
+ cells = _cycle(rep)
+ assert len(cells) == round((L - 1) * 2.5) + 1 == record["cells"]
+ filmed = hop()[rep["cycle"]["start"]: rep["cycle"]["start"] + L]
+ assert cells[0].tobytes() == filmed[0].tobytes() and cells[-1].tobytes() == filmed[-1].tobytes()
+ assert record["out_fps"]["applied"] is True
+
+
+def test_no_rife_delivers_a_clip_asked_for_at_a_higher_rate_at_its_own(tmp_path, monkeypatch, capsys):
+ _no_rife(monkeypatch, tmp_path)
+ rep = _run(tmp_path, walk(), "walk60", out_fps=60.0, state="walk", cycle_mode="fixed", start=0, length=N,
+ anchor="none", repair="off")
+ assert rep["status"] == "passed" and _meta(rep)["frames"] == N and "out_fps" not in _meta(rep)
+ assert rep["held_fill"]["out_fps"]["applied"] is False
+ err = capsys.readouterr().err
+ assert "walk60" in err and "--out-fps 60" in err and loop_mod.rife_mod.install_command() in err
+
+
+def test_a_rate_under_the_clip_s_own_is_refused(tmp_path):
+ with pytest.raises(SystemExit, match="--out-fps 12"):
+ _run(tmp_path, walk(), out_fps=12.0, state="walk", cycle_mode="fixed", start=0, length=N, anchor="none")
+
+
+def test_video_loop_and_video_set_take_the_switches():
+ import argparse
+
+ from sprite_gen.video import batch
+
+ parser = argparse.ArgumentParser()
+ loop_mod.add_arguments(parser)
+ args = parser.parse_args(["--frames-dir", "f", "--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])
+ assert (args.fill_held, args.out_fps) == ("off", 60.0)
+ assert parser.parse_args(["--frames-dir", "f", "--out-dir", "o"]).fill_held == "auto"
+ parser = argparse.ArgumentParser()
+ batch.add_arguments(parser)
+ args = parser.parse_args(["--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])
+ assert (args.fill_held, args.out_fps) == ("off", 60.0)
+ assert parser.parse_args(["--out-dir", "o"]).fill_held == "auto"
+
+
+def test_video_set_hands_the_switches_to_each_cut(monkeypatch, tmp_path):
+ from sprite_gen.video import batch
+
+ seen: list[dict] = []
+ monkeypatch.setattr(batch.frames_mod, "run_frames", lambda clip, out, **kw: {
+ "fps": 24, "frames": 10, "alpha_zero_pct_min": 50, "alpha_zero_pct_max": 60, "keyed_dir": str(out)})
+
+ def run_loop(*a, **kw):
+ seen.append(kw)
+ return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,
+ "gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"},
+ "held_fill": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2}], "made": [],
+ "before": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2, "filled": False,
+ "why": "--fill-held off"}]}}}
+
+ def video(image, prompt, out, report, **kw):
+ out.write_bytes(b"test-video")
+ report.write_text(json.dumps({"prompt": prompt}))
+ return 0
+
+ monkeypatch.setattr(batch.loop_mod, "run_loop", run_loop)
+ monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
+ still = tmp_path / "front.png"
+ Image.new("RGBA", (64, 64), (200, 80, 30, 255)).save(still)
+ result = batch.run_set(bases={"front": still}, states=["idle"], root=tmp_path / "set", character=None, duration=3,
+ resolution="720p", key="green", concurrency=1, force=False, gap=0, video_runner=video,
+ align_cycles="off", fill_held="off", out_fps=60.0)
+ assert [(kw["fill_held"], kw["out_fps"]) for kw in seen] == [("off", 60.0)]
+ # The set's report says each motion's poses over its cells.
+ assert result["items"][0]["loop"]["poses"] == "9/10"
+
+
+def test_a_cut_with_cells_made_is_not_restored_from_its_source_frames(tmp_path):
+ """The source frames do not hold a cell made between two of them: restoration (`video-loop-repair`) reads the cut
+ as one it cannot project (`source-processing-unsupported`), as it reads a blended wrap."""
+ import shutil
+ import subprocess
+
+ from sprite_gen.video import source
+ from sprite_gen.video.compare import Loop
+
+ if not shutil.which("ffmpeg") or not loop_mod.img2webp_supports_exact():
+ pytest.skip("ffmpeg and img2webp >=1.5 required")
+ filmed = shown_again(walk(), STALLED)
+ keyed = save(filmed, tmp_path / "keyed")
+ out = tmp_path / "cut"
+ loop_mod.run_loop(keyed, out, fps=24.0, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX,
+ name="walk", report_path=None, interpolate=Between(walk_at, range(N + 6), period=N), **STALLED_CUT)
+ files = sorted(keyed.glob("*.png"))
+ frames_report = tmp_path / "frames.json"
+ frames_report.write_text(json.dumps({"kind": "sprite-gen-video-frames-report", "fps": 24.0, "frames": len(files),
+ "width": filmed[0].width, "height": filmed[0].height, "stream_index": 0,
+ "key": "green"}))
+ clip = tmp_path / "clip.mp4"
+ subprocess.run(["ffmpeg", "-v", "error", "-framerate", "24", "-i", str(keyed / "%04d.png"), "-c:v", "libx264",
+ "-pix_fmt", "yuv420p", str(clip)], check=True)
+ manifest = tmp_path / "source.json"
+ manifest.write_text(json.dumps(source.manifest(clip=clip, canvas=files[0], frames_report=frames_report, files=files,
+ timestamps=source.timestamps(clip, 0))))
+ loop = Loop.read(out / "walk.strip.png", out / "walk.strip.json", out / "walk.loop.report.json")
+ projection, issue = source.project(loop, source.Source.read(
+ source_manifest=manifest, source_frames_dir=keyed, source_clip=clip, source_canvas=files[0],
+ source_frames_report=frames_report))
+ assert (projection, issue) == (None, "source-processing-unsupported")
+
+
+def test_the_alignment_and_a_stop_refuse_a_loop_cut_at_a_rate_of_its_own(tmp_path):
+ from sprite_gen.video import align, stop
+
+ rep = _run(tmp_path, walk(), "walk60", interpolate=Between(walk_at, range(N + 6), period=N), out_fps=60.0,
+ state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")
+ out = Path(rep["out_dir"])
+ with pytest.raises(ValueError, match="--out-fps 60"):
+ align._loop_files(out)
+ with pytest.raises(SystemExit, match="--out-fps 60"):
+ stop.read_loop(out / "walk60.strip.json")
+
+
+def test_the_curation_view_marks_the_cells_made_and_the_cells_still_held(tmp_path):
+ """A loop's `cycle/` imported into the curation view (`unpack-atlas --pngs-dir`): each card of a cell the fill made
+ says `made`, of a cell still showing the picture before it `held`."""
+ from sprite_gen import cli
+
+ rep = _run(tmp_path, shown_again(walk(), {**STALLED, 20: 5}), interpolate=Between(walk_at, range(N + 6), period=N),
+ **{**STALLED_CUT, "length": N + 7})
+ assert rep["held_fill"]["made"] == [6, 15, 16]
+ assert cli.main(["unpack-atlas", "--pngs-dir", str(Path(rep["out_dir"]) / "cycle"), "--out-dir", str(tmp_path / "run")]) == 0
+ rows = json.loads((tmp_path / "run" / "frames" / "frames-manifest.json").read_text())["rows"]
+ labels = rows[0]["labels"]
+ assert [k for k, label in enumerate(labels) if label.endswith(" (made)")] == [6, 15, 16]
+ assert [k for k, label in enumerate(labels) if label.endswith(" (held)")] == [24, 25, 26, 27]
+ assert labels[0] == "frame-000"
diff --git a/tests/video/test_idle_still.py b/tests/video/test_idle_still.py
index 4933844..af82ae5 100644
--- a/tests/video/test_idle_still.py
+++ b/tests/video/test_idle_still.py
@@ -78,7 +78,7 @@ def test_video_set_pins_idle_and_cuts_it_whole(tmp_path: Path, monkeypatch) -> N
def fake_loop(frames_dir, out_dir, **kw):
seen["cycle_mode"] = kw.get("cycle_mode")
- return {"cycle": {"kind": "pinned", "length": 47, "period_global": None, "ratio": 1.0}, "resampled_seam_ratio": 1.0, "n_out": 47,
+ return {"cycle": {"kind": "pinned", "length": 47, "period_global": None, "ratio": 1.0}, "resampled_seam_ratio": 1.0, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 47,
"gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}
def video(image, prompt, out, report, **kw):
diff --git a/tests/video/test_loop_prop_seam_held.py b/tests/video/test_loop_prop_seam_held.py
index a07daf5..53703b9 100644
--- a/tests/video/test_loop_prop_seam_held.py
+++ b/tests/video/test_loop_prop_seam_held.py
@@ -404,6 +404,8 @@ GHOST_KEYS_2430 = {"ghost_screen", "ghost_at"}
# Unreleased: every cut of the cut's length the clip holds, read for the same foot twice (video-loop), and the aligned
# loop's beat and its cut's screen steps (docs/loop-repair.md section 4)
CLIP_FEET_KEYS, BEAT_KEYS = {"clip_feet"}, {"beat", "screen"}
+# 3.8.0: the cut's held cells, read and made again (docs/loop-repair.md section 7)
+HELD_FILL_KEYS_3800 = {"held_fill"}
def test_cycle_align_writes_a_loop_without_a_held_part_as_before(tmp_path, staffless):
@@ -425,7 +427,7 @@ def test_cycle_align_writes_a_loop_without_a_held_part_as_before(tmp_path, staff
assert all("cycles_kept" not in row and "steps" not in row for row in out["loops"])
for d in dirs:
meta = json.loads((d / "loop.strip.json").read_text())
- assert set(meta) == STRIP_KEYS_2350 | SOURCE_KEYS_2390 | CLIP_FEET_KEYS
+ assert set(meta) == STRIP_KEYS_2350 | SOURCE_KEYS_2390 | CLIP_FEET_KEYS | HELD_FILL_KEYS_3800
assert set(meta["cycle_align"]) == CYCLE_ALIGN_KEYS_2350 | CORRESPONDENCE_KEYS_2410 | GHOST_KEYS_2430 | BEAT_KEYS
# The cut's source stays as the cut wrote it: `cycle_align` says the cells were turned after it, so it
# no longer names each cell's frame (docs/loop-comparison.md). The rebuilt strip names its own cells —
diff --git a/tests/video/test_once.py b/tests/video/test_once.py
index 1921a4e..35e92fd 100644
--- a/tests/video/test_once.py
+++ b/tests/video/test_once.py
@@ -176,7 +176,7 @@ def test_batch_sends_terminal_pin_and_does_not_reuse_a_changed_pin(tmp_path, mon
def loop_stub(frames, out, **kw):
assert kw["cycle_mode"] == "once" and kw["anchor"] == "none"
return {"cycle": {"kind": "once", "length": 24, "period_global": None, "ratio": 0},
- "resampled_seam_ratio": None, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}
+ "resampled_seam_ratio": None, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}
monkeypatch.setattr(batch.canvas_mod, "run_canvas", canvas_stub)
monkeypatch.setattr(batch.frames_mod, "run_frames", frames_stub)
diff --git a/tests/video/test_play.py b/tests/video/test_play.py
index c4eafbc..e71915a 100644
--- a/tests/video/test_play.py
+++ b/tests/video/test_play.py
@@ -184,7 +184,7 @@ def stub_set(tmp_path, monkeypatch, *, bases, states, **kwargs):
def loop_stub(frames, out, **kw):
seen.setdefault(out.parent.name, {})["cycle"] = kw["cycle_mode"]
return {"cycle": {"kind": kw["cycle_mode"], "length": 24, "period_global": None, "ratio": 0},
- "resampled_seam_ratio": None, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}
+ "resampled_seam_ratio": None, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}
monkeypatch.setattr(batch.frames_mod, "run_frames", frames_stub)
monkeypatch.setattr(batch.loop_mod, "run_loop", loop_stub)
diff --git a/tests/video/test_stop.py b/tests/video/test_stop.py
index fcb65fe..84470e8 100644
--- a/tests/video/test_stop.py
+++ b/tests/video/test_stop.py
@@ -146,6 +146,9 @@ def test_stop_plays_the_start_backwards_from_the_loop_to_the_first_frame(tmp_pat
assert smeta["from_loop"]["from_cell"] == out["entry"]["from_cell"] and smeta["body_h"] == lmeta["body_h"]
assert smeta["source_cut"]["source"]["sha256"] == lmeta["source_cut"]["source"]["sha256"]
assert out["source"]["same_as_loop"] is True
+ # Read for a picture shown again, as every cut is; a stop plays its filmed frames, none made between.
+ assert smeta["held_fill"]["mode"] == "off" and smeta["held_fill"]["made"] == []
+ assert (smeta["held_fill"]["cells"], smeta["held_fill"]["poses"], smeta["held_fill"]["held_runs"]) == (len(shown), len(shown), [])
with Image.open(tmp_path / "stop" / "stop.gif") as gif:
assert gif.n_frames == len(shown) and gif.info.get("loop") is None
report = json.loads((tmp_path / "stop" / "stop.stop.report.json").read_text())
diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.py
index 7282100..fa40d8e 100644
--- a/tests/video/test_video_pipeline.py
+++ b/tests/video/test_video_pipeline.py
@@ -443,7 +443,7 @@ def test_run_set_runs_each_clip_once_and_tables_failures(tmp_path: Path, monkeyp
monkeypatch.setattr(batch_mod.time, "sleep", lambda s: None) # no real stagger waits
monkeypatch.setattr(frames_mod, "run_frames", lambda clip, out_dir, **kw: {"fps": 24.0, "frames": 10, "alpha_zero_pct_min": 60.0, "alpha_zero_pct_max": 70.0, "keyed_dir": str(out_dir / "keyed")})
monkeypatch.setattr(batch_mod.frames_mod, "run_frames", frames_mod.run_frames)
- monkeypatch.setattr(batch_mod.loop_mod, "run_loop", lambda frames_dir, out_dir, **kw: {"cycle": {"length": 12, "period_global": 12, "ratio": 0.3, "review_recommended": kw["state"] == "run"}, "resampled_seam_ratio": 0.5, "n_out": 12, "gif": {"file": "x.gif"}, "webp": {"file": "x.webp"}, "strip": {"path": "x.png"}})
+ monkeypatch.setattr(batch_mod.loop_mod, "run_loop", lambda frames_dir, out_dir, **kw: {"cycle": {"length": 12, "period_global": 12, "ratio": 0.3, "review_recommended": kw["state"] == "run"}, "resampled_seam_ratio": 0.5, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 12, "gif": {"file": "x.gif"}, "webp": {"file": "x.webp"}, "strip": {"path": "x.png"}})
payload = batch_mod.run_set(bases={"side": base}, states=["walk", "run", "jump"], root=tmp_path / "set", character=None, duration=6, resolution="720p", key="green", concurrency=3, force=False, gap=0.0, video_runner=fake_video)