Skip to content

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

42.9 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Held cells (sprite_gen/video/held_fill.py, docs/loop-repair.md section 7): neighbour cells of a cut that show the
same picture are found on every cut `video-loop` makes, recorded (`held_fill`: the held runs, the poses and the cells)
and, by default, made again as the frames between the pose before them and the pose after; the cut's first and last
cells, its length, its beat and its wrap stay as they were, and a part standing still in both stays where it stood.
A clip asked for at a higher rate than it was filmed (`--out-fps`) is given frames between, not frames shown again.
With no RIFE the cut is delivered as filmed with a warning naming the motion and the install line; `--fill-held off`
cuts it as before. A cut with no held cell comes out byte for byte as before (the six inputs below, their pictures
pinned on the engine before the fill).

The interpolator is a stand-in that draws the synthetic clip again at the time asked for (`Between`), so the tests
need no binary and say which frame comes back."""

from __future__ import annotations

import hashlib
import json
import math
import os
from pathlib import Path

import numpy as np
import pytest
from PIL import Image

from sprite_gen.video import held_fill
from sprite_gen.video import loop as loop_mod
from sprite_gen.video import sway
from tests.picture_digest import picture_digest
from tests.video.held_fill_inputs import (N, Between, hop, planter, save, shown_again, slid, swing, topple, walk,
                                          walk_at)


def _no_rife(monkeypatch, tmp_path: Path) -> None:
    """No RIFE anywhere the engine looks: no SPRITE_GEN_RIFE, no directory on PATH holding one, an empty data
    directory."""
    monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)
    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 _run(tmp_path: Path, frames: list[Image.Image], name: str = "m", **kw) -> dict:
    keyed = save(frames, tmp_path / f"{name}-keyed")
    return loop_mod.run_loop(keyed, tmp_path / f"{name}-out", fps=24.0, min_len=None, max_len=None, n_out=None,
                             seam_max=loop_mod.SEAM_RATIO_MAX, name=name, report_path=None, **kw)


def _sha(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()


def _bytes(out: Path, name: str) -> dict[str, str]:
    cycle = hashlib.sha256(b"".join(p.read_bytes() for p in sorted((out / "cycle").glob("frame-*.png")))).hexdigest()
    return {"strip": _sha(out / f"{name}.strip.png"), "gif": _sha(out / f"{name}.gif"), "webp": _sha(out / f"{name}.webp"),
            "cycle": cycle}


def _pictures(out: Path, name: str) -> dict[str, str]:
    return {"strip": picture_digest([out / f"{name}.strip.png"]), "gif": picture_digest([out / f"{name}.gif"]),
            "webp": picture_digest([out / f"{name}.webp"]),
            "cycle": picture_digest(sorted((out / "cycle").glob("frame-*.png")))}


def _meta(rep: dict) -> dict:
    return json.loads(Path(rep["strip"]["path"]).with_suffix("").with_suffix(".strip.json").read_text())


def _cycle(rep: dict) -> list[Image.Image]:
    return [Image.open(p).convert("RGBA") for p in sorted((Path(rep["out_dir"]) / "cycle").glob("frame-*.png"))]


# Pinned on the engine before the fill (886936e): a cut with no held cell is delivered as it was. The pins are the
# pictures (`_pictures`, tests/picture_digest.py), not the files: the same pixels are other PNG bytes on Linux than on
# macOS, while the engine before the fill and this one write the same files on each.
UNHELD = {
    "walk-fixed": (lambda: walk(), dict(state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off"), {
        "strip": "1467e5923f24c4830ef24e6525e9e537d73504a0d95badf1ba4cd0ed3288572b",
        "gif": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
        "webp": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
        "cycle": "319c0f8aee34fb537b1702eecc018afc4a03b10dcda1b84c5cb204a14d4ac3fa"}),
    "walk-auto": (lambda: walk(N * 3 + 4), dict(state="walk", repair="off"), {
        "strip": "1c3945eadb5095d3b1c929bd2009bd510ebf7760a4f0f92c8e618b04d882b6ca",
        "gif": "6e9348b6d9ac27dc1868bf8a2b9aae7daee44847274eb65c1b6ce4431c686f06",
        "webp": "6e9348b6d9ac27dc1868bf8a2b9aae7daee44847274eb65c1b6ce4431c686f06",
        "cycle": "185053b6a035a9d0b672a1d93d7e378f819189cd3cf144540e9f95a111a0b2b2"}),
    "hop-one-shot": (lambda: hop(), dict(state="jump", cycle_mode="one-shot"), {
        "strip": "6442073e3ada3b03e2f7df6c52348fc001fcbdce6c51c8e91ce157e91c313ac7",
        "gif": "ab58ee8b25599331b7958701d81526b155a05b1cddfa8b9ed823134f9f2e93fb",
        "webp": "ab58ee8b25599331b7958701d81526b155a05b1cddfa8b9ed823134f9f2e93fb",
        "cycle": "189484dd441486fe6241534fae7a03ea7afac71ec204b8871e9da938e6e69793"}),
    "swing-pinned": (lambda: swing(), dict(state="attack", cycle_mode="pinned", anchor="none"), {
        "strip": "9dd4896eef213ae44b487f92d33ffa1d7e6aea66ac32e9c97773f6c0ed27e3d1",
        "gif": "75df72100becbdd3b823ae282b2dd28815f6271198dd8562d8d91ee9363d6358",
        "webp": "75df72100becbdd3b823ae282b2dd28815f6271198dd8562d8d91ee9363d6358",
        "cycle": "b2a255d5f0018a71225501a86dcfa54915fa9ed4c4d936319fb83c31ab57bf1e"}),
    "topple-once": (lambda: topple(), dict(state="death", cycle_mode="once"), {
        "strip": "c9b7900ec1d4523bb34c07eb8077f72352bbc8251fc5caab31647317e0634957",
        "gif": "285a7352ba6345648cfc48185f9121ce75f37cc63b3b5875dce5b4bed738fc8a",
        "webp": "285a7352ba6345648cfc48185f9121ce75f37cc63b3b5875dce5b4bed738fc8a",
        "cycle": "67a1691bc7cb2eabf5a885dd9b993eb8596ea20090594958b7a02afc09948c63"}),
    "swing-once-return": (lambda: swing(), dict(state="leap", cycle_mode="once-return", anchor="none"), {
        "strip": "883f7e44cc1f54ec5a1442ed12fe8f608070e12b9795c73d2f871425d76e977f",
        "gif": "70de98ed5a45f2e9840c6946057a868260cae3588bff9969205e453ef1b024f3",
        "webp": "70de98ed5a45f2e9840c6946057a868260cae3588bff9969205e453ef1b024f3",
        "cycle": "4dfe6899ab09db62987b27d0a35ba754a22ca78e02945e731b1025dfe3af90e3"}),
}


@pytest.mark.parametrize("case", sorted(UNHELD))
def test_a_cut_with_no_held_cell_is_delivered_byte_for_byte_as_before(case, tmp_path, monkeypatch):
    _no_rife(monkeypatch, tmp_path)  # nothing is made, so nothing looks for RIFE
    frames, kw, pinned = UNHELD[case]
    rep = _run(tmp_path, frames(), case, **kw)
    assert _pictures(Path(rep["out_dir"]), case) == pinned
    record = _meta(rep)["held_fill"]
    assert record == held_fill.public(rep["held_fill"])
    assert record["mode"] == "auto" and record["made"] == [] and "unmade" not in record
    cells = rep["cycle"]["length"]
    assert record["cells"] == cells
    if case == "topple-once":
        # It lies still for its last five cells: the cut's closing pose, kept.
        assert record["held_runs"] == [{"start": cells - 5, "length": 5}]
        assert record["before"]["held_runs"][0]["filled"] is False
        assert record["poses"] == cells - 4
    else:
        assert record["held_runs"] == [] and record["poses"] == cells



@pytest.mark.skipif(os.name == "nt", reason="a shebang script cannot stand in for rife-ncnn-vulkan.exe")
@pytest.mark.parametrize("model", ["rife-v4.25", "rife-v4.6"])
@pytest.mark.parametrize("case", sorted(UNHELD))
def test_a_cut_with_no_held_cell_runs_no_rife_and_is_the_same_bytes_whichever_model(case, model, tmp_path, monkeypatch):
    """The six cuts with no held cell, with a RIFE there to be found — either model named (SPRITE_GEN_RIFE_MODEL_NAME) —
    are the bytes pinned before the fill: the binary is never run, so changing the default model changes none of
    them."""
    from sprite_gen.video import rife

    log = tmp_path / "rife" / "argv.txt"
    binary = tmp_path / "rife" / rife.BINARY
    binary.parent.mkdir()
    binary.write_text(f'#!/bin/sh\necho "$@" >> "{log}"\nexit 1\n')
    binary.chmod(0o700)
    for name in rife.MODELS:
        (binary.parent / name).mkdir()
        for f in ("flownet.param", "flownet.bin"):
            (binary.parent / name / f).write_bytes(b"x")
    monkeypatch.setenv("SPRITE_GEN_RIFE", str(binary))
    monkeypatch.setenv("SPRITE_GEN_RIFE_MODEL_NAME", model)
    monkeypatch.delenv("SPRITE_GEN_RIFE_MODEL", raising=False)
    frames, kw, pinned = UNHELD[case]
    rep = _run(tmp_path, frames(), case, **kw)
    assert _pictures(Path(rep["out_dir"]), case) == pinned
    assert not log.exists()

STALLED = {5: 2, 13: 3}  # the walk's frame 5 shown twice, frame 13 three times
STALLED_OFF = {  # the stalled walk cut on the engine before the fill (886936e)
    "strip": "32f2c1b7f4f3aedfa3eba4d49b849fd8efea9e011aaf2e035407a97ac6e9430d",
    "gif": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
    "webp": "bf77ed39daaaecfbbd403243696dcf9e2bb6d99addc01a889a8dc00772468b8d",
    "cycle": "2d74651f64831c9c512f0486e1b03ca3827c4b9d3840bf11f8c67fad221bbfe9",
}
STALLED_CUT = dict(state="walk", cycle_mode="fixed", start=0, length=N + 3, anchor="none", repair="off")


def test_a_stalled_walk_has_its_held_cells_made_between_the_poses_beside_them(tmp_path):
    between = Between(walk_at, range(N + 6), period=N)
    rep = _run(tmp_path, shown_again(walk(), STALLED), interpolate=between, **STALLED_CUT)
    record = rep["held_fill"]
    assert record["before"]["cells"] == N + 3 and record["before"]["poses"] == N
    assert [(r["start"], r["length"], r["filled"]) for r in record["before"]["held_runs"]] == [(5, 2, True), (14, 3, True)]
    assert record["made"] == [6, 15, 16]
    # Each made at its own time between the pose before the run and the pose after it: half way, a third and two thirds.
    assert sorted(between.calls) == [(5.0, 6.0, 0.5), (13.0, 14.0, 0.3333), (13.0, 14.0, 0.6667)]
    assert (record["cells"], record["poses"], record["held_runs"]) == (N + 3, N + 3, [])
    cells = _cycle(rep)
    assert cells[6].tobytes() == walk_at(5.5).tobytes()
    assert cells[15].tobytes() == walk_at(13 + 1 / 3).tobytes()
    # Every other cell is the cut's as filmed: the first and the last, the length, the beat.
    filmed = shown_again(walk(), STALLED)[: N + 3]
    assert len(cells) == N + 3
    assert all(cells[k].tobytes() == filmed[k].tobytes() for k in range(N + 3) if k not in (6, 15, 16))
    assert _meta(rep)["held_fill"] == held_fill.public(record)
    assert rep["seam_measurement"] == "rendered-cells"


@pytest.mark.parametrize("given", ["the frame before", "the frame after"])
def test_an_interpolator_that_gives_the_pose_back_leaves_the_stalled_walk_as_filmed_and_says_so(given, tmp_path, capsys):
    # No frame between at all: each frame it gives is a pose beside it, a held cell itself. Tried again only on the
    # side away from that pose (later for the frame before, earlier for the frame after) within half a cell, never
    # taken: the cut is delivered as filmed, its record and its warnings say both runs are still held.
    calls: list[float] = []

    def stuck(a, b, t):
        calls.append(t)
        return a if given == "the frame before" else b

    rep = _run(tmp_path, shown_again(walk(), STALLED), interpolate=stuck, **STALLED_CUT)
    assert rep["status"] == "passed"
    record = rep["held_fill"]
    assert record["made"] == [] and "interpolator" not in record
    runs = record["before"]["held_runs"]
    assert [(r["start"], r["length"], r["filled"]) for r in runs] == [(5, 2, False), (14, 3, False)]
    assert all("held" in r["faults"] for r in runs)
    assert [[t["t"] for t in r["tries"][0]["tries"]] for r in runs] == (
        [[0.5, 0.55, 0.6, 0.65, 0.7], [0.3333, 0.35, 0.4, 0.45]] if given == "the frame before"
        else [[0.5, 0.45, 0.4, 0.35, 0.3], [0.3333, 0.3, 0.25, 0.2]])
    assert len(calls) == sum(len(r["tries"][0]["tries"]) for r in runs) == 9
    assert (record["cells"], record["poses"], record["held_runs"]) == (
        N + 3, N, [{"start": 5, "length": 2}, {"start": 14, "length": 3}])
    assert _pictures(Path(rep["out_dir"]), "m") == STALLED_OFF
    err = capsys.readouterr().err
    assert "held cells 5-6 kept as filmed" in err and "held cells 14-16 kept as filmed" in err


def test_fill_held_off_cuts_the_stalled_walk_as_before_and_still_names_its_runs(tmp_path):
    rep = _run(tmp_path, shown_again(walk(), STALLED), fill_held="off", **STALLED_CUT)
    assert _pictures(Path(rep["out_dir"]), "m") == STALLED_OFF
    record = rep["held_fill"]
    assert record["mode"] == "off" and record["made"] == []
    assert [(r["start"], r["length"], r["filled"], r["why"]) for r in record["before"]["held_runs"]] == [
        (5, 2, False, "--fill-held off"), (14, 3, False, "--fill-held off")]
    assert (record["cells"], record["poses"]) == (N + 3, N)


def test_no_rife_delivers_the_held_cells_as_filmed_and_says_which_motion(tmp_path, monkeypatch, capsys):
    _no_rife(monkeypatch, tmp_path)
    rep = _run(tmp_path, shown_again(walk(), STALLED), name="stalled-walk", **STALLED_CUT)
    assert rep["status"] == "passed"
    out = Path(rep["out_dir"])
    # The images are the cut as filmed: what --fill-held off delivers.
    off = _run(tmp_path, shown_again(walk(), STALLED), name="off", fill_held="off", **STALLED_CUT)
    assert {k: v for k, v in _bytes(out, "stalled-walk").items()} == _bytes(Path(off["out_dir"]), "off")
    record = rep["held_fill"]
    assert record["made"] == [] and record["unmade"]["cells"] == [6, 15, 16]
    assert record["unmade"]["install"] == loop_mod.rife_mod.install_command()
    assert (record["cells"], record["poses"]) == (N + 3, N)
    err = capsys.readouterr().err
    assert "stalled-walk" in err and "RIFE is not installed" in err and loop_mod.rife_mod.install_command() in err


def test_a_hold_longer_than_three_cells_is_the_motion_s_own_and_kept(tmp_path):
    between = Between(walk_at, range(N + 6), period=N)
    rep = _run(tmp_path, shown_again(walk(), {9: 5}), interpolate=between,
               **{**STALLED_CUT, "length": N + 4})
    run = rep["held_fill"]["before"]["held_runs"]
    assert [(r["start"], r["length"], r["filled"]) for r in run] == [(9, 5, False)]
    assert "longer than" in run[0]["why"]
    assert between.calls == [] and rep["held_fill"]["held_runs"] == [{"start": 9, "length": 5}]


@pytest.mark.slow
def test_a_walk_drawn_on_twos_is_limited_animation_and_kept(tmp_path):
    # Each drawing shown twice, as a clip of 12 drawings a second at 24 fps is (sprite_gen/video/held.py).
    twos = shown_again(walk(), {k: 2 for k in range(N + 6)})
    cut = {**STALLED_CUT, "length": 2 * N}
    between = Between(walk_at, range(N + 6), period=N)
    rep = _run(tmp_path, twos, interpolate=between, **cut)
    record = rep["held_fill"]
    assert rep["cycle_drawings"]["hold"] == 2 and record["drawn"] == 2
    assert between.calls == [] and record["made"] == []
    assert all(not r["filled"] and "drawn on twos" in r["why"] for r in record["before"]["held_runs"])
    assert (record["cells"], record["poses"]) == (2 * N, N)
    off = _run(tmp_path, twos, name="off", fill_held="off", **cut)
    assert _bytes(Path(rep["out_dir"]), "m") == _bytes(Path(off["out_dir"]), "off")


@pytest.mark.slow
def test_a_walk_carried_to_60_fps_by_repeating_frames_reads_a_hold_and_is_filled_to_a_pose_a_cell(tmp_path):
    # 24 fps carried to 60 by the frame under each time: each frame shown three and two times by turns. Its rhythm
    # reads a hold of 2, but its runs are not each two cells: the frames between are made.
    filmed = walk(2 * N + 2)
    carried = [filmed[k * 24 // 60] for k in range(len(filmed) * 60 // 24)]
    between = Between(walk_at, range(2 * N + 2), period=N)
    keyed = save(carried, tmp_path / "carried-keyed")
    rep = loop_mod.run_loop(keyed, tmp_path / "carried-out", fps=60.0, min_len=None, max_len=None, n_out=None,
                            seam_max=loop_mod.SEAM_RATIO_MAX, name="m", report_path=None, interpolate=between,
                            state="walk", anchor="none", repair="off")
    record = rep["held_fill"]
    assert rep["cycle_drawings"]["hold"] == 2 and "drawn" not in record
    assert {r["length"] for r in record["before"]["held_runs"]} == {2, 3}
    assert record["before"]["poses"] < record["before"]["cells"] == rep["cycle"]["length"] == 60
    assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])
    cells, start = _cycle(rep), rep["cycle"]["start"]
    assert cells[0].tobytes() == carried[start].tobytes() and cells[-1].tobytes() == carried[start + 59].tobytes()


def test_a_once_cut_and_a_one_shot_have_their_held_cells_made_too(tmp_path):
    frames = topple()
    stalled = shown_again(frames, {20: 2})
    times = {f.tobytes(): float(k) for k, f in enumerate(frames)}
    between = Between(lambda t: _topple_at(t), [])
    between.known.update(times)
    rep = _run(tmp_path, stalled, "fall", interpolate=between, state="death", cycle_mode="once")
    record = rep["held_fill"]
    start = rep["cycle"]["start"]
    assert [(r["start"], r["filled"]) for r in record["before"]["held_runs"] if r["filled"]] == [(20 - start, True)]
    # Half way, and a twentieth on, the body has sunk less than a pixel: each such frame shows frame 20 again and is
    # refused (`held`). A frame nearer frame 20 would show it too, so the cell is made again only later, at the nearest
    # fraction where the body has moved.
    assert between.calls == [(20.0, 21.0, t) for t in (0.5, 0.55, 0.6)]
    made = next(r for r in record["frames"] if r["cell"] == 21 - start)
    assert (made["t"], made["from_t"]) == (0.6, 0.5)
    assert [(t["faults"], t.get("shows")) for t in made["tries"]] == [(["held"], ["a"])] * 2 + [([], None)]
    assert all(r["start"] != 20 - start for r in record["held_runs"])  # read again, the cell made is a pose of its own
    hopped = shown_again(hop(), {18: 2})
    rep = _run(tmp_path, hopped, "hop", interpolate=lambda a, b, t: Image.blend(a, b, t), state="jump", cycle_mode="one-shot")
    assert any(r["start"] + rep["cycle"]["start"] == 18 for r in rep["held_fill"]["before"]["held_runs"])


def _topple_at(time: float) -> Image.Image:
    """`topple`'s body `time` frames in, between its frames as well."""
    t = min(1.0, max(0.0, (time - 6) / 30))
    a = np.zeros((96, 128, 4), dtype=np.uint8)
    height, width = round(64 - 40 * t), round(16 + 36 * t)
    a[86 - height:86, 40:40 + width] = (200, 80, 30, 255)
    return Image.fromarray(a, "RGBA")


