Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(cycle-align): start on a heel strike read off the legs, the same own foot in every view; RIFE leaves no black between crossing legs
Soohong Kime6542b39170a
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex 2ddf901..c5e41f4 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -6,8 +6,10 @@ set measured 16 to 27 frames). A game that turns a character mid-stride wants evto be the same number of frames and to start on the same step. So every loop of the set isresampled to the set's median length L*: frame k of the new loop is the source loop at timek·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. Then each loop is turned to start where-the body is lowest — a foot just landed. docs/loop-repair.md section 4.+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.Every frame between two source frames softens a little, so the length is the median (the onethat needs the fewest made frames across the set), and a loop already that long is not touched.@@ -26,12 +28,14 @@ import argparseimport jsonimport shutilimport statistics+import sysfrom pathlib import Pathfrom typing import Anyfrom PIL import Imagefrom sprite_gen._deps import np+from sprite_gen.gen import handedness as handed_modfrom sprite_gen.spec.runio import atomic_write_textfrom sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.video import loop as loop_mod@@ -40,16 +44,44 @@ from sprite_gen.video import rife as rife_modSNAP = 0.03 # a sample time within this of a source frame takes that frameSOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop againRATE_TOLERANCE = 0.002 # frame rates read back from the strip metadata agree within this-LOW_ALPHA = 128 # the body's top line for the foot-strike turn: solid pixels only+LOW_ALPHA = 128 # the foot-strike turn reads solid pixels only+# The foot-strike turn (docs/loop-repair.md section 4). A walk seen from the side or a diagonal opens+# its feet by a good part of its height each step; from the front or back its foot band hardly+# changes width, but the foot nearer the viewer is drawn lower by a few hundredths of it.+STRIDE_MIN = 0.15 # the foot band's swing (of the body's height) that says the feet open along the picture+REACH_MIN = 0.015 # the lowest row's swing (of the body's height) that says a foot steps toward the viewer+BODY_RUN = 0.5 # the body's top line: the first row at least half as wide as the frame's widest+START_FOOT = "right" # every loop of a set starts as this own foot lands, where its view can tell+SHADE_BAND = 0.15 # the shade cue reads the feet and lower legs: the lowest 15 % of the body+# The two strikes must differ by this to name a foot (`strike_foot`): shade in luma (0..1), depth in+# body heights. A smaller difference is the drawing, not the feet, and the foot is left unnamed.+SHADE_MARGIN = 0.015+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)+# 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-def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Interpolate | None) -> tuple[list[Image.Image], dict[str, Any]]:- """`frames` as one cycle, resampled to `length` frames at times k·L/length (offset 0)."""+def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Interpolate | None,+ *, between: str = "rife") -> 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)."""count = len(frames)if length < 2:raise ValueError(f"cycle length {length} is too short")+ if between not in BETWEEN:+ raise ValueError(f"between must be one of {', '.join(BETWEEN)}, not {between!r}")out: list[Image.Image] = []made_at: list[int] = []+ nearest_at: list[int] = []+ smears: list[dict[str, Any]] = []for k in range(length):t = k * count / lengthi = int(np.floor(t))@@ -58,27 +90,177 @@ def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Interout.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])+ 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")- out.append(interpolate(frames[i % count], frames[(i + 1) % count], frac))+ a, b = frames[i % count], frames[(i + 1) % count]+ out.append(interpolate(a, b, frac))made_at.append(k)- return out, {"from": count, "to": length, "taken": length - len(made_at), "made_by_rife": len(made_at), "made_at": made_at}+ smears.append({"at": k, **rife_mod.smear(out[-1], a, b)})+ 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":+ facts["nearest_at"] = nearest_at+ else:+ facts["smear"] = smears+ return out, facts+++def _longest_runs(solid: np.ndarray) -> np.ndarray:+ """The longest horizontal run of solid pixels in each row."""+ edges = np.diff(np.pad(solid.astype(np.int8), ((0, 0), (1, 1))), axis=1)+ runs = np.zeros(solid.shape[0], dtype=int)+ for y in np.nonzero(solid.any(axis=1))[0]:+ starts, ends = np.nonzero(edges[y] == 1)[0], np.nonzero(edges[y] == -1)[0]+ runs[y] = int((ends - starts).max())+ return runs-def foot_strike_start(frames: list[Image.Image]) -> int:- """The frame where the body is lowest — its top line lowest, both feet down just after a heel- lands — smoothed over its neighbours (1-2-1). A walk has two such moments a cycle; the first- is taken."""- tops = []+def strike_signals(frames: list[Image.Image]) -> dict[str, list[float]]:+ """Per frame, from the solid pixels: `stride`, the width of the foot band (the lowest FOOT_BAND+ of the frame's own height) as a fraction of that height; `reach`, the lowest solid row; `top`,+ the body's top line — the first row whose longest solid run is at least BODY_RUN of the+ frame's widest, so an ear, a hat's point or an antenna (a narrow run) is passed over."""+ out: dict[str, list[float]] = {"stride": [], "reach": [], "top": [], "height": []}for f in frames:- box = f.getchannel("A").point(lambda v: 255 if v >= LOW_ALPHA else 0).getbbox()- if box is None:+ solid = np.asarray(f.getchannel("A")) >= LOW_ALPHA+ rows = np.nonzero(solid.any(axis=1))[0]+ if rows.size == 0:raise ValueError("a loop frame has no solid body")- tops.append(box[1])- n = len(tops)- smooth = [(tops[(k - 1) % n] + 2 * tops[k] + tops[(k + 1) % n]) / 4 for k in range(n)]- return max(range(n), key=lambda k: smooth[k])+ y0, y1 = int(rows[0]), int(rows[-1])+ height = y1 - y0 + 1+ band = solid[y1 + 1 - max(1, round(height * loop_mod.FOOT_BAND)) : y1 + 1]+ xs = np.nonzero(band.any(axis=0))[0]+ runs = _longest_runs(solid)+ out["stride"].append((xs[-1] - xs[0] + 1) / height)+ out["reach"].append(float(y1))+ out["top"].append(float(np.nonzero(runs >= BODY_RUN * runs.max())[0][0]))+ out["height"].append(float(height))+ return out+++def _feet(frame: Image.Image) -> tuple[np.ndarray, np.ndarray, int]:+ """(solid mask, the picture's right half of the feet as a column mask, body height): the halves+ split at the middle of the foot band (the lowest FOOT_BAND of the frame's own height)."""+ solid = np.asarray(frame.getchannel("A")) >= LOW_ALPHA+ rows = np.nonzero(solid.any(axis=1))[0]+ y1, height = int(rows[-1]), int(rows[-1] - rows[0] + 1)+ xs = np.nonzero(solid[y1 + 1 - max(1, round(height * loop_mod.FOOT_BAND)) : y1 + 1].any(axis=0))[0]+ return solid, np.arange(solid.shape[1]) >= (xs[0] + xs[-1]) / 2, height+++def _depth_cue(frame: Image.Image) -> float:+ """How much lower the picture's right foot is drawn than its left, as a fraction of the body's+ height (the lowest solid row of each half)."""+ solid, right, height = _feet(frame)+ low = [int(np.nonzero(solid[:, half].any(axis=1))[0].max()) if solid[:, half].any() else 0 for half in (~right, right)]+ return (low[1] - low[0]) / height+++def _shade_cue(frame: Image.Image, facing: str) -> float:+ """How much lighter the front foot is drawn than the back one (mean luma 0..1 of the lowest+ SHADE_BAND of the body, front half against back half; the front is the side faced)."""+ solid, right, height = _feet(frame)+ rows = np.nonzero(solid.any(axis=1))[0]+ band = np.zeros_like(solid)+ band[rows[-1] + 1 - max(1, round(height * SHADE_BAND)) : rows[-1] + 1] = True+ rgb = np.asarray(frame.convert("RGB"), dtype=np.float32) / 255.0+ luma = rgb @ np.array([0.299, 0.587, 0.114], dtype=np.float32)+ front = right if facing == "right" else ~right+ parts = [luma[solid & band & cols[None, :]] for cols in (front, ~front)]+ return float(parts[0].mean() - parts[1].mean()) if all(p.size for p in parts) else 0.0+++def strike_foot(frames: list[Image.Image], strikes: tuple[int, int], view: str, facing: str | None) -> dict[str, Any]:+ """Which of the character's own feet lands at each of a walk's two strikes, from how the view+ draws them (`handedness.placement` says where each own side is), or why it cannot say.++ - front or back: the feet are side by side in the picture, one nearer the viewer and drawn+ lower. Seen from the front the foot landing is the one stepping toward the viewer, the+ lower one; seen from the back it is the one stepping away, the higher one, its own side+ where the picture puts it.+ - side or diagonal: the feet are one in front of the other, so the picture cannot tell them+ apart by place; but the far leg is drawn in shade. At the strike whose front foot is the+ lighter (against the back one), the near leg is in front.++ The cue must follow the step — its once-a-cycle swing at least CUE_RHYTHM of its spread over+ the cycle — and, read over each strike frame and its two neighbours, the two strikes must differ+ by FOOT_MARGIN (depth, of the body's height) or SHADE_MARGIN (luma); otherwise the foot is not+ named."""+ n = len(frames)+ lateral = view in handed_mod.LATERAL_VIEWS+ cue = (lambda f: _shade_cue(f, facing)) if lateral else _depth_cue # type: ignore[arg-type]+ every = np.array([cue(f) for f in frames])+ values = [float(np.mean([every[(k + d) % n] for d in (-1, 0, 1)])) for k in strikes]+ margin = abs(values[0] - values[1])+ # the cue swings with the feet, once a cycle: its first harmonic against its whole spread+ swing = float(abs(np.sum((every - every.mean()) * np.exp(-2j * np.pi * np.arange(n) / n))) * 2 / n)+ rhythm = swing / float(every.std()) if every.std() > 0 else 0.0+ record: dict[str, Any] = {"cue": "shade" if lateral else "depth", "at": list(strikes), "values": [round(v, 4) for v in values],+ "margin": round(margin, 4), "rhythm": round(rhythm, 3)}+ if rhythm < CUE_RHYTHM:+ return {**record, "feet": None, "why": f"the {record['cue']} does not follow the step (rhythm {rhythm:.2f})"}+ if margin < (SHADE_MARGIN if lateral else FOOT_MARGIN):+ return {**record, "feet": None, "why": f"the two strikes look alike in {record['cue']} ({margin:.4f})"}+ hi = 0 if values[0] > values[1] else 1+ at = {s: handed_mod.placement(s, view, facing) for s in handed_mod.SIDES}+ if lateral:+ hi_foot = next(s for s in handed_mod.SIDES if at[s]["depth"] == "near")+ else: # at the higher cue the picture's right foot is the lower one+ lower = next(s for s in handed_mod.SIDES if at[s]["picture"] == "right")+ hi_foot = lower if view == "front" else next(s for s in handed_mod.SIDES if s != lower)+ other = next(s for s in handed_mod.SIDES if s != hi_foot)+ return {**record, "feet": [hi_foot, other] if hi == 0 else [other, hi_foot]}+++def foot_strike_start(frames: list[Image.Image], *, view: str | None = None) -> int:+ """The frame a loop is turned to start on (`foot_strike`)."""+ return foot_strike(frames, view=view)["start"]+++def foot_strike(frames: list[Image.Image], *, view: str | None = None, foot: str = START_FOOT) -> dict[str, Any]:+ """Where a loop starts: the frame a heel has just landed, read off one signal smoothed over its+ neighbours (1-2-1), never off the frame's top edge, which a long ear or a hat's point owns.++ - `stride`: seen from the side or a diagonal the feet are widest apart as the front heel+ lands; used where the stride swings by STRIDE_MIN of the body's height or more.+ - `reach`: seen from the front or back the feet pass one behind the other and the stride+ hardly moves, but the foot nearest the viewer is drawn lowest, and lowest when the feet are+ furthest apart — as the heel lands; used where the lowest row swings by REACH_MIN or more.+ - `body_low`: neither — a body with no legs to read — starts where its top line is lowest.++ A walk has two such moments a cycle, half a cycle apart: the larger, and the frame half a cycle+ on (not the other peak: one step can stride much less than the other, or not peak at all).+ With the loop's `view` (`side@right`, `front`, …) the one where `foot` lands is taken+ (`strike_foot`); without a view, or where the view's cue cannot tell, the larger, the first on+ a tie, and `start_foot` is None with the reason."""+ if foot not in handed_mod.SIDES:+ raise ValueError(f"foot must be left or right, not {foot!r}")+ sig = strike_signals(frames)+ height = float(np.median(sig["height"]))+ swing = {k: float(max(sig[k]) - min(sig[k])) / (1.0 if k == "stride" else height) for k in ("stride", "reach")}+ by = "stride" if swing["stride"] >= STRIDE_MIN else "reach" if swing["reach"] >= REACH_MIN else "body_low"+ signal = sig["top" if by == "body_low" else by]+ n = len(signal)+ smooth = [(signal[(k - 1) % n] + 2 * signal[k] + signal[(k + 1) % n]) / 4 for k in range(n)]+ first = max(range(n), key=lambda k: smooth[k])+ second = (first + n // 2) % n+ out: dict[str, Any] = {"start": first, "by": by, "stride_swing": round(swing["stride"], 4), "reach_swing": round(swing["reach"], 4),+ "strikes": [first, second], "start_foot": None}+ if view is None:+ return {**out, "foot_why": "no view given for this loop"}+ name, _, facing = view.partition("@")+ handed_mod.validate_view(name, facing or None)+ if by == "body_low":+ return {**out, "foot_why": "no legs to read"}+ found = strike_foot(frames, (first, second), name, facing or None)+ if found["feet"] is None:+ return {**out, "foot": found, "foot_why": found["why"]}+ start = (first, second)[found["feet"].index(foot)]+ return {**out, "start": start, "start_foot": foot, "foot": found}def _loop_files(loop_dir: Path) -> tuple[Path, dict[str, Any]]:@@ -145,16 +327,30 @@ def _rebuild(loop_dir: Path, meta_path: Path, meta: dict[str, Any], frames: listsave_clean_gif(cells, gif_path, duration_ms=delay_ms, loop=0, alpha_threshold=128)loop_mod.write_webp(cells, webp_path, delay_ms=delay_ms, workdir=loop_dir / ".webp-frames")shutil.rmtree(loop_dir / ".webp-frames", ignore_errors=True)- record["gif"] = loop_mod.verify_animation(gif_path, expect_frames=len(cells), check_stale=False)- record["webp"] = loop_mod.verify_animation(webp_path, expect_frames=len(cells), check_stale=True)+ # a GIF or WebP holds a frame shown twice in a row (`--between nearest` stretching a loop) as one+ # frame of twice the delay, so each is checked for one frame per run of identical cells+ runs = 1 + sum(1 for a, b in zip(cells, cells[1:]) if a.tobytes() != b.tobytes())+ record["gif"] = loop_mod.verify_animation(gif_path, expect_frames=runs, check_stale=False)+ record["webp"] = loop_mod.verify_animation(webp_path, expect_frames=runs, check_stale=True)return mergeddef align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate: rife_mod.Interpolate | None = None,- report_path: Path | None = None) -> dict[str, Any]:- """Resample every loop of a set to one length (default: the median), turned to a foot strike."""+ report_path: Path | None = None, between: str = "rife", views: list[str | None] | None = None,+ start_foot: str = START_FOOT) -> dict[str, Any]:+ """Resample every loop of a set to one length (default: the median), turned to a foot strike —+ where `views` (one per loop: `front`, `back`, `side@right`, `front_diagonal@left`, …) lets it,+ the strike of the same own foot (`start_foot`) in every loop."""if len(loop_dirs) < 1:raise SystemExit("video-cycle-align: at least one --loop-dir")+ if views is not None and len(views) != len(loop_dirs):+ raise SystemExit(f"video-cycle-align: {len(views)} --view for {len(loop_dirs)} --loop-dir; give one per loop, in the same order")+ if start_foot not in handed_mod.SIDES:+ raise SystemExit(f"video-cycle-align: --start-foot must be left or right, not {start_foot!r}")+ for v in views or []:+ if v is not None:+ name, _, facing = v.partition("@")+ handed_mod.validate_view(name, facing or None)loops = []for d in loop_dirs:d = d.expanduser().resolve()@@ -189,23 +385,40 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:# Every loop is resampled before any is rewritten: a loop that cannot be made leaves the set as it was.aligned = []- for (d, *_), frames in zip(loops, sources):+ for (d, *_), frames, view in zip(loops, sources, views or [None] * len(loops)):try:- out, facts = resample(frames, target, lazy)- start = foot_strike_start(out)+ out, facts = resample(frames, target, lazy, between=between)+ strike = foot_strike(out, view=view, foot=start_foot)except rife_mod.RifeNotInstalled as exc:raise rife_mod.RifeNotInstalled(f"{d}: {exc}") from excexcept (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- record = {**facts, "turned_by": start, "fps": round(fps, 4), "source": SOURCE_DIR,+ start = strike["start"]+ record = {**facts, "turned_by": start, "turned_on": strike["by"], "view": view, "start_foot": strike["start_foot"],+ **({"foot": strike["foot"]} if "foot" in strike else {}), **({"foot_why": strike["foot_why"]} if "foot_why" in strike else {}),+ "stride_swing": strike["stride_swing"], "reach_swing": strike["reach_swing"],+ "fps": round(fps, 4), "source": SOURCE_DIR,"made_at": [(k - start) % target for k in facts["made_at"]]}+ if "nearest_at" in facts:+ 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"])aligned.append((out[start:] + out[:start], record))rows = []for (d, meta_path, meta, _), (out, record) in zip(loops, aligned):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]+ 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")+ else:+ warnings += [f"{r['name']}: starts on its larger strike, foot not named — {r['foot_why']}" for r in rows+ if r["view"] is not None and r["start_foot"] is None]report = {"kind": "sprite-gen-video-cycle-align-report", "length": target, "length_rule": "requested" if length is not None else "median",+ "between": between, "start_foot": start_foot, "warnings": warnings,"lengths": lengths, "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),@@ -219,17 +432,28 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--loop-dir", action="append", type=Path, required=True, help="a video-loop output directory (repeat once per direction of the set)")parser.add_argument("--length", type=int, help="cycle length in frames for every loop (default: the median of the set's own lengths)")parser.add_argument("--report", type=Path, help="where to write the set's alignment report (JSON)")+ parser.add_argument("--view", action="append",+ help="the view of each --loop-dir, in the same order: front, back, or side|front_diagonal|back_diagonal@right|left "+ "(the way it faces); with it every loop starts as the same own foot lands (--start-foot)")+ parser.add_argument("--start-foot", choices=handed_mod.SIDES, default=START_FOOT, help="the own foot every loop starts on (default right; needs --view)")+ 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")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]+ 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]+ start_foot=str(kwargs.get("start_foot") or START_FOOT))except rife_mod.RifeNotInstalled as exc:# Asked for by name, so no RIFE is a failure, never a quiet skip (video-set skips with a warning).raise SystemExit(f"video-cycle-align: {exc}; frames between source frames are made by RIFE — "f"`{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)") from exc- print(json.dumps({k: report[k] for k in ("length", "lengths", "made_by_rife", "cycle_seconds")}- | {"loops": [{k: r[k] for k in ("name", "from", "to", "made_by_rife", "turned_by", "seam_ratio")} for r in report["loops"]]},+ 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", "between", "made_by_rife", "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 0diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex 3da4240..c3551af 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -647,7 +647,15 @@ def resolve_bases(bases: dict[str, Path], facings: tuple[str, ...]) -> list[tuplALIGN_MODES = ("auto", "off")-def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpolate: Any = None) -> dict[str, Any]:+def _align_view(r: dict[str, Any]) -> str | None:+ """An item's view as `video-cycle-align --view` takes it, or None where it is not one the+ start-foot cue knows (a lateral view whose facing was not recorded)."""+ if r["direction"] not in handed_mod.VIEWS or (r["direction"] in handed_mod.LATERAL_VIEWS and not r.get("turned")):+ return 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]:"""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 tomatch. A failure is recorded under its state and the batch reports it; the loops stay as cut.@@ -665,7 +673,8 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpocontinuetry:report = align_mod.align_set([Path(r["dir"]) / "loop" for r in rows], interpolate=interpolate,- report_path=root / f"{state}.cycle-align.json")+ report_path=root / f"{state}.cycle-align.json", between=between,+ views=[_align_view(r) for r in rows])except rife_mod.RifeNotInstalled as exc:out[state] = {"ok": True, "applied": False, "why": "RIFE not installed — each loop keeps its own length","rife": str(exc), "install": rife_mod.INSTALL_COMMAND}@@ -676,10 +685,12 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpoexcept SystemExit as exc:out[state] = {"ok": False, "error": str(exc)}continue- out[state] = {"ok": True, "applied": True, "length": report["length"], "lengths": report["lengths"], "made_by_rife": report["made_by_rife"],- "report": str(root / f"{state}.cycle-align.json")}+ 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")}+ for line in report["warnings"]:+ print(f"video-set: warning: {state}: {line}", file=sys.stderr)for r, row in zip(rows, report["loops"]):- r["loop"]["cycle_align"] = {k: row[k] for k in ("from", "to", "made_by_rife", "turned_by", "seam_ratio")}+ r["loop"]["cycle_align"] = {k: row[k] for k in ("from", "to", "made_by_rife", "turned_by", "turned_on", "start_foot", "seam_ratio")}r["loop"]["n_out"] = row["strip"]["frames"]return out@@ -729,6 +740,7 @@ def run_set(fit: str = "state",decontam: str = "off",align_cycles: str = "auto",+ align_between: str = "rife",interpolate: Any = None,walk_start: str = "redraw",redraw_runner: Callable[..., int] = run_redraw_cli,@@ -783,7 +795,7 @@ def run_set(results.append(r)print(json.dumps({k: r[k] for k in ("item", "ok") if k in r} | ({"error": r["error"]} if not r.get("ok") else {"seam": r["loop"]["seam_ratio"]}), ensure_ascii=False), flush=True)results.sort(key=lambda r: [i for i, *_ in items].index(r["item"]))- aligned = align_gaits(results, root, align_cycles, interpolate=interpolate)+ aligned = align_gaits(results, root, align_cycles, interpolate=interpolate, between=align_between)table = write_table(results, root / "table.md", both=both)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.@@ -791,6 +803,7 @@ def run_set(+ [f"cycle-align:{st}: not aligned — {a['why']}" for st, a in aligned.items() if a.get("applied") is False])if warnings:warnings.append(f"install RIFE with `{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)")+ warnings += [f"cycle-align:{st}: {line}" for st, a in aligned.items() for line in a.get("warnings", [])]payload = {"kind": "sprite-gen-video-set-report", "root": str(root), "states": states, "facing": facing, "facing_fix": facing_fix, "directions": list(bases), **({"handed": [vars(h) for h in handed]} if handed else {}), "body_height": body_height, "ok": sum(1 for r in results if r.get("ok")), "failed": failed, "warnings": warnings, "items": results, "cycle_align": aligned}atomic_write_text(root / "set.report.json", json.dumps(payload, ensure_ascii=False, indent=2) + "\n")print(table)@@ -834,6 +847,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("--force", action="store_true", help="regenerate clips that already exist")@@ -848,6 +862,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"),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.pyindex 6dc28d3..aed8091 100644--- a/sprite_gen/video/rife.py+++ b/sprite_gen/video/rife.py@@ -2,10 +2,14 @@"""RIFE in-betweens for RGBA sprite frames, through the external `rife-ncnn-vulkan` binary.Where it runs, what it costs and why this build: docs/loop-repair.md section 1. RIFE reads-three colour channels and no alpha, so a frame is interpolated as two images — its colour-premultiplied over black and its coverage as a grey image — and put back together-unpremultiplied. Interpolating the straight colour instead would drag the key's black under-alpha 0 into the edge; interpolating RGBA as RGB would lose the coverage outright.+three colour channels and no alpha, so a frame is interpolated as two images — its colour and+its coverage as a grey image — and put back together. The two are two runs of the flow, and+where legs cross they do not agree: the coverage says body where the colour run still carries+what lay around the body. So around the body the colour image holds the body's own colour,+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).The binary's own CPU path (`-g -1`) returns a wrong frame with rife-v4.6 on both macOS andLinux (measured 2026-10-03: mean error 39 against 3.3 through Vulkan), so it is never passed;@@ -30,7 +34,7 @@ import tempfilefrom pathlib import Pathfrom typing import Callable-from PIL import Image+from PIL import Image, ImageFilterfrom sprite_gen._deps import np@@ -39,6 +43,13 @@ MODEL = "rife-v4.6"RELEASE = "20221029"# Coverage RIFE leaves under this is its own blur, not body: dropped so no halo is invented.ALPHA_FLOOR = 2 / 255+# The colour pushed out around the body is read this far inside its solid edge (a fraction of the+# body's height, at least a pixel): past a drawn outline, so a disagreement reads as the body's+# fill, not its outline: 0.008 is 6 px on an 800 px body, past an outline a few pixels wide.+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)CALL_TIMEOUT_SECONDS = 120Interpolate = Callable[[Image.Image, Image.Image, float], Image.Image]@@ -128,19 +139,70 @@ def _call(binary: Path, model: Path, a: Image.Image, b: Image.Image, t: float, treturn im.convert("RGB")+def _push_pull(rgb: np.ndarray, known: np.ndarray) -> np.ndarray:+ """`rgb` with every pixel where `known` is 0 filled by the weighted colour around it, coarse to+ fine (each level averages 2x2 blocks of the known colour; an unknown pixel takes its block's)."""+ if known.min() > 0 or min(known.shape) <= 1:+ return rgb+ h, w = known.shape+ pad = ((0, h % 2), (0, w % 2))+ weighted, weight = np.pad(rgb * known[..., None], pad + ((0, 0),)), np.pad(known, pad)+ wsum, csum = (x[0::2, 0::2] + x[1::2, 0::2] + x[0::2, 1::2] + x[1::2, 1::2] for x in (weight, weighted))+ coarse = _push_pull(np.where(wsum[..., None] > 0, csum / np.maximum(wsum[..., None], 1e-9), 0.0), np.minimum(wsum, 1.0))+ up = coarse.repeat(2, axis=0).repeat(2, axis=1)[:h, :w]+ return np.where(known[..., None] > 0, rgb, up)+++def bleed(frame: np.ndarray) -> np.ndarray:+ """The colour image of an RGBA frame (0..1) RIFE is given: the frame's own colour wherever it+ has coverage, and around it the colour from BLEED_DEPTH inside its solid edge, pushed out."""+ alpha = frame[..., 3]+ solid = alpha >= 0.5+ rows = np.nonzero(solid.any(axis=1))[0]+ if rows.size == 0:+ return np.where(alpha[..., None] > 0, frame[..., :3], 0.0)+ depth = max(1, round((rows[-1] - rows[0] + 1) * BLEED_DEPTH))+ core = np.asarray(Image.fromarray(np.uint8(solid) * 255).filter(ImageFilter.MinFilter(2 * depth + 1))) > 0+ if not core.any(): # a body thinner than its outline: read at its edge+ core = solid+ fill = _push_pull(frame[..., :3], core.astype(np.float32))+ return np.where(alpha[..., None] > 0, frame[..., :3], fill)++def between(a: Image.Image, b: Image.Image, t: float, *, binary: Path, model: Path, tmp: Path) -> Image.Image:"""The RGBA frame at fraction `t` (0..1) of the way from `a` to `b`."""if a.size != b.size:raise ValueError(f"rife: frames differ in size ({a.size} vs {b.size})")fa, fb = (np.asarray(f.convert("RGBA"), dtype=np.float32) / 255.0 for f in (a, b))- prem = [Image.fromarray(np.uint8(np.clip(x[..., :3] * x[..., 3:4], 0, 1) * 255 + 0.5), "RGB") for x in (fa, fb)]+ colour = [Image.fromarray(np.uint8(np.clip(bleed(x), 0, 1) * 255 + 0.5), "RGB") for x in (fa, fb)]cov = [Image.fromarray(np.uint8(x[..., 3] * 255 + 0.5), "L").convert("RGB") for x in (fa, fb)]- color = np.asarray(_call(binary, model, prem[0], prem[1], t, tmp), dtype=np.float32) / 255.0+ rgb = np.asarray(_call(binary, model, colour[0], colour[1], t, tmp), dtype=np.float32) / 255.0alpha = np.asarray(_call(binary, model, cov[0], cov[1], t, tmp).convert("L"), dtype=np.float32) / 255.0alpha = np.where(alpha < ALPHA_FLOOR, 0.0, alpha)- rgb = np.where(alpha[..., None] > 0, color / np.maximum(alpha[..., None], 1e-6), 0.0)- out = np.dstack([np.clip(rgb, 0, 1), alpha])- return Image.fromarray(np.uint8(out * 255 + 0.5), "RGBA")+ out = np.dstack([np.where(alpha[..., None] > 0, rgb, 0.0), alpha])+ 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)."""+ 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+ 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())+++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)+ solid = max(1, sm)+ return {"dark_excess": round((dm - max(da, db)) / solid, 5), "partial_excess": round((pm - max(pa, pb)) / solid, 5)}class Rife:diff --git a/tests/video/test_cycle_align.py b/tests/video/test_cycle_align.pyindex be743fb..a62ee17 100644--- a/tests/video/test_cycle_align.py+++ b/tests/video/test_cycle_align.py@@ -46,7 +46,9 @@ 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)- assert facts == {"from": 6, "to": 12, "taken": 6, "made_by_rife": 6, "made_at": [1, 3, 5, 7, 9, 11]}+ 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]assert all(out[2 * k] is frames[k] for k in range(6)) and rec.calls == [0.5] * 6same, facts = align.resample(frames, 6, None) # already that long: untouched, nothing madeassert facts["made_by_rife"] == 0 and all(a is b for a, b in zip(same, frames))@@ -54,11 +56,104 @@ def test_resample_keeps_every_frame_that_lands_on_a_source_frame():align.resample(frames, 9, None)-def test_the_loop_starts_where_the_body_is_lowest():- frames = [_walker(2 * math.pi * k / 12) for k in range(12)]+def test_between_nearest_takes_the_nearer_source_frame_and_makes_none():+ frames = [_walker(2 * math.pi * k / 8) for k in range(8)]+ out, facts = align.resample(frames, 6, None, between="nearest") # times 0, 1.33, 2.67, 4, 5.33, 6.67+ assert [frames.index(f) for f in out] == [0, 1, 3, 4, 5, 7]+ assert facts["made_by_rife"] == 0 and facts["nearest_at"] == [1, 2, 4, 5] and "smear" not in facts+++def _old_top_line_start(frames: list[Image.Image]) -> int:+ """The 2.24 turn: the frame whose alpha box top is lowest (1-2-1) — what a long ear owns."""+ tops = [f.getchannel("A").point(lambda v: 255 if v >= 128 else 0).getbbox()[1] for f in frames]+ n = len(tops)+ return max(range(n), key=lambda k: tops[(k - 1) % n] + 2 * tops[k] + tops[(k + 1) % n])+++def _figure(phase: float, *, view: str, legs: bool = True, bob_px: int = 2, shaded: bool = True) -> Image.Image:+ """A drawn walker at `phase` (radians): its own right heel lands at 0, its left at pi. The body+ bobs lowest (by `bob_px`) a sixth of a step after a heel lands; two thin ears on top flop on their+ own rhythm, lowest half a step after it, and further than the body bobs.++ `side`: faces right, its feet swing apart along the ground; the right leg is the near one, drawn+ light over the far left leg, which is shaded (`shaded`). `front`: the feet stay side by side, its+ right foot on the picture's left, and the foot stepping toward the viewer is drawn lower. With no+ legs the body sits on the ground and squats as it bobs."""+ a = np.zeros((H, W, 4), dtype=np.uint8)+ bob = round(bob_px * (1 + math.cos(2 * phase - math.pi / 3)) / 2)+ flop = round(7 * (1 + math.cos(2 * phase - math.pi)) / 2)+ top = 30 + bob+ a[top:top + 58 if legs else 100, 36:64] = (230, 230, 230, 255) # head and body; with no legs it squats on the ground+ for x in (40, 56):+ a[top - 26 + flop:top, x:x + 4] = (240, 180, 190, 255) # an ear: a narrow run+ if legs:+ if view == "side":+ for sign, leg, foot in ((-1, 150, 50), (1, 210, 110)): # far left leg first, near right leg over it+ if not shaded:+ leg, foot = 210, 110+ fx = 50 + round(sign * 18 * math.cos(phase))+ a[top + 58:106, fx - 3:fx + 3] = (leg, leg, leg, 255)+ a[100:106, fx - 7:fx + 7] = (foot, foot, foot, 255)+ else:+ for x, sign in ((38, 1), (52, -1)): # its right foot, then its left+ fy = 105 + round(sign * 3 * math.cos(phase))+ a[top + 58:fy, x + 2:x + 8] = (200, 200, 200, 255)+ a[fy - 10:fy, x:x + 10] = (60, 60, 60, 255)+ return Image.fromarray(a, "RGBA")+++def _cycle(**kw) -> list[Image.Image]:+ return [_figure(2 * math.pi * k / 12, **kw) for k in range(12)]+++def _mirror(frames: list[Image.Image]) -> list[Image.Image]:+ return [f.transpose(Image.Transpose.FLIP_LEFT_RIGHT) for f in frames]++[email protected]("view, by", [("side", "stride"), ("front", "reach")])[email protected]("bob_px", [2, 0])+def test_the_loop_starts_as_a_heel_lands_not_where_the_ears_are_lowest(view, by, bob_px):+ """With the body bobbing or not at all, the start is read off the legs; the 2.24 rule read the+ top edge, which the ears own."""+ frames = _cycle(view=view, bob_px=bob_px)turned = frames[5:] + frames[:5]- start = align.foot_strike_start(turned)- assert turned[start] is frames[0] or turned[start] is frames[6] # the two lows of the bob+ strike = align.foot_strike(turned)+ assert strike["by"] == by+ assert any(turned[strike["start"]] is frames[k] for k in (0, 6)) # a heel lands at phase 0 and pi+ assert any(turned[_old_top_line_start(turned)] is frames[k] for k in (3, 9)) # the ears' low+++def test_a_body_with_no_legs_starts_where_its_top_line_is_lowest_past_the_ears():+ frames = _cycle(view="front", legs=False)+ strike = align.foot_strike(frames)+ assert strike["by"] == "body_low" and strike["start"] in (1, 7) # the body's own low, a sixth of a step on+ assert _old_top_line_start(frames) in (3, 9) # the ears' low++[email protected]("view, figure", [("side@right", "side"), ("front", "front"), ("back", "front")])+def test_every_view_starts_as_the_same_own_foot_lands(view, figure):+ """Its right heel lands at frame 0 and its left at 6. Mirrored, the picture is the same walk on+ the other own feet: a side view faces left (its near leg, the light one, is its left), a front+ view puts its right foot on the picture's right, and a back view seen this way round has its+ right foot stepping away where the front view's left steps near."""+ frames = _cycle(view=figure)+ mirrored = _mirror(frames)+ flipped = view.replace("@right", "@left")+ for walk, seen, right_at in ((frames, view, 0), (mirrored, flipped, 6)):+ turned = walk[5:] + walk[:5]+ strike = align.foot_strike(turned, view=seen)+ assert strike["start_foot"] == "right", strike+ assert turned[strike["start"]] is walk[right_at], (seen, strike)+ assert turned[align.foot_strike(turned, view=seen, foot="left")["start"]] is walk[(right_at + 6) % 12]+++def test_a_foot_the_view_cannot_tell_is_not_named():+ turned = (lambda f: f[5:] + f[:5])(_cycle(view="side", shaded=False))+ strike = align.foot_strike(turned, view="side@right")+ assert strike["start_foot"] is None and "shade does not follow the step" in strike["foot_why"]+ assert any(turned[strike["start"]] is f for f in (turned[7], turned[1])) # still on a strike+ unseen = align.foot_strike(turned)+ assert unseen["start_foot"] is None and unseen["foot_why"] == "no view given for this loop"def _cut(tmp_path: Path, name: str, length: int) -> Path:@@ -98,6 +193,20 @@ def test_a_set_is_aligned_to_its_median_length_and_a_second_run_reads_the_sourceassert json.loads((tmp_path / "align.json").read_text())["kind"] == "sprite-gen-video-cycle-align-report"+def test_each_loop_records_its_view_and_start_foot_and_a_view_per_loop_is_required(tmp_path):+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]+ with pytest.raises(SystemExit, match="1 --view for 2 --loop-dir"):+ align.align_set(dirs, interpolate=Recorder(), views=["front"])+ with pytest.raises(SystemExit, match="facing right|left"):+ align.align_set(dirs, interpolate=Recorder(), views=["front", "side"])+ report = align.align_set(dirs, interpolate=Recorder(), views=["front", "side@right"])+ assert report["start_foot"] == "right" and [r["view"] for r in report["loops"]] == ["front", "side@right"]+ for r in report["loops"]:+ assert r["start_foot"] in ("right", None) and (r["start_foot"] or r["foot_why"])+ unseen = align.align_set(dirs, interpolate=Recorder())+ assert any("no view given" in w for w in unseen["warnings"])++def test_loops_at_different_frame_rates_are_refused(tmp_path):a, b = _cut(tmp_path, "A", 20), _cut(tmp_path, "B", 24)meta = json.loads((b / "walk.strip.json").read_text())@@ -156,6 +265,31 @@ def test_video_cycle_align_without_rife_fails_and_leaves_the_set_as_cut(tmp_pathassert [(d / "walk.strip.png").read_bytes() for d in dirs] == before+def test_video_cycle_align_between_nearest_needs_no_rife(tmp_path, monkeypatch):+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24), ("N", 28))]+ _no_rife(monkeypatch, tmp_path)+ report = align.align_set(dirs, between="nearest")+ assert report["between"] == "nearest" and report["made_by_rife"] == 0 and report["interpolator"] is None+ by = {Path(r["dir"]).name: r for r in report["loops"]}+ assert len(by["S"]["nearest_at"]) > 0 and by["E"]["nearest_at"] == []+ assert all(json.loads((d / "walk.strip.json").read_text())["frames"] == 24 for d in dirs)+++def test_a_made_frame_darker_than_both_neighbours_is_named_in_the_warnings(tmp_path):+ def smudge(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ made = np.asarray(Image.blend(a, b, t)).copy()+ made[60:80, 42:58, :3] = 0 # a black blot inside the body+ 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)+ 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")+ assert len(row["smear"]) == row["made_by_rife"] and min(m["dark_excess"] for m in row["smear"]) > align.SMEAR_WARN+ assert [m["at"] for m in row["smear"]] == sorted(row["made_at"])++def test_video_set_without_rife_skips_the_alignment_with_a_warning(tmp_path, monkeypatch, capsys):from sprite_gen.video import batchdiff --git a/tests/video/test_rife.py b/tests/video/test_rife.pyindex 2d12ab5..7f82563 100644--- a/tests/video/test_rife.py+++ b/tests/video/test_rife.py@@ -117,3 +117,57 @@ def test_real_rife_makes_the_frame_between_in_colour_and_alpha():rgb = np.asarray(mid)[..., :3][a > 0.9]assert np.abs(rgb.mean(axis=0) - (200, 60, 40)).max() < 12 # unpremultiplied back to the body colourassert interpolate.made == 1++[email protected](not _real_rife_available(), reason="rife-ncnn-vulkan not installed (SPRITE_GEN_RIFE / PATH / sprite-gen rife install)")+def test_real_rife_between_crossing_legs_adds_no_black():+ """Two outlined legs walk through each other (the near one forward, the far one back): the frame+ between must not be darker inside the body than either neighbour. 2.24 premultiplied the colour+ over black and left 6 % of the body dark at t=0.5 here."""+ interpolate = rife.Rife()+ a, b = _legs(36, 70), _legs(60, 46)+ for t in (0.25, 0.5, 0.75):+ assert rife.smear(interpolate(a, b, t), a, b)["dark_excess"] <= 0+++def _legs(x_near: int, x_far: int) -> Image.Image:+ """Hips and two legs with a 1 px black outline, on transparency: the near leg white and drawn+ over the far one, which is shaded."""+ im = np.zeros((96, 128, 4), dtype=np.uint8)+ for x, grey in ((x_far, 200), (x_near, 245)):+ im[16:86, x - 8:x + 8] = (20, 20, 20, 255)+ im[17:85, x - 7:x + 7] = (grey, grey, grey, 255)+ im[10:18, 30:90] = (20, 20, 20, 255)+ im[11:17, 31:89] = (230, 230, 230, 255)+ return Image.fromarray(im, "RGBA")+++def test_where_the_colour_and_coverage_runs_disagree_the_body_shows_not_black(monkeypatch, tmp_path):+ """RIFE warps the colour and the coverage in two runs. A stand-in returns the colour run as+ the first frame and the coverage run as the second, so where the second covers what the first+ leaves bare the two disagree — the overlap of crossing legs. That must read as the body."""+ a, b = _legs(40, 64), _legs(64, 52)+ calls = []++ def stand_in(binary, model, x, y, t, tmp):+ calls.append(1)+ return x if len(calls) % 2 else y++ monkeypatch.setattr(rife, "_call", stand_in)+ made = rife.between(a, b, 0.5, binary=tmp_path, model=tmp_path, tmp=tmp_path)+ m = np.asarray(made).astype(int)+ bare_in_a = np.asarray(a)[..., 3] == 0+ covered = (m[..., 3] >= 128) & bare_in_a+ inside = covered & (np.asarray(b)[..., 0] >= 190) # b's leg fill, where a had nothing+ assert inside.sum() > 0+ luma = m[..., :3] @ np.array([0.299, 0.587, 0.114])+ assert luma[inside].min() >= 190 # the body's own light fill, not the black 2.24 put there+++def test_smear_counts_a_black_blot_and_not_a_moved_dark_part():+ a, b = _legs(40, 64), _legs(48, 64)+ moved = _legs(44, 64)+ assert rife.smear(moved, a, b)["dark_excess"] <= 0+ 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