Skip to content

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

feat(rife): `sprite-gen rife install` puts the pinned RIFE where the engine finds it

Soohong Kim4f07a1996cb5
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 08733c9..6e46fa6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -26,14 +26,6 @@ jobs:
sudo cp /tmp/libwebp-1.6.0-linux-x86-64/bin/* /usr/local/bin/
img2webp -h 2>&1 | grep -q -- -exact # img2webp -version exits 1 without an output file; -h is the honest probe
- - name: Install RIFE for video-loop's jump repair (rife-ncnn-vulkan 20221029 on Mesa llvmpipe, docs/loop-repair.md)
- run: |
- sudo apt-get install -y -qq libvulkan1 mesa-vulkan-drivers unzip
- curl -fsSL -o /tmp/rife.zip https://github.com/nihui/rife-ncnn-vulkan/releases/download/20221029/rife-ncnn-vulkan-20221029-ubuntu.zip
- echo '1e2c7ee7fa7daa326542d50622f0afedc80cf6f1858bda411d16385ffa5cdf68 /tmp/rife.zip' | sha256sum -c -
- sudo unzip -q /tmp/rife.zip -d /opt
- sudo ln -s /opt/rife-ncnn-vulkan-20221029-ubuntu/rife-ncnn-vulkan /usr/local/bin/rife-ncnn-vulkan
-
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
@@ -43,6 +35,13 @@ jobs:
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
+ # The user's own install path: the pinned zip, its SHA-256, the user data directory, and a
+ # check frame through the binary — here on Mesa llvmpipe (docs/loop-repair.md section 1).
+ - name: Install RIFE for video-loop's jump repair (sprite-gen rife install)
+ run: |
+ sudo apt-get install -y -qq libvulkan1 mesa-vulkan-drivers
+ .venv/bin/sprite-gen rife install
+
- name: Quickstart smoke (prepare -> extract -> compose)
run: |
.venv/bin/python scripts/prepare_sprite_run.py --help > /dev/null
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.py
index b72b23b..89a008d 100644
--- a/sprite_gen/_modules.py
+++ b/sprite_gen/_modules.py
@@ -26,6 +26,7 @@ MODULE_DOMAIN = {
'loop': 'video',
'batch': 'video',
'align': 'video',
+ 'rife_install': 'video',
'prepare': 'gen',
'extract': 'frames',
'cutout': 'frames',
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 31c44b1..54b00d7 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -19,6 +19,7 @@ from sprite_gen.video import canvas as video_canvas
from sprite_gen.video import frames as video_frames
from sprite_gen.video import loop as video_loop
from sprite_gen.video import align as video_align
+from sprite_gen.video import rife_install
from sprite_gen.effects import recolor, shadow
from sprite_gen.scene import render, inspect_scene
from sprite_gen.serve import serve_compose, serve_curation
@@ -353,6 +354,11 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
video_align.add_arguments,
video_align.run,
),
+ "rife": (
+ "install: download the pinned RIFE (rife-ncnn-vulkan, sha256-checked) into the user data directory, where the loop repair finds it.",
+ rife_install.add_arguments,
+ rife_install.run,
+ ),
# The argument surface is `serve_curation.add_arguments` itself, not a copy of it: the
# webview's own `--help` and this subcommand are the same declaration, so `sprite-gen
# curation` cannot drift from the launch form the READMEs still document.
diff --git a/sprite_gen/video/rife_install.py b/sprite_gen/video/rife_install.py
new file mode 100644
index 0000000..59c6ab6
--- /dev/null
+++ b/sprite_gen/video/rife_install.py
@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sprite-gen rife install` — put the pinned RIFE where the engine finds it.
+
+Downloads the rife-ncnn-vulkan release zip for this platform (pinned release and SHA-256,
+docs/loop-repair.md section 1), checks the hash before anything is unpacked, and keeps only what
+the engine runs: the binary, the model `rife-v4.6/`, the licence and readme (and on Windows the
+OpenMP runtime the binary loads). The install lands in `rife.install_root()` — the user data
+directory — which `rife.locate()` searches after SPRITE_GEN_RIFE and PATH. `--dir` installs
+somewhere else and prints the SPRITE_GEN_RIFE line that points the engine at it.
+
+Unpacked into a staging directory and renamed into place, so an interrupted install never leaves
+a half-written RIFE where the engine looks. Running it again over a finished install of the same
+zip does nothing but the check. The check makes one frame between two discs through the
+installed binary, so a machine that has the files but no working Vulkan finds out here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import platform as platform_mod
+import shutil
+import stat
+import sys
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from sprite_gen._deps import np
+from sprite_gen.video import rife
+
+# SHA-256 of each release zip, measured on the downloaded files (docs/loop-repair.md section 1).
+ZIP_SHA256 = {
+ "macos": "4a63a1f3c9c715773c57d2ee51df1b315ed20cd6c63103e45c483ecc4400b595",
+ "ubuntu": "1e2c7ee7fa7daa326542d50622f0afedc80cf6f1858bda411d16385ffa5cdf68",
+ "windows": "d8e4d772d26cd8006ef0ad0bc82eb191b53c68677d1ae2f42506d74cbbbea606",
+}
+# The machines each zip's binary runs on (`platform.machine()`, lower case). The macOS binary is
+# universal; the Linux and Windows ones are x86-64 only.
+ZIP_MACHINES = {"macos": None, "ubuntu": {"x86_64", "amd64"}, "windows": {"amd64", "x86_64"}}
+URL = "https://github.com/nihui/rife-ncnn-vulkan/releases/download/{release}/{name}"
+MARKER = ".sprite-gen-install.json"
+CHUNK = 1 << 20
+TIMEOUT_SECONDS = 60
+
+
+def zip_name(platform: str) -> str:
+ return f"{rife.BINARY}-{rife.RELEASE}-{platform}.zip"
+
+
+def _platform(platform: str | None) -> str:
+ name = platform or rife.platform_release()
+ if name not in ZIP_SHA256:
+ raise SystemExit(f"rife install: rife-ncnn-vulkan {rife.RELEASE} ships no build for {sys.platform}; build it from "
+ f"github.com/nihui/rife-ncnn-vulkan and set SPRITE_GEN_RIFE to the binary (docs/loop-repair.md)")
+ machines = ZIP_MACHINES[name]
+ machine = platform_mod.machine().lower()
+ if platform is None and machines is not None and machine not in machines:
+ raise SystemExit(f"rife install: the {name} build of rife-ncnn-vulkan {rife.RELEASE} is x86-64 only and this machine "
+ f"is {machine}; build it from github.com/nihui/rife-ncnn-vulkan and set SPRITE_GEN_RIFE to the binary")
+ return name
+
+
+def _sha256(path: Path) -> str:
+ h = hashlib.sha256()
+ with path.open("rb") as f:
+ for block in iter(lambda: f.read(CHUNK), b""):
+ h.update(block)
+ return h.hexdigest()
+
+
+def _download(url: str, dest: Path) -> None:
+ """`url` to `dest`, with a progress line on stderr every tenth of the way."""
+ request = urllib.request.Request(url, headers={"User-Agent": "sprite-gen"})
+ with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response, dest.open("wb") as out:
+ total = int(response.headers.get("Content-Length") or 0)
+ done, shown = 0, 0
+ for block in iter(lambda: response.read(CHUNK), b""):
+ out.write(block)
+ done += len(block)
+ if total and done * 10 // total > shown:
+ shown = done * 10 // total
+ print(f"rife install: {done / 1e6:.0f} / {total / 1e6:.0f} MB", file=sys.stderr, flush=True)
+
+
+def _kept(member: str, top: str, platform: str) -> bool:
+ """Whether a zip member is part of what the engine runs (the rest are other models)."""
+ if not member.startswith(top + "/") or member.endswith("/"):
+ return False
+ rel = member[len(top) + 1:]
+ if any(part in ("", ".", "..") for part in rel.split("/")):
+ return False
+ if rel.startswith(rife.MODEL + "/"):
+ return "/" not in rel[len(rife.MODEL) + 1:]
+ if "/" in rel:
+ return False
+ return rel in (rife.BINARY, rife.BINARY + ".exe", "LICENSE", "README.md") or (platform == "windows" and rel.lower().endswith(".dll"))
+
+
+def _unpack(zip_path: Path, staging: Path, platform: str) -> list[str]:
+ top = f"{rife.BINARY}-{rife.RELEASE}-{platform}"
+ kept: list[str] = []
+ with zipfile.ZipFile(zip_path) as zf:
+ for info in zf.infolist():
+ if not _kept(info.filename, top, platform):
+ continue
+ rel = info.filename[len(top) + 1:]
+ dest = staging / rel
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ with zf.open(info) as src, dest.open("wb") as out:
+ shutil.copyfileobj(src, out, CHUNK)
+ kept.append(rel)
+ binary = staging / rife.installed_binary(Path("."), platform).name
+ model = staging / rife.MODEL
+ if not binary.is_file() or not (model / "flownet.param").is_file() or not (model / "flownet.bin").is_file():
+ raise SystemExit(f"rife install: {zip_path.name} has no {top}/{binary.name} with {rife.MODEL}/flownet.param and flownet.bin")
+ binary.chmod(binary.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+ return sorted(kept)
+
+
+def _complete(target: Path, platform: str, sha: str) -> bool:
+ try:
+ marker = json.loads((target / MARKER).read_text(encoding="utf-8"))
+ except (OSError, ValueError):
+ return False
+ binary = target / rife.installed_binary(Path("."), platform).name
+ return (marker.get("sha256") == sha and binary.is_file()
+ and all((target / rife.MODEL / f).is_file() for f in ("flownet.param", "flownet.bin")))
+
+
+def _disc(cx: int) -> Image.Image:
+ a = np.zeros((64, 96, 4), dtype=np.uint8)
+ yy, xx = np.mgrid[:64, :96]
+ a[(yy - 32) ** 2 + (xx - cx) ** 2 <= 12 ** 2] = (200, 60, 40, 255)
+ return Image.fromarray(a, "RGBA")
+
+
+def check(binary: Path, model: Path) -> dict[str, Any]:
+ """One frame half way between two discs through `binary`: the disc must land in the middle."""
+ try:
+ mid = rife.Rife(binary, model)(_disc(30), _disc(66), 0.5)
+ except rife.RifeUnavailable as exc:
+ linux = " — on Linux without a GPU install `libvulkan1 mesa-vulkan-drivers`" if sys.platform.startswith("linux") else ""
+ raise SystemExit(f"rife install: installed, but the check frame failed: {exc}{linux}") from exc
+ xs = np.nonzero(np.asarray(mid)[..., 3] > 127)[1]
+ centre = float(xs.mean()) if xs.size else None
+ if centre is None or abs(centre - 48) > 4:
+ raise SystemExit(f"rife install: installed, but the check frame is wrong (disc centre {centre}, expected 48)")
+ return {"passed": True, "disc_centre_x": round(centre, 2)}
+
+
+def install(*, dest: Path | None = None, zip_path: Path | None = None, platform: str | None = None,
+ force: bool = False, run_check: bool = True) -> dict[str, Any]:
+ name = _platform(platform)
+ sha = ZIP_SHA256[name]
+ root = (dest or rife.install_root()).expanduser().resolve()
+ binary = rife.installed_binary(root, name)
+ target = binary.parent
+ report: dict[str, Any] = {"release": rife.RELEASE, "model": rife.MODEL, "platform": name, "zip": zip_name(name),
+ "sha256": sha, "dir": str(target), "binary": str(binary)}
+ if not force and _complete(target, name, sha):
+ report["installed"] = "already"
+ else:
+ root.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix=".rife-install-", dir=root) as td:
+ work = Path(td)
+ if zip_path is None:
+ url = URL.format(release=rife.RELEASE, name=zip_name(name))
+ print(f"rife install: downloading {url}", file=sys.stderr, flush=True)
+ zip_path = work / zip_name(name)
+ _download(url, zip_path)
+ report["source"] = url
+ else:
+ report["source"] = str(zip_path)
+ got = _sha256(zip_path)
+ if got != sha:
+ raise SystemExit(f"rife install: {zip_path.name} has SHA-256 {got}, expected {sha}; nothing was installed")
+ staging = work / target.name
+ report["files"] = _unpack(zip_path, staging, name)
+ (staging / MARKER).write_text(json.dumps({"release": rife.RELEASE, "zip": zip_name(name), "sha256": sha}) + "\n",
+ encoding="utf-8")
+ if target.exists():
+ shutil.rmtree(target)
+ staging.rename(target)
+ report["installed"] = "now"
+ if run_check:
+ report["check"] = check(binary, target / rife.MODEL)
+ # What the engine will run: SPRITE_GEN_RIFE and PATH are searched before the install root.
+ try:
+ found = str(rife.locate()[0])
+ except rife.RifeUnavailable:
+ found = None
+ report["engine_finds"] = found
+ if found != str(binary.resolve()):
+ report["note"] = (f"the engine looks in {rife.install_root()} only after SPRITE_GEN_RIFE and PATH; to run this "
+ f"install set SPRITE_GEN_RIFE={binary}" + (f" (it now finds {found})" if found else ""))
+ return report
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+ sub = parser.add_subparsers(dest="action", required=True, metavar="<action>")
+ p = sub.add_parser("install", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ p.add_argument("--dir", type=Path, help=f"install root (default: the user data directory, {rife.install_root()}; "
+ "another directory needs SPRITE_GEN_RIFE, which the command prints)")
+ p.add_argument("--zip", type=Path, help=f"use this already-downloaded release zip ({zip_name('<platform>')}) instead of downloading it; "
+ "its SHA-256 is checked all the same")
+ p.add_argument("--force", action="store_true", help="unpack again over a finished install")
+ p.add_argument("--no-check", action="store_true", help="skip the check frame made through the installed binary")
+
+
+def run(**kwargs: object) -> int:
+ if kwargs.get("action") != "install":
+ raise SystemExit(f"rife: unknown action {kwargs.get('action')!r}; expected install")
+ report = install(dest=kwargs.get("dir"), zip_path=kwargs.get("zip"), force=bool(kwargs.get("force")), # type: ignore[arg-type]
+ run_check=not kwargs.get("no_check"))
+ if report.get("note"):
+ print(f"rife install: note: {report['note']}", file=sys.stderr)
+ print(json.dumps({k: v for k, v in report.items() if k != "files"}, ensure_ascii=False, indent=2))
+ return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(prog="sprite-gen rife", description=__doc__)
+ add_arguments(parser)
+ return run(**vars(parser.parse_args(argv)))
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/video/test_rife_install.py b/tests/video/test_rife_install.py
new file mode 100644
index 0000000..0a1ed5d
--- /dev/null
+++ b/tests/video/test_rife_install.py
@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sprite-gen rife install` without a network: a release-shaped zip built here, its SHA-256 put
+in place of the pinned one. The zip is checked before anything is unpacked, only what the engine
+runs is kept, the install lands where `rife.locate()` looks last, and a second run does nothing."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from sprite_gen import cli
+from sprite_gen.video import rife, rife_install
+
+PLATFORM = rife.platform_release() or "ubuntu"
+TOP = f"rife-ncnn-vulkan-{rife.RELEASE}-{PLATFORM}"
+BINARY = rife.installed_binary(Path("."), PLATFORM).name
+
+
+def _release_zip(tmp_path: Path, *, model: bool = True) -> Path:
+ path = tmp_path / rife_install.zip_name(PLATFORM)
+ with zipfile.ZipFile(path, "w") as zf:
+ zf.writestr(f"{TOP}/", "")
+ zf.writestr(f"{TOP}/{BINARY}", "#!/bin/sh\nexit 0\n")
+ zf.writestr(f"{TOP}/LICENSE", "MIT\n")
+ zf.writestr(f"{TOP}/README.md", "readme\n")
+ if model:
+ zf.writestr(f"{TOP}/{rife.MODEL}/flownet.param", "param\n")
+ zf.writestr(f"{TOP}/{rife.MODEL}/flownet.bin", "bin\n")
+ zf.writestr(f"{TOP}/rife-v4/flownet.bin", "another model\n") # not what the engine runs
+ zf.writestr(f"{TOP}/{rife.MODEL}/../../escape.txt", "outside\n")
+ zf.writestr("elsewhere/rife-ncnn-vulkan", "not in the release folder\n")
+ return path
+
+
+def pinned(monkeypatch, tmp_path):
+ """The fixture zip, with its SHA-256 as the pinned one, and the engine looking only at tmp_path."""
+ (tmp_path / "zips").mkdir()
+ path = _release_zip(tmp_path / "zips")
+ monkeypatch.setitem(rife_install.ZIP_SHA256, PLATFORM, hashlib.sha256(path.read_bytes()).hexdigest())
+ 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"))
+ return path
+
+
+def test_install_keeps_what_the_engine_runs_where_locate_finds_it(pinned, tmp_path):
+ with pytest.raises(rife.RifeNotInstalled):
+ rife.locate()
+ report = rife_install.install(zip_path=pinned, platform=PLATFORM, run_check=False)
+ target = tmp_path / "data" / "rife" / TOP
+ assert report["installed"] == "now" and report["dir"] == str(target.resolve())
+ assert sorted(report["files"]) == sorted([BINARY, "LICENSE", "README.md", f"{rife.MODEL}/flownet.bin", f"{rife.MODEL}/flownet.param"])
+ assert not (target / "rife-v4").exists() and not (tmp_path / "data" / "escape.txt").exists()
+ assert os.access(target / BINARY, os.X_OK) and (target / BINARY).stat().st_mode & stat.S_IXUSR
+ assert json.loads((target / rife_install.MARKER).read_text())["sha256"] == rife_install.ZIP_SHA256[PLATFORM]
+ assert rife.locate() == ((target / BINARY).resolve(), (target / rife.MODEL).resolve())
+ assert report["engine_finds"] == str((target / BINARY).resolve()) and "note" not in report
+ assert [p.name for p in (tmp_path / "data" / "rife").iterdir()] == [TOP] # no staging or download left behind
+
+
+def test_a_zip_whose_hash_differs_installs_nothing(pinned, tmp_path, monkeypatch):
+ monkeypatch.setitem(rife_install.ZIP_SHA256, PLATFORM, "0" * 64)
+ with pytest.raises(SystemExit, match="expected 0000"):
+ rife_install.install(zip_path=pinned, platform=PLATFORM, run_check=False)
+ assert not (tmp_path / "data" / "rife" / TOP).exists()
+
+
+def test_a_zip_without_the_model_is_refused(pinned, tmp_path, monkeypatch):
+ (tmp_path / "bare").mkdir()
+ bare = _release_zip(tmp_path / "bare", model=False)
+ monkeypatch.setitem(rife_install.ZIP_SHA256, PLATFORM, hashlib.sha256(bare.read_bytes()).hexdigest())
+ with pytest.raises(SystemExit, match="flownet.param"):
+ rife_install.install(zip_path=bare, platform=PLATFORM, run_check=False)
+ assert not (tmp_path / "data" / "rife" / TOP).exists()
+
+
+def test_a_second_run_does_nothing_and_force_unpacks_again(pinned, tmp_path):
+ rife_install.install(zip_path=pinned, platform=PLATFORM, run_check=False)
+ stray = tmp_path / "data" / "rife" / TOP / "stray"
+ stray.write_text("x")
+ assert rife_install.install(platform=PLATFORM, run_check=False)["installed"] == "already" # no zip, no download
+ assert stray.exists()
+ assert rife_install.install(zip_path=pinned, platform=PLATFORM, force=True, run_check=False)["installed"] == "now"
+ assert not stray.exists()
+
+
+def test_the_download_is_checked_like_a_given_zip(pinned, monkeypatch, tmp_path):
+ monkeypatch.setattr(rife_install, "URL", pinned.parent.as_uri() + "/{name}")
+ report = rife_install.install(platform=PLATFORM, run_check=False)
+ assert report["installed"] == "now" and report["source"] == pinned.as_uri()
+ assert rife.locate()[0].parent.name == TOP
+
+
+def test_another_dir_names_the_variable_that_points_the_engine_at_it(pinned, tmp_path, capsys):
+ rc = cli.main(["rife", "install", "--zip", str(pinned), "--dir", str(tmp_path / "elsewhere"), "--no-check"])
+ out, err = capsys.readouterr()
+ assert rc == 0 and json.loads(out)["installed"] == "now"
+ assert f"SPRITE_GEN_RIFE={tmp_path / 'elsewhere' / TOP / BINARY}" in err
+ with pytest.raises(rife.RifeNotInstalled):
+ rife.locate()
+
+
+def test_the_check_frame_fails_on_a_binary_that_does_not_run(pinned, tmp_path):
+ rife_install.install(zip_path=pinned, platform=PLATFORM, run_check=False)
+ target = tmp_path / "data" / "rife" / TOP
+ (target / BINARY).write_text("#!/bin/sh\necho no vulkan >&2\nexit 1\n")
+ with pytest.raises(SystemExit, match="check frame failed.*no vulkan"):
+ rife_install.install(platform=PLATFORM)
+
+
+def test_a_platform_without_a_release_build_is_refused(monkeypatch):
+ monkeypatch.setattr(rife, "platform_release", lambda: "")
+ with pytest.raises(SystemExit, match="ships no build"):
+ rife_install.install(run_check=False)