# The fill on a cut's frames, as `video-loop` calls it: which runs it makes, which it keeps and why.


def _reach(time: float) -> Image.Image:
    return planter(4 * time)


def _planted(times: list[float]) -> list[Image.Image]:
    return [_reach(t) for t in times]


def test_a_part_standing_still_on_both_sides_stays_where_it_stood():
    frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])
    out, record = held_fill.fill(frames, Between(_reach, range(7)), ring=False)
    assert record["made"] == [4]
    assert out[4].tobytes() == _reach(3.5).tobytes()
    assert record["before"]["held_runs"][0]["filled"] is True
    assert record["contact"][0]["kept"] == 1.0


def test_a_frame_between_that_drags_a_planted_foot_is_not_taken():
    frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])
    out, record = held_fill.fill(frames, Between(_reach, range(7), after=slid), ring=False)
    assert record["made"] == []
    assert out[4].tobytes() == frames[4].tobytes()  # the held cell, as filmed
    run = record["before"]["held_runs"][0]
    assert run["filled"] is False and "contact" in run["faults"]
    assert record["held_runs"] == [{"start": 3, "length": 2}]


def test_a_frame_between_that_cross_fades_two_poses_is_not_taken():
    # Two poses laid over each other at half strength: the double exposure an interpolator gives where it cannot follow.
    frames = shown_again(walk(), STALLED)[: N + 3]
    out, record = held_fill.fill(frames, lambda a, b, t: Image.blend(a, b, t), ring=True)
    assert record["made"] == [] and [o.tobytes() for o in out] == [f.tobytes() for f in frames]
    assert all(not r["filled"] and "ghost" in r["faults"] for r in record["before"]["held_runs"])


