Skip to content

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

33.5 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""One cycle length per set (docs/loop-repair.md section 4): every loop resampled to the median
length at times k·L/L*, a time on a source frame keeping that frame as filmed and only the times
between frames made by the interpolator; each loop turned to start where the body is lowest; the
cut as filmed kept in `cycle.source/`, so a second alignment reads the source, not its own output.

The interpolator is a stand-in that records what it was asked for and cross-fades. A cross-fade
is two half-covered ghosts with no outline, which `--between auto` (the default) judges melted and
replaces, so a test of the resampling itself asks for `rife`, which keeps every made frame."""

from __future__ import annotations

import json
import math
import os
import re
from pathlib import Path

import numpy as np
import pytest
from PIL import Image, ImageDraw

from sprite_gen.video import align, legs, local_cycle
from sprite_gen.video import loop as loop_mod
from tests.video import test_walk_steps as walks

W, H = 100, 120


def _walker(phase: float) -> Image.Image:
    """A body that bobs with the phase (lowest at phase 0) and a foot going round."""
    a = np.zeros((H, W, 4), dtype=np.uint8)
    bob = round(4 * (1 + math.cos(2 * phase)) / 2)  # two lows a cycle, as a walk has
    a[20 + bob:90, 40:60] = (90, 90, 200, 255)
    fx, fy = 50 + round(20 * math.cos(phase)), 104 + round(8 * math.sin(phase))
    a[fy - 5:fy + 5, fx - 5:fx + 5] = (60, 60, 60, 255)
    return Image.fromarray(a, "RGBA")


class Recorder:
    def __init__(self):
        self.calls: list[float] = []

    def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:
        self.calls.append(round(t, 4))
        return Image.blend(a, b, t)  # a frame of its own, never a copy of a neighbour


def test_resample_keeps_every_frame_that_lands_on_a_source_frame():
    frames = [_walker(2 * math.pi * k / 6) for k in range(6)]
    rec = Recorder()
    out, facts = align.resample(frames, 12, rec, between="rife")
    assert {k: v for k, v in facts.items() if k not in ("smear", "ghost_screen", "beat")} == {
        "from": 6, "to": 12, "between": "rife", "taken": 6, "made_by_rife": 6, "made_at": [1, 3, 5, 7, 9, 11], "ghost_at": []}
    assert facts["beat"]["path"] == "on-time" and facts["beat"]["jolt"] == 0.0  # every frame at its own time
    assert [m["at"] for m in facts["smear"]] == [1, 3, 5, 7, 9, 11]
    assert all(out[2 * k] is frames[k] for k in range(6)) and rec.calls == [0.5] * 6
    same, facts = align.resample(frames, 6, None)  # already that long: untouched, nothing made
    assert facts["made_by_rife"] == 0 and all(a is b for a, b in zip(same, frames))
    with pytest.raises(ValueError, match="no interpolator"):
        align.resample(frames, 9, None)


def test_between_nearest_takes_the_nearer_source_frame_and_makes_none():
    frames = [_walker(2 * math.pi * k / 8) for k in range(8)]
    out, facts = align.resample(frames, 6, None, between="nearest")  # times 0, 1.33, 2.67, 4, 5.33, 6.67
    assert [frames.index(f) for f in out] == [0, 1, 3, 4, 5, 7]
    assert facts["made_by_rife"] == 0 and facts["nearest_at"] == [1, 2, 4, 5] and "smear" not in facts


def _old_top_line_start(frames: list[Image.Image]) -> int:
    """The 2.24 turn: the frame whose alpha box top is lowest (1-2-1) — what a long ear owns."""
    tops = [f.getchannel("A").point(lambda v: 255 if v >= 128 else 0).getbbox()[1] for f in frames]
    n = len(tops)
    return max(range(n), key=lambda k: tops[(k - 1) % n] + 2 * tops[k] + tops[(k + 1) % n])


def _figure(phase: float, *, view: str, legs: bool = True, bob_px: int = 2, shaded: bool = True, far_darker: int = 60) -> Image.Image:
    """A drawn walker at `phase` (radians): its own right heel lands at 0, its left at pi. The body
    bobs lowest (by `bob_px`) a sixth of a step after a heel lands; two thin ears on top flop on their
    own rhythm, lowest half a step after it, and further than the body bobs.

    `side`: faces right, its feet swing apart along the ground; the right leg is the near one, drawn
    light over the far left leg, which is shaded (`shaded`) `far_darker` levels darker. `front`: the
    feet stay side by side, its right foot on the picture's left, and the foot stepping toward the viewer is drawn lower. With no
    legs the body sits on the ground and squats as it bobs."""
    a = np.zeros((H, W, 4), dtype=np.uint8)
    bob = round(bob_px * (1 + math.cos(2 * phase - math.pi / 3)) / 2)
    flop = round(7 * (1 + math.cos(2 * phase - math.pi)) / 2)
    top = 30 + bob
    a[top:top + 58 if legs else 100, 36:64] = (230, 230, 230, 255)  # head and body; with no legs it squats on the ground
    for x in (40, 56):
        a[top - 26 + flop:top, x:x + 4] = (240, 180, 190, 255)  # an ear: a narrow run
    if legs:
        if view == "side":
            shade = far_darker if shaded else 0
            for sign, leg, foot in ((-1, 210 - shade, 110 - shade), (1, 210, 110)):  # far left leg first, near right leg over it
                fx = 50 + round(sign * 18 * math.cos(phase))
                a[top + 58:106, fx - 3:fx + 3] = (leg, leg, leg, 255)
                a[100:106, fx - 7:fx + 7] = (foot, foot, foot, 255)
        else:
            for x, sign in ((38, 1), (52, -1)):  # its right foot, then its left
                fy = 105 + round(sign * 3 * math.cos(phase))
                a[top + 58:fy, x + 2:x + 8] = (200, 200, 200, 255)
                a[fy - 10:fy, x:x + 10] = (60, 60, 60, 255)
    return Image.fromarray(a, "RGBA")


def _cycle(**kw) -> list[Image.Image]:
    return [_figure(2 * math.pi * k / 12, **kw) for k in range(12)]


def _mirror(frames: list[Image.Image]) -> list[Image.Image]:
    return [f.transpose(Image.Transpose.FLIP_LEFT_RIGHT) for f in frames]


@pytest.mark.parametrize("view, by", [("side", "stride"), ("front", "reach")])
@pytest.mark.parametrize("bob_px", [2, 0])
def test_the_loop_starts_as_a_heel_lands_not_where_the_ears_are_lowest(view, by, bob_px):
    """With the body bobbing or not at all, the start is read off the legs; the 2.24 rule read the
    top edge, which the ears own."""
    frames = _cycle(view=view, bob_px=bob_px)
    turned = frames[5:] + frames[:5]
    strike = align.foot_strike(turned)
    assert strike["by"] == by
    assert any(turned[strike["start"]] is frames[k] for k in (0, 6))  # a heel lands at phase 0 and pi
    assert any(turned[_old_top_line_start(turned)] is frames[k] for k in (3, 9))  # the ears' low


def test_a_body_with_no_legs_starts_where_its_top_line_is_lowest_past_the_ears():
    frames = _cycle(view="front", legs=False)
    strike = align.foot_strike(frames)
    assert strike["by"] == "body_low" and strike["start"] in (1, 7)  # the body's own low, a sixth of a step on
    assert _old_top_line_start(frames) in (3, 9)  # the ears' low


@pytest.mark.parametrize("view, figure", [("side@right", "side"), ("front", "front"), ("back", "front")])
def test_every_view_starts_as_the_same_own_foot_lands(view, figure):
    """Its right heel lands at frame 0 and its left at 6. Mirrored, the picture is the same walk on
    the other own feet: a side view faces left (its near leg, the light one, is its left), a front
    view puts its right foot on the picture's right, and a back view seen this way round has its
    right foot stepping away where the front view's left steps near."""
    frames = _cycle(view=figure)
    mirrored = _mirror(frames)
    flipped = view.replace("@right", "@left")
    for walk, seen, right_at in ((frames, view, 0), (mirrored, flipped, 6)):
        turned = walk[5:] + walk[:5]
        strike = align.foot_strike(turned, view=seen)
        assert strike["start_foot"] == "right", strike
        assert turned[strike["start"]] is walk[right_at], (seen, strike)
        assert turned[align.foot_strike(turned, view=seen, foot="left")["start"]] is walk[(right_at + 6) % 12]


