Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
test(video-loop): a synthetic jump's root read on its parabola, its air doubled on the parabola with no frame shown again, and the cuts with no air keeping their bytes
Soohong Kim85ff2b6a6873
diff --git a/tests/video/jump_inputs.py b/tests/video/jump_inputs.pynew file mode 100644index 0000000..475ea65--- /dev/null+++ b/tests/video/jump_inputs.py@@ -0,0 +1,101 @@+# SPDX-License-Identifier: Apache-2.0+"""A synthetic jump for the root motion tests (tests/video/test_root_motion.py): a figure that crouches on the floor,+leaps, tucks its legs in the air with its mass centre on a parabola under a known gravity, lands and stands up with an+arm raised. Every frame shows a picture of its own but the held end pose. No real footage."""++from __future__ import annotations++import math+from pathlib import Path++import numpy as np+from PIL import Image++W, H = 240, 200+FLOOR = 186 # the lowest body row of a frame on the floor+FPS = 24.0+TAKEOFF, LANDING = 5, 15 # the last frame on the floor before the air, the first after+END = 19 # the frame from which the end pose is held+FRAMES = 25+X_TAKEOFF, X_LANDING = 60, 140 # the torso's middle on the floor at take-off and at landing+APEX = 40 # px the mass centre rises over the take-off's+AIR = (LANDING - TAKEOFF) / FPS # seconds from take-off to landing+GRAVITY = 8 * APEX / AIR ** 2 # px a second squared: the parabola g·t·(T - t)/2 rises APEX at T/2+METERS_PER_PX = 9.81 / GRAVITY # so the clip's gravity is the earth's+++def pose(tuck: float, crouch: int, arm: int, raised: bool = False) -> np.ndarray:+ """The figure on a canvas of its own: a torso, a head, two legs that bend `tuck` (0..1) and lower the hip `crouch`+ px, and an arm reaching out `arm` px, or raised."""+ a = np.zeros((140, 120, 4), dtype=np.uint8)+ hip = 80 + crouch+ a[hip - 40:hip, 50:70] = (90, 90, 200, 255)+ a[hip - 58:hip - 40, 52:68] = (230, 190, 160, 255)+ leg = 40 - crouch - round(18 * tuck)+ lean = round(10 * tuck)+ for x in (51, 61):+ a[hip:hip + leg, x + lean:x + lean + 8] = (60, 60, 60, 255)+ if raised:+ a[hip - 70:hip - 34, 70:76] = (200, 80, 30, 255)+ else:+ a[hip - 34:hip - 28, 70:70 + arm] = (200, 80, 30, 255)+ return a+++def centre(a: np.ndarray) -> tuple[float, float]:+ ys, xs = np.nonzero(a[..., 3] > 0)+ return float(xs.mean() + 0.5), float(ys.mean() + 0.5)+++def _on_floor(a: np.ndarray, x: int) -> Image.Image:+ """`a` placed with its lowest row on the floor and its torso's middle at `x`."""+ bottom = int(np.nonzero(a[..., 3].any(axis=1))[0][-1])+ out = Image.new("RGBA", (W, H))+ out.paste(Image.fromarray(a, "RGBA"), (x - 60, FLOOR - bottom))+ return out+++def _at(a: np.ndarray, x: float, y: float) -> Image.Image:+ """`a` placed with its mass centre at the whole pixel nearest (x, y)."""+ cx, cy = centre(a)+ out = Image.new("RGBA", (W, H))+ out.paste(Image.fromarray(a, "RGBA"), (round(x - cx), round(y - cy)))+ return out+++def takeoff_root() -> tuple[float, float]:+ """The take-off frame's mass centre, where the parabola starts."""+ a = pose(0.0, 6, 16)+ bottom = int(np.nonzero(a[..., 3].any(axis=1))[0][-1])+ cx, cy = centre(a)+ return cx + X_TAKEOFF - 60, cy + FLOOR - bottom+++def path(t: float) -> tuple[float, float]:+ """The mass centre `t` frames after take-off, on the parabola (px, y down)."""+ xa, ya = takeoff_root()+ s = t / FPS+ return xa + (X_LANDING - X_TAKEOFF) * s / AIR, ya - GRAVITY * s * (AIR - s) / 2+++def draw(t: float) -> Image.Image:+ """The jump `t` frames in."""+ if t <= TAKEOFF:+ return _on_floor(pose(0.0, round(1.2 * t), 6 + round(2 * t)), X_TAKEOFF)+ if t < LANDING:+ u = (t - TAKEOFF) / (LANDING - TAKEOFF)+ return _at(pose(math.sin(math.pi * u), 6, 16 + round(4 * math.sin(math.pi * u))), *path(t - TAKEOFF))+ if t < END:+ return _on_floor(pose(0.0, 6 - round(1.5 * (t - LANDING)), 16), X_LANDING)+ return _on_floor(pose(0.0, 0, 16, raised=True), X_LANDING)+++def jump() -> list[Image.Image]:+ return [draw(k) for k in range(FRAMES)]+++def save(frames: list[Image.Image], d: Path) -> Path:+ d.mkdir(parents=True)+ for k, f in enumerate(frames):+ f.save(d / f"{k:04d}.png")+ return ddiff --git a/tests/video/test_root_motion.py b/tests/video/test_root_motion.pynew file mode 100644index 0000000..caa96bd--- /dev/null+++ b/tests/video/test_root_motion.py@@ -0,0 +1,274 @@+# SPDX-License-Identifier: Apache-2.0+"""Root motion (sprite_gen/video/root_motion.py, docs/video-pipeline.md "Root motion"): a cut played once carries+where its body is in each cell (the mass centre), what each cell touches and its air, in the strip sidecar; with+`--air-retime` the air is given a length, a gravity and a speed of its own, its cells made between the clip's frames+(held_fill.at_times), the take-off and the landing as filmed and the contacts where they were. Without the handle the+cut is delivered byte for byte as before and its sidecar only grows a key.++The jump is synthetic (tests/video/jump_inputs.py), its mass centre on a parabola under a known gravity; the+interpolator is the stand-in that draws it again at the time asked for (`Between`)."""++from __future__ import annotations++import hashlib+import json+from pathlib import Path++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 nonloop+from sprite_gen.video import root_motion as rm+from tests.video import jump_inputs as J+from tests.video.held_fill_inputs import Between+from tests.video.test_held_fill import UNHELD, _bytes, _no_rife+++def _run(tmp_path: Path, frames: list[Image.Image], name: str = "j", **kw) -> dict:+ keyed = J.save(frames, tmp_path / f"{name}-keyed")+ return loop_mod.run_loop(keyed, tmp_path / f"{name}-out", fps=J.FPS, min_len=None, max_len=None, n_out=None,+ seam_max=loop_mod.SEAM_RATIO_MAX, name=name, report_path=None, **kw)+++def _meta(rep: dict) -> dict:+ return json.loads(Path(rep["strip"]["path"]).with_suffix("").with_suffix(".strip.json").read_text())+++def _cells(rep: dict) -> list[Image.Image]:+ meta = _meta(rep)+ strip = Image.open(rep["strip"]["path"]).convert("RGBA")+ return [strip.crop((k * meta["w"], 0, (k + 1) * meta["w"], meta["h"])) for k in range(meta["frames"])]+++def _read(frames: list[Image.Image], declared=()) -> dict:+ floor = max(nonloop.body_box(f)[3] for f in frames)+ roots = [rm.root(f) for f in frames]+ touch = rm.touching(frames, floor=floor, times=range(len(frames)), declared=declared)+ return {"roots": roots, "touch": touch, **rm.read(roots, touch, [k / J.FPS for k in range(len(frames))])}+++def test_the_root_of_a_body_flying_under_gravity_is_read_on_its_parabola():+ frames = J.jump()+ got = _read(frames)+ height = max(b[3] - b[1] for b in map(nonloop.body_box, frames))+ worst = max(max(abs(got["roots"][k][0] - J.path(k - J.TAKEOFF)[0]), abs(got["roots"][k][1] - J.path(k - J.TAKEOFF)[1]))+ for k in range(J.TAKEOFF, J.LANDING + 1))+ assert worst <= 0.5 and worst / height < 0.05 # a whole pixel's placing, under half a pixel+ (air,) = got["air"]+ assert air["cells"] == [J.TAKEOFF + 1, J.LANDING - 1]+ assert (air["takeoff"], air["landing"]) == (J.TAKEOFF, J.LANDING)+ assert air["seconds"] == pytest.approx(J.AIR, abs=1e-4)+ assert air["apex_px"] == pytest.approx(J.APEX, abs=1.0)+ assert got["contacts"] == [{"by": "ground", "cells": [0, J.TAKEOFF]}, {"by": "ground", "cells": [J.LANDING, J.FRAMES - 1]}]+++def test_a_contact_the_floor_does_not_show_is_named_over_the_clip_s_frames():+ frames = J.jump()+ declared = rm.parse_contacts(["hand=6:8"], len(frames))+ got = _read(frames, declared)+ assert {"by": "hand", "cells": [6, 8]} in got["contacts"]+ (air,) = got["air"]+ assert (air["takeoff"], air["cells"], air["landing"]) == (8, [9, 14], J.LANDING)+ with pytest.raises(ValueError, match="ground"):+ rm.parse_contacts(["ground=1:2"], 10)+ with pytest.raises(ValueError, match="numbered from 0"):+ rm.parse_contacts(["hand=4:40"], 10)+++def test_the_retime_keys_are_read_and_a_wrong_one_is_refused():+ assert rm.parse_retime("gravity=9.81,air=0.6,speed=4") == {"gravity": 9.81, "air": 0.6, "speed": 4.0}+ assert rm.parse_retime("air=1.2") == {"air": 1.2}+ for bad in ("air", "air=0", "lift=2", "air=1,air=2", "gravity=-1", "speed=x"):+ with pytest.raises(ValueError):+ rm.parse_retime(bad)+++def _retimed(**asked):+ frames = J.jump()+ between = Between(J.draw, range(J.FRAMES))+ floor = max(nonloop.body_box(f)[3] for f in frames)+ out, record, plan = rm.retime(frames, between, fps=J.FPS, rate=J.FPS, floor=floor, times=range(J.FRAMES), declared=(),+ asked=asked, meters_per_px=J.METERS_PER_PX)+ return frames, out, record, plan, between+++def test_the_air_twice_as_long_rises_g_t2_over_8_its_cells_made_between_and_the_contacts_kept():+ frames, out, record, plan, between = _retimed(gravity=9.81, air=2 * J.AIR)+ assert record["applied"]+ (air,) = record["air"]+ cells = round(2 * J.AIR * J.FPS)+ assert len(out) == J.FRAMES + cells - (J.LANDING - J.TAKEOFF) # the air holds twice the cells+ assert air["seconds"] == pytest.approx(2 * J.AIR, abs=1e-4) and air["gravity"] == pytest.approx(9.81, abs=1e-3)+ T = 2 * J.AIR+ assert air["apex_px"] == pytest.approx(J.GRAVITY * T * T / 8, abs=0.01)+ # read on the cells delivered: the air spans the new cells, rises g·t²/8 and lands where the parabola does+ ox, oy = plan["offset"]+ roots = [rm.root(f) for f in out]+ measured = rm.read(roots, plan["touch"], [k / J.FPS for k in range(len(out))])+ (got,) = measured["air"]+ assert got["cells"] == [J.TAKEOFF + 1, J.TAKEOFF + cells - 1] and got["seconds"] == pytest.approx(T, abs=1e-4)+ assert got["apex_px"] == pytest.approx(J.GRAVITY * T * T / 8, abs=1.0)+ # every air cell on the parabola, within a whole pixel's placing+ xa, ya = roots[J.TAKEOFF]+ for j in range(1, cells):+ t = j / J.FPS+ x = xa + 2 * (J.X_LANDING - J.X_TAKEOFF) * j / cells # the clip's own speed, for twice as long+ y = ya - J.GRAVITY * t * (T - t) / 2+ assert abs(roots[J.TAKEOFF + j][0] - x) <= 0.5 and abs(roots[J.TAKEOFF + j][1] - y) <= 0.5+ # the poses: the clip's at the same share of its air, every other one made between two frames+ assert record["made"] == cells // 2 and record["shown_again"] == []+ assert sorted({round(c[2], 4) for c in between.calls}) == [0.5]+ # no picture shown twice in the air+ same = held_fill.same_steps(out)+ assert not any(same[J.TAKEOFF:J.TAKEOFF + cells])+ # the take-off, the cells before it and the landing block are the frames as filmed, moved whole+ moved = air["moved_along_px"]+ assert moved == 2 * (J.X_LANDING - J.X_TAKEOFF) - (J.X_LANDING - J.X_TAKEOFF)+ for k in range(J.TAKEOFF + 1):+ assert out[k].crop((ox, oy, ox + J.W, oy + J.H)).tobytes() == frames[k].tobytes()+ for k in range(J.LANDING, J.FRAMES):+ o = J.TAKEOFF + cells + (k - J.LANDING)+ assert out[o].crop((ox + moved, oy, ox + moved + J.W, oy + J.H)).tobytes() == frames[k].tobytes()+ # the ground cells stand on the floor, moved, and the air cells touch nothing+ floor = J.FLOOR + 1 + oy+ for k, f in enumerate(out):+ on = nonloop.on_floor(nonloop.body_box(f), floor)+ assert on == (not J.TAKEOFF < k < J.TAKEOFF + cells), k+++def test_the_air_given_only_a_length_keeps_the_clip_s_own_gravity_and_speed():+ frames, out, record, plan, _ = _retimed(air=J.AIR)+ (air,) = record["air"]+ assert air["gravity_before_px"] == pytest.approx(J.GRAVITY, rel=0.02)+ assert air["seconds"] == pytest.approx(J.AIR, abs=1e-4) and air["moved_along_px"] == 0+ assert record["made"] == 0 # every cell a frame: nothing to make, no RIFE asked for+++def test_a_cut_with_no_air_is_not_retimed_and_says_why():+ frames = [J.draw(0)] * 2 + J.jump()[:J.TAKEOFF + 1]+ floor = max(nonloop.body_box(f)[3] for f in frames)+ out, record, plan = rm.retime(frames, None, fps=J.FPS, rate=J.FPS, floor=floor, times=range(len(frames)),+ declared=(), asked={"air": 1.0}, meters_per_px=None)+ assert out is frames and plan is None and record["applied"] is False and record["why"] == "no air in the cut"+++def test_video_loop_carries_the_root_motion_of_a_jump_and_retimes_its_air(tmp_path):+ rep = _run(tmp_path, J.jump(), "plain", state="jump", cycle_mode="once")+ meta = _meta(rep)+ root = meta["root_motion"]+ assert len(root["root"]) == meta["frames"]+ start = meta["source_cut"]["start"]+ (air,) = root["air"]+ assert (air["takeoff"], air["landing"]) == (J.TAKEOFF - start, J.LANDING - start)+ assert air["seconds"] == pytest.approx(J.AIR, abs=1e-3)+ assert air["apex_px"] == pytest.approx(J.APEX * meta["scale"], abs=1.0)+ assert "air_retime" not in meta and rep["root_motion"]["air"] == root["air"]+ between = Between(J.draw, range(J.FRAMES))+ rep = _run(tmp_path, J.jump(), "long", state="jump", cycle_mode="once", air_retime=f"gravity=9.81,air={2 * J.AIR}",+ meters_per_px=J.METERS_PER_PX, interpolate=between)+ meta = _meta(rep)+ record = meta["air_retime"]+ assert record["applied"] and record["made"] == 10 and meta["frames"] == rep["cycle"]["length"] + 10+ (air,) = meta["root_motion"]["air"]+ T = 2 * J.AIR+ assert air["seconds"] == pytest.approx(T, abs=1e-3)+ assert air["apex_m"] == pytest.approx(9.81 * T * T / 8, rel=0.03)+ assert "times" in meta["source_cut"] and "out_fps" not in meta+ # no picture shown twice in the air: the held runs left are the end pose the cut holds+ first, last = air["cells"]+ assert all(r["start"] > last or r["start"] + r["length"] <= first for r in meta["held_fill"]["held_runs"])+ assert record["poses"] == meta["held_fill"]["poses"] and record["cells"] == meta["frames"]+++def test_no_rife_leaves_the_air_as_filmed_and_says_which_motion(tmp_path, monkeypatch, capsys):+ _no_rife(monkeypatch, tmp_path)+ rep = _run(tmp_path, J.jump(), "leap", state="jump", cycle_mode="once", air_retime=f"air={2 * J.AIR}")+ err = capsys.readouterr().err+ meta = _meta(rep)+ assert meta["air_retime"]["applied"] is False and meta["air_retime"]["why"] == "RIFE is not installed"+ assert "leap" in err and "was not retimed" in err and "rife install" in err+ assert meta["frames"] == rep["cycle"]["length"] # as filmed+ assert meta["root_motion"]["air"][0]["seconds"] == pytest.approx(J.AIR, abs=1e-3)+++def test_gravity_or_speed_without_metres_per_pixel_is_refused(tmp_path):+ with pytest.raises(SystemExit, match="--meters-per-px"):+ _run(tmp_path, J.jump(), "g", state="jump", cycle_mode="once", air_retime="gravity=9.81")+ with pytest.raises(SystemExit, match="--contact"):+ _run(tmp_path, J.jump(), "c", state="jump", cycle_mode="once", contacts=["hand=3:99"])+++# The base engine's sidecars of the six inputs the held-cell tests pin (559d498, v3.8.0), every key: without the handle+# the cut keeps every one of them, value for value, and a cut played once grows `root_motion`.+SIDECARS = {+ "hop-one-shot": "59ef079606d627a0a4e3d25a4ea6ef3ef7b0aa72dd6a9111a566a4c4a0f56def",+ "swing-once-return": "558a1a1142b0b0a033d88f021c0c6085c0c14cb7cce66c70480e5fa9e535df6b",+ "swing-pinned": "286345f6dc30681c50dbd646e27fa3779b46ed0d6d2d3e29d5aa273b323400ef",+ "topple-once": "0a1f5ad5f0d851af989d9561006cd78af0021ce1a996bc4cf479c6377ede3f0e",+ "walk-auto": "996af533ae949cc8fd2fba2acbab14db23d3fe741aff922889dbe312214fefea",+ "walk-fixed": "0327ba19b76b6294dd42edb1e30489d1c607cbe6f14174cebd90e043d2802835",+}++[email protected]("case", sorted(UNHELD))+def test_without_the_handle_the_cut_is_byte_for_byte_as_before_and_its_sidecar_only_grows(case, tmp_path, monkeypatch):+ _no_rife(monkeypatch, tmp_path)+ frames, kw, pinned = UNHELD[case]+ keyed = J.save(frames(), tmp_path / f"{case}-keyed")+ rep = loop_mod.run_loop(keyed, tmp_path / f"{case}-out", fps=24.0, min_len=None, max_len=None, n_out=None,+ seam_max=loop_mod.SEAM_RATIO_MAX, name=case, report_path=None, **kw)+ assert _bytes(Path(rep["out_dir"]), case) == pinned+ meta = _meta(rep)+ grown = meta.pop("root_motion", None)+ assert hashlib.sha256(json.dumps(meta, sort_keys=True).encode()).hexdigest() == SIDECARS[case]+ assert (grown is not None) == (meta["kind"] in rm.KINDS)+ if grown is not None:+ assert len(grown["root"]) == meta["frames"] and grown["point"] == "mass-centre"+++def test_video_loop_and_video_set_take_the_switches():+ from tests.conftest import help_options++ loop = help_options("-m", "sprite_gen.cli", "video-loop")+ assert {"--air-retime", "--meters-per-px", "--contact"} <= loop+ assert {"--air-retime", "--meters-per-px"} <= help_options("-m", "sprite_gen.cli", "video-set")+++def test_video_set_hands_the_switches_to_each_cut_and_says_each_air(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": None, "ratio": 0.0, "kind": "once"}, "resampled_seam_ratio": None,+ "n_out": 10, "gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"},+ "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [],+ "before": {"cells": 10, "poses": 10, "held_runs": []}},+ "root_motion": {"air": [{"cells": [3, 6], "takeoff": 2, "landing": 7, "seconds": 0.2083, "apex_px": 31.5,+ "apex_m": 0.42}]},+ "air_retime": {"applied": False, "why": "RIFE is not installed", "before": []}}++ 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 / "side.png"+ Image.new("RGBA", (64, 64), (200, 80, 30, 255)).save(still)+ result = batch.run_set(bases={"side": still}, states=["jump"], root=tmp_path / "set", character=None, duration=3,+ resolution="720p", key="green", concurrency=1, force=False, gap=0, video_runner=video,+ align_cycles="off", air_retime="gravity=9.81,air=0.6,speed=4", meters_per_px=0.005)+ assert [(kw["air_retime"], kw["meters_per_px"]) for kw in seen] == [("gravity=9.81,air=0.6,speed=4", 0.005)]+ assert result["items"][0]["loop"]["air"] == ["air 0.21 s, apex 0.42 m (cells 3-6)"]+ assert any("air not retimed" in w for w in result["warnings"])+ with pytest.raises(SystemExit, match="--meters-per-px"):+ batch.run_set(bases={"side": still}, states=["jump"], root=tmp_path / "set2", character=None, duration=3,+ resolution="720p", key="green", concurrency=1, force=False, gap=0, video_runner=video,+ align_cycles="off", air_retime="speed=4")