@pytest.mark.parametrize("given", ["the frame before", "the frame after"])
def test_a_frame_between_that_shows_a_pose_beside_it_again_is_not_taken(given):
    frames = shown_again(walk(), STALLED)[: N + 3]
    calls: list[float] = []

    def back(a, b, t):
        calls.append(t)
        return a if given == "the frame before" else b

    out, record = held_fill.fill(frames, back, ring=True)
    assert record["made"] == [] and [o.tobytes() for o in out] == [f.tobytes() for f in frames]
    runs = record["before"]["held_runs"]
    assert all(not r["filled"] and r["faults"] == ["held"] for r in runs)
    # Each run's first cell tried at its own time, then at the other fractions within half a cell of it on the side
    # away from the pose it showed again: later for the frame before, earlier for the frame after.
    shown, later = ("a", True) if given == "the frame before" else ("b", False)
    for r in runs:
        tries = r["tries"][0]["tries"]
        assert len(tries) > 1 and all(t["faults"] == ["held"] and t["shows"] == [shown] for t in tries)
        assert [t["t"] for t in tries] == sorted((t["t"] for t in tries), reverse=not later)
    assert (record["poses"], record["held_runs"]) == (N, [{"start": 5, "length": 2}, {"start": 14, "length": 3}])


def _lit(blue: int) -> Image.Image:
    """`planter(10)` with its body `blue` in the blue channel: one pose, lit differently."""
    a = np.asarray(planter(10)).copy()
    a[30:110, 50:70] = (90, 90, blue, 255)
    return Image.fromarray(a, "RGBA")


