Skip to content

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

fix(video-loop): a walk without RIFE is cut as filmed with a warning

Soohong Kimbda38a947b1f
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.py
index 8190913..6fb0bb7 100644
--- a/sprite_gen/video/align.py
+++ b/sprite_gen/video/align.py
@@ -15,6 +15,9 @@ that needs the fewest made frames across the set), and a loop already that long
The loop directories are `video-loop` output directories. Their first alignment keeps the cut
as filmed in `cycle.source/`; every later alignment reads from there, so running it again — or
with another length — never resamples a resampled loop.
+
+A set that needs a made frame where no RIFE is installed raises `rife.RifeNotInstalled` with
+nothing rewritten: this command fails on it, `video-set` skips the alignment with a warning.
"""
from __future__ import annotations
@@ -35,7 +38,7 @@ from sprite_gen.video import loop as loop_mod
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 = "cycle.source"
+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
@@ -186,6 +189,8 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:
try:
out, facts = resample(frames, target, lazy)
start = foot_strike_start(out)
+ 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,
@@ -213,7 +218,12 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
def run(**kwargs: object) -> int:
- report = align_set(list(kwargs["loop_dir"]), length=kwargs.get("length"), report_path=kwargs.get("report")) # type: ignore[arg-type]
+ try:
+ report = align_set(list(kwargs["loop_dir"]), length=kwargs.get("length"), report_path=kwargs.get("report")) # type: ignore[arg-type]
+ 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"]]},
ensure_ascii=False, indent=2))
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 74e35b2..8c4b729 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -31,6 +31,7 @@ from sprite_gen.video import canvas as canvas_mod
from sprite_gen.video import frames as frames_mod
from sprite_gen.video import loop as loop_mod
from sprite_gen.video import align as align_mod
+from sprite_gen.video import rife as rife_mod
START_GAP_SECONDS = 2.0
# Clip length the batch asks the video model for. 3 s holds two or more cycles of every
@@ -531,6 +532,9 @@ def run_item(
result["loop"]["half_period_guard"] = lp["cycle"].get("half_period_guard")
if lp.get("motion_anchor", {}).get("applied") is False:
result["loop"]["motion_anchor"] = lp["motion_anchor"]
+ if "rife" in (lp.get("jump_repair") or {}):
+ # cut as filmed for want of RIFE: the set report lists it under `warnings`
+ result["loop"]["jump_repair"] = {k: lp["jump_repair"][k] for k in ("applied", "why", "score_max_before", "install")}
result["ok"] = True
except SystemExit as exc:
result["ok"] = False
@@ -544,7 +548,9 @@ ALIGN_MODES = ("auto", "off")
def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpolate: Any = None) -> 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."""
+ match. A failure is recorded under its state and the batch reports it; the loops stay as cut.
+ Where a frame is to be made and no RIFE is installed the state is skipped, not failed: each
+ loop keeps its own length, the record says why, and a warning line names the install."""
out: dict[str, Any] = {}
if mode == "off":
return out
@@ -558,10 +564,17 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpo
try:
report = align_mod.align_set([Path(r["dir"]) / "loop" for r in rows], interpolate=interpolate,
report_path=root / f"{state}.cycle-align.json")
+ 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}
+ print(f"video-set: warning: {state}: cycles not aligned — RIFE is not installed, so each loop keeps its own "
+ f"length; run `{rife_mod.INSTALL_COMMAND}`, then `sprite-gen video-cycle-align` (docs/loop-repair.md)",
+ file=sys.stderr)
+ continue
except SystemExit as exc:
out[state] = {"ok": False, "error": str(exc)}
continue
- out[state] = {"ok": True, "length": report["length"], "lengths": report["lengths"], "made_by_rife": report["made_by_rife"],
+ 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")}
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")}
@@ -577,6 +590,8 @@ def write_table(results: list[dict[str, Any]], path: Path) -> str:
status = "OK (review gait)" if lp.get("review_recommended") else "OK"
if lp.get("motion_anchor", {}).get("applied") is False:
status = "OK (uncorrected; review gait)"
+ if "jump_repair" in lp:
+ status += " (jump not repaired: no RIFE)"
lines.append(f"| {r['direction']} | {r['state']} | {lp.get('kind', 'periodic')} | {lp['cycle']} | {lp['period'] if lp['period'] is not None else '-'} | {lp['seam_ratio']:.2f} | {lp['n_out']} | {status} |")
else:
lines.append(f"| {r['direction']} | {r['state']} | - | - | - | - | - | FAIL: {r.get('error', '')[:80]} |")
@@ -653,7 +668,12 @@ def run_set(
aligned = align_gaits(results, root, align_cycles, interpolate=interpolate)
table = write_table(results, root / "table.md")
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")]
- payload = {"kind": "sprite-gen-video-set-report", "root": str(root), "states": states, "facing": facing, "facing_fix": facing_fix, "directions": list(bases), "body_height": body_height, "ok": sum(1 for r in results if r.get("ok")), "failed": failed, "items": results, "cycle_align": aligned}
+ # What the set left undone for want of RIFE — never a failure, never silent.
+ warnings = ([f"{r['item']}: jump frame not repaired — {r['loop']['jump_repair']['why']}" for r in results if r.get("ok") and "jump_repair" in r["loop"]]
+ + [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)")
+ payload = {"kind": "sprite-gen-video-set-report", "root": str(root), "states": states, "facing": facing, "facing_fix": facing_fix, "directions": list(bases), "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)
return payload
@@ -694,7 +714,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--decontam", choices=frames_mod.DECONTAM_MODES, default="off", help="passed to video-frames: palette re-explains key-tinted edges with the subject's own colours (default off)")
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); off: each loop keeps its own length")
+ 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("--force", action="store_true", help="regenerate clips that already exist")
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 3a5b98f..a69a28e 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -84,9 +84,16 @@ BODY_ANCHOR_BAND = 0.6 # --anchor body reads the wrap offset from the top 60 %
BODY_ANCHOR_SEARCH = 24 # px either side searched for the last frame's horizontal offset against the first
FOOT_BAND = 0.08 # fraction of the frame's own height, measured up from its lowest opaque row
# Jump-frame repair (docs/loop-repair.md section 2). auto: walk and run loops get a RIFE frame in
-# place of each frame that follows a jump; off: the loop is cut as filmed, and says so.
-REPAIR_MODES = ("auto", "off")
+# place of each frame that follows a jump, and a loop that needs one where no RIFE is installed is
+# cut as filmed with a warning (a walk that cut before RIFE existed still cuts); on: the same, but
+# no RIFE fails the loop — a caller that asked for the repair is never handed less; off: the loop
+# is cut as filmed, and says so.
+REPAIR_MODES = ("auto", "on", "off")
FACINGS = ("right", "left")
+# Where `video-cycle-align` keeps the cut as filmed (sprite_gen/video/align.py). A new cut makes
+# the kept one stale, so writing the cycle removes it: an alignment after a re-cut (say, once RIFE
+# is installed and the jumps are repaired) reads the new cut, not the old one.
+CYCLE_SOURCE_DIR = "cycle.source"
# A gait's period is a fact about the body, not about how long the clip runs: the
@@ -778,9 +785,13 @@ def write_loop_report(target: Path, payload: dict[str, Any]) -> None:
atomic_write_text(target, json.dumps(finite(payload), ensure_ascii=False, indent=2, allow_nan=False) + "\n")
-def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, facing: str) -> tuple[list[Image.Image], dict[str, Any]]:
+def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, facing: str,
+ required: bool) -> tuple[list[Image.Image], dict[str, Any]]:
"""`repair_mod.repair_jumps`, with RIFE located only once a frame is to be made: a loop
- without a jump needs no binary. The report names the interpolator that made the frames."""
+ without a jump needs no binary. The report names the interpolator that made the frames.
+
+ A frame to make and no RIFE installed: `required` lets `RifeNotInstalled` through; otherwise
+ the loop comes back as filmed and the record says why (`applied: false`, `rife`, `install`)."""
made_by: list[dict[str, str]] = []
def lazy(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
@@ -791,7 +802,17 @@ def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate |
interpolate = located
return interpolate(a, b, t)
- frames, record = repair_mod.repair_jumps(frames, lazy, facing=facing)
+ try:
+ repaired, record = repair_mod.repair_jumps(frames, lazy, facing=facing)
+ except rife_mod.RifeNotInstalled as exc:
+ if required:
+ raise
+ # RIFE is located before the first frame is made, so nothing was replaced yet.
+ worst = round(float(repair_mod.jump_scores(frames, facing=facing)["score"].max()), 4)
+ return frames, {"applied": False, "why": "RIFE not installed — cut as filmed", "rife": str(exc),
+ "install": rife_mod.INSTALL_COMMAND, "ratio": repair_mod.JUMP_RATIO, "facing": facing,
+ "score_max_before": worst, "score_max_after": worst, "replaced": []}
+ frames = repaired
record["applied"] = bool(record["replaced"])
if made_by:
record["interpolator"] = {"kind": "rife-ncnn-vulkan", **made_by[0]}
@@ -975,29 +996,35 @@ def run_loop(
write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})
raise SystemExit(error) from exc
report_base["motion_anchor"] = motion
- if repair == "auto" and prof.gait:
+ if repair != "off" and prof.gait:
report_base["jump_repair"] = None
try:
- frames, report_base["jump_repair"] = _repair_jumps(frames, interpolate, facing=facing)
+ frames, report_base["jump_repair"] = _repair_jumps(frames, interpolate, facing=facing, required=repair == "on")
except (ValueError, rife_mod.RifeUnavailable) as exc:
- error = (f"video-loop: {exc}; the loop has a jump frame to repair — install RIFE, or pass --repair off "
- "to cut it as filmed (docs/loop-repair.md)")
+ fix = (f"install RIFE (`{rife_mod.INSTALL_COMMAND}`), or pass --repair auto to cut it as filmed with a warning"
+ if isinstance(exc, rife_mod.RifeNotInstalled) else "fix RIFE, or pass --repair off to cut it as filmed")
+ error = f"video-loop: {exc}; the loop has a jump frame to repair — {fix} (docs/loop-repair.md)"
shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)
write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})
raise SystemExit(error) from exc
if report_base["jump_repair"]["replaced"]:
report_base["seam_measurement"] = "rendered-cells"
+ if "rife" in report_base["jump_repair"]:
+ print(f"video-loop: warning: a jump frame was not repaired ({report_base['jump_repair']['score_max_before']:.2f}x "
+ f"the median step) — RIFE is not installed, so the loop is cut as filmed; run `{rife_mod.INSTALL_COMMAND}` "
+ "and cut it again (docs/loop-repair.md)", file=sys.stderr)
else:
report_base["jump_repair"] = {"applied": False, "why": "--repair off" if repair == "off" else f"not a gait state ({state})"}
if prof.gait:
# The jolt is measured on the loop as it will play — after the repair — and reported on
# every walk and run (docs/loop-repair.md section 3). Beyond the reference bounds it is a
# warning line; it fails the loop only against a bound the caller passed (--jolt-max /
- # --head-step-max), and only when the repair ran: --repair off cuts and reports as filmed.
+ # --head-step-max), and never with --repair off, which cuts and reports as filmed. A loop
+ # whose repair could not run (no RIFE) is gated as filmed, and the failure says why.
jolt = repair_mod.measure_jolt(frames, facing=facing)
reference = {"jolt_max": repair_mod.JOLT_REFERENCE, "head_step_max": repair_mod.HEAD_STEP_REFERENCE}
warnings = repair_mod.jolt_verdict(jolt, **reference)
- gated = repair == "auto" and (jolt_max is not None or head_step_max is not None)
+ gated = repair != "off" and (jolt_max is not None or head_step_max is not None)
over = repair_mod.jolt_verdict(jolt, jolt_max=jolt_max, head_step_max=head_step_max) if gated else []
report_base["jolt"] = {**jolt, "reference": reference, "warnings": warnings,
"gate": {"jolt_max": jolt_max, "head_step_max": head_step_max} if gated else None,
@@ -1006,7 +1033,8 @@ def run_loop(
if over:
error = (f"video-loop: loop jolts — {'; '.join(over)} ({cycle.get('kind', 'periodic')} length {L} frames from {i}"
f"{', after repairing frames ' + str(report_base['jump_repair']['replaced']) if report_base['jump_repair'].get('replaced') else ''}); "
- "the motion does not play smoothly — regenerate the clip")
+ "the motion does not play smoothly — regenerate the clip"
+ f"{' (the jump repair did not run: RIFE is not installed — ' + rife_mod.INSTALL_COMMAND + ')' if 'rife' in report_base['jump_repair'] else ''}")
shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)
write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})
raise SystemExit(error)
@@ -1015,6 +1043,7 @@ def run_loop(
cycle_dir.mkdir(parents=True, exist_ok=True)
for old in cycle_dir.glob("frame-*.png"):
old.unlink()
+ shutil.rmtree(out_dir / CYCLE_SOURCE_DIR, ignore_errors=True)
for k, im in enumerate(frames):
im.save(cycle_dir / f"frame-{k:03d}.png")
strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),
@@ -1137,7 +1166,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--body-height", type=int, help="scale so the STANDING height (the subject in the clip's first frame, i.e. the base still's pose) is this many px — the same value across states gives the same character size; --strip-height stays the cap")
parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="motion-auto: automatic stable regions, local repeat selection and XY ramp (walk/run); motion: fixed cut with explicit regions; body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")
parser.add_argument("--anchor-region", type=motion_anchor.parse_region, action="append", help="motion anchor only: repeat twice with head then torso x0,y0,x1,y1 in the first selected frame; requires --cycle fixed and at least 6 frames")
- parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): in a walk or run loop, a frame that follows a jump (a step 1.4x the median, whole body or the hair behind it) is replaced by RIFE's frame between its neighbours, at most 3 and never two side by side, recorded in the report (docs/loop-repair.md); off: cut as filmed")
+ parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): in a walk or run loop, a frame that follows a jump (a step 1.4x the median, whole body or the hair behind it) is replaced by RIFE's frame between its neighbours, at most 3 and never two side by side, recorded in the report (docs/loop-repair.md); where no RIFE is installed a loop that needs a frame is cut as filmed with a warning (`sprite-gen rife install` adds RIFE); on: the same repair, but no RIFE fails the loop; off: cut as filmed")
parser.add_argument("--jolt-max", type=float, default=None, help=f"walk/run: fail the repaired loop when its jolt index (how far each step strays from its neighbours' mean, over the median step) exceeds this. Default: no gate — the index is reported and a value over {repair_mod.JOLT_REFERENCE} is a warning line")
parser.add_argument("--head-step-max", type=float, default=None, help=f"walk/run: fail the repaired loop when the head's largest sideways move in one frame exceeds this %% of the body height. Default: no gate — reported, and over {repair_mod.HEAD_STEP_REFERENCE} is a warning line")
parser.add_argument("--facing", choices=FACINGS, default="right", help="which way the body faces in the frames (default right): the hair the jump search watches is behind it")
diff --git a/sprite_gen/video/rife.py b/sprite_gen/video/rife.py
index 6bb1a30..6dc28d3 100644
--- a/sprite_gen/video/rife.py
+++ b/sprite_gen/video/rife.py
@@ -11,6 +11,11 @@ The binary's own CPU path (`-g -1`) returns a wrong frame with rife-v4.6 on both
Linux (measured 2026-10-03: mean error 39 against 3.3 through Vulkan), so it is never passed;
a machine without a GPU runs the Vulkan path on Mesa's llvmpipe, which gives the GPU's frame.
+The binary is found by SPRITE_GEN_RIFE, then on PATH, then where `sprite-gen rife install`
+puts it (`install_root()`, docs/loop-repair.md section 1). A RIFE that cannot be found is
+`RifeNotInstalled`, which a caller may answer by cutting the loop as filmed with a warning; a
+RIFE that is found and then fails is `RifeUnavailable` and always an error.
+
The interpolator is a plain callable `(a, b, t) -> frame`, so a caller can be handed a stand-in
(`Interpolate`), and a test needs no binary.
"""
@@ -20,6 +25,7 @@ from __future__ import annotations
import os
import shutil
import subprocess
+import sys
import tempfile
from pathlib import Path
from typing import Callable
@@ -37,30 +43,73 @@ CALL_TIMEOUT_SECONDS = 120
Interpolate = Callable[[Image.Image, Image.Image, float], Image.Image]
+# The one line that installs it, quoted wherever a missing RIFE is reported.
+INSTALL_COMMAND = "sprite-gen rife install"
INSTALL_HINT = (
- f"install rife-ncnn-vulkan {RELEASE} (github.com/nihui/rife-ncnn-vulkan/releases/tag/{RELEASE}; "
- f"on Linux without a GPU also `libvulkan1 mesa-vulkan-drivers`) and put it on PATH or set SPRITE_GEN_RIFE "
- f"to the binary — the model {MODEL}/ ships beside it (SPRITE_GEN_RIFE_MODEL overrides); see docs/loop-repair.md"
+ f"run `{INSTALL_COMMAND}` (rife-ncnn-vulkan {RELEASE} with the model {MODEL}, sha256-checked, into the "
+ f"user data directory), or put {BINARY} on PATH or set SPRITE_GEN_RIFE to the binary — the model {MODEL}/ "
+ f"ships beside it (SPRITE_GEN_RIFE_MODEL overrides); on Linux without a GPU also `libvulkan1 mesa-vulkan-drivers`; "
+ f"see docs/loop-repair.md"
)
class RifeUnavailable(RuntimeError):
- """No usable RIFE binary or model. The message names what is missing and how to install it."""
+ """No usable RIFE: not installed, or found and failed. The message names what went wrong."""
+
+
+class RifeNotInstalled(RifeUnavailable):
+ """No RIFE binary or model where the engine looks. The message carries the install line."""
+
+
+def platform_release() -> str:
+ """The release zip's platform name for this machine (`macos`, `ubuntu`, `windows`), or '' when it ships none."""
+ if sys.platform == "darwin":
+ return "macos"
+ if sys.platform.startswith("linux"):
+ return "ubuntu"
+ if sys.platform == "win32":
+ return "windows"
+ return ""
+
+
+def data_dir() -> Path:
+ """sprite-gen's user data directory: SPRITE_GEN_DATA_DIR, else %LOCALAPPDATA%\\sprite-gen on
+ Windows, else $XDG_DATA_HOME/sprite-gen or ~/.local/share/sprite-gen."""
+ named = os.environ.get("SPRITE_GEN_DATA_DIR")
+ if named:
+ return Path(named).expanduser()
+ if sys.platform == "win32" and os.environ.get("LOCALAPPDATA"):
+ return Path(os.environ["LOCALAPPDATA"]) / "sprite-gen"
+ return Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share").expanduser() / "sprite-gen"
+
+
+def install_root() -> Path:
+ """Where `sprite-gen rife install` puts RIFE by default, and the last place `locate()` looks."""
+ return data_dir() / "rife"
+
+
+def installed_binary(root: Path | None = None, platform: str | None = None) -> Path:
+ """The binary inside an install root: `<root>/rife-ncnn-vulkan-<release>-<platform>/rife-ncnn-vulkan[.exe]`."""
+ platform = platform or platform_release()
+ return (root or install_root()) / f"{BINARY}-{RELEASE}-{platform}" / (BINARY + (".exe" if platform == "windows" else ""))
def locate() -> tuple[Path, Path]:
- """(binary, model directory), from SPRITE_GEN_RIFE / PATH and SPRITE_GEN_RIFE_MODEL / beside the binary."""
+ """(binary, model directory): the binary from SPRITE_GEN_RIFE, else PATH, else `install_root()`;
+ the model from SPRITE_GEN_RIFE_MODEL, else beside the binary."""
named = os.environ.get("SPRITE_GEN_RIFE")
- found = named or shutil.which(BINARY)
+ installed = installed_binary() if platform_release() else None
+ found = named or shutil.which(BINARY) or (str(installed) if installed and installed.is_file() else None)
if not found:
- raise RifeUnavailable(f"{BINARY} not found on PATH and SPRITE_GEN_RIFE is not set; {INSTALL_HINT}")
+ raise RifeNotInstalled(f"{BINARY} not found (SPRITE_GEN_RIFE is not set, it is not on PATH, and "
+ f"{installed or install_root()} does not exist); {INSTALL_HINT}")
binary = Path(found).expanduser()
if not binary.is_file() or not os.access(binary, os.X_OK):
- raise RifeUnavailable(f"{binary} is not an executable file; {INSTALL_HINT}")
+ raise RifeNotInstalled(f"{binary} is not an executable file; {INSTALL_HINT}")
binary = binary.resolve()
model = Path(os.environ.get("SPRITE_GEN_RIFE_MODEL") or binary.parent / MODEL).expanduser()
if not (model / "flownet.param").is_file() or not (model / "flownet.bin").is_file():
- raise RifeUnavailable(f"RIFE model {model} has no flownet.param / flownet.bin; {INSTALL_HINT}")
+ raise RifeNotInstalled(f"RIFE model {model} has no flownet.param / flownet.bin; {INSTALL_HINT}")
return binary, model
diff --git a/tests/video/test_cycle_align.py b/tests/video/test_cycle_align.py
index 5023f79..be743fb 100644
--- a/tests/video/test_cycle_align.py
+++ b/tests/video/test_cycle_align.py
@@ -10,6 +10,7 @@ from __future__ import annotations
import json
import math
+import os
from pathlib import Path
import numpy as np
@@ -136,3 +137,52 @@ def test_video_set_aligns_each_gait_filmed_in_two_or_more_directions(tmp_path):
assert rows[0]["loop"]["cycle_align"]["from"] == 20
assert (tmp_path / "walk.cycle-align.json").is_file()
assert batch.align_gaits(rows, tmp_path, "off") == {}
+
+
+def _no_rife(monkeypatch, tmp_path: Path) -> None:
+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
+ # PATH keeps every other tool (img2webp, ffmpeg); only the directories holding a RIFE go
+ path = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not (Path(d) / "rife-ncnn-vulkan").exists()]
+ monkeypatch.setenv("PATH", os.pathsep.join(path))
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))
+
+
+def test_video_cycle_align_without_rife_fails_and_leaves_the_set_as_cut(tmp_path, monkeypatch):
+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24), ("N", 28))]
+ before = [(d / "walk.strip.png").read_bytes() for d in dirs]
+ _no_rife(monkeypatch, tmp_path)
+ with pytest.raises(SystemExit, match=r"video-cycle-align: .*rife-ncnn-vulkan not found.*sprite-gen rife install"):
+ align.run(loop_dir=dirs, length=None, report=None)
+ assert [(d / "walk.strip.png").read_bytes() for d in dirs] == before
+
+
+def test_video_set_without_rife_skips_the_alignment_with_a_warning(tmp_path, monkeypatch, capsys):
+ from sprite_gen.video import batch
+
+ rows = []
+ for direction, length in (("front", 20), ("side", 24)):
+ item = tmp_path / f"{direction}-walk"
+ item.mkdir()
+ _cut(item, "loop", length)
+ rows.append({"item": f"{direction}-walk", "direction": direction, "state": "walk", "dir": str(item), "ok": True,
+ "loop": {"n_out": length}})
+ _no_rife(monkeypatch, tmp_path)
+ out = batch.align_gaits(rows, tmp_path, "auto")
+ assert out["walk"]["ok"] is True and out["walk"]["applied"] is False
+ assert out["walk"]["install"] == "sprite-gen rife install" and "rife-ncnn-vulkan not found" in out["walk"]["rife"]
+ assert [r["loop"]["n_out"] for r in rows] == [20, 24] and "cycle_align" not in rows[0]["loop"]
+ assert not (tmp_path / "walk.cycle-align.json").exists()
+ err = capsys.readouterr().err
+ assert "video-set: warning: walk: cycles not aligned" in err and "sprite-gen rife install" in err
+
+
+def test_cutting_a_loop_again_drops_the_kept_source(tmp_path):
+ """Once RIFE is installed a loop is cut again; the next alignment must read that cut."""
+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
+ align.align_set(dirs, interpolate=Recorder())
+ assert (dirs[0] / align.SOURCE_DIR).is_dir()
+ keyed = tmp_path / "S-keyed"
+ loop_mod.run_loop(keyed, dirs[0], fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=1000.0,
+ name="walk", report_path=None, cycle_mode="fixed", start=0, length=22, anchor="none", repair="off")
+ assert not (dirs[0] / align.SOURCE_DIR).exists()
+ assert align.align_set(dirs, interpolate=Recorder())["lengths"] == [22, 24]
diff --git a/tests/video/test_loop_repair.py b/tests/video/test_loop_repair.py
index daaecdc..1e3d6d2 100644
--- a/tests/video/test_loop_repair.py
+++ b/tests/video/test_loop_repair.py
@@ -2,8 +2,9 @@
"""Jump-frame repair (docs/loop-repair.md section 2): only the frame after a jump is replaced,
by the interpolator's frame between its two neighbours; at most three, never two side by side;
the hair watched is behind the body whichever way it faces; and `video-loop` records what it
-replaced, gates the cells as they now play, and refuses — naming `--repair off` — when a frame
-needs making and no RIFE is installed.
+replaced and gates the cells as they now play. When a frame needs making and no RIFE is
+installed, `--repair auto` cuts the loop as filmed with a warning and the install line, and
+`--repair on` refuses.
The interpolator is a stand-in that returns the true in-between of the synthetic loop, so the
tests need no binary and can say exactly which frame should come back."""
@@ -12,6 +13,7 @@ from __future__ import annotations
import json
import math
+import os
from pathlib import Path
import numpy as np
@@ -142,17 +144,75 @@ def test_video_loop_records_the_repair_and_plays_the_made_frame(tmp_path):
assert made == [0.5]
-def test_a_jump_without_rife_is_refused_naming_repair_off(tmp_path, monkeypatch):
+def _no_rife(monkeypatch, tmp_path: Path) -> None:
+ """No RIFE anywhere the engine looks: no SPRITE_GEN_RIFE, an empty PATH, an empty data directory."""
monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
- monkeypatch.setenv("PATH", str(tmp_path / "empty"))
+ # PATH keeps every other tool (img2webp, ffmpeg); only the directories holding a RIFE go
+ path = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not (Path(d) / "rife-ncnn-vulkan").exists()]
+ monkeypatch.setenv("PATH", os.pathsep.join(path))
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))
+
+
+def test_a_jump_without_rife_is_cut_as_filmed_with_a_warning(tmp_path, monkeypatch, capsys):
+ _no_rife(monkeypatch, tmp_path)
filmed, _ = _loop({10: 12})
keyed = _keyed(tmp_path, filmed)
- with pytest.raises(SystemExit, match=r"--repair off"):
- _run(tmp_path, keyed)
+ reopened = [Image.open(p).convert("RGBA") for p in sorted(keyed.glob("*.png"))][:N]
+ rep = _run(tmp_path, keyed)
+ assert rep["status"] == "passed"
+ jr = rep["jump_repair"]
+ assert jr["applied"] is False and jr["replaced"] == [] and jr["why"] == "RIFE not installed — cut as filmed"
+ assert jr["install"] == "sprite-gen rife install" and "rife-ncnn-vulkan not found" in jr["rife"]
+ assert jr["score_max_before"] >= repair.JUMP_RATIO and jr["score_max_after"] == jr["score_max_before"]
+ assert rep["seam_measurement"] == "source-frames" and rep["jolt"]["measured"] == "as filmed"
+ on_disk = np.asarray(Image.open(tmp_path / "out" / "cycle" / "frame-010.png"))
+ assert np.array_equal(on_disk, np.asarray(reopened[10])) # the jump frame stays as filmed
+ warning = [l for l in capsys.readouterr().err.splitlines() if "jump frame was not repaired" in l]
+ assert len(warning) == 1 and "sprite-gen rife install" in warning[0]
+ assert json.loads((tmp_path / "w.json").read_text())["jump_repair"]["applied"] is False
+
+
+def test_a_smooth_walk_without_rife_has_nothing_to_warn_about(tmp_path, monkeypatch, capsys):
+ _no_rife(monkeypatch, tmp_path)
+ filmed, _ = _loop()
+ rep = _run(tmp_path, _keyed(tmp_path, filmed))
+ assert rep["jump_repair"]["replaced"] == [] and "rife" not in rep["jump_repair"]
+ assert "not repaired" not in capsys.readouterr().err
+
+
+def test_repair_on_without_rife_is_refused_with_the_install_line(tmp_path, monkeypatch):
+ _no_rife(monkeypatch, tmp_path)
+ filmed, _ = _loop({10: 12})
+ with pytest.raises(SystemExit, match=r"sprite-gen rife install.*--repair auto"):
+ _run(tmp_path, _keyed(tmp_path, filmed), repair="on")
report = json.loads((tmp_path / "w.json").read_text())
assert report["status"] == "failed" and "rife-ncnn-vulkan not found" in report["error"]
+def test_repair_on_with_rife_repairs_as_auto_does(tmp_path):
+ filmed, truth = _loop({10: 12})
+ rep = _run(tmp_path, _keyed(tmp_path, filmed), repair="on", interpolate=lambda a, b, t: truth[10])
+ assert rep["jump_repair"]["replaced"] == [10] and rep["jump_repair"]["applied"] is True
+
+
+def test_a_rife_that_is_found_and_fails_still_fails_the_loop(tmp_path):
+ from sprite_gen.video import rife
+
+ def broken(a, b, t):
+ raise rife.RifeUnavailable("rife-ncnn-vulkan failed (exit 255): vkCreateInstance failed")
+
+ filmed, _ = _loop({10: 12})
+ with pytest.raises(SystemExit, match=r"vkCreateInstance failed.*--repair off"):
+ _run(tmp_path, _keyed(tmp_path, filmed), interpolate=broken)
+
+
+def test_a_jolt_gate_on_a_loop_left_unrepaired_says_rife_was_missing(tmp_path, monkeypatch):
+ _no_rife(monkeypatch, tmp_path)
+ filmed, _ = _loop({10: 12})
+ with pytest.raises(SystemExit, match=r"regenerate the clip \(the jump repair did not run: RIFE is not installed"):
+ _run(tmp_path, _keyed(tmp_path, filmed), jolt_max=0.01)
+
+
def test_repair_off_cuts_as_filmed_and_says_so(tmp_path):
filmed, _ = _loop({10: 12})
rep = _run(tmp_path, _keyed(tmp_path, filmed), repair="off")
diff --git a/tests/video/test_rife.py b/tests/video/test_rife.py
index 99bc7bb..fa93393 100644
--- a/tests/video/test_rife.py
+++ b/tests/video/test_rife.py
@@ -20,7 +20,7 @@ from sprite_gen.video import rife
def _fake_binary(tmp_path: Path, with_model: bool = True) -> Path:
binary = tmp_path / "bin" / rife.BINARY
- binary.parent.mkdir()
+ binary.parent.mkdir(parents=True)
binary.write_text("#!/bin/sh\nexit 0\n")
binary.chmod(binary.stat().st_mode | stat.S_IXUSR)
if with_model:
@@ -33,10 +33,47 @@ def _fake_binary(tmp_path: Path, with_model: bool = True) -> Path:
def test_missing_binary_is_refused_with_the_install_line(monkeypatch, tmp_path):
monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
monkeypatch.setenv("PATH", str(tmp_path))
- with pytest.raises(rife.RifeUnavailable, match="install rife-ncnn-vulkan 20221029"):
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))
+ with pytest.raises(rife.RifeNotInstalled, match=r"run `sprite-gen rife install` \(rife-ncnn-vulkan 20221029"):
rife.locate()
+def test_the_installed_copy_is_found_after_the_environment_and_path(monkeypatch, tmp_path):
+ """SPRITE_GEN_RIFE, then PATH, then the install root of `sprite-gen rife install`."""
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))
+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
+ monkeypatch.delenv("SPRITE_GEN_RIFE_MODEL", raising=False)
+ monkeypatch.setenv("PATH", str(tmp_path / "empty"))
+ staged = _fake_binary(tmp_path / "staged")
+ installed = rife.installed_binary()
+ assert installed.parent.parent == tmp_path / "data" / "rife"
+ installed.parent.parent.mkdir(parents=True)
+ staged.parent.rename(installed.parent)
+ assert rife.locate()[0] == installed.resolve()
+ on_path = _fake_binary(tmp_path / "path")
+ monkeypatch.setenv("PATH", str(on_path.parent))
+ assert rife.locate()[0] == on_path.resolve()
+ named = _fake_binary(tmp_path / "named")
+ monkeypatch.setenv("SPRITE_GEN_RIFE", str(named))
+ assert rife.locate()[0] == named.resolve()
+
+
+def test_the_data_directory_follows_the_platform_rules(monkeypatch, tmp_path):
+ monkeypatch.delenv("SPRITE_GEN_DATA_DIR", raising=False)
+ monkeypatch.setattr(rife.sys, "platform", "linux")
+ monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "xdg"))
+ assert rife.data_dir() == tmp_path / "xdg" / "sprite-gen"
+ assert rife.installed_binary().parent.name == "rife-ncnn-vulkan-20221029-ubuntu"
+ monkeypatch.delenv("XDG_DATA_HOME")
+ assert rife.data_dir() == Path.home() / ".local" / "share" / "sprite-gen"
+ monkeypatch.setattr(rife.sys, "platform", "win32")
+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "local"))
+ assert rife.data_dir() == tmp_path / "local" / "sprite-gen"
+ assert rife.installed_binary().name == "rife-ncnn-vulkan.exe"
+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "named"))
+ assert rife.data_dir() == tmp_path / "named"
+
+
def test_model_beside_the_binary_is_found(monkeypatch, tmp_path):
binary = _fake_binary(tmp_path)
monkeypatch.setenv("SPRITE_GEN_RIFE", str(binary))