Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video-stop): the stop's seam line is its own, 1.4 steps, as the jump repair keeps no line
Soohong Kimf64daec52f46
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 87e9896..6eb248a 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -1514,7 +1514,7 @@ sprite-gen video-stop --frames-dir run/frames/keyed --loop run/loop/run.strip.js- **The rest.** The clip's opening run of frames within `SAME_POSE` (0.35 steps) of its first frame by engine pose distance (`gait_fallback.poses`: 48 px thumbnails cut about the feet). A step is the clip's median neighbouring-frame pose distance in the loop's window on the clip as filmed, whether cut or aligned. The stop ends on the first frame itself, the still as filmed.- **The entry and the cell left from.** The first frame after the rest within `SAME_POSE` of a loop cell, searched to the end of the loop's window (`source_cut`): where the clip reaches the loop. The stop leaves from the nearest cell (`from_cell`) — a player shows the loop through that cell, then the stop — and its first frame is the clip frame before the entry. The entry frame is laid on its cell within 12 % of the cell height (coverage difference, quarter-size search then to the pixel); the first frame is searched across a cell's width.-- **The seam and its refusal.** Reported in steps from the leaving cell into the stop's first frame. Past the jump line (1.4 steps, `repair.JUMP_RATIO`, overridden by `--seam-max`), the stop is refused: "the clip reaches the loop by a jump".+- **The seam and its refusal.** Reported in steps from the leaving cell into the stop's first frame. Past the jump line (1.4 steps, `stop.SEAM_MAX`, overridden by `--seam-max`), the stop is refused: "the clip reaches the loop by a jump".- **Another motion and its refusal.** A setting-off goes one way, from the still into the loop: the body does not come back to a pose it has left. `video-stop` finds, among the run-up's frames, the one that comes nearest back to the pose of an earlier frame of the clip (the still or one of the rest's frames, or an earlier frame of the run-up itself), counting only earlier frames the body went `TURN_BACK_AWAY` (one step) or more away from in between. That nearest comeback is recorded in the report as `turn_back` (fields `frame`: the frame that comes back; `back_to`: the earlier frame whose pose it is back at; `steps`: how far it still is from that pose; `away_frame`: the farthest frame between; `away_steps`: how far that one went), alongside `turn_back_away` (the one-step threshold); `turn_back` is null when the body never leaves any pose by a step. If that comeback is within `SAME_POSE` (0.35 steps), the run-up turned back: it holds another motion — for example a gesture that ends where it began (an arm waved, a crouch, then standing again before the run sets off), a motion done again, or a run going round a cycle of its own. The stop would play it backwards, so the command refuses, however short the motion is (two frames are enough), naming the three frames: "the run-up turns back — another motion, that the stop would play backwards". This is the only judgment that refuses another motion; the run-up's length plays no part in it, and `--run-up-max` cannot let it through. A motion carried one way into the run (an arm drawn in, a crouch, a turn before the first stride) is the setting-off's own and is not refused; the pose distance cannot tell it from a gesture carried one way into the run.- **The run-up and its refusal.** The frames between the rest and the entry that the stop plays before the still. A body sets off into its gait within about a cycle; a run-up longer than `RUN_UP_MAX_CYCLES` (1.5 cycles, `source_cut.length` frames, overridden by `--run-up-max`) plays strides unlike the loop's — a run of its own before the loop's, or a start slower than a setting-off — and is refused: "strides unlike the loop's, that the stop would play backwards". The seam refusal (overridden by `--seam-max`), the another-motion refusal and the run-up refusal can all be named in one message.- **Drift.** A body setting off may move across its frame, sliding into the still if played back as filmed. Two frames are laid where the loop stands: the entry on its cell (least coverage difference), and the first frame with its lowest body row on the loop's ground and across where it covers the loop best (mean coverage of the cells). Frames between are moved by a straight share of the difference per step of the stop, none at the entry and all on the first frame: drift is taken out without moving any frame by its own pose. Because a standing pose is laid on a running one by coverage, a run leaning or reaching away moves the still a few pixels — a straight glide over the stop, the same with drift or without it — and drift not straight over the frames shown leaves a little of itself.diff --git a/sprite_gen/video/stop.py b/sprite_gen/video/stop.pyindex eb2c42e..5ffe9c7 100644--- a/sprite_gen/video/stop.py+++ b/sprite_gen/video/stop.py@@ -16,7 +16,7 @@ and a report.to the end of the loop's window (`source_cut`): where the clip reaches the loop. The stop leaves theloop from the cell nearest to it (`from_cell`) — a player shows the loop through that cell, then thestop — and its first frame is the clip frame before the entry. The seam, from that cell into that- frame, is reported in steps; past the jump line (`repair.JUMP_RATIO`, `--seam-max`) the stop is refused.+ frame, is reported in steps; past the jump line (SEAM_MAX, `--seam-max`) the stop is refused.- **Another motion**: a setting-off goes one way, from the still into the loop; the body does not comeback to a pose it has left. A run-up frame within SAME_POSE of an earlier frame of the clip — the still,or a pose of the run-up — after the body went TURN_BACK_AWAY steps or more from it in between is a@@ -72,7 +72,7 @@ from sprite_gen.video import gait_fallbackfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import nonloopfrom sprite_gen.video.interpolation_quality import ghost_screen-from sprite_gen.video.repair import ALPHA_SOLID, JUMP_RATIO+from sprite_gen.video.repair import ALPHA_SOLIDPROG = "video-stop"KIND = "stop"@@ -84,6 +84,9 @@ TURN_BACK_AWAY = 1.0# A body sets off into its gait within about a cycle; past one and a half of the clip's own cycles the run-up# plays strides unlike the loop's.RUN_UP_MAX_CYCLES = 1.5+# A seam past this many of the clip's steps is a jump, and the stop is refused: the line a loop's step read by its+# size was judged a jump at, 2.44.0's `repair.JUMP_RATIO` (the jump repair now reads a loop's flow and keeps no line).+SEAM_MAX = 1.4SPEEDS = (1, 2)MARGIN = 8 # px of transparent room around the bodies, the strip cells' own side and top marginREGISTER_SEARCH = 0.12 # of the cell height: how far the entry is searched for on its cell@@ -224,7 +227,7 @@ def turn_back(poses: np.ndarray, rest_end: int, entry: int, step: float) -> dictdef find_stop(cells: list[Image.Image], frames: list[Image.Image], *, start: int, length: int,- seam_max: float = JUMP_RATIO, run_up_max: float = RUN_UP_MAX_CYCLES) -> dict[str, Any]:+ seam_max: float = SEAM_MAX, run_up_max: float = RUN_UP_MAX_CYCLES) -> dict[str, Any]:"""Rest, entry, the cell left from, the seam, the turn-back and the run-up of a clip whose frames (`frames`,from the first, at the loop's scale, through the frame after the window) reach the loop's `cells` in the window[start, start + length). Refused (`StopRefused`) where no frame reaches the loop, the seam is past `seam_max`@@ -337,7 +340,7 @@ def pick(played: list[int], *, speed: int, max_frames: int | None) -> list[int]:def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = "stop", speed: int = 1,max_frames: int | None = None, fps: float | None = None, report_path: Path | None = None,- seam_max: float = JUMP_RATIO, run_up_max: float = RUN_UP_MAX_CYCLES) -> dict[str, Any]:+ seam_max: float = SEAM_MAX, run_up_max: float = RUN_UP_MAX_CYCLES) -> dict[str, Any]:"""Cut the stop and write `<name>.strip.png`, `<name>.strip.json`, `<name>.gif`, `<name>.webp` and the report(`<name>.stop.report.json`, or `report_path`) into `out_dir`. A refusal writes the report and exits."""if speed not in SPEEDS:@@ -461,8 +464,8 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--name", default="stop", help="basename of the strip, sidecar, GIF, WebP and report (default stop)")parser.add_argument("--speed", type=int, choices=SPEEDS, default=1, help="1: every frame; 2: every other frame, the still kept last")parser.add_argument("--max-frames", type=int, help="at most this many frames, evenly spaced from the first to the still")- parser.add_argument("--seam-max", type=float, default=JUMP_RATIO,- help=f"refuse a seam (the last loop cell into the stop's first frame) over this many of the clip's steps (default {JUMP_RATIO}, the jump line)")+ parser.add_argument("--seam-max", type=float, default=SEAM_MAX,+ help=f"refuse a seam (the last loop cell into the stop's first frame) over this many of the clip's steps (default {SEAM_MAX}, the jump line)")parser.add_argument("--run-up-max", type=float, default=RUN_UP_MAX_CYCLES,help=f"refuse a stop whose frames between the rest and the loop's frames are longer than this many of the clip's cycles (default {RUN_UP_MAX_CYCLES})")parser.add_argument("--fps", type=float, help="the frames' rate (default: the loop's source_cut, else 24)")@@ -473,7 +476,7 @@ def run(**kwargs: object) -> int:payload = make_stop(Path(str(kwargs["frames_dir"])), Path(str(kwargs["loop"])), Path(str(kwargs["out_dir"])),name=str(kwargs.get("name") or "stop"), speed=int(kwargs.get("speed") or 1), # type: ignore[arg-type]max_frames=kwargs.get("max_frames"), fps=kwargs.get("fps"), report_path=kwargs.get("report"), # type: ignore[arg-type]- seam_max=float(JUMP_RATIO if kwargs.get("seam_max") is None else kwargs["seam_max"]), # type: ignore[arg-type]+ seam_max=float(SEAM_MAX if kwargs.get("seam_max") is None else kwargs["seam_max"]), # type: ignore[arg-type]run_up_max=float(RUN_UP_MAX_CYCLES if kwargs.get("run_up_max") is None else kwargs["run_up_max"])) # type: ignore[arg-type]print(json.dumps({"strip": payload["strip"]["path"], "frames": payload["strip"]["frames"], "seconds": payload["seconds"],"from_cell": payload["entry"]["from_cell"], "entry": payload["entry"]["frame"], "rest_end": payload["rest"]["end"],diff --git a/tests/video/test_stop.py b/tests/video/test_stop.pyindex d4d64e8..be57fcf 100644--- a/tests/video/test_stop.py+++ b/tests/video/test_stop.py@@ -133,7 +133,7 @@ def test_stop_plays_the_start_backwards_from_the_loop_to_the_first_frame(tmp_patassert all(j > out["rest"]["end"] for j in shown[:-1]) and out["rest"]["end"] >= REST - 1# The cell it leaves is the loop's cell at the entry's phase: the run is cut a cycle on, so the same phase.assert out["entry"]["from_cell"] == (out["entry"]["frame"] - (run_from + PERIOD)) % PERIOD- assert out["seam"]["steps"] <= stop.JUMP_RATIO and out["run_up"]["cycles"] <= stop.RUN_UP_MAX_CYCLES+ assert out["seam"]["steps"] <= stop.SEAM_MAX and out["run_up"]["cycles"] <= stop.RUN_UP_MAX_CYCLES# The last cell is the clip's first frame — the still as filmed — at the loop's scale, pixel for pixel.smeta, cells = cells_of(tmp_path / "stop" / "stop.strip.json")lmeta = json.loads(meta.read_text())@@ -240,7 +240,7 @@ def test_stop_refuses_a_seam_past_the_jump_line(tmp_path):with pytest.raises(SystemExit, match="jump line"):make(tmp_path, keyed, meta)report = json.loads((tmp_path / "stop" / "stop.stop.report.json").read_text())- assert report["status"] == "failed" and report["seam"]["steps"] > stop.JUMP_RATIO+ assert report["status"] == "failed" and report["seam"]["steps"] > stop.SEAM_MAXdef test_stop_leaves_an_aligned_loop_from_the_cell_nearest_the_entry(tmp_path):