def test_a_frame_between_that_shows_both_poses_beside_it_is_not_made_again():
    # The pose after the held one lit 40 levels brighter (over PIXEL_SAME): any frame between them shows one of the
    # two, and half way it shows both again. No fraction can show a picture of its own, so it is made once.
    a, b = _lit(200), _lit(240)
    frames = [planter(0), a, a, b, planter(20)]
    calls: list[float] = []
    out, record = held_fill.fill(frames, lambda x, y, t: calls.append(t) or Image.blend(x, y, t), ring=False)
    run = record["before"]["held_runs"][0]
    assert (run["start"], run["length"], run["filled"], run["faults"]) == (1, 2, False, ["held"])
    assert calls == [0.5]
    assert [{k: v for k, v in tried.items() if k != "judged"} for tried in run["tries"][0]["tries"]] == [{"t": 0.5, "faults": ["held"], "shows": ["a", "b"]}]
    assert record["made"] == [] and [o.tobytes() for o in out] == [f.tobytes() for f in frames]


def test_a_run_whose_frames_between_show_one_picture_twice_is_kept_as_filmed():
    # An interpolator that draws the time half way whatever it is asked: a run of two is made, a run of three would
    # show its one frame between on both its cells.
    frames = shown_again(walk(), STALLED)[: N + 3]
    between = Between(walk_at, range(N + 6), period=N)
    out, record = held_fill.fill(frames, lambda a, b, t: between(a, b, 0.5), ring=True)
    runs = record["before"]["held_runs"]
    assert [(r["start"], r["filled"]) for r in runs] == [(5, True), (14, False)]
    assert runs[1]["faults"] == ["held"] and [row["cell"] for row in runs[1]["tries"]] == [15, 16]
    # The second shows the first again, the cell before it: made again only later, within half a cell.
    assert [(t["t"], t["shows"]) for t in runs[1]["tries"][1]["tries"]] == [(t, ["before"]) for t in (0.6667, 0.7, 0.75, 0.8)]
    assert record["made"] == [6] and out[6].tobytes() == walk_at(5.5).tobytes()
    assert [o.tobytes() for o in out[14:17]] == [f.tobytes() for f in frames[14:17]]
    assert record["held_runs"] == [{"start": 14, "length": 3}]


