Skip to content

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.py
index 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.py
index 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_align
from sprite_gen.video import follow as video_follow
from sprite_gen.video import follow_inspect as video_follow_inspect
from sprite_gen.video import set_sheet as video_set_sheet
+from sprite_gen.video import stop as video_stop
from sprite_gen.video import compare as video_compare
from sprite_gen.video import restoration as video_restoration
from sprite_gen.video import source as video_source
@@ -430,6 +431,11 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
video_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.py
index 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) -> dic
return {**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.py
new file mode 100644
index 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())