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): 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.py
index 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 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. 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 one
that needs the fewest made frames across the set), and a loop already that long is not touched.
@@ -26,12 +28,14 @@ import argparse
import json
import shutil
import statistics
+import sys
from pathlib import Path
from typing import Any
from PIL import Image
from sprite_gen._deps import np
+from sprite_gen.gen import handedness as handed_mod
from sprite_gen.spec.runio import atomic_write_text
from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.video import loop as loop_mod
@@ -40,16 +44,44 @@ from sprite_gen.video import rife as rife_mod
SNAP = 0.03 # a sample time within this of a source frame takes that frame
SOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop again
RATE_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 / length
i = int(np.floor(t))
@@ -58,27 +90,177 @@ def resample(frames: list[Image.Image], length: int, interpolate: rife_mod.Inter
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])
+ 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: list
save_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 merged
def 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 exc
except (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 0
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 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[tupl
ALIGN_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 to
match. 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, *, interpo
continue
try:
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, *, interpo
except 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.py
index 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 and
Linux (measured 2026-10-03: mean error 39 against 3.3 through Vulkan), so it is never passed;
@@ -30,7 +34,7 @@ import tempfile
from pathlib import Path
from typing import Callable
-from PIL import Image
+from PIL import Image, ImageFilter
from 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 = 120
Interpolate = 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, t
return 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.0
alpha = np.asarray(_call(binary, model, cov[0], cov[1], t, tmp).convert("L"), dtype=np.float32) / 255.0
alpha = 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.py
index 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] * 6
same, facts = align.resample(frames, 6, None) # already that long: untouched, nothing made
assert 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_source
assert 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_path
assert [(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 batch
diff --git a/tests/video/test_rife.py b/tests/video/test_rife.py
index 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 colour
assert 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