def test_the_opening_and_the_closing_pose_of_a_cut_played_once_are_kept():
    frames = _planted([0, 0, 1, 2, 3, 4, 4])
    calls: list = []
    out, record = held_fill.fill(frames, lambda a, b, t: calls.append(t) or a, ring=False)
    whys = [r["why"] for r in record["before"]["held_runs"]]
    assert calls == [] and record["made"] == []
    assert "opening" in whys[0] and "closing" in whys[1]


def test_a_loop_s_held_cells_at_its_wrap_are_made_between_its_last_pose_and_its_first_cell():
    # A loop has no closing pose: its last cells' next pose is its first cell, across the wrap. Before, the run at the
    # end was kept as filmed and said nothing (`the loop's last cells`), a picture shown twice on every pass.
    frames = [walk_at(t) for t in [0, 0, *range(1, N - 2), N - 3]]
    between = Between(walk_at, range(N), period=N)
    out, record = held_fill.fill(frames, between, ring=True)
    runs = record["before"]["held_runs"]
    assert [(r["start"], r["filled"]) for r in runs] == [(0, True), (N - 2, True)]
    assert record["made"] == [1, N - 1] and "wrap" not in record["before"]
    # cell 1 half way from cell 0 to the pose after it; the last cell half way from the last pose to cell 0 a cycle on
    assert out[1].tobytes() == walk_at(0.5).tobytes() and out[N - 1].tobytes() == walk_at(N - 1.5).tobytes()
    assert out[0].tobytes() == frames[0].tobytes() and record["held_runs"] == [] and "wrap_held" not in record


def test_a_loop_whose_last_cell_shows_its_first_again_keeps_its_first_cell_and_makes_the_last():
    # The step across the wrap is read too: a last cell that shows the first cell's picture again (a cut one cell too
    # long) is made between the pose before it and the first cell; the first cell stays the first cell.
    frames = [walk_at(t) for t in [*range(N - 1), 0]]
    between = Between(walk_at, range(N), period=N)
    out, record = held_fill.fill(frames, between, ring=True)
    assert record["before"]["held_runs"] == [] and record["before"]["wrap_held"] is True
    assert record["before"]["poses"] == N - 1
    wrap = record["before"]["wrap"]
    assert (wrap["start"], wrap["length"], wrap["joined"], wrap["filled"]) == (N - 1, 1, 2, True)
    assert record["made"] == [N - 1] and out[N - 1].tobytes() == walk_at(N - 1).tobytes()
    assert out[0].tobytes() == frames[0].tobytes() and record["poses"] == N and "wrap_held" not in record
    assert held_fill.public(record)["before"]["wrap"]["made"] == [N - 1]


def test_a_hold_across_a_loop_s_wrap_longer_than_three_cells_is_kept_whole():
    # Two cells before the wrap and two after it show one picture: one hold of four, the motion's own, kept whole.
    frames = [walk_at(t) for t in [0, 0, *range(1, N - 3), 0, 0]]
    calls: list = []
    out, record = held_fill.fill(frames, lambda a, b, t: calls.append(t) or a, ring=True)
    runs = record["before"]["held_runs"]
    assert calls == [] and record["made"] == []
    assert [(r["start"], r["filled"]) for r in runs] == [(0, False), (N - 2, False)]
    assert all("across the loop's wrap" in r["why"] for r in runs) and runs[1]["wrap"] is True
    assert record["before"]["wrap"]["joined"] == 4 and record["wrap_held"] is True