def test_a_foot_the_view_cannot_tell_is_not_named():
    turned = (lambda f: f[5:] + f[:5])(_cycle(view="side", shaded=False))
    strike = align.foot_strike(turned, view="side@right")
    assert strike["start_foot"] is None and "shade does not follow the step" in strike["foot_why"]
    assert any(turned[strike["start"]] is f for f in (turned[7], turned[1]))  # still on a strike
    unseen = align.foot_strike(turned)
    assert unseen["start_foot"] is None and unseen["foot_why"] == "no view given for this loop"


def _chibi(phase: float, *, view: str, step: float = 22, lift: int = 8, persp: int = 6, apart: int = 14) -> Image.Image:
    """An earless walker with short legs under a big head, at `phase` (radians): its own right heel
    lands at 0, its left at pi. Each leg swings `step` degrees either way about the hip; the stance
    leg stays planted, so the hip rides lowest as a heel lands, and the foot behind lifts by `lift`
    px mid-step. `front`: the feet `apart` px either side of the middle, its right foot on the
    picture's left, the foot stepping toward the viewer drawn up to `persp` px lower. `side`: faces
    right, its near right leg drawn light and `persp` px lower over the shaded far left leg."""
    img = Image.new("RGBA", (300, 360))
    draw = ImageDraw.Draw(img)
    ground, leg, head, a = 340, 42, 50, math.radians(step)
    swing = {"right": a * math.cos(phase), "left": -a * math.cos(phase)}
    stance = "right" if phase % (2 * math.pi) < math.pi else "left"
    hip, mid = ground - leg * math.cos(swing[stance]), 150
    for own in ("left", "right") if view == "side" else ("right", "left"):
        lifted = lift * abs(math.sin(phase)) if own != stance else 0
        if view == "side":
            fx, fy, tone = mid + leg * math.sin(swing[own]), ground - lifted - (persp if own == "left" else 0), 210 if own == "right" else 140
        else:
            fx, fy, tone = mid - apart if own == "right" else mid + apart, ground - lifted + persp * (math.sin(swing[own]) / math.sin(a) - 1), 200
        draw.line([(mid if view == "side" else fx, hip), (fx, fy - 6)], fill=(tone, tone, tone, 255), width=7)
        draw.rectangle([fx - 9, fy - 8, fx + 9, fy], fill=(tone - 60, tone - 60, tone - 60, 255))
    torso = int(leg * 0.9)
    draw.rectangle([mid - 22, hip - torso, mid + 22, hip], fill=(230, 200, 180, 255))
    draw.ellipse([mid - head, hip - torso - 2 * head, mid + head, hip - torso], fill=(240, 210, 190, 255))
    return img


