Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

fix(video-loop): --anchor feet removes drift only, no longer sways a walk

Soohong Kim51e4a902cfdc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5bc7be6..d5d5c16 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
+- `video-loop --anchor feet` no longer sways a walk. It pinned every cell on that frame's own foot line, which in an in-place gait jumps to the planted foot each step, so a body that stood still lurched back and forth by the stride. It now fits a straight line to the body's centre across the cycle and removes only that drift, keeping the step as performed; every cell stands on the mean foot line. `drift_px` now means the drift removed, and the strip meta adds `foot_sway_px` (the planted foot's in-gait movement, reported but not erased). Default `none` is unchanged.
- `video-loop` gait half-period guard: a `walk`/`run` period shorter than the state's floor (`LoopProfile.min_seconds`: 0.6 s / 0.35 s) is treated as one step of a two-step gait and doubled when the doubled period repeats within 25 % of it — the case where a costume hides the legs and the half period dips as deep as the full one, which the depth rule alone returned as a one-legged loop. The report carries `cycle.half_period_guard` (`applied`, `from`, `to`, depth ratio, or `below_floor` + why it was left alone). `--min-len` still overrides.
- `video-loop` one-shot detection no longer refuses an excursion shorter than the periodic window's lower edge; only a cut under 4 frames or longer than the clip is refused. Short performed actions (a set-down, a nod) come back as the frames they are.
- `video-loop --anchor feet` (also `video-set --anchor`): re-centre every strip cell on that frame's own foot line so a subject the model walked across an "in-place" canvas stops sliding once per cycle. Strip meta gains `foot_anchor`, `drift_px` and `foot_x`, and declares the spec loader's `anchor` as `[foot_x, h]` so scenes stand the sprite on its feet; the video-set table row carries `drift_px`. Default `none` keeps existing output byte-identical.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 6d24c6b..a97bf3c 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -251,11 +251,22 @@ set-down, a nod, a flinch come back as the frames they are.
subject across an in-place canvas, and the union crop that `build_strip` uses keeps that
drift inside every cell, so a runtime that places the strip by its cell box sees the body
slide back and forth once per cycle. `--anchor feet` (on `video-loop` and `video-set`)
-measures each cycle frame's foot line — the mean x of the opaque pixels in the lowest
-`FOOT_BAND` (8 %) of that frame's own bbox — and re-centres every cell on it. The strip
-meta gains `foot_anchor`, `drift_px` (how far the foot line wandered across the cycle, in
-source pixels, before alignment) and `foot_x` (the foot column inside every cell), plus the spec loader's `anchor`
-as `[foot_x, h]` so a scene stands the sprite on its foot line; `video-set`'s table row
-carries `drift_px`. The default stays `none`: existing strips do
-not change, and `drift_px` is 0 when it was not measured.
+removes that drift and nothing else. Drift is a slow translation and a gait is periodic,
+so a straight line fitted to the body's centre (the mean x of every opaque pixel) across
+the cycle carries the drift and not the step. Each cell is shifted by that line only,
+so every cell stands on the same **mean** foot line — the mean x of the opaque pixels in
+the lowest `FOOT_BAND` (8 %) of each frame's bbox, averaged over the cycle.
+
+Do not pin each frame's own foot line. In an in-place walk one foot is lifted out of the
+floor band every step, so the per-frame foot line jumps to the planted foot by about the
+stride; pinning it makes a body that stood still lurch back and forth by that much. The
+first version of this option did exactly that, and the synthetic lifting-leg walker in
+`tests/video` pins the rule.
+
+The strip meta gains `foot_anchor`, `drift_px` (the drift removed across the cycle, in
+source pixels), `foot_sway_px` (how far the planted foot moves within the gait — kept, only
+reported) and `foot_x` (the mean foot column inside every cell), plus the spec loader's
+`anchor` as `[foot_x, h]` so a scene stands the sprite on its foot line; `video-set`'s
+table row carries `drift_px`. The default stays `none`: existing strips do not change,
+and `drift_px` / `foot_sway_px` are 0 when they were not measured.
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index e470fbc..ed8e28c 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -207,7 +207,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--concurrency", type=int, default=3, help="parallel clip generations (starts are staggered regardless)")
parser.add_argument("--start-gap", type=float, default=START_GAP_SECONDS, help="seconds between clip request starts")
parser.add_argument("--shape", choices=canvas_mod.SHAPES, help="force one canvas shape for every state (e.g. wide for a costume or arms that leave a 1:1 frame)")
- parser.add_argument("--anchor", choices=loop_mod.ANCHOR_MODES, default="none", help="feet: re-centre strip cells on the foot line (undoes in-canvas drift)")
+ parser.add_argument("--anchor", choices=loop_mod.ANCHOR_MODES, default="none", help="feet: remove in-canvas drift so every cell stands on the mean foot line")
parser.add_argument("--force", action="store_true", help="regenerate clips that already exist")
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 91066e0..1da3c93 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -295,6 +295,32 @@ def foot_centre(image: Image.Image, box: tuple[int, int, int, int]) -> float:
return float(box[0] + xs.mean())
+def body_centre(image: Image.Image, box: tuple[int, int, int, int]) -> float:
+ """Mean x of every opaque pixel — the whole body's mass, which a gait swings far less
+ than it swings the foot line."""
+ a = np.asarray(image.getchannel("A"))[box[1] : box[3], box[0] : box[2]]
+ xs = np.nonzero(a >= 8)[1]
+ return float(box[0] + xs.mean()) if xs.size else (box[0] + box[2]) / 2
+
+
+def drift_reference(frames: list[Image.Image], boxes: list[tuple[int, int, int, int]]) -> tuple[list[float], float, float]:
+ """Per-frame alignment reference for `--anchor feet`.
+
+ Drift is a slow translation; a gait is periodic. The cycle holds whole periods, so a
+ straight line fitted to the body's centre across it carries the drift and not the
+ step. Only that line is removed: the reference is the mean foot line riding the
+ drift. Pinning each frame's own foot line instead pins the planted foot — which
+ changes every step — and makes a body that stood still lurch by the stride.
+ Returns (reference x per frame, drift removed in px, foot-line sway in px)."""
+ feet = np.array([foot_centre(im, b) for im, b in zip(frames, boxes)])
+ centres = np.array([body_centre(im, b) for im, b in zip(frames, boxes)])
+ t = np.arange(len(frames), dtype=float)
+ slope = float(np.polyfit(t, centres, 1)[0]) if len(frames) > 1 else 0.0
+ trend = slope * t
+ ref = float(np.mean(feet - trend)) + trend
+ return [float(r) for r in ref], abs(slope * (len(frames) - 1)), float(np.ptp(feet - trend))
+
+
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") -> tuple[Image.Image, dict[str, Any]]:
"""Union-crop (no bottom pad so feet meet the floor), scale, bottom-align, tile horizontally.
@@ -325,10 +351,10 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,
fit = max_height / (bottom - top)
scale = min(1.0, fit) if body_height is None else min(fit, body_height / body_src)
# --anchor feet: the model may have walked the subject across an "in-place" canvas;
- # a union crop keeps that drift inside every cell. Re-centre each frame on its own
- # foot line instead, and report how far the feet wandered before alignment.
- feet = [foot_centre(im, b) for im, b in zip(frames, boxes)] if anchor == "feet" else None
- drift_px = round(max(feet) - min(feet)) if feet else 0
+ # a union crop keeps that drift inside every cell. Remove the drift (see
+ # drift_reference) so every cell stands on the same mean foot line, and report it.
+ feet, drift, sway = drift_reference(frames, boxes) if anchor == "feet" else (None, 0.0, 0.0)
+ drift_px = round(drift)
if feet:
lead = max(fc - b[0] for fc, b in zip(feet, boxes)) + 8
trail = max(b[2] - fc for fc, b in zip(feet, boxes)) + 8
@@ -367,7 +393,8 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,
"top_margin_px": top,
"body_height_target": body_height,
"foot_anchor": anchor, # "none" | "feet" — how the cells were aligned
- "drift_px": drift_px, # source px the foot line wandered across the cycle (0 when not measured)
+ "drift_px": drift_px, # source px of slow in-canvas drift removed across the cycle (0 when not measured)
+ "foot_sway_px": round(sway), # source px the planted foot moves within the gait, kept as is (0 when not measured)
"foot_x": round(lead * scale) if feet else None, # x of the foot line inside every cell
}
if feet:
@@ -595,7 +622,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: re-centre every cell on its own foot line (undoes in-canvas drift) and report drift_px")
+ 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("--name", default="loop", help="basename for strip/gif/webp outputs")
parser.add_argument("--report", type=Path)
diff --git a/tests/video/test_gait_guard_anchor_wide.py b/tests/video/test_gait_guard_anchor_wide.py
index 65ee184..ce8679f 100644
--- a/tests/video/test_gait_guard_anchor_wide.py
+++ b/tests/video/test_gait_guard_anchor_wide.py
@@ -3,7 +3,7 @@
* gait half-period guard — a walker whose two half-strides are pixel-identical must
still come back as a two-step period;
* one-shot detection is not bound by the periodic window's lower edge;
-* `--anchor feet` re-centres drifting cells and reports the drift;
+* `--anchor feet` removes in-canvas drift (not the step) and reports it;
* raised-limb states get a wide canvas, and video-set can force shape/anchor.
"""
from __future__ import annotations
@@ -209,3 +209,65 @@ def test_cheer_motion_template_names_no_limbs() -> None:
text = batch_mod.MOTION_TEXT["cheer"] + batch_mod.MOTION_TEXT["wave"]
for limb in ("arm", "leg", "knee", "hand", "foot", "wing"):
assert limb not in text.lower()
+
+
+def _lifting_walker(tmp_path: Path, *, period: int, n: int, drift_per_frame: float = 0.0, size=(220, 64)) -> list[Path]:
+ """A body that stays put while its legs take turns: each half of the period one leg
+ stands on the floor and the other is lifted clear of the lowest rows. The mean x of
+ the floor band therefore jumps from one foot to the other every step even though the
+ body never moves — the in-place walk a video model actually returns."""
+ d = tmp_path / "keyed"
+ d.mkdir(exist_ok=True)
+ files = []
+ for t in range(n):
+ im = Image.new("RGBA", size, (0, 0, 0, 0))
+ cx = 60 + t * drift_per_frame
+ for y in range(10, 40):
+ for x in range(round(cx) - 6, round(cx) + 6):
+ im.putpixel((x, y), (200, 60, 60, 255))
+ phase = 2 * math.pi * t / period
+ stride = round(14 * math.sin(phase))
+ for sign in (1, -1):
+ leg_x = round(cx + sign * stride)
+ lifted = sign * stride < 0 # the trailing leg is in the air
+ bottom = 50 if lifted else 58
+ for y in range(40, bottom):
+ for x in range(leg_x - 3, leg_x + 3):
+ if 0 <= x < size[0]:
+ im.putpixel((x, y), (60, 60, 200, 255))
+ p = d / f"frame-{t:04d}.png"
+ im.save(p)
+ files.append(p)
+ return files
+
+
+def _cell_body_centres(strip: Image.Image, meta: dict) -> list[float]:
+ """x of the body block (the red rows above the legs) inside every cell."""
+ w, h = meta["w"], meta["h"]
+ out = []
+ for k in range(meta["frames"]):
+ cell = np.asarray(strip.crop((k * w, 0, (k + 1) * w, h)))
+ red = (cell[:, :, 0] > 150) & (cell[:, :, 2] < 120) & (cell[:, :, 3] >= 8)
+ out.append(float(np.nonzero(red)[1].mean()))
+ return out
+
+
+def test_feet_anchor_does_not_sway_a_body_that_stands_still(tmp_path: Path) -> None:
+ # The per-frame foot line of an in-place walk jumps between the planted feet; pinning
+ # it made the whole body lurch back and forth by the stride. Only drift is removed.
+ files = _lifting_walker(tmp_path, period=12, n=24)
+ frames = [Image.open(f).convert("RGBA") for f in files]
+ anchored, meta = loop_mod.build_strip(frames, cycle_seconds=1.0, anchor="feet")
+ body = _cell_body_centres(anchored, meta)
+ assert max(body) - min(body) <= 1.5
+ assert meta["drift_px"] <= 2 # nothing moved, nothing was removed
+ assert meta["foot_sway_px"] >= 10 # the planted foot does change — reported, not erased
+
+
+def test_feet_anchor_removes_drift_but_keeps_the_step(tmp_path: Path) -> None:
+ files = _lifting_walker(tmp_path, period=12, n=24, drift_per_frame=1.5)
+ frames = [Image.open(f).convert("RGBA") for f in files]
+ anchored, meta = loop_mod.build_strip(frames, cycle_seconds=1.0, anchor="feet")
+ body = _cell_body_centres(anchored, meta)
+ assert max(body) - min(body) <= 1.5
+ assert 30 <= meta["drift_px"] <= 40 # 23 frames * 1.5 px of authored drift