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.ymlindex 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@v5with: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/nulldiff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.pyindex 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.pyindex 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_canvasfrom sprite_gen.video import frames as video_framesfrom sprite_gen.video import loop as video_loopfrom sprite_gen.video import align as video_align+from sprite_gen.video import rife_installfrom sprite_gen.effects import recolor, shadowfrom sprite_gen.scene import render, inspect_scenefrom sprite_gen.serve import serve_compose, serve_curation@@ -353,6 +354,11 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callabvideo_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.pynew file mode 100644index 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.pynew file mode 100644index 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)