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): a filmed ghost kept with no clean frame beside it is a take to film again — retake reason filmed-ghost

Soohong Kim569669359ba2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0dd035c..2ba36bd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,9 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- **The lane's RIFE-less run fails a skip that `--rife-only` will not run.** `--rife-unmeasured` runs the suite as `pytest --rife-unmeasured`, where `tests/conftest.py` reads every skip — by a skip mark, in a fixture or the test body, or of a whole file at import: one whose test is not marked `real_rife` fails by name, unless `NOT_RIFE_SKIPS` in the same file names it as skipping for an input the lane does not give (the `SPRITE_GEN_CHROMA_REAL_STILLS` stills). Such a skip would be measured by neither run.
- **`tests/release/test_lane_rife_collection.py`** collects the suite twice, once with a stand-in RIFE where `rife.locate()` looks (`SPRITE_GEN_RIFE`, `PATH`, the install root) and once with none: a test the two collections skip or collect differently and that is not marked `real_rife` fails it by name — a test collected only where RIFE is reachable never reaches the RIFE-less run. It also runs a marked test and each unmarked way to skip without RIFE through `pytest --rife-unmeasured`: the marked one skips, every other fails by name.
- **Correction to 2.43.0's cross-fade measure:** "the windows step by half their size, so one lost pixel is counted in up to four of them" holds where the window is an even number of pixels wide. The step is half the width rounded down, so an odd-width window counts one pixel in up to nine. The `rife.crossfade` docstring and `docs/loop-repair.md` section 4 now say "up to four of them (nine where the window is an odd number of pixels wide)". The measure is unchanged.
+- **Output change: a filmed ghost with no clean frame beside it is a take to film again — `retake` reason `filmed-ghost`.** Since 2.43.0 `video-cycle-align` delivers a filmed ghost only where the source frames on both sides of its time are ghosts too, and said so in a warning line alone: the loop's `retake` stayed `null`, so a pipeline that films a direction again on `retake` delivered the ghost. Such a loop is now named: its row's `retake` (and the report's, and `video-set`'s) reads `reason: "filmed-ghost"` with `ghost` — the cells `kept`, their frames of `cycle.source/` (`sources`), the highest reading (`ghost_max`) and the screen's `limit` — and `limits.ghost_kept_min` (one cell, `align.RETAKE_GHOST_KEPT_MIN`), with a line "film this direction again (filmed-ghost) — …". `retake` stays one object: `reason` is the first that applies (`held-drawings`, then `filmed-ghost`), the new `reasons` lists every one (`["held-drawings"]` for a held loop as before), and the held numbers stand only where that reason applies. Each `ghost_at` cell that keeps its ghost says why (`kept`: `no-clean-frame`, under any `--between`, or `between-rife` where `--between rife` kept it beside a clean frame — the aligner's choice, not counted). The set is aligned as before (`applied: true`, exit 0). Docs: `docs/loop-repair.md` section 4 (filmed ghost), `docs/video-pipeline.md`.
+- **Fix: a made frame given way at a cell that keeps its ghost no longer says the nearer source frame settled it.** Its line said "so the nearer source frame was taken there" where that frame was itself a filmed ghost, delivered for want of a clean one; it now says "the nearer source frame, a filmed ghost, was kept there, the frames beside it being filmed ghosts too". A ghost `--between rife` kept with no clean frame beside it is named "film this direction again", no longer told to align with `auto` for a clean frame that is not there.
+- **`tests/video/test_ghost_retake.py`** reproduces on the synthetic legs of `tests/video/test_ghost_screen.py` a ghost kept at a whole time (three in a row), one kept at a time made between two (the stand-in RIFE, and the real one, marked `real_rife`), and a held loop on twos that keeps ghosts too (both reasons, `held-drawings` first); under `--between rife` only the ghost with no clean frame beside it is counted; the fault line names the kept cell as it is.
## v2.43.0 - No loop delivers a ghost frame unmeasured; a cross-fade inside one silhouette is named, not judged
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index e3c9a1c..77bbea2 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -24,7 +24,10 @@ A loop whose cut holds each drawing for two or three frames (`held_drawings`, sp
held.py), that the length leaves at under RETAKE_DRAWINGS_MIN drawings a second, with frames
between them that could not be made, is aligned all the same — and named in the report's `retake`
(reason `held-drawings`, with its numbers) and in a warning: the gap is wider than any interpolator
-bridges, and only a new take fixes it.
+bridges, and only a new take fixes it. So is a loop that delivers a filmed ghost where neither source
+frame beside it is clean (reason `filmed-ghost`, its cells and source frames under `ghost`): no frame of
+the take shows the drawing there. A loop named for both carries one record, `reason` the first of them
+and `reasons` both.
The loop directories are `video-loop` output directories. Their first alignment keeps the cut
as filmed in `cycle.source/`; every later alignment reads from there, so running it again — or
@@ -133,6 +136,14 @@ CYCLES = (1, 2, 3) # what --cycles <loop>=k may say a loop holds
RETAKE_DRAWINGS_MIN = 13.0
RETAKE_UNMADE_MIN = 1
RETAKE_REASON = "held-drawings"
+# A filmed ghost the screen names is kept where it is the ghost itself that is delivered (`ghost_at`
+# `kept`): `no-clean-frame` where neither source frame beside its time is clean, `between-rife` where
+# `--between rife` kept it beside a clean one. A loop with RETAKE_GHOST_KEPT_MIN or more cells kept with no
+# clean frame is a take to film again, the reason `filmed-ghost`: no frame of the take shows the drawing
+# there. One kept under rife is the choice of whoever aligned it, and no reason.
+RETAKE_GHOST_KEPT_MIN = 1
+RETAKE_GHOST_REASON = "filmed-ghost"
+KEPT_NO_CLEAN, KEPT_RIFE = "no-clean-frame", "between-rife"
def held_drawings(frames: list[Image.Image], *, fps: float, clip: dict[str, Any] | None = None,
@@ -161,27 +172,51 @@ def held_drawings(frames: list[Image.Image], *, fps: float, clip: dict[str, Any]
return {"source": "cycle", **held_mod.measure([float(D[k, (k + 1) % n]) for k in range(n)], fps=fps, cyclic=True)}
-def retake(drawings: dict[str, Any], facts: dict[str, Any], *, fps: float) -> dict[str, Any] | None:
- """The reason to film a loop again, with its numbers, or None. `drawings` is the source's
- `held_drawings`, `facts` its `resample` facts: a held source stretched to under
- RETAKE_DRAWINGS_MIN drawings a second, with RETAKE_UNMADE_MIN or more frames between them not made
- — taken from the nearer source frame (`nearest_at`), or made with a fault and kept (`--between rife`)."""
- if not drawings.get("hold") or drawings["hold"] < 2:
+def retake(drawings: dict[str, Any], facts: dict[str, Any], ghost_at: list[dict[str, Any]], *, fps: float) -> dict[str, Any] | None:
+ """The reasons to film a loop again, with their numbers, in one record, or None. `drawings` is the
+ source's `held_drawings`, `facts` its `resample` facts, `ghost_at` its cells where a filmed ghost
+ gave way or was kept, as the loop's row records them (each cell where it now stands).
+
+ `held-drawings`: a held source stretched to under RETAKE_DRAWINGS_MIN drawings a second, with
+ RETAKE_UNMADE_MIN or more frames between them not made — taken from the nearer source frame
+ (`nearest_at`), or made with a fault and kept (`--between rife`); its numbers stand in the record
+ only where it applies. `filmed-ghost`: RETAKE_GHOST_KEPT_MIN or more cells where the ghost itself
+ was kept, neither frame beside its time clean (`kept` no-clean-frame) — `ghost` names them (`kept`),
+ their frames of the source (`sources`), the highest reading (`ghost_max`) and the screen's `limit`.
+ `reason` is the first that applies, in that order, `reasons` all of them, `limits` each one's."""
+ reasons: list[str] = []
+ record: dict[str, Any] = {}
+ limits: dict[str, Any] = {}
+ if drawings.get("hold") and drawings["hold"] >= 2:
+ per_second = drawings["drawings"] / (facts["to"] / fps)
+ unmade = len(facts.get("nearest_at", [])) + sum(1 for m in facts.get("smear", []) if m["method"] == "rife" and m["faults"])
+ if per_second < RETAKE_DRAWINGS_MIN and unmade >= RETAKE_UNMADE_MIN:
+ reasons.append(RETAKE_REASON)
+ record |= {"hold": drawings["hold"], "source": drawings["source"], "drawings": drawings["drawings"],
+ "drawings_per_second_filmed": drawings["drawings_per_second"], "drawings_per_second": round(per_second, 3),
+ "frames_per_drawing": round(facts["to"] / drawings["drawings"], 3), "unmade": unmade}
+ limits |= {"drawings_per_second_min": RETAKE_DRAWINGS_MIN, "unmade_min": RETAKE_UNMADE_MIN}
+ kept = [g for g in ghost_at if g.get("kept") == KEPT_NO_CLEAN]
+ if len(kept) >= RETAKE_GHOST_KEPT_MIN:
+ reasons.append(RETAKE_GHOST_REASON)
+ record["ghost"] = {"kept": [g["at"] for g in kept], "sources": sorted({g["source"] for g in kept}),
+ "ghost_max": max(g["ghost"] for g in kept), "limit": facts["ghost_screen"]["limit"]}
+ limits["ghost_kept_min"] = RETAKE_GHOST_KEPT_MIN
+ if not reasons:
return None
- seconds = facts["to"] / fps
- per_second = drawings["drawings"] / seconds
- unmade = len(facts.get("nearest_at", [])) + sum(1 for m in facts.get("smear", []) if m["method"] == "rife" and m["faults"])
- if per_second >= RETAKE_DRAWINGS_MIN or unmade < RETAKE_UNMADE_MIN:
- return None
- return {"reason": RETAKE_REASON, "hold": drawings["hold"], "source": drawings["source"], "drawings": drawings["drawings"],
- "drawings_per_second_filmed": drawings["drawings_per_second"], "drawings_per_second": round(per_second, 3),
- "frames_per_drawing": round(facts["to"] / drawings["drawings"], 3), "unmade": unmade,
- "limits": {"drawings_per_second_min": RETAKE_DRAWINGS_MIN, "unmade_min": RETAKE_UNMADE_MIN}}
-
-
-def _retake_line(name: str, r: dict[str, Any]) -> str:
- """A loop to film again, in words."""
- return (f"{name}: film this direction again ({r['reason']}) — its {'clip' if r['source'] == 'clip' else 'cut'} shows each drawing for {r['hold']} frames "
+ return {"reason": reasons[0], "reasons": reasons, **record, "limits": limits}
+
+
+def _retake_line(name: str, r: dict[str, Any], reason: str) -> str:
+ """A loop to film again for `reason` (one of its `reasons`), in words."""
+ if reason == RETAKE_GHOST_REASON:
+ g = r["ghost"]
+ cells, sources = ", ".join(map(str, g["kept"])), ", ".join(map(str, g["sources"]))
+ return (f"{name}: film this direction again ({reason}) — frame(s) {cells} show source frame(s) {sources} of {SOURCE_DIR}/, "
+ f"filmed ghosts (up to {_ghost_words(g['ghost_max'])}), and the source frames beside each are filmed ghosts too: "
+ "no clean frame stands there, so the loop shows the ghost. A new take fixes it; no frame of this one shows the "
+ "drawing there (docs/loop-repair.md section 4)")
+ return (f"{name}: film this direction again ({reason}) — its {'clip' if r['source'] == 'clip' else 'cut'} shows each drawing for {r['hold']} frames "
f"({r['drawings']:g} drawings in the cycle, {r['drawings_per_second_filmed']:g} a second as filmed); at the set's length "
f"that is {r['drawings_per_second']:g} drawings a second, {r['frames_per_drawing']:g} frames apart, and {r['unmade']} "
"frame(s) between them could not be made, so the loop halts there. A new take that draws every frame "
@@ -207,7 +242,8 @@ def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Inter
a source frame it names is not taken under auto or nearest — at a time on it, the frame after it is,
or the one before it; where it is the nearer frame, the other beside the time is — and rife keeps it.
Each such cell is listed in `ghost_at`: `at`, the ghost `source` and its reading, and the frame
- `taken` (the ghost itself where rife kept it, or where neither frame beside it is clean)."""
+ `taken` — the ghost itself where rife kept it beside a clean frame (`kept` between-rife), or where
+ neither frame beside it is clean (`kept` no-clean-frame, under any `between`)."""
count = len(frames)
if length < 2:
raise ValueError(f"cycle length {length} is too short")
@@ -223,11 +259,12 @@ def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Inter
def clean(k: int, first: int, other: int) -> int:
"""`first` where the screen passes it, else `other` where it passes that (rife takes `first`
- as it is); each ghost passed over or taken is listed in `ghost_at`."""
+ as it is); each ghost passed over or taken is listed in `ghost_at`, a ghost taken with why it was kept."""
if first not in ghosts:
return first
taken_ = first if between == "rife" or other in ghosts else other
- ghost_at.append({"at": k, "source": first, "ghost": ghosts[first], "taken": taken_})
+ ghost_at.append({"at": k, "source": first, "ghost": ghosts[first], "taken": taken_,
+ **({"kept": KEPT_NO_CLEAN if other in ghosts else KEPT_RIFE} if taken_ == first else {})})
return taken_
for k in range(length):
@@ -693,9 +730,10 @@ def _ghost_words(reading: float) -> str:
return f"a part-covered band over {100 * reading:.2f} % of its body, at least {rife_mod.GHOST_THICK} px thick"
-def _fault_line(name: str, m: dict[str, Any], *, other_side: bool = False) -> str:
- """A made frame's faults, in words, and what became of it; `other_side` where the nearer source
- frame is a filmed ghost and the other beside it was taken (`_ghost_line` names both)."""
+def _fault_line(name: str, m: dict[str, Any], ghost: dict[str, Any] | None = None) -> str:
+ """A made frame's faults, in words, and what became of it; `ghost` is its cell's `ghost_at` entry
+ where the nearer source frame is a filmed ghost — the other beside it taken, or the ghost kept, the
+ other a filmed ghost too (`_ghost_line` names both)."""
what = [*([f"has {100 * m['dark_excess']:.2f} % more dark pixels inside the body than either source frame beside it — a smear"]
if "smear" in m["faults"] else []),
*([f"lost its outline on {100 * m['outline_loss']:.2f} % of its edge beyond either source frame beside it — "
@@ -703,8 +741,11 @@ def _fault_line(name: str, m: dict[str, Any], *, other_side: bool = False) -> st
*([f"carries {_ghost_words(m['ghost'])} — a ghost"] if "ghost" in m["faults"] else [])]
if m["method"] == "nearest":
return (f"{name}: frame {m['at']}: RIFE's frame " + "; ".join(what)
- + (", so the source frame on its other side was taken there, the nearer being a filmed ghost (--between auto)"
- if other_side else ", so the nearer source frame was taken there (--between auto)"))
+ + (", so the nearer source frame was taken there (--between auto)" if ghost is None else
+ ", so the source frame on its other side was taken there, the nearer being a filmed ghost (--between auto)"
+ if ghost["taken"] != ghost["source"] else
+ ", so the nearer source frame, a filmed ghost, was kept there, the frames beside it being filmed ghosts too "
+ "(--between auto)"))
return (f"{name}: frame {m['at']} (made by RIFE) " + "; ".join(what)
+ "; see it in cycle/, or align with --between auto (the nearer source frame there) or --between nearest")
@@ -717,12 +758,12 @@ def _look_line(name: str, m: dict[str, Any]) -> str:
"--between nearest or film the direction again (docs/loop-repair.md section 4)")
-def _ghost_line(name: str, g: dict[str, Any], between: str) -> str:
+def _ghost_line(name: str, g: dict[str, Any]) -> str:
"""A cell where a filmed ghost frame would have been delivered, and what was instead."""
line = f"{name}: frame {g['at']}: source frame {g['source']} is a filmed ghost ({_ghost_words(g['ghost'])})"
if g["taken"] != g["source"]:
return line + f", so source frame {g['taken']} beside it was taken there"
- if between == "rife":
+ if g["kept"] == KEPT_RIFE:
return line + "; kept (--between rife) — see it in cycle/, or align with --between auto or nearest (a clean frame beside it there)"
return line + ", and so are the frames beside it; kept — film this direction again"
@@ -865,7 +906,10 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
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"))
- again = retake(drawings, facts, fps=fps)
+ # 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"])
+ again = retake(drawings, facts, ghost_at, fps=fps)
record = {**facts, "drawings": drawings, "retake": again, "turned_by": start, "turned_on": strike["by"], "view": view, "start_foot": strike["start_foot"],
"start_foot_source": strike["start_foot_source"],
# the two strikes as they stand in the rebuilt cycle/: the larger first
@@ -879,10 +923,9 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
record["nearest_at"] = sorted((k - start) % target for k in facts["nearest_at"])
if "smear" in facts:
record["smear"] = sorted(({**m, "at": (m["at"] - start) % target} for m in facts["smear"]), key=lambda m: m["at"])
- # the screen's frames and the ghosts passed over as frames of cycle.source/, each cell where it now stands
+ # the screen's frames as frames of cycle.source/
record["ghost_screen"] = {**facts["ghost_screen"], "ghosts": [{**g, "frame": index[g["frame"]]} for g in facts["ghost_screen"]["ghosts"]]}
- record["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"])
+ record["ghost_at"] = ghost_at
provenance = [{"source": index[p["source"]]} if "source" in p else {"between": [index[j] for j in p["between"]], "t": p["t"]}
for p in provenance]
aligned.append((out[start:] + out[:start], record, provenance[start:] + provenance[:start]))
@@ -893,17 +936,18 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
rows.append({"dir": str(d), "name": meta_path.name[: -len(".strip.json")],
**{k: v for k, v in record.items() if k not in ("gif", "webp", "origin")},
"strip": {k: merged[k] for k in ("frames", "w", "h", "body_h", "delay_ms")}})
- warnings = [_fault_line(r["name"], m, other_side=any(g["at"] == m["at"] and g["taken"] != g["source"] for g in r["ghost_at"]))
+ warnings = [_fault_line(r["name"], m, next((g for g in r["ghost_at"] if g["at"] == m["at"]), None))
for r in rows for m in r.get("smear", []) if m["faults"]]
warnings += [_look_line(r["name"], m) for r in rows for m in r.get("smear", []) if m["method"] == "rife" and m["look"]]
retakes = [{"dir": r["dir"], "name": r["name"], **r["retake"]} for r in rows if r["retake"]]
# A loop to film again is named by its directory where two loops share a strip name (each `walk`).
shared = len({r["name"] for r in rows}) < len(rows)
- warnings += [_ghost_line(r["dir"] if shared else r["name"], g, between) for r in rows for g in r["ghost_at"]]
+ warnings += [_ghost_line(r["dir"] if shared else r["name"], g) for r in rows for g in r["ghost_at"]]
warnings += [f"{r['dir'] if shared else r['name']}: the ghost screen does not read it — {r['ghost_screen']['why']}; no frame of it "
"is named a ghost or given way for one, so look at cycle/ (docs/loop-repair.md section 4)"
for r in rows if not r["ghost_screen"]["reads"]]
- warnings = cycle_warnings + [_retake_line(r["dir"] if shared else r["name"], r["retake"]) for r in rows if r["retake"]] + warnings
+ warnings = cycle_warnings + [_retake_line(r["dir"] if shared else r["name"], r["retake"], reason)
+ for r in rows if r["retake"] for reason in r["retake"]["reasons"]] + warnings
unnamed = [_unnamed_foot(r) for r in rows if r["start_foot"] is None]
if len(rows) > 1 and views is None and unnamed:
warnings.append("no view given (--view): each loop " + ("not named by --foot " if told else "")