Skip to content

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.py
new file mode 100644
index 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 d
diff --git a/tests/video/test_root_motion.py b/tests/video/test_root_motion.py
new file mode 100644
index 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")