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-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.py
index 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 degen
GAIT_DOUBLE_TOL = 0.25
GAIT_DOUBLE_SEARCH = 3 # frames either side of 2x the step where the full gait's own minimum may sit
GAIT_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 first
FOOT_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.py
new file mode 100644
index 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")