Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

fix(video-loop): a loop that is not a walk has the frames round a wrap that jumps made again by RIFE, the fewest first (the seam bridge)

Soohong Kim3702b0a57238
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 68b6544..22cc5f1 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -867,8 +867,10 @@ def run_item(
if lp.get("motion_anchor", {}).get("applied") is False:
result["loop"]["motion_anchor"] = lp["motion_anchor"]
if "rife" in (lp.get("jump_repair") or {}):
- # cut as filmed for want of RIFE: the set report lists it under `warnings`
- result["loop"]["jump_repair"] = {k: lp["jump_repair"][k] for k in ("applied", "why", "off_max_before", "install")}
+ # 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`)
+ result["loop"]["jump_repair"] = {k: lp["jump_repair"][k] for k in ("applied", "why", "off_max_before", "seam", "install")
+ if k in lp["jump_repair"]}
result["ok"] = True
except CodexUnavailableAsk as exc:
result["ok"] = False
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 93df3cc..4ed369d 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -106,10 +106,10 @@ BODY_ANCHOR_BAND = 0.6 # --anchor body reads the wrap offset from the top 60 %
BODY_ANCHOR_SEARCH = 24 # px either side searched for the last frame's horizontal offset against the first
FOOT_BAND = legs_mod.FOOT_BAND # fraction of the frame's own height, measured up from its lowest opaque row
# Jump-frame repair (docs/loop-repair.md section 2). auto: walk and run loops get a RIFE frame in
-# place of each frame that follows a jump, and a loop that needs one where no RIFE is installed is
-# cut as filmed with a warning (a walk that cut before RIFE existed still cuts); on: the same, but
-# no RIFE fails the loop — a caller that asked for the repair is never handed less; off: the loop
-# is cut as filmed, and says so.
+# place of each frame that follows a jump, any other loop RIFE frames round a wrap that jumps (the
+# seam bridge), and a loop that needs one where no RIFE is installed is cut as filmed with a warning
+# (a walk that cut before RIFE existed still cuts); on: the same, but no RIFE fails the loop — a
+# caller that asked for the repair is never handed less; off: the loop is cut as filmed, and says so.
REPAIR_MODES = ("auto", "on", "off")
# The overlapped wrap (docs/loop-repair.md section 2, "The overlapped wrap"), under --repair auto or on. on: a two-step
# cut whose wrap the gate refuses has the frames beside its wrap made again from the clip's frames a cycle apart, each
@@ -1071,6 +1071,64 @@ def _overlap_lines(overlap: dict[str, Any]) -> list[str]:
return [f"{said}, and the overlapped wrap was refused ({refused}): cut as filmed (docs/loop-repair.md section 2)"]
+def _bridge_seam(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, facing: str, required: bool,
+ seam_max: float, hold: int | None, skip: str | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """`repair_mod.seam_bridge` on a loop that is not a walk, with RIFE located only once a frame is to be made: a wrap
+ that reads as a step of the loop needs no binary. The record names the interpolator that made the frames.
+
+ A frame to make and no RIFE installed: `required` lets `RifeNotInstalled` through; otherwise the wrap is read again
+ with no interpolator, cut as filmed, and the record says why (`rife`, `install`, the run it stopped at `unmade`)."""
+ made_by: list[dict[str, str]] = []
+
+ 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)
+
+ asked = partial(repair_mod.seam_bridge, limit=seam_max, hold=hold, facing=facing, skip=skip)
+ try:
+ frames, record = asked(frames, lazy)
+ except rife_mod.RifeNotInstalled as exc:
+ if required:
+ raise
+ frames, record = asked(frames, None)
+ record.update(why="RIFE not installed — the wrap cut as filmed", rife=str(exc), install=rife_mod.INSTALL_COMMAND)
+ record["applied"] = bool(record["replaced"])
+ if record["calls"]:
+ record["interpolator"] = ({"kind": "rife-ncnn-vulkan", **made_by[0], "binary_calls": interpolate.calls}
+ if made_by else {"kind": "injected"})
+ return frames, record
+
+
+def _bridge_lines(bridge: dict[str, Any]) -> list[str]:
+ """What became of a wrap the seam bridge read as a jump (`repair.seam_bridge`), in words (`video-loop: warning:`
+ lines): the frames made and the ones to look at, or why none was made. A wrap that reads as a step says nothing."""
+ if "skipped" in bridge:
+ return []
+ said = (f"the loop's wrap jumps (its step {bridge['seam']:.2f}x the mean of the {bridge['around']} steps either side, "
+ f"over {bridge['limit']:g})")
+ if bridge["replaced"]:
+ taken = bridge["tries"][-1]
+ a, b = taken["anchors"]
+ return [f"{said}: frames {', '.join(map(str, taken['frames']))} were made again by RIFE between frames {a} and {b} "
+ "(cycle/), so the loop plays across it — look at them in the loop, or cut it with --repair off "
+ "(docs/loop-repair.md section 2)",
+ *(f"frame {m['frame']} was made at the wrap with RIFE's frame between frames {a} and {b}, which may "
+ f"cross-fade two drawings inside its outline (crossfade {m['proposal']['crossfade']:.4f}); kept, a reading "
+ "to look at (docs/loop-repair.md section 4)" for m in taken["made"] if m["look"])]
+ if "unmade" in bridge:
+ return [f"{said}, and RIFE is not installed, so no frame was made round it — run `{rife_mod.INSTALL_COMMAND}` "
+ "and cut it again (docs/loop-repair.md section 2)"]
+ reasons = {"line": "the straight line between its anchors does not close it", "fault": "a frame made has a fault",
+ "seam": "the frames made do not close it"}
+ refused = "; ".join(f"{t['width']}: {reasons[t['rejected_for']]}" + (f" ({', '.join(t['faults'])})" if t.get("faults") else "")
+ for t in bridge["tries"])
+ return [f"{said}, and no frames made round it close it ({refused}): cut as filmed (docs/loop-repair.md section 2)"]
+
+
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)
@@ -1186,13 +1244,25 @@ def seam_on_cells(frames: list[Image.Image]) -> float:
return wrap_on_cells(frames)
+def cells_box(frames: list[Image.Image]) -> tuple[int, int, int, int]:
+ """The union box of a loop's frames, every pixel not fully transparent: the crop its rendered cells are read on."""
+ boxes = [f.getbbox() for f in frames]
+ boxes = [b for b in boxes if b]
+ return (min(b[0] for b in boxes), min(b[1] for b in boxes), max(b[2] for b in boxes), max(b[3] for b in boxes))
+
+
+def cell_features(frames: list[Image.Image], box: tuple[int, int, int, int] | None = None) -> np.ndarray:
+ """A loop's frames on the analysis thumbnail, each cropped to `box` (their union box, `cells_box`, where none is
+ given): the rendered cells, short of the strip's scale, as the seam gate (`wrap_on_cells`) and the seam bridge
+ (`repair.seam_bridge`) read them."""
+ box = box if box is not None else cells_box(frames)
+ return np.stack([_small_features(f.crop(box)) for f in frames])
+
+
def wrap_on_cells(frames: list[Image.Image]) -> float:
"""The seam gate's reading of a loop's frames as corrected: cropped to their union box, the wrap over the mean step
on the analysis thumbnail — the rendered cells the gate reads, short of the strip's scale."""
- boxes = [f.getbbox() for f in frames]
- boxes = [b for b in boxes if b]
- box = (min(b[0] for b in boxes), min(b[1] for b in boxes), max(b[2] for b in boxes), max(b[3] for b in boxes))
- flat = np.stack([_small_features(f.crop(box)) for f in frames])
+ flat = cell_features(frames)
step = float(np.abs(flat[1:] - flat[:-1]).mean())
return float(np.abs(flat[-1] - flat[0]).mean()) / step if step > 0 else math.inf
@@ -1747,6 +1817,26 @@ def run_loop(
print(f"video-loop: warning: a part of the loop rushes (frames {rush['frames']}, {rush['ratio']:.1f}x its steps "
"either side) and was not eased — RIFE is not installed, so the loop is cut as filmed; "
f"run `{rife_mod.INSTALL_COMMAND}` and cut it again (docs/loop-repair.md section 2)", file=sys.stderr)
+ elif repair != "off" and cycle["kind"] not in nonloop.KINDS:
+ # A loop that is not a walk: its flow is not read (an idle's blink would leave it), its wrap alone is, and the
+ # frames round a wrap that jumps are made again (the seam bridge, docs/loop-repair.md section 2). A pinned clip
+ # the pin refuses is refused whatever its wrap shows.
+ pin_refused = cycle["kind"] == "pinned" and cycle["pin_error"] > cycle["pin_tolerance"]
+ try:
+ frames, report_base["jump_repair"] = _bridge_seam(
+ frames, interpolate, facing=facing, required=repair == "on", seam_max=seam_max,
+ hold=report_base["cycle_drawings"]["hold"],
+ skip="the pin does not close: the clip is refused on it" if pin_refused else None)
+ except (ValueError, rife_mod.RifeUnavailable) as exc:
+ fix = (f"install RIFE (`{rife_mod.INSTALL_COMMAND}`), or pass --repair auto to cut it as filmed with a warning"
+ if isinstance(exc, rife_mod.RifeNotInstalled) else "fix RIFE, or pass --repair off to cut it as filmed")
+ error = f"video-loop: {exc}; the loop's wrap jumps and the frames round it are to be made — {fix} (docs/loop-repair.md section 2)"
+ write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})
+ raise SystemExit(error) from exc
+ if report_base["jump_repair"]["replaced"]:
+ report_base["seam_measurement"] = "rendered-cells"
+ for line in _bridge_lines(report_base["jump_repair"]):
+ print(f"video-loop: warning: {line}", file=sys.stderr)
else:
report_base["jump_repair"] = {"applied": False, "why": "--repair off" if repair == "off" else f"not a gait state ({state})"}
if prof.gait:
@@ -1991,7 +2081,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--body-height", type=int, help="scale so the STANDING height (the subject in the clip's first frame, i.e. the base still's pose) is this many px — the same value across states gives the same character size; --strip-height stays the cap")
parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="motion-auto: automatic stable regions, local repeat selection and XY ramp (walk/run); motion: fixed cut with explicit regions; body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")
parser.add_argument("--anchor-region", type=motion_anchor.parse_region, action="append", help="motion anchor only: repeat twice with head then torso x0,y0,x1,y1 in the first selected frame; requires --cycle fixed and at least 6 frames")
- parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): take out the frames off the walk's flow (one or two drawings that lie 3x their region's usual step off the line between the frames either side) and make them again with RIFE between those frames, each at its own time, so the loop keeps its length; adopt only without smear/outline faults, at most 3 calls and never made from or beside a frame made (docs/loop-repair.md section 2). A rejected group keeps its frames. Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")
+ parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): take out the frames off the walk's flow (one or two drawings that lie 3x their region's usual step off the line between the frames either side) and make them again with RIFE between those frames, each at its own time, so the loop keeps its length; adopt only without smear/outline faults, at most 3 calls and never made from or beside a frame made (docs/loop-repair.md section 2). A rejected group keeps its frames. A loop that is not a walk or run is not read for its flow: where its wrap steps over --seam-max times the mean of the three steps either side, one, two or four frames round it are made again by RIFE between the frames either side, the fewest first, taken only without faults and where every step from one to the other then reads within that limit (docs/loop-repair.md section 2, \"The seam bridge\"). Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")
parser.add_argument("--overlap-wrap", choices=OVERLAP_WRAP_MODES, default="on", help="--anchor motion-auto, under --repair auto or on: on (default): a cut two steps long whose wrap a part on its own beat leaves open (the seam gate refuses it) has four to twelve frames beside its wrap made again between the clip's frames a cycle apart and its own, each read with RIFE's single passes for a part torn — 34 calls of the binary a frame, up to forty frames (docs/loop-repair.md section 2, \"The overlapped wrap\"); off: not tried, recorded `wrap_overlap.skipped` with a warning line, and the gate refuses the cut as filmed — for a host whose RIFE runs on a CPU, where one frame of a 960 px clip takes minutes")
parser.add_argument("--jolt-max", type=float, default=None, help=f"walk/run: fail the repaired loop when its jolt index (how far each step strays from its neighbours' mean, over the median step) exceeds this. Default: no gate — the index is reported and a value over {repair_mod.JOLT_REFERENCE} is a warning line")
parser.add_argument("--head-step-max", type=float, default=None, help=f"walk/run: fail the repaired loop when the head's largest sideways move in one frame exceeds this %% of the body height. Default: no gate — reported, and over {repair_mod.HEAD_STEP_REFERENCE} is a warning line")
@@ -2053,7 +2143,11 @@ def run(**kwargs: object) -> int:
if payload.get("wrap_overlap"):
overlap = payload["wrap_overlap"]
summary["wrap_overlap"] = {k: overlap[k] for k in ("seam", "frames", "side", "width", "seam_after", "skipped") if k in overlap}
- if payload.get("jump_repair", {}).get("replaced"):
+ if payload.get("jump_repair", {}).get("reading") == "seam":
+ bridge = payload["jump_repair"]
+ if "skipped" not in bridge:
+ summary["jump_repair"] = {k: bridge[k] for k in ("reading", "seam", "replaced", "seam_after", "why") if k in bridge}
+ elif payload.get("jump_repair", {}).get("replaced"):
summary["jump_repair"] = {k: payload["jump_repair"][k] for k in ("replaced", "off_max_before", "off_max_after")}
eased = [r for r in payload["jump_repair"]["rounds"] if r.get("why") == "ease" and r["outcome"] == "accepted"]
if eased:
diff --git a/sprite_gen/video/repair.py b/sprite_gen/video/repair.py
index 84cb8d9..6c57667 100644
--- a/sprite_gen/video/repair.py
+++ b/sprite_gen/video/repair.py
@@ -1272,6 +1272,124 @@ def repair_jumps(frames: list[Image.Image], interpolate: Interpolate | None, *,
return out, record
+# --- the seam bridge (docs/loop-repair.md section 2, "The seam bridge") -------------------------------------------
+
+# A loop that is not a walk — an idle, an action cut whole — is not read for its flow: an idle's blinks and half-shut
+# eyes leave the walk's flow, and the flow repair would make them again. Its wrap alone is read, on the frames as they
+# play (`loop.cell_features`, the seam gate's own thumbnail): the step from its last frame to its first against the mean
+# of the SURGE_AROUND steps either side of it. A wrap over the gate's limit there jumps, and the frames round it are made
+# again by RIFE between the frames either side, the fewest first.
+BRIDGE_WIDTHS = (1, 2, 4) # frames made round the wrap: ceil(m / 2) before it and floor(m / 2) after
+BRIDGE_MIN_FRAMES = 2 * SURGE_AROUND + max(BRIDGE_WIDTHS) + 2 # the widest stretch and the steps either side, none shared
+
+
+def bridge_run(width: int, count: int) -> list[int]:
+ """The frames a bridge `width` frames wide makes round the wrap of a loop `count` frames long, in play order."""
+ return [*range(count - (width + 1) // 2, count), *range(width // 2)]
+
+
+def _ring(flat: np.ndarray) -> np.ndarray:
+ """A loop's steps as it plays, on its frames' features: `ring[k]` from frame k to the next, the last into the first."""
+ return np.abs(np.roll(flat, -1, axis=0) - flat).mean(axis=1)
+
+
+def _around(ring: np.ndarray, first: int, last: int) -> float:
+ """The mean of the SURGE_AROUND steps before step `first` and after step `last` of a loop's steps (`_ring`)."""
+ n = len(ring)
+ near = [(first - 1 - i) % n for i in range(SURGE_AROUND)] + [(last + 1 + i) % n for i in range(SURGE_AROUND)]
+ return max(float(ring[near].mean()), 1e-12)
+
+
+def seam_bridge(frames: list[Image.Image], interpolate: Interpolate | None, *, limit: float, hold: int | None,
+ facing: str = "right", skip: str | None = None) -> tuple[list[Image.Image], dict[str, Any]]:
+ """The seam bridge (docs/loop-repair.md section 2, "The seam bridge") of a loop that is not a walk.
+
+ The wrap jumps where its step is over `limit` (the seam gate's) times the mean of the SURGE_AROUND steps either side
+ of it, and over `loop.PIN_NOISE_MAX`, the re-render noise of a pinned first frame: a near-still loop moves so
+ little a step that its ratios are large where nothing shows. Read on the frames as they play, cropped to their union
+ box, on the seam gate's thumbnail (`loop.cell_features`). A loop drawn on twos or threes (`hold`, the cut's own,
+ `held.measure_cycle`) is not bridged: a frame made round the wrap would split a drawing, and a loop that changes its
+ drawing every other step reads the wrap against steps of nothing.
+
+ A wrap that jumps is bridged BRIDGE_WIDTHS frames at a time, the fewest first (`bridge_run`): each frame made by
+ `interpolate` between the frames either side of the run, at its own time (`between_time`), so the loop keeps its
+ length. Before a frame is made the straight line between the two (their thumbnails, mixed in steps of one) is read:
+ a run whose line leaves a step of the stretch from one to the other over `limit` times the mean of the steps
+ either side is not made, a reading RIFE's frames have not brought under it on any loop measured. A run is taken
+ where none of its frames carries an interpolation fault (`interpolation_quality.faults`, a ghost read where the
+ ghost screen reads the stretch and the steps either side) and, read again with them, every step of the stretch is
+ within `limit` times the mean of the steps either side; the first run taken ends the search. Where none is, the
+ loop is kept as filmed for the seam gate to judge. At most 1 + 2 + 4 frames are made.
+
+ `interpolate` None reads the wrap and stops at the first run to make (`unmade`). `skip` (why) reads nothing.
+ `facing` reads nothing here: it is recorded for the jump guard of `video-loop-compare` (`restoration.jump`)."""
+ from sprite_gen.video import loop as loop_mod # loop imports this module
+
+ n = len(frames)
+ record: dict[str, Any] = {"reading": "seam", "limit": limit, "floor": loop_mod.PIN_NOISE_MAX, "around": SURGE_AROUND,
+ "widths": list(BRIDGE_WIDTHS), "facing": facing, "replaced": [], "tries": [], "calls": 0}
+ if skip is not None:
+ record["skipped"] = skip
+ return frames, record
+ if n < BRIDGE_MIN_FRAMES:
+ record["skipped"] = f"a loop of {n} frames, under {BRIDGE_MIN_FRAMES}: no steps either side of the widest stretch"
+ return frames, record
+ box = loop_mod.cells_box(frames)
+ flat = loop_mod.cell_features(frames, box)
+ ring = _ring(flat)
+ wrap = float(ring[-1])
+ seam = wrap / _around(ring, n - 1, n - 1)
+ record.update(seam=round(seam, 4), wrap=round(wrap, 5), hold=hold)
+ if hold is not None and hold > 1:
+ record["skipped"] = "drawn on twos or threes: a frame made round the wrap would split a drawing"
+ return frames, record
+ if seam <= limit or wrap <= loop_mod.PIN_NOISE_MAX:
+ record["skipped"] = "the wrap reads as a step of the loop"
+ return frames, record
+ reads: bool | None = None
+ for width in BRIDGE_WIDTHS:
+ run = bridge_run(width, n)
+ a, b = (run[0] - 1) % n, (run[-1] + 1) % n
+ stretch = [(a + i) % n for i in range((b - a) % n)]
+ line = float(np.abs(flat[b] - flat[a]).mean()) / len(stretch) / _around(ring, stretch[0], stretch[-1])
+ tried: dict[str, Any] = {"width": width, "frames": run, "anchors": [a, b], "line": round(line, 4)}
+ record["tries"].append(tried)
+ if line > limit:
+ tried.update(outcome="rejected", rejected_for="line")
+ continue
+ if interpolate is None:
+ record["unmade"] = {k: tried[k] for k in ("frames", "anchors", "line")}
+ break
+ if reads is None:
+ # the ghost screen on the stretch and the steps either side, read once a frame is to be made
+ near = sorted({(a - SURGE_AROUND + i) % n for i in range(len(stretch) + 2 * SURGE_AROUND + 1)})
+ reads = bool(ghost_screen([frames[k] for k in near])["reads"])
+ out = list(frames)
+ made = []
+ for k in run:
+ t = between_time(a, k, b, n)
+ frame = interpolate(frames[a], frames[b], t)
+ record["calls"] += 1
+ if frame.mode != "RGBA" or frame.size != frames[k].size:
+ raise ValueError("repair interpolator must return an RGBA frame of the original size")
+ measure = {**smear(frame, frames[a], frames[b]), "outline_shift": outline_shift(frame, frames[a], frames[b]),
+ "ghost": ghost(frame) if reads else None, "crossfade": crossfade(frame, frames[a], frames[b], t)}
+ made.append({"frame": k, "t": round(t, 4), "proposal": measure, "look": looks(measure),
+ "faults": faults(measure) + ([] if frame.getchannel("A").getbbox() else ["empty"])})
+ out[k] = frame
+ after_ring = _ring(loop_mod.cell_features(out, box))
+ after = float(after_ring[stretch].max()) / _around(after_ring, stretch[0], stretch[-1])
+ wrong = sorted({f for m in made for f in m["faults"]})
+ tried.update(made=made, faults=wrong, look=sorted({w for m in made for w in m["look"]}), after=round(after, 4))
+ if wrong or after > limit:
+ tried.update(outcome="rejected", rejected_for="fault" if wrong else "seam")
+ continue
+ tried["outcome"] = "accepted"
+ record.update(replaced=run, width=width, seam_after=tried["after"])
+ return out, record
+ return frames, record
+
+
# --- the jolt index (docs/loop-repair.md section 3) ------------------------------------------
# Reference bounds, at the edge of what was kept on the 2026-10-03 takes (section 3): nothing kept