Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(video-loop): --anchor body closes a gait's wrap with one ramp
Soohong Kim9d91fd97607b
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 3059f45..e557ab4 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -69,7 +69,9 @@ ONE_SHOT_MIN_LEN = 4 # a one-shot's length is the clip's own fact; only a degenGAIT_DOUBLE_TOL = 0.25GAIT_DOUBLE_SEARCH = 3 # frames either side of 2x the step where the full gait's own minimum may sitGAIT_NEAR_EXACT_STEP_FRACTION = 0.10 # no ambiguity extension when repeat error is tiny compared with a playback step-ANCHOR_MODES = ("none", "feet")+ANCHOR_MODES = ("none", "feet", "body")+BODY_ANCHOR_BAND = 0.6 # --anchor body reads the wrap offset from the top 60 % of the first frame's box: head and torso, not the legs+BODY_ANCHOR_SEARCH = 24 # px either side searched for the last frame's horizontal offset against the firstFOOT_BAND = 0.08 # fraction of the frame's own height, measured up from its lowest opaque row@@ -499,6 +501,53 @@ def drift_reference(frames: list[Image.Image], boxes: list[tuple[int, int, int,return [float(r) for r in ref], abs(slope * (len(frames) - 1)), float(np.ptp(feet - trend))+def body_wrap_offset(frames: list[Image.Image], *, band: float = BODY_ANCHOR_BAND, search: int = BODY_ANCHOR_SEARCH) -> int:+ """Horizontal offset (px) that best lays the LAST frame's head and torso over the FIRST's.++ A gait clip drifts a few pixels over one cycle, and the last-to-first wrap shows that+ drift as a sideways jump. The legs are mid-stride and the tail mid-swing at both ends,+ so they cannot say where the body is; the top of the first frame's box (head, torso,+ `band` of its height) can. Whole-pixel registration over that region, over a small+ horizontal search, is the one measurement `--anchor body` makes — it is then spread+ as a ramp across the cycle, never applied frame by frame (per-frame fitting turns a+ head bob into a full-body shiver, measured 2026-09-22)."""+ if len(frames) < 2:+ return 0+ first = np.asarray(frames[0], dtype=np.float32)+ last = np.asarray(frames[-1], dtype=np.float32)+ alpha = first[:, :, 3] >= 8+ rows = np.where(alpha.any(axis=1))[0]+ cols = np.where(alpha.any(axis=0))[0]+ if len(rows) == 0 or len(cols) == 0:+ return 0+ top, bottom, left, right = rows[0], rows[-1], cols[0], cols[-1]+ mask = np.zeros_like(alpha)+ mask[top : top + max(1, int((bottom - top) * band)), left : right + 1] = True+ ref = first[mask]++ def cost(dx: int) -> float:+ return float(np.abs(ref - np.roll(last, dx, axis=1)[mask]).mean())++ return min(range(-search, search + 1), key=cost)+++def ramp_frames(frames: list[Image.Image], wrap_dx: int) -> list[Image.Image]:+ """Shift frame k by round(wrap_dx * k / L) so the cycle's end returns to its start."""+ L = len(frames)+ if wrap_dx == 0 or L < 2:+ return frames+ out = []+ for k, im in enumerate(frames):+ dx = int(round(wrap_dx * k / L))+ if dx == 0:+ out.append(im)+ continue+ shifted = Image.new("RGBA", im.size, (0, 0, 0, 0))+ shifted.paste(im, (dx, 0))+ out.append(shifted)+ return out++def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS, max_height: int = STRIP_MAX_HEIGHT, max_width: int = STRIP_MAX_WIDTH, cycle_seconds: float, body_height: int | None = None, anchor: str = "none", kind: str = "periodic") -> tuple[Image.Image, dict[str, Any]]:"""Union-crop (no bottom pad so feet meet the floor), scale, bottom-align, tile horizontally.@@ -685,8 +734,11 @@ def run_loop(length: int | None = None,strip_height: int = STRIP_MAX_HEIGHT,body_height: int | None = None,- anchor: str = "none",+ anchor: str | None = None,) -> dict[str, Any]:+ if anchor is None:+ # gaits drift a few pixels over a cycle and the wrap shows it; in-place states do not+ anchor = "body" if profile_for(state).gait else "none"if anchor not in ANCHOR_MODES:raise SystemExit(f"video-loop: unknown --anchor {anchor!r}; expected one of {', '.join(ANCHOR_MODES)}")if cycle_mode not in CYCLE_MODES:@@ -766,7 +818,20 @@ def run_loop(frames.append(im)cycle_seconds = L / fps- strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor=anchor, kind=str(cycle.get("kind") or "periodic"))+ wrap_dx = 0+ if anchor == "body":+ wrap_dx = body_wrap_offset(frames)+ frames = ramp_frames(frames, wrap_dx)+ for k, im in enumerate(frames):+ im.save(cycle_dir / f"frame-{k:03d}.png")+ strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"))+ if anchor == "body":+ strip_meta["foot_anchor"] = "body"+ strip_meta["wrap_dx_px"] = wrap_dx+ # the wrap as it now plays: last ramped frame -> first, against an ordinary step+ Dr = distance_matrix(sorted(cycle_dir.glob("frame-*.png")))+ inner = float(np.mean([Dr[k, k + 1] for k in range(len(frames) - 1)])) if len(frames) > 1 else 0.0+ strip_meta["seam_ratio_after_anchor"] = round(float(Dr[len(frames) - 1, 0]) / inner, 4) if inner > 0 else None# The GIF/WebP are cut from the strip's cells. A cycle longer than the cell cap was# subsampled there, so asking for more frames than cells repeats cells back to back# and the GIF writer merges the identical neighbours — the file then holds fewer@@ -853,7 +918,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--length", type=int, help="fixed cut: cycle length in frames (with --cycle fixed)")parser.add_argument("--strip-height", type=int, default=STRIP_MAX_HEIGHT, help=f"cell/strip/GIF height cap in px (default {STRIP_MAX_HEIGHT}); the cycle is scaled down to fit, and never up unless --body-height asks for it")parser.add_argument("--body-height", type=int, help="scale so the STANDING height (tallest floor-contact frame) is this many px — the same value across states gives the same character size; --strip-height stays the cap")- parser.add_argument("--anchor", choices=ANCHOR_MODES, default="none", help="feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; reports drift_px and foot_sway_px")+ parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")parser.add_argument("--name", default="loop", help="basename for strip/gif/webp outputs")parser.add_argument("--report", type=Path)@@ -867,7 +932,7 @@ def run(**kwargs: object) -> int:cycle_mode=str(kwargs.get("cycle") or "auto"), gif_fps=float(kwargs.get("gif_fps") or GIF_FPS_DEFAULT),start=kwargs.get("start"), length=kwargs.get("length"), strip_height=int(kwargs.get("strip_height") or STRIP_MAX_HEIGHT), # type: ignore[arg-type]body_height=kwargs.get("body_height"), # type: ignore[arg-type]- anchor=str(kwargs.get("anchor") or "none"),+ anchor=kwargs.get("anchor"), # None resolves by state inside run_loop)summary = {k: payload[k] for k in ("state", "frames_total", "window", "cycle_seconds", "n_out", "delay_ms", "resampled_seam_ratio", "specks_dropped", "report")}summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio", "review_recommended", "half_period_guard")}diff --git a/tests/video/test_body_anchor.py b/tests/video/test_body_anchor.pynew file mode 100644index 0000000..63e5b40--- /dev/null+++ b/tests/video/test_body_anchor.py@@ -0,0 +1,76 @@+"""`--anchor body`: one wrap measurement, spread as a ramp.++A gait clip drifts a few pixels over one cycle and the last-to-first wrap shows it+as a sideways jump. The body anchor measures the last frame's head-and-torso offset+against the first once and shifts frame k by that offset times k/L. It never fits+frame by frame: that turns a head bob into a full-body shiver.+"""+from __future__ import annotations++import json+from pathlib import Path++import numpy as np+import pytest+from PIL import Image++from sprite_gen.video import loop+++def _walker(x: int, leg: int, w: int = 160, h: int = 160) -> Image.Image:+ """A body (head + torso) at column x with one leg whose x differs per frame."""+ im = Image.new("RGBA", (w, h), (0, 0, 0, 0))+ px = im.load()+ for yy in range(20, 40): # head+ for xx in range(x + 10, x + 30):+ px[xx, yy] = (200, 120, 60, 255)+ for yy in range(40, 110): # torso+ for xx in range(x, x + 40):+ px[xx, yy] = (60, 90, 200, 255)+ for yy in range(110, 150): # leg, swinging+ for xx in range(x + leg, x + leg + 10):+ px[xx, yy] = (30, 30, 30, 255)+ return im+++def _cycle(drift: int, n: int = 12) -> list[Image.Image]:+ return [_walker(40 + round(drift * k / n), leg=(k * 3) % 30) for k in range(n)]+++def test_wrap_offset_reads_the_body_not_the_leg():+ frames = _cycle(drift=6)+ # the leg alone moved 33 px between first and last; the body moved 5-6+ assert loop.body_wrap_offset(frames) in (-6, -5)+++def test_ramp_spreads_the_offset_and_closes_the_wrap():+ frames = _cycle(drift=6)+ dx = loop.body_wrap_offset(frames)+ ramped = loop.ramp_frames(frames, dx)+ assert ramped[0] is frames[0]+ # after the ramp the last frame's body sits over the first's+ assert abs(loop.body_wrap_offset(ramped)) <= 1+++def test_zero_offset_leaves_frames_untouched():+ frames = _cycle(drift=0)+ assert loop.body_wrap_offset(frames) == 0+ assert loop.ramp_frames(frames, 0) is frames+++def test_run_loop_defaults_to_body_for_gaits_and_none_otherwise(tmp_path: Path):+ keyed = tmp_path / "keyed"+ keyed.mkdir()+ for k, im in enumerate(_cycle(drift=6, n=24) * 3):+ im.save(keyed / f"frame-{k + 1:04d}.png")+ walk = loop.run_loop(keyed, tmp_path / "walk", fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=1000.0, name="w", report_path=tmp_path / "w.json", cycle_mode="fixed", start=0, length=24)+ assert walk["strip"]["foot_anchor"] == "body" and walk["strip"]["wrap_dx_px"] in (-6, -5)+ idle = loop.run_loop(keyed, tmp_path / "idle", fps=24.0, state="idle", min_len=None, max_len=None, n_out=None, seam_max=1000.0, name="i", report_path=tmp_path / "i.json", cycle_mode="fixed", start=0, length=24)+ assert idle["strip"]["foot_anchor"] == "none" and "wrap_dx_px" not in idle["strip"]+ feet = loop.run_loop(keyed, tmp_path / "feet", fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=1000.0, name="f", report_path=tmp_path / "f.json", cycle_mode="fixed", start=0, length=24, anchor="feet")+ assert feet["strip"]["foot_anchor"] == "feet" and "wrap_dx_px" not in feet["strip"]+++def test_unknown_anchor_is_refused():+ with pytest.raises(SystemExit):+ loop.run_loop(Path("/nonexistent"), Path("/tmp/x"), fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=2.0, name="x", report_path=None, anchor="head")