@pytest.mark.parametrize("view, figure, kw, by", [
    ("front", "front", {"lift": 8, "persp": 6}, "reach"),  # its feet lift out of the foot band: the band swings like a side stride
    ("front", "front", {"lift": 12, "persp": 6}, "reach"),
    ("front", "front", {"lift": 4, "persp": 10}, "reach"),
    ("front", "front", {"lift": 20, "persp": 0, "apart": 16}, "body_low"),  # no foot drawn nearer: the band's swing is a lift, not a strike
    ("side@right", "side", {"step": 10, "persp": 6}, "stride"),  # a short step under STRIDE_MIN still opens the feet as a heel lands
    ("side@right", "side", {"step": 14, "persp": 3, "lift": 12}, "stride"),
])
def test_the_view_picks_the_signal_so_a_short_legged_walk_starts_on_a_strike(view, figure, kw, by):
    """A short-legged walk's swings mislead the thresholds: from the front its stride swings past
    STRIDE_MIN as the foot behind lifts out of the band, and from the side a short step swings under
    it. The view says which signal the step is on; the start is on a strike (or one frame after it,
    the heel just landed), and a foot it names is the one landing there."""
    frames = [_chibi(2 * math.pi * k / 12, view=figure, **kw) for k in range(12)]
    turned = frames[5:] + frames[:5]  # its right heel lands at turned[7], its left at turned[1]
    strike = align.foot_strike(turned, view=view)
    assert strike["by"] == by, strike
    landed = {"right": 7, "left": 1}
    near = min(landed, key=lambda f: min((strike["start"] - landed[f]) % 12, (landed[f] - strike["start"]) % 12))
    assert (strike["start"] - landed[near]) % 12 in (0, 1), strike
    assert strike["start_foot"] in (None, near), strike
    if by == "body_low":
        assert strike["foot_why"].startswith("no legs to read"), strike


