Skip to content

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

video-loop: admit a one-shot excursion by moved subject mass when the rest is not one pose

Soohong Kimee9f7e78ccc8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b69921f..a154c04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased (v2.4.1)
+
+- `video-loop` one-shot detection no longer refuses a visible hop because the rest pose is not one pose. The excursion is admitted by either the peak's height in MADs of the rest noise (as before) or the fraction of the subject's pixel mass the peak moves (new, ≥ 0.4); the report records `excursion_moved` and `excursion_rule`. A body that walked a few steps, hopped 42 px and froze scored 1.8 MADs because the walking preamble and the frozen tail inflate the "rest noise"; by moved mass it scores 1.07. A jittering stand still fails both rules, and clips the MAD rule already accepted are cut exactly as before.
+
## v2.4.0 - Three-second clips and gait windows in seconds
- `video-set --duration` defaults to 3 seconds (was 6). A repeating motion holds two or more cycles at 3 s (walk strides measured at 0.6–1.3 s across seven bodies), a single action is one hop or swing that the one-shot cut already handles, and 6 s bought only a longer wait — and, for jump, more idle standing between hops. `--duration 6` still asks for a longer clip.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index a6fb3ed..d6aa64b 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -212,7 +212,15 @@ failed and the window), `table.md` has a `kind` column, the strip sidecar carrie
play it once on a trigger rather than repeating it), and the same seam and animation
gates still apply. `--cycle periodic` keeps the old hard failure; `--cycle
one-shot` forces the excursion cut. A clip that never leaves its rest pose fails loud
-in both detectors. `--cycle fixed --start N --length L` skips detection and cuts exactly
+in both detectors. The excursion is admitted by either of two measures, and the report
+says which (`cycle.excursion_rule`): the peak's height in MADs of the rest noise
+(`excursion_contrast` ≥ 3), or the fraction of the rest frame's pixel mass the peak moves
+(`excursion_moved` ≥ 0.4). The second exists because the MAD is not rest noise when the
+rest is not one pose — a body that walks a few steps, hops once and freezes has its
+frames spread between the walking preamble and the frozen tail, and a 42 px hop scored
+1.8 MADs (2026-09-20). Moved mass is scale-free: a hop shifts the whole silhouette out of
+its own footprint (0.54–1.07 on eight measured jumps), a jittering stand does not
+(0.12–0.24). Under the mass rule the active frames are those above half the peak. `--cycle fixed --start N --length L` skips detection and cuts exactly
those frames — for a clip that holds too few repeats for the periodicity gate but whose
cycle is known (the 2026-09-09 reel jump: 2.3 hops in 145 frames). It is an explicit
instruction, not a failover: the report says `kind = "fixed"`, and the seam gate still
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 68fc7e5..f0acc2e 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -48,6 +48,16 @@ PERIODICITY_MIN = 0.15 # the period must dip at least 15% below the profile mea
GIF_FPS_DEFAULT = 24.0 # GIF/WebP playback density = the source rate: every cycle frame is kept, a fast action never looks slow (12 made a jump read sluggish, 2026-09-09)
GIF_FRAMES_MIN = 4
ONE_SHOT_MIN_CONTRAST = 3.0 # one-shot: the excursion peak must stand this far above the rest-pose noise (in MADs)
+# Second acceptance for the one-shot excursion, in units of the subject itself: the peak
+# must move at least this fraction of the rest frame's pixel mass. The MAD contrast
+# measures the peak against the spread of *every* frame's distance to the rest pose,
+# and that spread is not rest noise when the rest is not one pose — a body that walks a
+# few steps, hops once and then freezes (2026-09-20 jump field test: 42 px of lift refused
+# at 1.8 MADs because the walking preamble and the frozen tail sit 0.03 apart). Moved
+# mass is scale-free: a hop shifts the whole silhouette out of its own footprint (measured
+# 0.54-1.07 on eight jumps), a jittering stand does not (0.12-0.24 on the synthetic
+# jitter-only fixtures).
+ONE_SHOT_MIN_MOVED = 0.4
ONE_SHOT_PAD = 2 # one-shot: rest frames kept on each side of the excursion so the seam is rest -> rest
CYCLE_MODES = ("auto", "periodic", "one-shot", "fixed")
ONE_SHOT_MIN_LEN = 4 # a one-shot's length is the clip's own fact; only a degenerate cut is refused
@@ -127,6 +137,12 @@ def _load_small(path: Path) -> np.ndarray:
return np.concatenate([rgb, a[..., 3:4]], axis=-1).reshape(-1)
+def frame_masses(files: list[Path]) -> np.ndarray:
+ """Per-frame pixel mass of the analysis thumbnail (mean |premultiplied rgba|): how much
+ subject there is, on the same scale as the distance matrix."""
+ return np.array([float(np.abs(_load_small(f)).mean()) for f in files], dtype=np.float32)
+
+
def distance_matrix(files: list[Path]) -> np.ndarray:
flat = np.stack([_load_small(f) for f in files])
n = len(files)
@@ -188,42 +204,51 @@ def detect_cycle(D: np.ndarray, *, min_len: int, max_len: int, gait_floor: int |
return best
-def detect_one_shot(D: np.ndarray, *, min_len: int, max_len: int) -> dict[str, Any]:
+def detect_one_shot(D: np.ndarray, *, min_len: int, max_len: int, frame_mass: np.ndarray | None = None) -> dict[str, Any]:
"""A cycle for an action the model performed ONCE: rest -> excursion -> rest.
The rest pose is the medoid frame (smallest mean distance to every other frame — in a
clip that mostly stands still that is a standing frame). Frames whose distance to it
rises above the rest noise (median + ONE_SHOT_MIN_CONTRAST MADs) are the excursion; the
- longest contiguous run of them, padded by ONE_SHOT_PAD rest frames on each side, is the
- cycle, so the loop seam is rest -> rest by construction. Fails loud when nothing stands
+ contiguous run of them that holds the peak, padded by ONE_SHOT_PAD rest frames on each
+ side, is the cycle, so the loop seam is rest -> rest by construction. Fails loud when nothing stands
out or the excursion does not fit the window — never returns a guess.
+
+ `frame_mass` (from `frame_masses`) enables the second acceptance rule: when the MAD
+ contrast is under the bar because the rest is not one pose, a peak that moves at least
+ ONE_SHOT_MIN_MOVED of the rest frame's pixel mass is still an excursion, and the
+ active frames are then those above half the peak (the hump itself) rather than a
+ noise threshold that the peak does not clear.
"""
n = D.shape[0]
rest = int(np.argmin(D.mean(axis=1)))
e = D[rest]
med = float(np.median(e))
mad = float(np.median(np.abs(e - med))) or 1e-6
- contrast = (float(e.max()) - med) / mad
- if contrast < ONE_SHOT_MIN_CONTRAST:
+ peak = float(e.max())
+ contrast = (peak - med) / mad
+ moved = (peak - med) / float(frame_mass[rest]) if frame_mass is not None and float(frame_mass[rest]) > 0 else None
+ if contrast >= ONE_SHOT_MIN_CONTRAST:
+ rule = "contrast"
+ active = e > med + ONE_SHOT_MIN_CONTRAST * mad
+ elif moved is not None and moved >= ONE_SHOT_MIN_MOVED:
+ rule = "moved"
+ active = e > med + 0.5 * (peak - med)
+ else:
+ by_mass = f", moved {moved:.2f} of the subject's mass, need {ONE_SHOT_MIN_MOVED}" if moved is not None else ""
raise SystemExit(
f"video-loop: no one-shot excursion either — the clip never leaves its rest pose "
- f"(peak {contrast:.1f} MADs above rest, need {ONE_SHOT_MIN_CONTRAST}); regenerate the clip"
+ f"(peak {contrast:.1f} MADs above rest, need {ONE_SHOT_MIN_CONTRAST}{by_mass}); regenerate the clip"
)
- active = e > med + ONE_SHOT_MIN_CONTRAST * mad
- best_run: tuple[int, int] | None = None
- j = 0
- while j < n:
- if active[j]:
- k = j
- while k + 1 < n and active[k + 1]:
- k += 1
- if best_run is None or (k - j) > (best_run[1] - best_run[0]):
- best_run = (j, k)
- j = k + 1
- else:
- j += 1
- assert best_run is not None
- a, b = best_run
+ # The excursion is the contiguous active run that holds the peak — the largest
+ # departure from rest — not the longest run: a walking preamble can be a longer
+ # departure than the hop itself and would otherwise be cut instead of the action.
+ peak_at = int(np.argmax(e))
+ a = b = peak_at
+ while a > 0 and active[a - 1]:
+ a -= 1
+ while b + 1 < n and active[b + 1]:
+ b += 1
start = max(0, a - ONE_SHOT_PAD)
end = min(n - 1, b + ONE_SHOT_PAD)
L = end - start + 1
@@ -249,6 +274,8 @@ def detect_one_shot(D: np.ndarray, *, min_len: int, max_len: int) -> dict[str, A
"rest_frame": rest,
"excursion": [a, b],
"excursion_contrast": round(contrast, 2),
+ "excursion_moved": round(moved, 3) if moved is not None else None,
+ "excursion_rule": rule, # which acceptance admitted it: "contrast" (MADs) or "moved" (subject mass)
}
@@ -538,13 +565,14 @@ def run_loop(
lo = min_len if min_len is not None else lo_default
hi = max_len if max_len is not None else max(lo + 2, hi_default)
D = distance_matrix(files)
+ masses = frame_masses(files)
periodic_attempt: dict[str, Any] | None = None
if cycle_mode == "fixed":
if start is None or length is None:
raise SystemExit("video-loop: --cycle fixed needs --start and --length")
cycle = fixed_cycle(D, start=start, length=length)
elif cycle_mode == "one-shot":
- cycle = detect_one_shot(D, min_len=lo, max_len=hi)
+ cycle = detect_one_shot(D, min_len=lo, max_len=hi, frame_mass=masses)
else:
gait_floor = round(prof.min_seconds * fps) if prof.gait and prof.min_seconds > 0 else None
cycle = detect_cycle(D, min_len=lo, max_len=hi, gait_floor=gait_floor)
@@ -557,7 +585,7 @@ def run_loop(
# explicit, recorded failover: the action happened once (allowed for this state),
# so cut rest -> excursion -> rest instead. The periodic attempt stays in the report.
periodic_attempt = {"periodicity": cycle["periodicity"], "window": [lo, hi], "profile_minima": cycle["profile_minima"], "why_rejected": flat}
- cycle = detect_one_shot(D, min_len=lo, max_len=max(hi, round(n * 0.9)))
+ cycle = detect_one_shot(D, min_len=lo, max_len=max(hi, round(n * 0.9)), frame_mass=masses)
else:
raise SystemExit(
f"video-loop: no periodic cycle found — {flat}; the motion does not repeat, widen the window, "
diff --git a/tests/video/test_one_shot_moved.py b/tests/video/test_one_shot_moved.py
new file mode 100644
index 0000000..3686a30
--- /dev/null
+++ b/tests/video/test_one_shot_moved.py
@@ -0,0 +1,84 @@
+"""One-shot acceptance by moved subject mass (2026-09-20 jump field test).
+
+The MAD contrast rejects a hop when the rest is not one pose: a body that walks a few
+steps, hops once and then freezes has its distance-to-rest spread between the walking
+preamble and the frozen tail, so the "rest noise" is inflated and a 42 px hop scores
+under 3 MADs. The moved-mass rule admits it; a jittering stand still fails both.
+"""
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from sprite_gen.video import loop as loop_mod
+from tests.video.test_video_pipeline import _one_shot_frames
+
+
+def _walk_hop_freeze(tmp_path: Path, *, n: int = 96, walk_until: int = 40, hop: tuple[int, int] = (42, 56), shift: int = 5, lift: int = 16, jitter: int = 1, seed: int = 1, size=(64, 96)) -> list[Path]:
+ """Walking sway on a stance a few px over for the first frames, one hop, then a stand
+ that never moves again (a little jitter so no two frames are byte-identical). The rest
+ pose (the stand) is the medoid, and the walking frames sit far enough from it that the
+ MAD of every frame's distance to rest is inflated well past the rest noise."""
+ d = tmp_path / "keyed"
+ d.mkdir()
+ files = []
+ rng = np.random.default_rng(seed)
+ for t in range(n):
+ im = Image.new("RGBA", size, (0, 0, 0, 0))
+ lf = 0
+ if hop[0] <= t < hop[1]:
+ lf = round(lift * math.sin(math.pi * (t - hop[0]) / (hop[1] - hop[0])))
+ walking = t < walk_until
+ dx = (shift if walking else 0) + int(rng.integers(-jitter, jitter + 1))
+ dy = int(rng.integers(-jitter, jitter + 1))
+ for y in range(30 - lf + dy, 70 - lf + dy):
+ for x in range(24 + dx, 40 + dx):
+ im.putpixel((x, y), (200, 60, 60, 255))
+ leg = 32 + dx + (round(8 * math.sin(2 * math.pi * t / 12)) if walking else 0)
+ for y in range(70 - lf + dy, 88 - lf + dy):
+ for x in range(leg - 3, leg + 3):
+ im.putpixel((x, y), (60, 60, 200, 255))
+ p = d / f"frame-{t:04d}.png"
+ im.save(p)
+ files.append(p)
+ return files
+
+
+def test_moved_mass_admits_a_hop_the_mad_contrast_rejects(tmp_path: Path) -> None:
+ files = _walk_hop_freeze(tmp_path)
+ D = loop_mod.distance_matrix(files)
+ with pytest.raises(SystemExit, match="never leaves its rest pose"):
+ loop_mod.detect_one_shot(D, min_len=8, max_len=86) # no masses: the old rule alone
+ cycle = loop_mod.detect_one_shot(D, min_len=8, max_len=86, frame_mass=loop_mod.frame_masses(files))
+ assert cycle["kind"] == "one-shot" and cycle["excursion_rule"] == "moved"
+ assert cycle["excursion_contrast"] < loop_mod.ONE_SHOT_MIN_CONTRAST
+ assert cycle["excursion_moved"] >= loop_mod.ONE_SHOT_MIN_MOVED
+ a, b = cycle["excursion"]
+ assert 42 <= a <= b < 56 # the hop, not the walking preamble
+ assert cycle["ratio"] < 2.0 # rest -> rest seam within the gate
+
+
+def test_moved_mass_does_not_admit_a_jittering_stand(tmp_path: Path) -> None:
+ files = _one_shot_frames(tmp_path, hop=(0, 0), jitter=4)
+ D = loop_mod.distance_matrix(files)
+ with pytest.raises(SystemExit, match="moved 0\\.[0-3]"):
+ loop_mod.detect_one_shot(D, min_len=8, max_len=130, frame_mass=loop_mod.frame_masses(files))
+
+
+def test_contrast_rule_still_wins_when_it_clears_the_bar(tmp_path: Path) -> None:
+ files = _one_shot_frames(tmp_path)
+ D = loop_mod.distance_matrix(files)
+ plain = loop_mod.detect_one_shot(D, min_len=9, max_len=65)
+ with_mass = loop_mod.detect_one_shot(D, min_len=9, max_len=65, frame_mass=loop_mod.frame_masses(files))
+ assert with_mass["excursion_rule"] == "contrast"
+ assert (with_mass["start"], with_mass["length"], with_mass["excursion"]) == (plain["start"], plain["length"], plain["excursion"])
+
+
+def test_frame_masses_are_positive_and_per_frame(tmp_path: Path) -> None:
+ files = _one_shot_frames(tmp_path, n=12)
+ m = loop_mod.frame_masses(files)
+ assert m.shape == (12,) and bool(np.all(m > 0))