def test_a_cut_read_again_that_plays_on_twos_keeps_its_held_pair():
    # The read after the repairs keeps a run where the cells as they now play read drawn on twos or threes (`hold`, the
    # reading the seam and the step gate take): a walk on twos redrawn a pixel aside each repeat reads a drawing a frame as
    # filmed, so the fill keeps nothing, and the anchor brings a pair back to one picture. Read as a drawing a frame, the
    # pair is made again. The hold is asked only where a run is read.
    _, record = held_fill.fill([walk_at(t) for t in range(N)], None, ring=True)
    assert record["before"]["held_runs"] == []
    unread = [walk_at(t) for t in range(N)]
    assert held_fill.again(unread, None, record, ring=True, hold=lambda cells: pytest.fail("asked")) == (unread, None)
    frames = [walk_at(9 if t == 10 else t) for t in range(N)]  # cell 10 shows cell 9's picture
    calls: list = []
    out, again = held_fill.again(frames, lambda a, b, t: calls.append(t) or a, record, ring=True, hold=lambda cells: 2)
    assert calls == [] and again["made"] == [] and again["drawn"] == 2
    assert [f.tobytes() for f in out] == [f.tobytes() for f in frames]
    assert [(h["from"], h["to"], h["kind"]) for h in held_fill.intended(again)] == [(9, 10, "drawn")]
    between = Between(walk_at, range(N), period=N)
    out, again = held_fill.again(frames, between, record, ring=True, hold=lambda cells: 1)
    assert again["made"] == [10] and "drawn" not in again and out[10].tobytes() == walk_at(10).tobytes()


def test_a_cut_played_once_does_not_read_a_wrap():
    frames = [walk_at(t) for t in [*range(N - 1), 0]]
    out, record = held_fill.fill(frames, lambda a, b, t: a, ring=False)
    assert "wrap" not in record["before"] and "wrap_held" not in record and record["made"] == []


def test_codec_copies_read_as_the_same_picture_and_the_slowest_motion_does_not():
    still = planter(10)
    noisy = np.asarray(still).astype(np.int16)
    noisy[..., :3] += np.random.default_rng(0).integers(-3, 4, size=noisy[..., :3].shape).astype(np.int16)
    noisy = Image.fromarray(np.clip(noisy, 0, 255).astype(np.uint8), "RGBA")
    assert held_fill.same_steps([still, noisy, planter(11)]) == [True, False]


def test_a_whole_figure_moving_under_a_thumbnail_pixel_is_not_the_same_picture():
    # A walker going away, a frame 280 px wide: its steps move a thousand of its pixels, and some move none of the
    # analysis thumbnail's. The frame as cut is read too: a cut of it shows no held cell.
    from tests.video.test_gait_fallback import walking_away

    frames = [walking_away(k) for k in range(73)][24:48]
    thumbs = held_fill._thumbs(frames)
    assert any(held_fill._same(a, b) for a, b in zip(thumbs, thumbs[1:]))
    assert held_fill.same_steps(frames) == [False] * 23


# A higher rate than the clip's: frames between, never frames shown again.


@pytest.mark.slow
def test_a_walk_asked_for_at_60_fps_is_made_of_frames_between(tmp_path):
    between = Between(walk_at, range(N + 6), period=N)
    rep = _run(tmp_path, walk(), "walk60", interpolate=between, out_fps=60.0,
               state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")
    meta = _meta(rep)
    record = rep["held_fill"]
    assert record["out_fps"]["applied"] is True and record["out_fps"]["cells"] == 60
    assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])
    assert meta["frames"] == 60 and meta["cycle_seconds"] == 1.0 and meta["delay_ms"] == pytest.approx(16.67)
    assert meta["out_fps"] == 60.0
    cells = _cycle(rep)
    assert len(cells) == 60
    assert cells[0].tobytes() == walk_at(0).tobytes() and cells[5].tobytes() == walk_at(2).tobytes()
    assert cells[1].tobytes() == walk_at(0.4).tobytes()
    assert len({c.tobytes() for c in cells}) == 60