def _cut(tmp_path: Path, name: str, length: int, cycles: int = 1, report: bool = False) -> Path:
    keyed = tmp_path / f"{name}-keyed"
    keyed.mkdir()
    for k in range(length + 6):
        _walker(2 * math.pi * cycles * k / length).save(keyed / f"{k:04d}.png")
    out = tmp_path / name
    loop_mod.run_loop(keyed, out, fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=1000.0,
                      name="walk", report_path=out / "walk.loop.report.json" if report else None, cycle_mode="fixed",
                      start=0, length=length, anchor="none", repair="off")
    return out


@pytest.mark.slow
def test_a_set_is_aligned_to_its_median_length_and_a_second_run_reads_the_source(tmp_path):
    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24), ("N", 28))]
    rec = Recorder()
    report = align.align_set(dirs, interpolate=rec, report_path=tmp_path / "align.json", between="rife")
    assert report["length"] == 24 and report["lengths"] == [20, 24, 28] and report["length_rule"] == "median"
    by = {Path(r["dir"]).name: r for r in report["loops"]}
    assert by["E"]["made_by_rife"] == 0 and by["E"]["taken"] == 24
    assert by["S"]["made_by_rife"] > 0 and by["N"]["made_by_rife"] > 0
    assert report["made_by_rife"] == len(rec.calls) == by["S"]["made_by_rife"] + by["N"]["made_by_rife"]
    for d in dirs:
        meta = json.loads((d / "walk.strip.json").read_text())
        assert meta["frames"] == 24 and meta["cycle_frames"] == 24 and meta["cycle_align"]["to"] == 24
        assert meta["cycle_seconds"] == pytest.approx(1.0)
        assert len(list((d / "cycle").glob("frame-*.png"))) == 24
        assert Image.open(d / "walk.gif").n_frames == 24
        assert (d / align.SOURCE_DIR).is_dir()
        lowest = align.foot_strike_start([Image.open(p).convert("RGBA") for p in sorted((d / "cycle").glob("frame-*.png"))])
        assert lowest == 0
    assert len(list((dirs[0] / align.SOURCE_DIR).glob("frame-*.png"))) == 20
    first = (dirs[0] / "walk.strip.png").read_bytes()
    again = align.align_set(dirs, interpolate=Recorder(), between="rife")
    assert again["lengths"] == [20, 24, 28]  # read from cycle.source, not the aligned cycle
    assert (dirs[0] / "walk.strip.png").read_bytes() == first
    assert json.loads((tmp_path / "align.json").read_text())["kind"] == "sprite-gen-video-cycle-align-report"


@pytest.mark.slow
def test_each_loop_records_its_view_and_start_foot_and_a_view_per_loop_is_required(tmp_path):
    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
    with pytest.raises(SystemExit, match="1 --view for 2 --loop-dir"):
        align.align_set(dirs, interpolate=Recorder(), views=["front"])
    with pytest.raises(SystemExit, match="facing right|left"):
        align.align_set(dirs, interpolate=Recorder(), views=["front", "side"])
    report = align.align_set(dirs, interpolate=Recorder(), views=["front", "side@right"])
    assert report["start_foot"] == "right" and [r["view"] for r in report["loops"]] == ["front", "side@right"]
    for r in report["loops"]:
        assert r["start_foot"] in ("right", None) and (r["start_foot"] or r["foot_why"])
    unseen = align.align_set(dirs, interpolate=Recorder())
    assert any("no view given" in w for w in unseen["warnings"])


