Skip to content

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

fix(cycle-align): a frame RIFE melted is caught by the outline it lost, and --between auto (the default) takes the nearer source frame there

Soohong Kimcd17c59bb672
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index e16cb88..a0b6ff1 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -6,10 +6,11 @@ set measured 16 to 27 frames). A game that turns a character mid-stride wants ev
to be the same number of frames and to start on the same step. So every loop of the set is
resampled to the set's median length L*: frame k of the new loop is the source loop at time
k·L/L* (cyclic, offset 0), so a time that lands on a source frame takes that frame as filmed
-and only the times between two frames are made by RIFE (or, `--between nearest`, take the nearer
-source frame). Then each loop is turned to start as a heel lands — read off the stride, the
-lowest row or the body's top line (`foot_strike`), never off the frame's top edge, which a long
-ear owns. docs/loop-repair.md section 4.
+and only the times between two frames are made by RIFE — each kept unless it smeared or lost its
+outline, where the nearer source frame is taken instead (`--between auto`, the default; `rife`
+keeps every made frame and warns, `nearest` makes none). Then each loop is turned to start as a
+heel lands — read off the stride, the lowest row or the body's top line (`foot_strike`), never off
+the frame's top edge, which a long ear owns. docs/loop-repair.md section 4.
Every frame between two source frames softens a little, so the length is the median (the one
that needs the fewest made frames across the set), and a loop already that long is not touched.
@@ -70,7 +71,8 @@ FOOT_MARGIN = 0.01
# A cue that does not swing with the step is the drawing's own flicker: its once-a-cycle swing (first
# harmonic) must be at least this share of its spread over the cycle.
CUE_RHYTHM = 0.25
-BETWEEN = ("rife", "nearest") # how a time between two source frames is filled (resample)
+BETWEEN = ("auto", "rife", "nearest") # how a time between two source frames is filled (resample)
+DEFAULT_BETWEEN = "auto"
# A set with a loop the two-cycle screen suspects and no --cycles for it: fail (default) stops the
# set before anything is rewritten, warn aligns it as it is and names the loop in the warnings.
MULTI_CYCLE = ("fail", "warn")
@@ -78,15 +80,30 @@ CYCLES = (1, 2, 3) # what --cycles <loop>=k may say a loop holds
# A made frame whose dark pixels inside the body exceed both neighbours' by this fraction of its
# solid pixels is named in the report's warnings: a smear, not a dark part that moved.
SMEAR_WARN = 0.001
+# A made frame whose coverage edge has no outline beyond both neighbours' by this fraction of its
+# edge (`rife.smear`'s `outline_loss`) has melted: legs that crossed too far for the flow became one
+# shape of fill, or a limb a pale ghost. Outlined legs crossing too far melt at 32 %, a short step
+# the flow follows stays under 3 % (tests/video/test_rife.py; docs/loop-repair.md section 4).
+OUTLINE_WARN = 0.05
+
+
+def faults(measure: dict[str, float]) -> list[str]:
+ """What is wrong with a made frame, by its `rife.smear` measure: `smear` (dark beyond both
+ neighbours, SMEAR_WARN) and `outline` (outline lost beyond both, OUTLINE_WARN)."""
+ return ([*(["smear"] if measure["dark_excess"] > SMEAR_WARN else []),
+ *(["outline"] if measure["outline_loss"] > OUTLINE_WARN else [])])
def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Interpolate | None,
- *, between: str = "rife") -> tuple[list[Image.Image], dict[str, Any]]:
+ *, between: str = DEFAULT_BETWEEN) -> tuple[list[Image.Image], dict[str, Any]]:
"""`frames` as one cycle, resampled to `length` frames at times k·L/length (offset 0).
- A time between two source frames is made by `interpolate` (`between` rife), with what it added
- measured (`rife.smear`), or takes the nearer source frame (`between` nearest: nothing is made,
- the motion keeps the filmed frames at up to half a frame off their time)."""
+ A time between two source frames is made by `interpolate`, with what it added and the outline it
+ lost measured (`rife.smear`) and judged (`faults`); `between` auto keeps a made frame with no
+ fault and takes the nearer source frame where it has one, rife keeps every made frame, nearest
+ makes none and takes the nearer source frame (the motion keeps the filmed frames at up to half a
+ frame off their time). Every made frame is listed in `smear` with its `method`: rife (kept) or
+ nearest (the nearer source frame taken instead)."""
count = len(frames)
if length < 2:
raise ValueError(f"cycle length {length} is too short")
@@ -100,25 +117,30 @@ def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Inter
t = k * count / length
i = int(np.floor(t))
frac = t - i
+ nearer = frames[(i + (frac >= 0.5)) % count]
if frac < SNAP:
out.append(frames[i % count])
elif frac > 1 - SNAP:
out.append(frames[(i + 1) % count])
elif between == "nearest":
- out.append(frames[(i + (frac >= 0.5)) % count])
+ out.append(nearer)
nearest_at.append(k)
else:
if interpolate is None:
raise ValueError(f"frame {k} of {length} falls between source frames and no interpolator is available")
a, b = frames[i % count], frames[(i + 1) % count]
- out.append(interpolate(a, b, frac))
- made_at.append(k)
- smears.append({"at": k, **rife_mod.smear(out[-1], a, b)})
+ made = interpolate(a, b, frac)
+ measure = rife_mod.smear(made, a, b)
+ wrong = faults(measure)
+ keep = between == "rife" or not wrong
+ out.append(made if keep else nearer)
+ (made_at if keep else nearest_at).append(k)
+ smears.append({"at": k, "method": "rife" if keep else "nearest", **measure, "faults": wrong})
facts: dict[str, Any] = {"from": count, "to": length, "between": between, "taken": length - len(made_at),
"made_by_rife": len(made_at), "made_at": made_at}
- if between == "nearest":
+ if between != "rife":
facts["nearest_at"] = nearest_at
- else:
+ if between != "nearest":
facts["smear"] = smears
return out, facts
@@ -420,8 +442,20 @@ def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: list
return merged
+def _fault_line(name: str, m: dict[str, Any]) -> str:
+ """A made frame's faults, in words, and what became of it."""
+ 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 — "
+ "a melted or ghost limb"] if "outline" in m["faults"] else [])]
+ if m["method"] == "nearest":
+ return f"{name}: frame {m['at']}: RIFE's frame " + "; ".join(what) + ", so the nearer source frame was taken there (--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")
+
+
def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate: rife_mod.Interpolate | None = None,
- report_path: Path | None = None, between: str = "rife", views: list[str | None] | None = None,
+ report_path: Path | None = None, between: str = DEFAULT_BETWEEN, views: list[str | None] | None = None,
start_foot: str = START_FOOT, multi_cycle: str = "fail", cycles: dict[str, int] | None = None,
state: str | None = None) -> dict[str, Any]:
"""Resample every loop of a set to one length (default: the median), turned to a foot strike —
@@ -492,7 +526,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
# holds one cycle, or the number it holds (each loop's `settle` lists the choices).
rerun = ["sprite-gen video-cycle-align", *(f"--loop-dir {d}" for d, *_ in loops),
*(f"--view {v}" for v in (views or []) if v is not None), *([f"--length {length}"] if length is not None else []),
- *([f"--between {between}"] if between != "rife" else []), *([f"--start-foot {start_foot}"] if start_foot != START_FOOT else []),
+ *([f"--between {between}"] if between != DEFAULT_BETWEEN else []), *([f"--start-foot {start_foot}"] if start_foot != START_FOOT else []),
*([f"--state {state}"] if state else []), *([f"--report {report_path}"] if report_path is not None else []),
*(f"--cycles {loops[i][0]}={k}" for i, k in sorted(given.items())),
*(f"--cycles {e['dir']}=<{'|'.join(s.rpartition('=')[2] for s in e['settle'])}>" for e in stopped)]
@@ -550,9 +584,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
merged = _rebuild(d, meta_path, meta, out, fps, record)
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")},
"strip": {k: merged[k] for k in ("frames", "w", "h", "body_h", "delay_ms")}})
- warnings = [f"{r['name']}: frame {m['at']} (made by RIFE) has {100 * m['dark_excess']:.2f} % more dark pixels inside the body "
- f"than either source frame beside it — a smear; see it in cycle/, or align with --between nearest"
- for r in rows for m in r.get("smear", []) if m["dark_excess"] > SMEAR_WARN]
+ warnings = [_fault_line(r["name"], m) for r in rows for m in r.get("smear", []) if m["faults"]]
warnings = cycle_warnings + warnings
if len(rows) > 1 and views is None:
warnings.append("no view given (--view): each loop starts on its larger strike, whichever foot that is")
@@ -566,8 +598,9 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
"cycles_given": {str(loops[i][0]): k for i, k in given.items()},
"fps": round(fps, 4), "cycle_seconds": round(target / fps, 4),
"interpolator": ({"kind": "rife-ncnn-vulkan", **located[0]} if located else
- {"kind": "injected"} if any(r["made_by_rife"] for r in rows) else None),
- "made_by_rife": sum(r["made_by_rife"] for r in rows), "loops": rows}
+ {"kind": "injected"} if any(r.get("smear") for r in rows) else None),
+ "made_by_rife": sum(r["made_by_rife"] for r in rows),
+ "replaced": sum(1 for r in rows for m in r.get("smear", []) if m["method"] == "nearest"), "loops": rows}
if report_path is not None:
loop_mod.write_loop_report(report_path.expanduser().resolve(), report)
return report
@@ -591,9 +624,11 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
"`suspects`; warn aligns it as it is and names it in the warnings")
parser.add_argument("--state", help="the set's motion state (walk, run), for loops cut before video-loop wrote it in the strip metadata: "
"its gait floor is the shortest cycle the screen looks for")
- parser.add_argument("--between", choices=BETWEEN, default="rife",
- help="a time between two source frames: rife (default) makes that frame, its smear measured per frame in the report; "
- "nearest takes the nearer source frame — nothing made, no RIFE needed, the motion up to half a frame off its time")
+ parser.add_argument("--between", choices=BETWEEN, default=DEFAULT_BETWEEN,
+ help="a time between two source frames: auto (default) makes that frame with RIFE and keeps it unless it smeared "
+ "or lost its outline (a melted limb), where the nearer source frame is taken and named in the warnings; rife "
+ "keeps every made frame and warns on those; nearest takes the nearer source frame — nothing made, no RIFE "
+ "needed, the motion up to half a frame off its time. Every made frame is measured in the report (`smear`)")
def parse_cycles(values: list[str]) -> dict[str, int]:
@@ -612,7 +647,7 @@ def parse_cycles(values: list[str]) -> dict[str, int]:
def run(**kwargs: object) -> int:
try:
report = align_set(list(kwargs["loop_dir"]), length=kwargs.get("length"), report_path=kwargs.get("report"), # type: ignore[arg-type]
- between=str(kwargs.get("between") or "rife"), views=kwargs.get("view"), # type: ignore[arg-type]
+ between=str(kwargs.get("between") or DEFAULT_BETWEEN), views=kwargs.get("view"), # type: ignore[arg-type]
start_foot=str(kwargs.get("start_foot") or START_FOOT),
multi_cycle=str(kwargs.get("multi_cycle") or "fail"), cycles=parse_cycles(list(kwargs.get("cycles") or [])), # type: ignore[arg-type]
state=kwargs.get("state")) # type: ignore[arg-type]
@@ -622,7 +657,7 @@ def run(**kwargs: object) -> int:
f"`{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)") from exc
for line in report["warnings"]:
print(f"video-cycle-align: warning: {line}", file=sys.stderr)
- print(json.dumps({k: report[k] for k in ("length", "lengths", "cycles_given", "between", "made_by_rife", "cycle_seconds")}
+ print(json.dumps({k: report[k] for k in ("length", "lengths", "cycles_given", "between", "made_by_rife", "replaced", "cycle_seconds")}
| {"loops": [{k: r[k] for k in ("name", "from", "to", "made_by_rife", "turned_by", "turned_on", "start_foot", "seam_ratio")} for r in report["loops"]]},
ensure_ascii=False, indent=2))
return 0
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 5617a6d..88feddb 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -660,7 +660,7 @@ def _align_view(r: dict[str, Any]) -> str | None:
return r["direction"] + (f"@{r['turned']}" if r["direction"] in handed_mod.LATERAL_VIEWS else "")
-def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpolate: Any = None, between: str = "rife") -> dict[str, Any]:
+def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpolate: Any = None, between: str = align_mod.DEFAULT_BETWEEN) -> dict[str, Any]:
"""One cycle length per gait state across the set's directions (`video-cycle-align`,
docs/loop-repair.md section 4). A state filmed in fewer than two directions has nothing to
match. A failure is recorded under its state and the batch reports it; the loops stay as cut.
@@ -701,7 +701,7 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpo
out[state] = {"ok": False, "error": str(exc)}
continue
out[state] = {"ok": True, "applied": True, "length": report["length"], "lengths": report["lengths"], "between": report["between"],
- "made_by_rife": report["made_by_rife"], "warnings": report["warnings"], "report": str(root / f"{state}.cycle-align.json")}
+ "made_by_rife": report["made_by_rife"], "replaced": report["replaced"], "warnings": report["warnings"], "report": str(root / f"{state}.cycle-align.json")}
for line in report["warnings"]:
print(f"video-set: warning: {state}: {line}", file=sys.stderr)
for r, row in zip(rows, report["loops"]):
@@ -755,7 +755,7 @@ def run_set(
fit: str = "state",
decontam: str = "off",
align_cycles: str = "auto",
- align_between: str = "rife",
+ align_between: str = align_mod.DEFAULT_BETWEEN,
interpolate: Any = None,
walk_start: str = "redraw",
redraw_runner: Callable[..., int] = run_redraw_cli,
@@ -866,7 +866,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--walk-start", choices=WALK_START_MODES, default="redraw", help="redraw (default): a front or back walk films from its base still redrawn mid-step (one image generation, `sprite-gen gen --ref base`, kept as walk-start.png) — from a standing still the clip model walks askew; as-given: film from the base still itself")
parser.add_argument("--still-provider", help="image provider for the mid-step redraw (default: sprite-gen gen's own default)")
parser.add_argument("--align-cycles", choices=ALIGN_MODES, default="auto", help="auto (default): after the loops are cut, every walk/run filmed in two or more directions is resampled to the set's median cycle length and turned to start on a foot strike (video-cycle-align; RIFE makes only the frames between source frames — where no RIFE is installed the alignment is skipped with a warning and recorded); off: each loop keeps its own length")
- parser.add_argument("--align-between", choices=align_mod.BETWEEN, default="rife", help="how the alignment fills a time between two source frames (video-cycle-align --between): rife (default) makes the frame, nearest takes the nearer source frame")
+ parser.add_argument("--align-between", choices=align_mod.BETWEEN, default=align_mod.DEFAULT_BETWEEN, help="how the alignment fills a time between two source frames (video-cycle-align --between): auto (default) makes the frame with RIFE and takes the nearer source frame where it smeared or lost its outline, rife keeps every made frame, nearest takes the nearer source frame")
parser.add_argument("--force", action="store_true", help="regenerate clips that already exist")
@@ -881,7 +881,7 @@ def run(**kwargs: object) -> int:
shape=(str(kwargs["shape"]) if kwargs.get("shape") else None), anchor=str(kwargs.get("anchor") or "none"), spill=str(kwargs.get("spill") or "auto"),
body_height=(int(kwargs["body_height"]) if kwargs.get("body_height") else None), fit=str(kwargs.get("fit") or "state"),
decontam=str(kwargs.get("decontam") or "off"), align_cycles=str(kwargs.get("align_cycles") or "auto"),
- align_between=str(kwargs.get("align_between") or "rife"),
+ align_between=str(kwargs.get("align_between") or align_mod.DEFAULT_BETWEEN),
walk_start=str(kwargs.get("walk_start") or "redraw"), still_provider=kwargs.get("still_provider"), # type: ignore[arg-type]
handed=handed_mod.parse_all(list(kwargs.get("handed") or [])) or None, # type: ignore[arg-type]
)
diff --git a/sprite_gen/video/rife.py b/sprite_gen/video/rife.py
index aed8091..652683e 100644
--- a/sprite_gen/video/rife.py
+++ b/sprite_gen/video/rife.py
@@ -9,7 +9,8 @@ what lay around the body. So around the body the colour image holds the body's o
pushed out from inside its outline (`bleed`): a disagreement there reads as the body, not as the
black a frame premultiplied over black put under it (2.24 and before: a black smear between
crossing legs). Inside the coverage the colour is the frame's own, outline included.
-`smear` measures what a made frame has that neither neighbour has (docs/loop-repair.md section 4).
+`smear` measures what a made frame has that neither neighbour has, and the outline it lost where
+the flow failed and melted a limb into the fill (docs/loop-repair.md section 4).
The binary's own CPU path (`-g -1`) returns a wrong frame with rife-v4.6 on both macOS and
Linux (measured 2026-10-03: mean error 39 against 3.3 through Vulkan), so it is never passed;
@@ -50,6 +51,10 @@ BLEED_DEPTH = 0.008
# `smear`: a pixel is dark under this luma (0..1), and part-covered between these alphas.
DARK_LUMA = 70 / 255
PARTIAL_ALPHA = (0.1, 0.9)
+# `smear`'s outline: a pixel of the coverage's edge (alpha from PARTIAL_ALPHA's floor) is outlined
+# when a dark solid pixel lies within this many pixels of it. A drawn outline sits on the edge, under
+# an antialiased pixel or two, whatever the frame's size.
+OUTLINE_REACH = 2
CALL_TIMEOUT_SECONDS = 120
Interpolate = Callable[[Image.Image, Image.Image, float], Image.Image]
@@ -183,26 +188,39 @@ def between(a: Image.Image, b: Image.Image, t: float, *, binary: Path, model: Pa
return Image.fromarray(np.uint8(np.clip(out, 0, 1) * 255 + 0.5), "RGBA")
-def _smear_counts(frame: Image.Image) -> tuple[int, int, int]:
- """(dark pixels inside the solid body, one pixel in from its edge; solid pixels; part-covered pixels)."""
+def _mask(mask: np.ndarray, size: int, op: type) -> np.ndarray:
+ return np.asarray(Image.fromarray(np.uint8(mask) * 255).filter(op(size))) > 0
+
+
+def _smear_counts(frame: Image.Image) -> tuple[int, int, int, int, int]:
+ """(dark pixels inside the solid body, one pixel in from its edge; solid pixels; part-covered
+ pixels; pixels on the coverage's edge; those of them with no outline within OUTLINE_REACH)."""
x = np.asarray(frame.convert("RGBA"), dtype=np.float32) / 255.0
solid = x[..., 3] >= 0.5
- inner = np.asarray(Image.fromarray(np.uint8(solid) * 255).filter(ImageFilter.MinFilter(3))) > 0
+ inner = _mask(solid, 3, ImageFilter.MinFilter)
luma = x[..., 0] * 0.299 + x[..., 1] * 0.587 + x[..., 2] * 0.114
lo, hi = PARTIAL_ALPHA
- return int((inner & (luma < DARK_LUMA)).sum()), int(solid.sum()), int(((x[..., 3] > lo) & (x[..., 3] < hi)).sum())
+ covered = x[..., 3] >= lo
+ edge = covered & ~_mask(covered, 3, ImageFilter.MinFilter)
+ outlined = _mask(solid & (luma < DARK_LUMA), 2 * OUTLINE_REACH + 1, ImageFilter.MaxFilter)
+ return (int((inner & (luma < DARK_LUMA)).sum()), int(solid.sum()), int(((x[..., 3] > lo) & (x[..., 3] < hi)).sum()),
+ int(edge.sum()), int((edge & ~outlined).sum()))
def smear(made: Image.Image, a: Image.Image, b: Image.Image) -> dict[str, float]:
- """What a made frame has that neither of its two neighbours has, as fractions of its solid
- pixels: `dark_excess`, dark pixels inside the body beyond the darker neighbour's count (a black
- smear raises it; a moved dark part — a hat, a watch — keeps its count), and `partial_excess`,
- part-covered pixels beyond the more ragged neighbour's (a limb RIFE could not follow, drawn as
- a pale ghost). Zero or less: nothing added."""
- dm, sm, pm = _smear_counts(made)
- (da, _, pa), (db, _, pb) = _smear_counts(a), _smear_counts(b)
+ """What a made frame has that neither of its two neighbours has: `dark_excess`, dark pixels
+ inside the body beyond the darker neighbour's count (a black smear raises it; a moved dark
+ part — a hat, a watch — keeps its count), and `partial_excess`, part-covered pixels beyond the
+ more ragged neighbour's, both as fractions of its solid pixels; and `outline_loss`, the edge of
+ its coverage that has no outline beyond the less outlined neighbour's, as a fraction of its edge
+ (where legs crossing too far for the flow melt into one shape of fill, or a limb is left a pale
+ ghost, the outline is gone; a frame drawn without outlines loses none against neighbours that
+ have none). Zero or less: nothing added, no outline lost."""
+ dm, sm, pm, em, um = _smear_counts(made)
+ (da, _, pa, _, ua), (db, _, pb, _, ub) = _smear_counts(a), _smear_counts(b)
solid = max(1, sm)
- return {"dark_excess": round((dm - max(da, db)) / solid, 5), "partial_excess": round((pm - max(pa, pb)) / solid, 5)}
+ return {"dark_excess": round((dm - max(da, db)) / solid, 5), "partial_excess": round((pm - max(pa, pb)) / solid, 5),
+ "outline_loss": round((um - max(ua, ub)) / max(1, em), 5)}
class Rife:
diff --git a/tests/video/test_cycle_align.py b/tests/video/test_cycle_align.py
index c882e33..b0494e4 100644
--- a/tests/video/test_cycle_align.py
+++ b/tests/video/test_cycle_align.py
@@ -4,7 +4,9 @@ length at times k·L/L*, a time on a source frame keeping that frame as filmed a
between frames made by the interpolator; each loop turned to start where the body is lowest; the
cut as filmed kept in `cycle.source/`, so a second alignment reads the source, not its own output.
-The interpolator is a stand-in that records what it was asked for and cross-fades."""
+The interpolator is a stand-in that records what it was asked for and cross-fades. A cross-fade
+is two half-covered ghosts with no outline, which `--between auto` (the default) judges melted and
+replaces, so a test of the resampling itself asks for `rife`, which keeps every made frame."""
from __future__ import annotations
@@ -45,7 +47,7 @@ class Recorder:
def test_resample_keeps_every_frame_that_lands_on_a_source_frame():
frames = [_walker(2 * math.pi * k / 6) for k in range(6)]
rec = Recorder()
- out, facts = align.resample(frames, 12, rec)
+ out, facts = align.resample(frames, 12, rec, between="rife")
assert {k: v for k, v in facts.items() if k != "smear"} == {"from": 6, "to": 12, "between": "rife", "taken": 6, "made_by_rife": 6,
"made_at": [1, 3, 5, 7, 9, 11]}
assert [m["at"] for m in facts["smear"]] == [1, 3, 5, 7, 9, 11]
@@ -222,7 +224,7 @@ def _cut(tmp_path: Path, name: str, length: int) -> Path:
def test_a_set_is_aligned_to_its_median_length_and_a_second_run_reads_the_source(tmp_path):
dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24), ("N", 28))]
rec = Recorder()
- report = align.align_set(dirs, interpolate=rec, report_path=tmp_path / "align.json")
+ report = align.align_set(dirs, interpolate=rec, report_path=tmp_path / "align.json", between="rife")
assert report["length"] == 24 and report["lengths"] == [20, 24, 28] and report["length_rule"] == "median"
by = {Path(r["dir"]).name: r for r in report["loops"]}
assert by["E"]["made_by_rife"] == 0 and by["E"]["taken"] == 24
@@ -239,7 +241,7 @@ def test_a_set_is_aligned_to_its_median_length_and_a_second_run_reads_the_source
assert lowest == 0
assert len(list((dirs[0] / align.SOURCE_DIR).glob("frame-*.png"))) == 20
first = (dirs[0] / "walk.strip.png").read_bytes()
- again = align.align_set(dirs, interpolate=Recorder())
+ again = align.align_set(dirs, interpolate=Recorder(), between="rife")
assert again["lengths"] == [20, 24, 28] # read from cycle.source, not the aligned cycle
assert (dirs[0] / "walk.strip.png").read_bytes() == first
assert json.loads((tmp_path / "align.json").read_text())["kind"] == "sprite-gen-video-cycle-align-report"
@@ -334,7 +336,7 @@ def test_a_made_frame_darker_than_both_neighbours_is_named_in_the_warnings(tmp_p
return Image.fromarray(made, "RGBA")
dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
- report = align.align_set(dirs, interpolate=smudge)
+ report = align.align_set(dirs, interpolate=smudge, between="rife")
smears = [w for w in report["warnings"] if "more dark pixels inside the body" in w]
assert len(smears) == report["made_by_rife"] > 0
row = next(r for r in report["loops"] if Path(r["dir"]).name == "S")
@@ -342,6 +344,51 @@ def test_a_made_frame_darker_than_both_neighbours_is_named_in_the_warnings(tmp_p
assert [m["at"] for m in row["smear"]] == sorted(row["made_at"])
+def _melt(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
+ """A stand-in RIFE that lost the dark foot: the frame between drawn whole, its dark grey taken
+ into the body's blue — the outline around the foot gone, nothing darker added."""
+ made = np.asarray(Image.blend(a, b, t)).copy()
+ made[..., 3] = np.where(made[..., 3] >= 64, 255, 0)
+ made[(made[..., 3] > 0) & (made[..., :3].max(axis=-1) < 130)] = (90, 90, 200, 255)
+ return Image.fromarray(made, "RGBA")
+
+
+def test_a_made_frame_that_lost_its_outline_is_replaced_by_the_nearer_source_frame_and_named(tmp_path):
+ """--between auto (the default): every made frame is measured, and one that lost its outline
+ takes the nearer source frame instead, named in the warnings and in its row (`method`
+ nearest); --between rife keeps it and names it."""
+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
+ report = align.align_set(dirs, interpolate=_melt, report_path=tmp_path / "align.json")
+ row = next(r for r in report["loops"] if Path(r["dir"]).name == "S")
+ assert report["between"] == "auto" and report["made_by_rife"] == 0 and row["made_at"] == []
+ assert len(row["smear"]) == len(row["nearest_at"]) > 0
+ assert report["replaced"] == sum(len(r["smear"]) for r in report["loops"])
+ assert all(m["method"] == "nearest" and m["faults"] == ["outline"] and m["outline_loss"] > align.OUTLINE_WARN for m in row["smear"])
+ assert sorted(m["at"] for m in row["smear"]) == row["nearest_at"]
+ named = [w for w in report["warnings"] if "lost its outline" in w and "the nearer source frame was taken there" in w]
+ assert len(named) == report["replaced"]
+ assert report["interpolator"] == {"kind": "injected"}
+ source = [Image.open(p).convert("RGBA").tobytes() for p in sorted((dirs[0] / align.SOURCE_DIR).glob("frame-*.png"))]
+ cells = [Image.open(p).convert("RGBA").tobytes() for p in sorted((dirs[0] / "cycle").glob("frame-*.png"))]
+ assert all(cells[k] in source for k in row["nearest_at"]) # a filmed frame, as filmed
+ kept = align.align_set(dirs, interpolate=_melt, between="rife")
+ row = next(r for r in kept["loops"] if Path(r["dir"]).name == "S")
+ assert kept["replaced"] == 0 and len(row["made_at"]) == len(row["smear"]) > 0 and "nearest_at" not in row
+ assert len([w for w in kept["warnings"] if "lost its outline" in w and "--between auto" in w]) == kept["made_by_rife"]
+
+
+def test_a_made_frame_that_keeps_its_outline_is_kept_under_auto(tmp_path):
+ def drawn(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
+ return a.copy() # a frame RIFE followed: whole, outlined as its neighbours
+
+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
+ report = align.align_set(dirs, interpolate=drawn)
+ row = next(r for r in report["loops"] if Path(r["dir"]).name == "S")
+ assert report["replaced"] == 0 and row["nearest_at"] == [] and len(row["made_at"]) == len(row["smear"]) > 0
+ assert all(m["method"] == "rife" and m["faults"] == [] for m in row["smear"])
+ assert not any("lost its outline" in w for w in report["warnings"])
+
+
def test_video_set_without_rife_skips_the_alignment_with_a_warning(tmp_path, monkeypatch, capsys):
from sprite_gen.video import batch
diff --git a/tests/video/test_rife.py b/tests/video/test_rife.py
index 7f82563..dadb857 100644
--- a/tests/video/test_rife.py
+++ b/tests/video/test_rife.py
@@ -171,3 +171,63 @@ def test_smear_counts_a_black_blot_and_not_a_moved_dark_part():
blot = np.asarray(moved).copy()
blot[40:60, 58:70, :3] = 0
assert rife.smear(Image.fromarray(blot, "RGBA"), a, b)["dark_excess"] > 0.01
+
+
+def _walker(front: float, back: float) -> Image.Image:
+ """A body over two legs swung from the hip to these angles (degrees, 0 straight down), each a
+ capsule with a 2 px black outline on transparency; the far leg shaded, the near drawn over it."""
+ from PIL import ImageDraw
+
+ w, h = 128, 192
+ im = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+ d = ImageDraw.Draw(im)
+ hip, length, r = (w // 2, int(h * 0.55)), int(h * 0.36), int(w * 0.09)
+ for angle, fill in ((back, (215, 205, 200, 255)), (front, (250, 240, 235, 255))):
+ a = np.radians(angle)
+ foot = (hip[0] + length * np.sin(a), hip[1] + length * np.cos(a))
+ for radius, colour in ((r, (20, 20, 20, 255)), (r - 2, fill)):
+ d.line([hip, foot], fill=colour, width=2 * radius)
+ d.ellipse([foot[0] - radius, foot[1] - radius, foot[0] + radius, foot[1] + radius], fill=colour)
+ body = [w * 0.25, h * 0.15, w * 0.75, h * 0.62]
+ d.ellipse(body, fill=(20, 20, 20, 255))
+ d.ellipse([body[0] + 2, body[1] + 2, body[2] - 2, body[3] - 2], fill=(250, 240, 235, 255))
+ return im
+
+
+def test_outline_loss_reads_a_melted_limb_and_not_a_moved_one():
+ """A frame whose legs became one shape of fill (the outline gone where they meet the air) loses
+ its outline; legs drawn half way lose none, and art drawn without outlines loses none."""
+ a, b = _walker(20, -20), _walker(-5, 5)
+ assert rife.smear(_walker(8, -8), a, b)["outline_loss"] <= 0.01
+ melted = np.asarray(_walker(8, -8)).copy()
+ legs = melted[110:, :]
+ dark = (legs[..., 3] > 0) & (legs[..., :3].max(axis=-1) < 70)
+ legs[dark] = (240, 230, 225, 255)
+ m = rife.smear(Image.fromarray(melted, "RGBA"), a, b)
+ assert m["outline_loss"] > 0.05 and m["dark_excess"] < 0
+ flat = [Image.fromarray(np.where(np.asarray(f)[..., 3:] > 0, (240, 230, 225, 255), 0).astype(np.uint8), "RGBA")
+ for f in (a, b, Image.fromarray(melted, "RGBA"))]
+ assert rife.smear(flat[2], flat[0], flat[1])["outline_loss"] <= 0.01
+
+
[email protected](not _real_rife_available(), reason="rife-ncnn-vulkan not installed (SPRITE_GEN_RIFE / PATH / sprite-gen rife install)")
+def test_real_rife_melts_legs_crossing_too_far_and_alignment_takes_the_nearer_frame_there():
+ """Outlined legs that cross a long way between two drawings (a clip drawn on twos) come out of
+ RIFE as one shape with no outline where they meet the air (measured 32 % of the edge at t=0.5);
+ a short step comes out outlined (under 3 % at any t). `--between auto` takes the nearer source
+ frame for the first and keeps RIFE's for the second; `rife` keeps both and names the first."""
+ from sprite_gen.video import align
+
+ interpolate = rife.Rife()
+ far, near = (_walker(20, -20), _walker(-5, 5)), (_walker(10, -10), _walker(4, -4))
+ assert rife.smear(interpolate(*far, 0.5), *far)["outline_loss"] > align.OUTLINE_WARN
+ for t in (0.25, 0.5, 0.75):
+ assert rife.smear(interpolate(*near, t), *near)["outline_loss"] < align.OUTLINE_WARN
+ out, facts = align.resample(list(far), 4, interpolate) # times 0, 0.5, 1, 1.5: both made at t=0.5
+ assert facts["between"] == "auto" and facts["made_by_rife"] == 0 and facts["nearest_at"] == [1, 3]
+ assert out[1] is far[1] and out[3] is far[0]
+ assert [(m["method"], m["faults"]) for m in facts["smear"]] == [("nearest", ["outline"])] * 2
+ kept, facts = align.resample(list(far), 4, interpolate, between="rife")
+ assert facts["made_at"] == [1, 3] and all(m["faults"] == ["outline"] and m["method"] == "rife" for m in facts["smear"])
+ out, facts = align.resample(list(near), 4, interpolate)
+ assert facts["made_at"] == [1, 3] and facts["nearest_at"] == [] and all(not m["faults"] for m in facts["smear"])