@pytest.mark.slow
def test_a_cut_at_a_rate_of_its_own_records_each_cell_as_the_frame_it_is_and_a_cell_made_between_as_not_filmed(tmp_path):
    # The strip's record of its cells (`cell_record`, video-sway --read-on-cut) of a walk that shows frame 9 twice, its
    # held cells kept, at --out-fps 49: a cell that is a frame (on its time, a hair before it, or between the two frames
    # of one picture, that picture again; `out_fps.source_frames`) is that frame as filmed; one made between two frames reads
    # as the frame before its time, is not as filmed but where its pixels are that frame's, and --read-on-cut does not
    # pair it.
    clip, between = shown_again(walk(), {9: 2}), Between(walk_at, range(N + 6), period=N)
    cut = dict(state="walk", cycle_mode="fixed", length=N, anchor="none", repair="off", fill_held="off")
    rep = _run(tmp_path, clip, "walk49", interpolate=between, out_fps=49.0, start=0, **cut)
    record = rep["held_fill"]["out_fps"]
    assert record["applied"] is True and record["cells"] == 49 and record["shown_again"] == []
    own = _meta(rep)
    cells = sway.cell_record(own, _sha(Path(rep["strip"]["path"])))
    shown = _cycle(rep)
    kinds = []
    for c, (cell, times, source) in enumerate(zip(cells, record["times"], record["source_frames"])):
        assert cell["anchor_move_px"] == [0, 0] and cell["scale"] == {"size_hold": 1.0, "gait_fallback": 1.0}
        frame = clip[cell["source_frame"]].tobytes()
        if source is not None:
            assert cell["source_frame"] == source and cell["as_filmed"] is True and shown[c].tobytes() == frame
            kinds.append("on" if abs(times - round(times)) <= held_fill.SNAP else "again")
        else:
            # the stand-in draws the walk again at the cell's time: now and then that is a frame's own picture
            assert cell["source_frame"] == math.floor(times) and cell["as_filmed"] is (shown[c].tobytes() == frame)
            kinds.append("made")
    # frame 1 a hair before its time (0.98), frame 9 again between its two cells (9.31, 9.80), the rest made
    assert record["times"][2] == 0.9796 and cells[2]["source_frame"] == 1 and kinds[2] == "on"
    assert [cells[c]["source_frame"] for c in (19, 20)] == [9, 9] and kinds[19:21] == ["again", "again"]
    assert [c for c, kind in enumerate(kinds) if kind != "made"] == [0, 2, 19, 20, 47] and kinds.count("made") == 44
    assert sum(not cells[c]["as_filmed"] for c, kind in enumerate(kinds) if kind == "made") >= 40
    # Read on a cut of the same clip from frame 3 (24 fps): this cut's first cell of frame 3 is made between 3 and 4.
    read = _run(tmp_path, clip, "from3", start=3, **cut)
    first = [c["source_frame"] for c in cells].index(3)
    assert cells[first]["as_filmed"] is False and kinds[first] == "made"
    with pytest.raises(SystemExit, match=rf"cell {first} is not that frame as filmed: video-loop did not cut it as filmed "
                                         rf"\(cell_record\.cells\[{first}\]\.as_filmed\)"):
        sway.recut_pair(own, _meta(read), _sha(Path(read["strip"]["path"])), strip_sha256=_sha(Path(rep["strip"]["path"])))


@pytest.mark.slow
def test_a_one_shot_asked_for_at_60_fps_keeps_its_first_and_last_frame(tmp_path):
    frames = hop()
    times = {f.tobytes(): float(k) for k, f in enumerate(frames)}
    made: list = []

    def between(a, b, t):
        made.append((times[a.tobytes()], times[b.tobytes()], round(t, 4)))
        return Image.blend(a, b, t)

    rep = _run(tmp_path, frames, "hop60", interpolate=between, out_fps=60.0, state="jump", cycle_mode="one-shot")
    L = rep["cycle"]["length"]
    record = rep["held_fill"]
    cells = _cycle(rep)
    assert len(cells) == round((L - 1) * 2.5) + 1 == record["cells"]
    filmed = hop()[rep["cycle"]["start"]: rep["cycle"]["start"] + L]
    assert cells[0].tobytes() == filmed[0].tobytes() and cells[-1].tobytes() == filmed[-1].tobytes()
    assert record["out_fps"]["applied"] is True


def test_a_cell_at_a_higher_rate_whose_frame_between_shows_a_frame_again_is_named_shown_again():
    # Five frames at 24 fps given at 60: eleven cells, three on a frame's time. An interpolator that gives back the frame
    # before makes none of the eight between: each is the nearer frame, named.
    frames = walk()[:5]
    out, record = held_fill.upsample(frames, lambda a, b, t: a, ring=False, fps=24.0, out_fps=60.0)
    assert record["made"] == 0 and record["shown_again"] == [1, 2, 3, 4, 6, 7, 8, 9]
    assert all(t["faults"] == ["held"] for m in record["frames"] for t in m["tries"])
    # Each tried again only later than its own time: a frame nearer the one it showed would show it too.
    assert all(t["t"] >= m["t"] for m in record["frames"] for t in m["tries"])
    assert [o.tobytes() for o in out] == [frames[round(k * 0.4)].tobytes() for k in range(11)]


def test_two_cells_at_a_higher_rate_between_one_pair_are_not_one_picture():
    # Given at 60, the cells at 0.4 and 0.8 of a step both lie between its two frames. An interpolator that draws the
    # time half way whatever it is asked makes the first; the second would show it again, and is the nearer frame.
    frames = walk()[:5]
    between = Between(walk_at, range(5))
    out, record = held_fill.upsample(frames, lambda a, b, t: between(a, b, 0.5), ring=False, fps=24.0, out_fps=60.0)
    assert record["shown_again"] == [2, 4, 7, 9] and record["made"] == 4
    # The second shows the first again, the cell before it: made again only later, at 0.85, the last fraction there.
    assert [[t["t"] for t in m["tries"]] for m in record["frames"] if m["cell"] == 2] == [[0.8, 0.85]]
    assert out[1].tobytes() == walk_at(0.5).tobytes() and out[2].tobytes() == frames[1].tobytes()
    assert out[3].tobytes() == walk_at(1.5).tobytes() and out[4].tobytes() == frames[2].tobytes()


def test_no_rife_delivers_a_clip_asked_for_at_a_higher_rate_at_its_own(tmp_path, monkeypatch, capsys):
    _no_rife(monkeypatch, tmp_path)
    rep = _run(tmp_path, walk(), "walk60", out_fps=60.0, state="walk", cycle_mode="fixed", start=0, length=N,
               anchor="none", repair="off")
    assert rep["status"] == "passed" and _meta(rep)["frames"] == N and "out_fps" not in _meta(rep)
    assert rep["held_fill"]["out_fps"]["applied"] is False
    err = capsys.readouterr().err
    assert "walk60" in err and "--out-fps 60" in err and loop_mod.rife_mod.install_command() in err


def test_a_rate_under_the_clip_s_own_is_refused(tmp_path):
    with pytest.raises(SystemExit, match="--out-fps 12"):
        _run(tmp_path, walk(), out_fps=12.0, state="walk", cycle_mode="fixed", start=0, length=N, anchor="none")