def test_loops_at_different_frame_rates_are_refused(tmp_path):
    a, b = _cut(tmp_path, "A", 20), _cut(tmp_path, "B", 24)
    meta = json.loads((b / "walk.strip.json").read_text())
    meta["cycle_seconds"] = 24 / 30
    (b / "walk.strip.json").write_text(json.dumps(meta))
    with pytest.raises(SystemExit, match="different frame rates"):
        align.align_set([a, b], interpolate=Recorder())


def test_a_loop_cut_before_the_cell_cap_was_recorded_is_refused_by_name(tmp_path):
    d = _cut(tmp_path, "A", 20)
    meta = json.loads((d / "walk.strip.json").read_text())
    del meta["cell_height_cap"]
    (d / "walk.strip.json").write_text(json.dumps(meta))
    with pytest.raises(SystemExit, match="cell_height_cap"):
        align.align_set([d], interpolate=Recorder())


def _files(d: Path) -> dict[str, bytes | None]:
    """Every path under a loop directory, a file by its bytes and a directory as None."""
    return {p.relative_to(d).as_posix(): p.read_bytes() if p.is_file() else None for p in sorted(d.rglob("*"))}


def test_a_loop_whose_strip_as_cut_is_missing_is_refused_by_name_and_the_set_left_as_it_was(tmp_path):
    """A first alignment reads the strip as cut (`cycle_align.origin`): a loop directory without it is refused, its strip
    named, before any loop of the set is touched — no traceback, no `cycle.source/` left behind in it or the loop before it."""
    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
    (dirs[1] / "walk.strip.png").unlink()
    before = [_files(d) for d in dirs]
    with pytest.raises(SystemExit, match=rf"^video-cycle-align: {re.escape(str(dirs[1].resolve()))}: no walk\.strip\.png — .*cycle_align\.origin"):
        align.main([*(a for d in dirs for a in ("--loop-dir", str(d))), "--report", str(tmp_path / "align.json")])
    assert [_files(d) for d in dirs] == before
    assert not (tmp_path / "align.json").exists()


@pytest.mark.slow
def test_a_loop_aligned_before_is_aligned_again_without_its_strip(tmp_path):
    """Only a first alignment reads the strip as cut; a later one keeps the origin the first recorded."""
    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
    align.align_set(dirs, interpolate=Recorder())
    origin = json.loads((dirs[0] / "walk.strip.json").read_text())["cycle_align"]["origin"]
    (dirs[0] / "walk.strip.png").unlink()
    assert align.align_set(dirs, interpolate=Recorder(), length=22)["length"] == 22
    meta = json.loads((dirs[0] / "walk.strip.json").read_text())
    assert meta["cycle_align"]["origin"] == origin and (dirs[0] / "walk.strip.png").is_file()


@pytest.mark.slow
def test_video_set_aligns_each_gait_filmed_in_two_or_more_directions(tmp_path):
    from sprite_gen.video import batch

    rows = []
    for direction, length in (("front", 20), ("side", 24), ("back", 28)):
        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}})
    lone = tmp_path / "side-run"
    lone.mkdir()
    _cut(lone, "loop", 18)
    rows.append({"item": "side-run", "direction": "side", "state": "run", "dir": str(lone), "ok": True, "loop": {"n_out": 18}})
    out = batch.align_gaits(rows, tmp_path, "auto", interpolate=Recorder())
    assert set(out) == {"walk"}  # a run in one direction has nothing to match
    assert out["walk"]["ok"] and out["walk"]["length"] == 24 and out["walk"]["lengths"] == [20, 24, 28]
    assert [r["loop"]["n_out"] for r in rows[:3]] == [24, 24, 24] and rows[3]["loop"]["n_out"] == 18
    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") == {}


