Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(video-stop): a walk or run that stops, cut from the clip's own start played backwards to the still it was filmed from; seam, run-up, drift, speed, frame cap and ghosts reported
Soohong Kim38ccea538eaa
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.pyindex 5b3e913..7ef2b4a 100644--- a/sprite_gen/_modules.py+++ b/sprite_gen/_modules.py@@ -32,6 +32,7 @@ MODULE_DOMAIN = {'follow': 'video','follow_inspect': 'video','set_sheet': 'video',+ 'stop': 'video','compare': 'video','restoration': 'video','source': 'video',@@ -102,8 +103,8 @@ DOMAIN_TITLE = dict(DOMAINS)PIPELINES: list[dict[str, object]] = [{"key": "A", "name": "atlas rows", "verbs": ["prepare", "gen", "gen-set", "extract", "compose-atlas", "curation"],"chain": "prepare → gen (or gen-set) → extract → compose-atlas; optional curation and recompose", "doc": "docs/run-contract.md"},- {"key": "B", "name": "video → loop", "verbs": ["video-canvas", "video", "video-prompt", "video-frames", "video-loop", "video-set", "video-cycle-align", "video-follow", "video-follow-inspect", "video-set-sheet", "handed-check"],- "chain": "video-canvas → video (or video-prompt + a video MCP) → video-frames → video-loop, or video-set; video-cycle-align across a set; video-follow for a soft part's follow-through (video-follow-inspect shows every cell of it and moves nothing); video-set-sheet lays a set's directions on one sheet on one ground line; handed-check for an item on one side", "doc": "docs/video-pipeline.md"},+ {"key": "B", "name": "video → loop", "verbs": ["video-canvas", "video", "video-prompt", "video-frames", "video-loop", "video-set", "video-cycle-align", "video-follow", "video-follow-inspect", "video-set-sheet", "video-stop", "handed-check"],+ "chain": "video-canvas → video (or video-prompt + a video MCP) → video-frames → video-loop, or video-set; video-cycle-align across a set; video-follow for a soft part's follow-through (video-follow-inspect shows every cell of it and moves nothing); video-set-sheet lays a set's directions on one sheet on one ground line; video-stop cuts a walk or run's stop from its clip's start played backwards; handed-check for an item on one side", "doc": "docs/video-pipeline.md"},]TOOL_GROUPS: list[dict[str, object]] = [diff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex cbb6c40..44bc7ed 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -26,6 +26,7 @@ from sprite_gen.video import align as video_alignfrom sprite_gen.video import follow as video_followfrom sprite_gen.video import follow_inspect as video_follow_inspectfrom sprite_gen.video import set_sheet as video_set_sheet+from sprite_gen.video import stop as video_stopfrom sprite_gen.video import compare as video_comparefrom sprite_gen.video import restoration as video_restorationfrom sprite_gen.video import source as video_source@@ -430,6 +431,11 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callabvideo_set_sheet.add_arguments,video_set_sheet.run,),+ "video-stop": (+ "A walk or run that stops: the clip's own start played backwards from where it reaches the loop to the still it was filmed from, cut as a one-shot strip beside the loop (seam, drift, speed and refusals reported).",+ video_stop.add_arguments,+ video_stop.run,+ ),"rife": ("install: download the pinned RIFE (rife-ncnn-vulkan, sha256-checked) into the user data directory, where the loop repair finds it.",rife_install.add_arguments,diff --git a/sprite_gen/video/gait_fallback.py b/sprite_gen/video/gait_fallback.pyindex 6f4e0b7..61a5031 100644--- a/sprite_gen/video/gait_fallback.py+++ b/sprite_gen/video/gait_fallback.py@@ -115,7 +115,7 @@ def scale_drift(frames: list[Image.Image]) -> dict:POSE_EDGE = 48 # px: the pose thumbnail's longer side, the body cut out about its feet-def _poses(frames: list[Image.Image], boxes: np.ndarray) -> np.ndarray:+def poses(frames: list[Image.Image], boxes: np.ndarray) -> np.ndarray:"""Per frame: the body's thumbnail, cut out about its own feet (the bottom middle of its box),so a body that walks across the frame or bobs still matches itself a cycle later."""known = ~np.isnan(boxes[:, 0])@@ -171,8 +171,8 @@ def cycle_drift(frames: list[Image.Image], *, min_lag: int, max_lag: int) -> dicreturn {**base, "lag": None, "pairs": 0, "per_lag": 1.0, "pose_match": None, "drift": 0.0,"height_first_px": fitted["height_first_px"], "height_last_px": fitted["height_first_px"],"height": np.full(n, fitted["height"][0])}- poses = _poses(frames, boxes)- profile = {lag: float(np.nanmean(np.abs(poses[lag:] - poses[:-lag]))) for lag in range(max(1, min_lag), hi + 1)}+ thumbs = poses(frames, boxes)+ profile = {lag: float(np.nanmean(np.abs(thumbs[lag:] - thumbs[:-lag]))) for lag in range(max(1, min_lag), hi + 1)}lag = min(profile, key=lambda k: (profile[k], k))rates = np.concatenate([np.log(heights[span:] / heights[:-span]) / span for span in range(lag, n, lag)])rates = rates[np.isfinite(rates)]diff --git a/sprite_gen/video/stop.py b/sprite_gen/video/stop.pynew file mode 100644index 0000000..845432a--- /dev/null+++ b/sprite_gen/video/stop.py@@ -0,0 +1,457 @@+# SPDX-License-Identifier: Apache-2.0+"""`sprite-gen video-stop` — a walk or run that stops, from the clip's own start played backwards.++A walk or run clip filmed from a standing still (image to video) opens on that still: the body stands,+sets off, and runs into the gait the loop is cut from. Played backwards from the frame where the clip+reaches the loop, that start is the body running into the standing still — filmed frames, no frame+made between two others, ending on the clip's first frame, the still as filmed. This cuts it as a+one-shot clip beside the loop: a strip, its sidecar (`loop: false`, `hold_last: true`), a GIF, a WebP+and a report.++- **The rest** is the clip's opening run of frames within SAME_POSE steps of its first frame (the engine+ pose distance, `gait_fallback.poses`; a step is the clip's median step between neighbouring frames in+ the loop's window, the loop as filmed, whether the loop given is that cut or aligned from it). The stop+ ends on the first frame itself.+- **The entry** is the first frame after the rest within SAME_POSE of one of the loop's cells, searched+ to the end of the loop's window (`source_cut`): where the clip reaches the loop. The stop leaves the+ loop from the cell nearest to it (`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 seam, from that cell into that+ frame, is reported in steps; past the jump line (`repair.JUMP_RATIO`, `--seam-max`) the stop is refused.+- **The run-up** is what lies between the rest and the entry, the frames 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 of+ the clip's own cycles (`--run-up-max`) holds something else — another motion, or strides unlike the+ loop's — that the stop would play backwards, and it is refused.+- **Drift**: the clip's body may move across its frame as it sets off, and played back as filmed the stop+ would slide that far into the still. Two frames are laid where the loop stands: the entry on its cell+ (the 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 (the cells' mean coverage). The frames between are moved by a+ straight share of the difference per step of the stop, none at the entry and all of it on the first+ frame: the drift is taken out, and no frame is moved by its own pose. A standing pose is laid on a+ running one by its coverage, so a run that leans or reaches away from it moves the still a few pixels —+ a straight glide over the stop, the same with the drift or without it — and a drift that is not+ straight over the frames shown leaves a little of itself.+- **Speed and length**: `--speed 2` plays every other frame (the still kept last); `--max-frames N`+ takes N frames evenly spaced from the first to the still. Every frame is shown one clip tick.+- **Ghosts**: the frames shown pass the ghost screen every loop path delivers (`interpolation_quality`),+ read on them as filmed, as `video-loop` reads its cut; a ghost is named in the report and a warning, by+ its cell and clip frame, and kept as filmed.++The cells are the loop's cells' scale and placement: the loop's cell sits inside the stop's cell+(`loop_cell_origin`), centred on it with the same bottom unless a frame reaches lower, and the sidecar's+`anchor` is the loop's own pivot there, so a stop drawn at the loop's pivot stands where the loop stood.+"""++from __future__ import annotations++import argparse+import hashlib+import json+import math+import shutil+import sys+from pathlib import Path+from typing import Any++from PIL import Image++from sprite_gen._deps import np+from sprite_gen.spec.runio import atomic_write_text+from sprite_gen.util.gif_utils import save_clean_gif+from sprite_gen.util.resample import resize_cell+from sprite_gen.video import evidence as evidence_mod+from sprite_gen.video import gait_fallback+from sprite_gen.video import loop as loop_mod+from sprite_gen.video import nonloop+from sprite_gen.video.interpolation_quality import ghost_screen+from sprite_gen.video.repair import ALPHA_SOLID, JUMP_RATIO++PROG = "video-stop"+KIND = "stop"+REPORT_KIND = "sprite-gen-video-stop-report"+# Two poses within a third of the loop's step are one pose: a frame of the rest, or one of the loop's frames.+SAME_POSE = 0.35+# A body sets off into its gait within about a cycle; past one and a half of the clip's own cycles the+# frames before the loop hold something else.+RUN_UP_MAX_CYCLES = 1.5+SPEEDS = (1, 2)+MARGIN = 8 # px of transparent room around the bodies, the strip cells' own side and top margin+REGISTER_SEARCH = 0.12 # of the cell height: how far the entry is searched for on its cell+++class StopRefused(ValueError):+ """A stop the clip cannot give; `record` holds what was measured before the refusal."""++ def __init__(self, message: str, record: dict[str, Any]):+ super().__init__(message)+ self.record = record+++def read_loop(meta_path: Path) -> tuple[dict[str, Any], list[Image.Image], str]:+ """The loop's sidecar, its cells and its strip's sha256. A loop the stop cannot leave from is refused."""+ meta_path = Path(meta_path).expanduser()+ if not meta_path.name.endswith(".strip.json"):+ raise SystemExit(f"{PROG}: --loop {meta_path}: a loop strip's sidecar, <name>.strip.json")+ meta = json.loads(meta_path.read_text(encoding="utf-8"))+ strip_path = meta_path.with_name(meta_path.name[: -len(".json")] + ".png")+ data = strip_path.read_bytes()+ strip = Image.open(strip_path).convert("RGBA")+ n, w, h = int(meta["frames"]), int(meta["w"]), int(meta["h"])+ if strip.size != (n * w, h):+ raise SystemExit(f"{PROG}: {strip_path.name} is {strip.size[0]}x{strip.size[1]}, its sidecar says {n * w}x{h}")+ if meta.get("loop") is False:+ raise SystemExit(f"{PROG}: {meta_path.name} plays once (loop false); a stop leaves a loop")+ state = str(meta.get("state") or "")+ if not loop_mod.profile_for(state).gait:+ raise SystemExit(f"{PROG}: {meta_path.name} is a {state or 'state-less'} loop; a stop is cut from a walk or run loop")+ cut = meta.get("source_cut")+ if not isinstance(cut, dict) or not all(k in cut for k in ("source", "start", "length")):+ raise SystemExit(f"{PROG}: {meta_path.name} names no source cut (source_cut: source, start, length); "+ "cut the loop again with video-loop")+ cells = [strip.crop((k * w, 0, (k + 1) * w, h)) for k in range(n)]+ return meta, cells, hashlib.sha256(data).hexdigest()+++def _scaled(path: Path, scale: float) -> Image.Image:+ im = Image.open(path).convert("RGBA")+ return resize_cell(im, (max(1, round(im.width * scale)), max(1, round(im.height * scale))))+++def _box(im: Image.Image) -> tuple[int, int, int, int] | None:+ return im.getchannel("A").point(lambda v: 255 if v >= ALPHA_SOLID else 0).getbbox()+++class Space:+ """One canvas for the loop's cells and the clip's frames, in the loop's cell coordinates (the cell's top left+ at 0, 0): every body laid where it lies there, with room around them, so the cells and the frames are read in+ one place and a pose is measured the same on both (`gait_fallback.poses` cuts each body out about its box, on+ whole pixels)."""++ def __init__(self, laid: list[tuple[Image.Image, tuple[int, int]]], room: int):+ boxes = [(b[0] + x, b[1] + y, b[2] + x, b[3] + y) for im, (x, y) in laid if (b := _box(im)) is not None]+ self.origin = (min(b[0] for b in boxes) - room, min(b[1] for b in boxes) - room)+ self.size = (max(b[2] for b in boxes) + room - self.origin[0], max(b[3] for b in boxes) + room - self.origin[1])++ def lay(self, im: Image.Image, at: tuple[int, int]) -> Image.Image:+ canvas = Image.new("RGBA", self.size, (0, 0, 0, 0))+ canvas.paste(im, (at[0] - self.origin[0], at[1] - self.origin[1]))+ return canvas+++def _alpha(im: Image.Image) -> np.ndarray:+ return np.asarray(im.getchannel("A"), np.float32) / 255+++def _shifted(alpha: np.ndarray, by: tuple[int, int]) -> np.ndarray:+ """`alpha` moved by `by` (x, y) on its own canvas; what falls outside is cut, what comes in is empty."""+ h, w = alpha.shape+ out = np.zeros_like(alpha)+ dx, dy = by+ if abs(dx) >= w or abs(dy) >= h:+ return out+ out[max(0, dy):h + min(0, dy), max(0, dx):w + min(0, dx)] = alpha[max(0, -dy):h - max(0, dy), max(0, -dx):w - max(0, dx)]+ return out+++def _quarter(a: np.ndarray) -> np.ndarray:+ a = np.pad(a, ((0, -a.shape[0] % 4), (0, -a.shape[1] % 4)))+ return a.reshape(a.shape[0] // 4, 4, a.shape[1] // 4, 4).mean(axis=(1, 3))+++def register(cell: Image.Image, frame: Image.Image, reach: int) -> tuple[tuple[int, int], float]:+ """The move that lays `frame` on `cell` (both laid in one `Space`) with the least coverage difference, within+ `reach` px either way: searched on a quarter-size matte, then to the pixel. Returns the move and its difference+ (the mean over the canvas)."""+ target, alpha = _alpha(cell), _alpha(frame)+ qt, qa = _quarter(target), _quarter(alpha)+ q = reach // 4 + 1+ coarse = min(((dx, dy) for dy in range(-q, q + 1) for dx in range(-q, q + 1)),+ key=lambda by: (float(np.abs(_shifted(qa, by) - qt).mean()), abs(by[0]) + abs(by[1])))++ def cost(by: tuple[int, int]) -> float:+ return float(np.abs(_shifted(alpha, by) - target).mean())++ best = min(((coarse[0] * 4 + dx, coarse[1] * 4 + dy) for dy in range(-4, 5) for dx in range(-4, 5)),+ key=lambda by: (cost(by), abs(by[0]) + abs(by[1])))+ return best, round(cost(best), 6)+++def stand_on(cells: list[Image.Image], frame: Image.Image, ground: int, reach: int) -> tuple[tuple[int, int], float]:+ """The move that stands `frame` on `ground` (its lowest body row there) and across where it covers the loop best —+ the cells' mean coverage, where the loop's body is over a cycle — within `reach` px either way: searched on a+ quarter-size matte, then to the pixel. Returns the move and its coverage difference (the mean over the canvas)."""+ box = _box(frame)+ dy = ground - (box[3] - 1)+ target, alpha = np.mean([_alpha(c) for c in cells], axis=0), _shifted(_alpha(frame), (0, dy))+ qt, qa = _quarter(target), _quarter(alpha)+ q = reach // 4 + 1+ coarse = min(range(-q, q + 1), key=lambda v: (float(np.abs(_shifted(qa, (v, 0)) - qt).mean()), abs(v)))++ def cost(dx: int) -> float:+ return float(np.abs(_shifted(alpha, (dx, 0)) - target).mean())++ dx = min(range(coarse * 4 - 4, coarse * 4 + 5), key=lambda v: (cost(v), abs(v)))+ return (dx, dy), round(cost(dx), 6)+++def 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]:+ """Rest, entry, the cell left from, the seam 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` steps, or the run-up is longer than `run_up_max` cycles."""+ n = len(cells)+ thumbs = gait_fallback.poses(cells + frames, gait_fallback.subject_boxes(cells + frames))+ pc, pf = thumbs[:n], thumbs[n:]++ def dist(a: np.ndarray, b: np.ndarray) -> float:+ return float(np.nanmean(np.abs(a - b)))++ # The clip's own step, over the loop's window as filmed: the frames the stop plays are a step apart.+ step = float(np.median([dist(pf[j], pf[j + 1]) for j in range(start, min(start + length, len(pf) - 1))]))+ cell_step = float(np.median([dist(pc[k], pc[(k + 1) % n]) for k in range(n)]))+ if not step > 0:+ raise StopRefused(f"{PROG}: the clip does not move in the loop's window (median step 0); there is no gait to stop", {})+ to_rest = [dist(p, pf[0]) / step for p in pf]+ near = [min((dist(p, q) / step, k) for k, q in enumerate(pc)) for p in pf]+ rest_end = 0+ while rest_end + 1 < len(pf) and to_rest[rest_end + 1] <= SAME_POSE:+ rest_end += 1+ record: dict[str, Any] = {+ "step": round(step, 6), "loop_cell_step": round(cell_step / step, 4), "same_pose": SAME_POSE,+ "rest": {"end": rest_end},+ "to_rest": [round(v, 4) for v in to_rest],+ "to_loop": [[round(v, 4), k] for v, k in near],+ }+ end = min(len(pf), start + length)+ entry = next((j for j in range(rest_end + 1, end) if near[j][0] <= SAME_POSE), None)+ if entry is None:+ raise StopRefused(f"{PROG}: no clip frame after the rest (frame {rest_end}) comes within {SAME_POSE} steps of a loop "+ f"cell before the loop's window ends (frame {end - 1}); these frames are not the loop's clip", record)+ cell = near[entry][1]+ played = list(range(entry - 1, rest_end, -1)) + [0]+ seam = dist(pc[cell], pf[played[0]]) / step+ run_up = entry - 1 - rest_end+ record.update(entry={"frame": entry, "match": round(near[entry][0], 4), "from_cell": cell},+ seam={"steps": round(seam, 4), "from_cell": cell, "into_frame": played[0], "max": seam_max},+ run_up={"frames": run_up, "cycles": round(run_up / length, 3), "max_cycles": run_up_max},+ played=played)+ refused = []+ if seam > seam_max:+ refused.append(f"the seam from loop cell {cell} into clip frame {played[0]} is {seam:.2f} steps, past the jump line "+ f"{seam_max} (--seam-max): the clip reaches the loop (frame {entry}) by a jump")+ if run_up > run_up_max * length:+ refused.append(f"the head holds {run_up} frames ({run_up / length:.2f} cycles) between the rest (frame {rest_end}) and "+ f"the loop's frames (frame {entry}), more than a setting-off ({run_up_max} cycles, --run-up-max): "+ "another motion, or strides unlike the loop's, that the stop would play backwards")+ if refused:+ raise StopRefused(f"{PROG}: " + "; ".join(refused), record)+ return record+++def place(cells: list[Image.Image], frames: list[Image.Image], found: dict[str, Any], *, reach: int+ ) -> tuple[dict[int, tuple[int, int]], dict[str, Any]]:+ """How far each played frame is moved from where it is laid (cells and frames laid in one `Space`): the module's+ "Drift". Returns {frame: (dx, dy)} and the record, in the Space's pixels."""+ entry, cell = found["entry"]["frame"], found["entry"]["from_cell"]+ leave, mismatch = register(cells[cell], frames[entry], reach)+ boxes = [_box(c) for c in cells]+ if any(b is None for b in boxes) or _box(frames[0]) is None:+ raise StopRefused(f"{PROG}: a loop cell or the clip's first frame is empty", found)+ ground = max(b[3] - 1 for b in boxes) # the loop's lowest body row: its feet on the ground+ # The clip may have carried its body far across its frame: the still is looked for over a cell's width.+ end, end_mismatch = stand_on(cells, frames[0], ground, cells[0].width)+ # A straight share per frame shown, the stop's own steps: the still's rest frames, never shown, take none.+ played = found["played"]+ moves = {j: tuple(int(round(a + (b - a) * (i + 1) / len(played))) for a, b in zip(leave, end)) for i, j in enumerate(played)}+ return moves, {"leave": {"by": list(leave), "cell": cell, "mismatch": mismatch},+ "stand": {"by": list(end), "mismatch": end_mismatch},+ "clip_px": [b - a for a, b in zip(leave, end)], "ground": ground}+++def _cells(frames: list[Image.Image], moves: list[tuple[int, int]], loop_rect: tuple[int, int, int, int]+ ) -> tuple[list[Image.Image], tuple[int, int, int, int]]:+ """The stop's cells: every shown frame moved, in one cell that holds them all and the loop's own cell+ (`loop_rect`), centred on it across, with no room below the lowest body (as a strip's cells). Returns the cells+ and the stop cell's rectangle, both rectangles in the frames' canvas."""+ boxes = [(b[0] + x, b[1] + y, b[2] + x, b[3] + y) for im, (x, y) in zip(frames, moves) if (b := _box(im)) is not None]+ l0, t0, r0, b0 = loop_rect+ side = max(0, l0 - (min(b[0] for b in boxes) - MARGIN), max(b[2] for b in boxes) + MARGIN - r0)+ rect = (l0 - side, min(t0, min(b[1] for b in boxes) - MARGIN), r0 + side, max(b0, max(b[3] for b in boxes)))+ size = (rect[2] - rect[0], rect[3] - rect[1])+ out = []+ for im, (x, y) in zip(frames, moves):+ canvas = Image.new("RGBA", size, (0, 0, 0, 0))+ canvas.paste(im, (x - rect[0], y - rect[1]))+ a = np.asarray(canvas).copy()+ a[a[..., 3] == 0] = 0+ out.append(Image.fromarray(a, "RGBA"))+ return out, rect+++def pick(played: list[int], *, speed: int, max_frames: int | None) -> list[int]:+ """The frames shown: every `speed`-th from the first (the still kept last), then at most `max_frames` of+ them evenly spaced from the first to the still."""+ shown = played[::speed]+ if shown[-1] != played[-1]:+ shown.append(played[-1])+ if max_frames is not None and len(shown) > max_frames:+ shown = [shown[k] for k in nonloop.samples(len(shown), max_frames)]+ return shown+++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]:+ """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:+ raise SystemExit(f"{PROG}: --speed {speed}: 1 or 2")+ if not (math.isfinite(seam_max) and seam_max > 0 and math.isfinite(run_up_max) and run_up_max >= 0):+ raise SystemExit(f"{PROG}: --seam-max is a positive number and --run-up-max a number of cycles, 0 or more")+ if max_frames is not None and max_frames < 2:+ raise SystemExit(f"{PROG}: --max-frames {max_frames}: at least 2 (a stop shows the frame it leaves on and the still)")+ out_dir = Path(out_dir).expanduser().resolve()+ target = Path(report_path or out_dir / f"{name}.stop.report.json").expanduser().resolve()+ meta, cells, strip_sha = read_loop(loop_meta)+ cut = meta["source_cut"]+ fps = float(fps or cut["source"].get("fps") or 24.0)+ files = sorted(Path(frames_dir).expanduser().resolve().glob("*.png"))+ start, length = int(cut["start"]), int(cut["length"])+ if len(files) < start + length:+ raise SystemExit(f"{PROG}: {frames_dir} holds {len(files)} frames; the loop was cut from frames {start} to "+ f"{start + length - 1} of its clip — give the clip's keyed frames (video-frames …/keyed)")+ identity = evidence_mod.source_identity(files, fps)+ same_source = identity["sha256"] == cut["source"].get("sha256")+ base: dict[str, Any] = {+ "kind": REPORT_KIND, "frames_dir": str(Path(frames_dir).expanduser().resolve()), "loop": str(Path(loop_meta).expanduser().resolve()),+ "loop_strip_sha256": strip_sha, "producer": evidence_mod.engine_identity(), "fps": fps,+ "source": {**identity, "loop_source_sha256": cut["source"].get("sha256"), "same_as_loop": same_source},+ "loop_cut": {"start": start, "length": length, "cells": len(cells), "state": meta.get("state")},+ "speed": speed, "max_frames": max_frames, "same_pose": SAME_POSE, "seam_max": seam_max, "run_up_max_cycles": run_up_max,+ }+ scale = float(meta["scale"])+ w, h = int(meta["w"]), int(meta["h"])+ scaled = [_scaled(f, scale) for f in files[: min(len(files), start + length + length // 2 + 1)]]+ # Where each frame lies on the loop's cells before it is registered: the strip's own crop and scale, or, for a+ # strip that records no crop (cut about its feet), its body's bottom centre on the cells'.+ rect = meta.get("source_rect")+ if rect:+ guess = (round(-rect[0] * scale), round(-rect[1] * scale))+ else:+ b = _box(scaled[0]) or (0, 0, 0, 0)+ guess = (round(w / 2 - (b[0] + b[2]) / 2), h - b[3])+ reach = max(8, round(REGISTER_SEARCH * h))+ space = Space([(c, (0, 0)) for c in cells] + [(f, guess) for f in scaled], reach + MARGIN)+ laid_cells = [space.lay(c, (0, 0)) for c in cells]+ laid = [space.lay(f, guess) for f in scaled]+ try:+ found = find_stop(laid_cells, laid, start=start, length=length, seam_max=seam_max, run_up_max=run_up_max)+ moves, drift = place(laid_cells, laid, found, reach=reach)+ except StopRefused as exc:+ loop_mod.write_loop_report(target, {**base, **exc.record, "status": "failed", "error": str(exc)})+ raise SystemExit(str(exc)) from exc+ shown = pick(found["played"], speed=speed, max_frames=max_frames)+ loop_rect = (-space.origin[0], -space.origin[1], w - space.origin[0], h - space.origin[1])+ stop_cells, rect = _cells([laid[j] for j in shown], [moves[j] for j in shown], loop_rect)+ cw, ch = stop_cells[0].size+ if cw * len(stop_cells) > loop_mod.STRIP_MAX_WIDTH:+ error = (f"{PROG}: {len(stop_cells)} cells of {cw} px make a strip {cw * len(stop_cells)} px wide, over "+ f"{loop_mod.STRIP_MAX_WIDTH}; pass --max-frames or --speed 2")+ loop_mod.write_loop_report(target, {**base, **found, "drift": drift, "status": "failed", "error": error})+ raise SystemExit(error)+ origin = [loop_rect[0] - rect[0], loop_rect[1] - rect[1]]+ pivot = meta.get("anchor") or [w / 2, h]+ last = _box(stop_cells[-1])+ # Read as filmed, at the keyed frames' own size, as video-loop reads its cut: a part-covered band is a+ # number of pixels thick, and scaled down a ghost's band falls under it.+ screen = ghost_screen([Image.open(files[j]).convert("RGBA") for j in shown])+ for g in screen.get("ghosts", []):+ g["clip_frame"] = shown[g["frame"]]+ delay = round(1000 / fps, 2)+ strip_meta = {+ "frames": len(stop_cells), "w": cw, "h": ch, "delay_ms": delay, "kind": KIND, "state": KIND,+ "loop": False, "hold_last": True, "end_frame": len(stop_cells) - 1, "events": [],+ "anchor": [round(pivot[0] + origin[0], 2), round(pivot[1] + origin[1], 2)], "loop_cell_origin": origin,+ "body_h": meta.get("body_h"), "body_src_h": meta.get("body_src_h"), "scale": meta.get("scale"),+ "cycle_frames": len(stop_cells), "cycle_seconds": round(len(stop_cells) / fps, 4),+ "from_loop": {"strip_sha256": strip_sha, "state": meta.get("state"), "frames": len(cells), "w": w, "h": h,+ "from_cell": found["entry"]["from_cell"]},+ "source_cut": {"source": identity, "frames": shown, "entry": found["entry"]["frame"], "rest_end": found["rest"]["end"]},+ "speed": speed, "seam_steps": found["seam"]["steps"],+ }+ out_dir.mkdir(parents=True, exist_ok=True)+ strip = Image.new("RGBA", (cw * len(stop_cells), ch), (0, 0, 0, 0))+ for k, im in enumerate(stop_cells):+ strip.paste(im, (k * cw, 0))+ strip_path = out_dir / f"{name}.strip.png"+ strip.save(strip_path)+ atomic_write_text(out_dir / f"{name}.strip.json", json.dumps(strip_meta, indent=2) + "\n")+ gif_path, webp_path = out_dir / f"{name}.gif", out_dir / f"{name}.webp"+ ms = max(20, round(1000 / fps))+ save_clean_gif(stop_cells, gif_path, duration_ms=ms, loop=None, alpha_threshold=128)+ loop_mod.write_webp(stop_cells, webp_path, delay_ms=ms, workdir=out_dir / ".webp-frames", loop=1)+ shutil.rmtree(out_dir / ".webp-frames", ignore_errors=True)+ shown_runs = loop_mod.shown_runs(stop_cells)+ gif = loop_mod.verify_animation(gif_path, expect_frames=shown_runs, check_stale=False, expected_loop=None)+ webp = loop_mod.verify_animation(webp_path, expect_frames=shown_runs, check_stale=True, expected_loop=1)+ payload = {+ **base, **found, "status": "passed",+ "drift": {**drift, "ground_in_cell": drift["ground"] - rect[1],+ "ends_on_ground": last is not None and last[3] - 1 == drift["ground"] - rect[1]},+ "shown": shown, "frames_shown": len(shown), "seconds": round(len(shown) / fps, 4),+ "ghost_screen": screen,+ "strip": {"path": str(strip_path), **strip_meta}, "gif": gif, "webp": webp,+ }+ loop_mod.write_loop_report(target, payload)+ if not same_source:+ print(f"{PROG}: warning: the frames in {frames_dir} are not byte for byte the keyed frames the loop was cut from "+ f"(source {identity['sha256'][:12]}, the loop's {str(cut['source'].get('sha256'))[:12]}): keyed again; the entry "+ "is found by pose, so look at the stop", file=sys.stderr)+ for g in screen.get("ghosts", []):+ print(f"{PROG}: warning: cell {g['frame']} (clip frame {g['clip_frame']}) carries a part-covered band over "+ f"{100 * g['ghost']:.2f} % of its body — a filmed ghost, kept as filmed", file=sys.stderr)+ if not screen["reads"]:+ print(f"{PROG}: warning: the ghost screen does not read this stop — {screen['why']}", file=sys.stderr)+ payload["report"] = str(target)+ return payload+++def add_arguments(parser: argparse.ArgumentParser) -> None:+ parser.add_argument("--frames-dir", type=Path, required=True,+ help="the clip's keyed frames, every one from the first (video-frames …/keyed): the clip the loop was cut from")+ parser.add_argument("--loop", type=Path, required=True,+ help="the walk or run loop the stop leaves, its <name>.strip.json (as cut or aligned; the strip PNG beside it)")+ parser.add_argument("--out-dir", type=Path, required=True)+ 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("--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)")+ parser.add_argument("--report", type=Path, help="report path (default <out-dir>/<name>.stop.report.json)")+++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(kwargs.get("seam_max") or JUMP_RATIO),+ 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"],+ "seam_steps": payload["seam"]["steps"], "run_up": payload["run_up"], "drift": payload["drift"],+ "ghosts": [g["clip_frame"] for g in payload["ghost_screen"].get("ghosts", [])], "report": payload["report"]},+ ensure_ascii=False, indent=2))+ return 0+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(prog=f"sprite-gen {PROG}", description=__doc__)+ add_arguments(parser)+ return run(**vars(parser.parse_args(argv)))+++if __name__ == "__main__":+ raise SystemExit(main())