def test_video_loop_and_video_set_take_the_switches():
    import argparse

    from sprite_gen.video import batch

    parser = argparse.ArgumentParser()
    loop_mod.add_arguments(parser)
    args = parser.parse_args(["--frames-dir", "f", "--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])
    assert (args.fill_held, args.out_fps) == ("off", 60.0)
    assert parser.parse_args(["--frames-dir", "f", "--out-dir", "o"]).fill_held == "auto"
    parser = argparse.ArgumentParser()
    batch.add_arguments(parser)
    args = parser.parse_args(["--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])
    assert (args.fill_held, args.out_fps) == ("off", 60.0)
    assert parser.parse_args(["--out-dir", "o"]).fill_held == "auto"


def test_video_set_hands_the_switches_to_each_cut(monkeypatch, tmp_path):
    from sprite_gen.video import batch

    seen: list[dict] = []
    monkeypatch.setattr(batch.frames_mod, "run_frames", lambda clip, out, **kw: {
        "fps": 24, "frames": 10, "alpha_zero_pct_min": 50, "alpha_zero_pct_max": 60, "keyed_dir": str(out)})

    def run_loop(*a, **kw):
        seen.append(kw)
        return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,
                "gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"},
                "held_fill": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2}], "made": [],
                              "before": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2, "filled": False,
                                                                                  "why": "--fill-held off"}]}}}

    def video(image, prompt, out, report, **kw):
        out.write_bytes(b"test-video")
        report.write_text(json.dumps({"prompt": prompt}))
        return 0

    monkeypatch.setattr(batch.loop_mod, "run_loop", run_loop)
    monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)
    still = tmp_path / "front.png"
    Image.new("RGBA", (64, 64), (200, 80, 30, 255)).save(still)
    result = batch.run_set(bases={"front": still}, states=["idle"], root=tmp_path / "set", character=None, duration=3,
                           resolution="720p", key="green", concurrency=1, force=False, gap=0, video_runner=video,
                           align_cycles="off", fill_held="off", out_fps=60.0)
    assert [(kw["fill_held"], kw["out_fps"]) for kw in seen] == [("off", 60.0)]
    # The set's report says each motion's poses over its cells.
    assert result["items"][0]["loop"]["poses"] == "9/10"


def test_a_cut_with_cells_made_is_not_restored_from_its_source_frames(tmp_path):
    """The source frames do not hold a cell made between two of them: restoration (`video-loop-repair`) reads the cut
    as one it cannot project (`source-processing-unsupported`), as it reads a blended wrap."""
    import shutil
    import subprocess

    from sprite_gen.video import source
    from sprite_gen.video.compare import Loop

    if not shutil.which("ffmpeg") or not loop_mod.img2webp_supports_exact():
        pytest.skip("ffmpeg and img2webp >=1.5 required")
    filmed = shown_again(walk(), STALLED)
    keyed = save(filmed, tmp_path / "keyed")
    out = tmp_path / "cut"
    loop_mod.run_loop(keyed, out, fps=24.0, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX,
                      name="walk", report_path=None, interpolate=Between(walk_at, range(N + 6), period=N), **STALLED_CUT)
    files = sorted(keyed.glob("*.png"))
    frames_report = tmp_path / "frames.json"
    frames_report.write_text(json.dumps({"kind": "sprite-gen-video-frames-report", "fps": 24.0, "frames": len(files),
                                         "width": filmed[0].width, "height": filmed[0].height, "stream_index": 0,
                                         "key": "green"}))
    clip = tmp_path / "clip.mp4"
    subprocess.run(["ffmpeg", "-v", "error", "-framerate", "24", "-i", str(keyed / "%04d.png"), "-c:v", "libx264",
                    "-pix_fmt", "yuv420p", str(clip)], check=True)
    manifest = tmp_path / "source.json"
    manifest.write_text(json.dumps(source.manifest(clip=clip, canvas=files[0], frames_report=frames_report, files=files,
                                                   timestamps=source.timestamps(clip, 0))))
    loop = Loop.read(out / "walk.strip.png", out / "walk.strip.json", out / "walk.loop.report.json")
    projection, issue = source.project(loop, source.Source.read(
        source_manifest=manifest, source_frames_dir=keyed, source_clip=clip, source_canvas=files[0],
        source_frames_report=frames_report))
    assert (projection, issue) == (None, "source-processing-unsupported")


@pytest.mark.slow
def test_the_alignment_and_a_stop_refuse_a_loop_cut_at_a_rate_of_its_own(tmp_path):
    from sprite_gen.video import align, stop

    rep = _run(tmp_path, walk(), "walk60", interpolate=Between(walk_at, range(N + 6), period=N), out_fps=60.0,
               state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")
    out = Path(rep["out_dir"])
    with pytest.raises(ValueError, match="--out-fps 60"):
        align._loop_files(out)
    with pytest.raises(SystemExit, match="--out-fps 60"):
        stop.read_loop(out / "walk60.strip.json")


def test_the_curation_view_marks_the_cells_made_and_the_cells_still_held(tmp_path):
    """A loop's `cycle/` imported into the curation view (`unpack-atlas --pngs-dir`): each card of a cell the fill made
    says `made`, of a cell still showing the picture before it `held`."""
    from sprite_gen import cli

    rep = _run(tmp_path, shown_again(walk(), {**STALLED, 20: 5}), interpolate=Between(walk_at, range(N + 6), period=N),
               **{**STALLED_CUT, "length": N + 7})
    assert rep["held_fill"]["made"] == [6, 15, 16]
    assert cli.main(["unpack-atlas", "--pngs-dir", str(Path(rep["out_dir"]) / "cycle"), "--out-dir", str(tmp_path / "run")]) == 0
    rows = json.loads((tmp_path / "run" / "frames" / "frames-manifest.json").read_text())["rows"]
    labels = rows[0]["labels"]
    assert [k for k, label in enumerate(labels) if label.endswith(" (made)")] == [6, 15, 16]
    assert [k for k, label in enumerate(labels) if label.endswith(" (held)")] == [24, 25, 26, 27]
    assert labels[0] == "frame-000"