@pytest.mark.slow
@pytest.mark.parametrize("named, reasons", [
    ({"retake": {"reason": "start-stop", "reasons": ["start-stop"], "remedy": "retake"}}, ["start-stop"]),
    ({"cycle-unwitnessed": True}, ["cycle-unwitnessed"]),
    ({"retake": {"reason": "start-stop", "reasons": ["start-stop"], "remedy": "retake"}, "cycle-unwitnessed": True},
     ["start-stop", "cycle-unwitnessed"]),
])
def test_video_set_leaves_a_take_to_film_again_or_an_unwitnessed_count_out_of_the_alignment(tmp_path, capsys, named, reasons):
    """A loop named a take to film again because the walk starts or stops in it (`retake` `start-stop`) loops no two
    steps; a loop whose cut nothing witnesses whole cycles (`cycle-unwitnessed`, `local_cycle.unwitnessed`: its
    crossings left on steps, or its cut held by the cut witness) may hold half a cycle or two, and aligned as one it
    would play at twice its speed or half. Either is left out, its loop as cut, its reasons named in words true of
    half a cycle and of two, and the rest are aligned without it. Left alone, the state is not aligned."""
    from sprite_gen.video import batch

    rows = []
    for direction, length, extra in (("front", 20, {}), ("side", 24, {}), ("back", 19, named)):
        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, **extra}})
    out = batch.align_gaits(rows, tmp_path, "auto", interpolate=Recorder())
    assert out["walk"]["applied"] and out["walk"]["lengths"] == [20, 24] and out["walk"]["left_out"] == {"back-walk": reasons}
    assert [r["loop"]["n_out"] for r in rows] == [out["walk"]["length"]] * 2 + [19] and "cycle_align" not in rows[2]["loop"]
    said = capsys.readouterr().err
    assert ("a take to film again (start-stop)" in said) is ("start-stop" in reasons)
    held = f"nothing witnesses its cut whole cycles ({local_cycle.UNWITNESSED}): it may hold half a cycle or two"
    assert (held in said) is (local_cycle.UNWITNESSED in reasons) and "may be one step" not in said
    alone = batch.align_gaits(rows[1:], tmp_path, "auto", interpolate=Recorder())
    assert alone == {"walk": {"ok": True, "applied": False, "why": "fewer than two directions left to align",
                              "left_out": {"back-walk": reasons}}}


@pytest.mark.slow
def test_video_set_leaves_a_loop_its_body_rises_and_falls_four_times_in_out_of_the_alignment(tmp_path, capsys):
    """A walk's cut its body rises and falls four times in (`cut_witness.says` four steps, `local_cycle.four_steps`) is
    two cycles long and stands, and its strip counts the two steps its crossings counted (`steps: 2`), which
    `video-cycle-align` reads as one cycle, a return half way its second step: aligned so to the set's median length,
    it would play its two cycles where the rest play one, twice as fast. `video-set` leaves it out, its loop and strip
    as cut, named (`cycle-four-steps`), and aligns the rest without it."""
    from sprite_gen.video import batch

    rows = []
    for direction, length, cycles in (("front", 20, 1), ("side", 24, 1), ("back", 40, 2)):
        item = tmp_path / f"{direction}-walk"
        item.mkdir()
        loop = _cut(item, "loop", length, cycles=cycles)
        named = {}
        if cycles == 2:
            strip = loop / "walk.strip.json"
            strip.write_text(json.dumps({**json.loads(strip.read_text()), "steps": 2}))
            named = {"cycle-four-steps": True}
        rows.append({"item": f"{direction}-walk", "direction": direction, "state": "walk", "dir": str(item), "ok": True,
                     "loop": {"n_out": length, **named}})
    out = batch.align_gaits(rows, tmp_path, "auto", interpolate=Recorder())
    assert out["walk"].get("lengths") == [20, 24], f"the loop of two cycles is aligned as one: {out['walk']}"
    assert out["walk"]["applied"] and out["walk"]["left_out"] == {"back-walk": ["cycle-four-steps"]}
    assert [r["loop"]["n_out"] for r in rows] == [out["walk"]["length"]] * 2 + [40] and "cycle_align" not in rows[2]["loop"]
    meta = json.loads((tmp_path / "back-walk" / "loop" / "walk.strip.json").read_text())
    assert meta["frames"] == 40 and meta["steps"] == 2 and "cycle_align" not in meta
    assert f"four times in its cut ({local_cycle.FOUR_STEPS})" in capsys.readouterr().err


