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): the seam gate reads a cell given way to the frame beside it as filmed

Soohong Kima4938ab35401
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 57d4fb2..298fe6f 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -38,6 +38,7 @@ import shutil
import subprocess
import sys
from dataclasses import dataclass
+from functools import partial
from pathlib import Path
from typing import Any
@@ -254,8 +255,12 @@ def leg_signals(frames: list[Image.Image]) -> dict[str, list[float]] | None:
def distance_matrix(files: list[Path]) -> np.ndarray:
- flat = np.stack([_load_small(f) for f in files])
- n = len(files)
+ return _distances(np.stack([_load_small(f) for f in files]))
+
+
+def _distances(flat: np.ndarray) -> np.ndarray:
+ """The distance between every two frames of their analysis features (`_small_features`)."""
+ n = len(flat)
D = np.zeros((n, n), dtype=np.float32)
for i in range(n):
D[i] = np.abs(flat - flat[i]).mean(axis=1)
@@ -850,6 +855,14 @@ def write_loop_report(target: Path, payload: dict[str, Any]) -> None:
atomic_write_text(target, json.dumps(finite(payload), ensure_ascii=False, indent=2, allow_nan=False) + "\n")
+def resampled_cells(strip: Image.Image, meta: dict[str, Any], idx: list[int], length: int) -> list[Image.Image]:
+ """The cells of `strip` (`build_strip`, its `meta`) at the frames `idx` of a cycle `length` frames long: the
+ GIF and WebP frames, and what the seam gate reads on rendered cells. A strip subsampled past its cell cap
+ holds fewer cells than the cycle has frames, and gives the nearest."""
+ cells = [strip.crop((k * meta["w"], 0, (k + 1) * meta["w"], meta["h"])) for k in range(meta["frames"])]
+ return [cells[min(len(cells) - 1, round(j * len(cells) / length))] for j in idx]
+
+
def shown_runs(cells: list[Image.Image]) -> int:
"""The frames a GIF or WebP of `cells` holds: a cell shown twice in a row (a filmed ghost given way
to the frame beside it, `--between nearest` stretching a loop) is one frame of twice the delay in
@@ -1346,8 +1359,11 @@ def run_loop(
# filmed ghost it names is a target of that repair, which gives it way to a clean frame where there is one.
# A loop delivered as cut, never aligned, would show it otherwise.
report_base["ghost_screen"] = ghost_screen(frames)
+ # Each cut frame given way to the frame beside it, as filmed: the seam is read on it there (`seam_as_filmed`).
+ as_filmed: dict[int, Image.Image] = {}
if repair != "off" and prof.gait:
report_base["jump_repair"] = None
+ filmed = frames
try:
frames, report_base["jump_repair"] = _repair_jumps(frames, interpolate, facing=facing, required=repair == "on",
screen=report_base["ghost_screen"])
@@ -1359,10 +1375,17 @@ def run_loop(
shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)
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"
# What became of each filmed ghost: given way (the cell and what it shows now) or kept, no clean frame beside it.
ghost_rounds = [r for r in report_base["jump_repair"]["rounds"] if r.get("why") == "ghost"]
+ # A cell given way to the frame beside it is that frame shown twice in a row — a step of nothing and a step of two,
+ # wherever the ghost was. The seam gate asks whether the cut closes, so it reads that cell as filmed (`seam_as_filmed`):
+ # at the wrap the step of two would read as a cut that does not close, and the step of nothing as one that closes
+ # whatever the cut. Only a frame made (RIFE's, for a jump or a ghost) has the gate read the rendered cells.
+ as_filmed = {r["target"]: filmed[r["target"]] for r in ghost_rounds if isinstance(r["taken"], dict)}
+ if as_filmed:
+ report_base["seam_as_filmed"] = sorted(as_filmed)
+ if set(report_base["jump_repair"]["replaced"]) - set(as_filmed):
+ report_base["seam_measurement"] = "rendered-cells"
report_base["ghost_given_way"] = [{"frame": r["target"], "ghost": r["original"]["ghost"], "taken": r["taken"]}
for r in ghost_rounds if r["taken"] is not None]
report_base["ghost_kept"] = [{"frame": r["target"], "ghost": r["original"]["ghost"]} for r in ghost_rounds if r["taken"] is None]
@@ -1437,9 +1460,12 @@ def run_loop(
report_base["cut_size"] = gait_fallback.size_change(gait_fallback.body_size(Image.open(files[0]).convert("RGBA")), cut_sizes)
if abs(report_base["cut_size"]["change"]) >= gait_fallback.SIZE_HOLD_MIN:
standing_frame = i
- strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),
- standing_src=standing_height(files[standing_frame], standing_frame) if body_height is not None else None,
- standing_frame=standing_frame)
+ strip_of = partial(build_strip, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),
+ standing_src=standing_height(files[standing_frame], standing_frame) if body_height is not None else None,
+ standing_frame=standing_frame)
+ strip, strip_meta = strip_of(frames)
+ # 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"]]}
# The scaled-back frames are read for the last time above; the cycle cells keep them.
@@ -1469,8 +1495,8 @@ def run_loop(
if anchor == "body":
strip_meta["foot_anchor"] = "body"
strip_meta["wrap_dx_px"] = wrap_dx
- # the wrap as it now plays: last ramped frame -> first, against an ordinary step
- Dr = distance_matrix(sorted(cycle_dir.glob("frame-*.png")))
+ # the wrap as it now plays: last ramped frame -> first, against an ordinary step (a cell given way read as filmed)
+ Dr = _distances(np.stack([_small_features(f) for f in seam_frames]))
inner = float(np.mean([Dr[k, k + 1] for k in range(len(frames) - 1)])) if len(frames) > 1 else 0.0
strip_meta["seam_ratio_after_anchor"] = round(float(Dr[len(frames) - 1, 0]) / inner, 4) if inner > 0 else None
# The GIF/WebP are cut from the strip's cells. A cycle longer than the cell cap was
@@ -1485,14 +1511,14 @@ def run_loop(
# resampled GIF/WebP frames: same crop as the strip, n_out evenly across the cycle
idx = [min(L - 1, i2) for i2 in (round(k * L / n_out) for k in range(n_out))]
- cells = [strip.crop((k * strip_meta["w"], 0, (k + 1) * strip_meta["w"], strip_meta["h"])) for k in range(strip_meta["frames"])]
- pick = [cells[min(len(cells) - 1, round(j * len(cells) / L))] for j in idx]
+ pick = resampled_cells(strip, strip_meta, idx, L)
seam_idx = [i + j for j in idx]
resampled_adjacent = float(np.mean([D[seam_idx[k], seam_idx[k + 1]] for k in range(len(seam_idx) - 1)]))
resampled_seam = float(D[seam_idx[-1], seam_idx[0]])
if report_base["seam_measurement"] == "rendered-cells":
- # Gate the actual corrected/repaired/resampled strip cells, with the same limit.
- flat = np.stack([_small_features(im) for im in pick])
+ # Gate 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.
+ flat = np.stack([_small_features(im) for im in (resampled_cells(*strip_of(seam_frames), idx, L) if as_filmed else pick)])
resampled_adjacent = float(np.abs(flat[1:] - flat[:-1]).mean())
resampled_seam = float(np.abs(flat[-1] - flat[0]).mean())
seam_ratio = resampled_seam / resampled_adjacent if resampled_adjacent > 0 else math.inf