def _drawn_four_steps() -> dict:
    """The body's word on a cut of two cycles of a walker whose arms swing past its sides, off its frames (`cut_word`):
    the loop `video-loop` writes where the cut it was asked for, or the one it was handed, runs two cycles long."""
    frames = [walks._behind(k, cycle=20, hold=2) for k in range(walks.FRAMES)]
    word = local_cycle.cut_word({**legs.strike_signals(frames), **legs.body_signals(frames)}, 40)
    return {k: word.get(k) for k in ("says", "by")}


@pytest.mark.slow
@pytest.mark.parametrize("witness, reason", [({"held": "unwitnessed"}, local_cycle.UNWITNESSED),
                                             ({"says": "four steps", "by": ["order"]}, local_cycle.FOUR_STEPS),
                                             (_drawn_four_steps, local_cycle.FOUR_STEPS)],
                         ids=["held", "four-steps-by-its-order", "four-steps-by-its-body"])
def test_video_cycle_align_alone_stops_on_a_loop_whose_cut_its_report_holds_and_names_why(tmp_path, witness, reason):
    """`video-cycle-align` run on a set's loops alone, without the rows `video-set` marks, reads the report beside each
    loop (`align.held_cut`): a loop whose cut nothing witnessed whole cycles (`cycle-unwitnessed`) may hold half a
    cycle or two, and one cut two cycles long where its strip counts two steps (`cycle-four-steps`) returns half way at
    its second step, which alone reads as one cycle. Either stops the set before anything is rewritten, named under
    `suspects` with its reason and its report, never aligned as one cycle without a word (the parent engine aligned
    both: the first at its own length, the second at twice the speed of the rest); a count settles it. A body read as
    four steps stops it as the order does, witnessed on the screen and over its feet; the parent engine held such a
    cut's arms against it, and the loop that reads two cycles now stops the set as one held does."""
    witness = witness() if callable(witness) else witness
    four = reason == local_cycle.FOUR_STEPS
    dirs = [_cut(tmp_path, n, L, cycles=c, report=n == "N")
            for n, L, c in (("S", 20, 1), ("E", 24, 1), ("N", 40 if four else 28, 2 if four else 1))]
    report = dirs[2] / "walk.loop.report.json"
    data = json.loads(report.read_text())
    report.write_text(json.dumps({**data, "cycle": {**data["cycle"], "cut_witness": witness}}))
    if four:
        strip = dirs[2] / "walk.strip.json"
        strip.write_text(json.dumps({**json.loads(strip.read_text()), "steps": 2}))
    before = [(d / "walk.strip.png").read_bytes() for d in dirs]
    with pytest.raises(align.CycleSuspects) as stop:
        align.align_set(dirs, interpolate=Recorder(), between="rife")
    (entry,) = stop.value.suspects
    assert entry["dir"] == str(dirs[2].resolve()) and entry["status"] == "stopped" and "one_step" not in entry
    assert entry["held"] == {"reason": reason, "report": str(report.resolve())}
    assert entry["settle"] == [f"--cycles {dirs[2].resolve()}={c}" for c in (1, 2)]
    said = str(stop.value)
    assert reason in said and "nothing witnessed some of the cuts whole cycles" in said and ("--steps 1" in said) is (not four)
    assert [(d / "walk.strip.png").read_bytes() for d in dirs] == before
    out = align.align_set(dirs, interpolate=Recorder(), between="rife", multi_cycle="warn")
    assert out["applied"] is True and any(reason in line for line in out["warnings"])
    counted = align.align_set(dirs, interpolate=Recorder(), between="rife", cycles={str(dirs[2]): 2 if four else 1})
    assert counted["applied"] is True and counted["lengths"] == [20, 24, 20 if four else 28]
    assert counted["suspects"][0]["status"] == "counted" and counted["suspects"][0]["held"]["reason"] == reason


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


@pytest.mark.slow
def test_video_cycle_align_between_nearest_needs_no_rife(tmp_path, monkeypatch):
    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24), ("N", 28))]
    _no_rife(monkeypatch, tmp_path)
    report = align.align_set(dirs, between="nearest")
    assert report["between"] == "nearest" and report["made_by_rife"] == 0 and report["interpolator"] is None
    by = {Path(r["dir"]).name: r for r in report["loops"]}
    assert len(by["S"]["nearest_at"]) > 0 and by["E"]["nearest_at"] == []
    assert all(json.loads((d / "walk.strip.json").read_text())["frames"] == 24 for d in dirs)


@pytest.mark.slow
def test_a_made_frame_darker_than_both_neighbours_is_named_in_the_warnings(tmp_path):
    def smudge(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
        made = np.asarray(Image.blend(a, b, t)).copy()
        made[60:80, 42:58, :3] = 0  # a black blot inside the body
        return Image.fromarray(made, "RGBA")

    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
    report = align.align_set(dirs, interpolate=smudge, between="rife")
    smears = [w for w in report["warnings"] if "more dark pixels inside the body" in w]
    assert len(smears) == report["made_by_rife"] > 0
    row = next(r for r in report["loops"] if Path(r["dir"]).name == "S")
    assert len(row["smear"]) == row["made_by_rife"] and min(m["dark_excess"] for m in row["smear"]) > align.SMEAR_WARN
    assert [m["at"] for m in row["smear"]] == sorted(row["made_at"])


def _melt(a: Image.Image, b: Image.Image, t: float) -> Image.Image:
    """A stand-in RIFE that lost the dark foot: the frame between drawn whole, its dark grey taken
    into the body's blue — the outline around the foot gone, nothing darker added."""
    made = np.asarray(Image.blend(a, b, t)).copy()
    made[..., 3] = np.where(made[..., 3] >= 64, 255, 0)
    made[(made[..., 3] > 0) & (made[..., :3].max(axis=-1) < 130)] = (90, 90, 200, 255)
    return Image.fromarray(made, "RGBA")


@pytest.mark.slow
def test_a_made_frame_that_lost_its_outline_is_replaced_by_the_nearer_source_frame_and_named(tmp_path):
    """--between auto (the default): every made frame is measured, and one that lost its outline
    takes the nearer source frame instead, named in the warnings and in its row (`method`
    nearest); --between rife keeps it and names it."""
    dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]
    report = align.align_set(dirs, interpolate=_melt, report_path=tmp_path / "align.json")
    row = next(r for r in report["loops"] if Path(r["dir"]).name == "S")
    assert report["between"] == "auto" and report["made_by_rife"] == 0 and row["made_at"] == []
    assert len(row["smear"]) == len(row["nearest_at"]) > 0
    assert report["replaced"] == sum(len(r["smear"]) for r in report["loops"])
    assert all(m["method"] == "nearest" and m["faults"] == ["outline"] and m["outline_loss"] > align.OUTLINE_WARN for m in row["smear"])
    assert sorted(m["at"] for m in row["smear"]) == row["nearest_at"]
    named = [w for w in report["warnings"] if "lost its outline" in w and "the nearer source frame was taken there" in w]
    assert len(named) == report["replaced"]
    assert report["interpolator"] == {"kind": "injected"}
    source = [Image.open(p).convert("RGBA").tobytes() for p in sorted((dirs[0] / align.SOURCE_DIR).glob("frame-*.png"))]
    cells = [Image.open(p).convert("RGBA").tobytes() for p in sorted((dirs[0] / "cycle").glob("frame-*.png"))]
    assert all(cells[k] in source for k in row["nearest_at"])  # a filmed frame, as filmed
    kept = align.align_set(dirs, interpolate=_melt, between="rife")
    row = next(r for r in kept["loops"] if Path(r["dir"]).name == "S")
    assert kept["replaced"] == 0 and len(row["made_at"]) == len(row["smear"]) > 0 and "nearest_at" not in row
    assert len([w for w in kept["warnings"] if "lost its outline" in w and "--between auto" in w]) == kept["made_by_rife"]


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


@pytest.mark.slow
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]