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): the same picture read on the frames as cut as well as on the thumbnail, so a move under a thumbnail pixel is not a held cell

Soohong Kimfee07db22cee
diff --git a/sprite_gen/video/held_fill.py b/sprite_gen/video/held_fill.py
index ad73d00..b81e66f 100644
--- a/sprite_gen/video/held_fill.py
+++ b/sprite_gen/video/held_fill.py
@@ -9,13 +9,15 @@ them (`same_steps`, `reading`): the cells, the poses (the cells less the ones th
again) and each run of cells showing one picture (`held_runs`, its first cell and how many). The cells are read as
filmed, before an anchor moves each frame of a pair apart.
-The same picture is a step no thumbnail pixel of which (the analysis thumbnail `video-loop` cuts by, premultiplied)
-changes by more than PIXEL_SAME, but for at most CHANGED_MAX of the subject's pixels. A textured figure shown three
-times, encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`, changes no pixel of a frame shown again by
-more than 0.008, 0.020 and 0.051; an arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the
-subject's pixels by more than PIXEL_SAME. A distance over the subject's mass (`nonloop.STABLE_MAX`, which reads a once
-cut's settled end) does not part them: the arm's pixel reads under it. Read on a thumbnail 96 px on its longer side, a
-small part's move of a fraction of one of its pixels reads as the same picture, as a hold plays.
+The same picture is a step at most CHANGED_MAX of whose subject's pixels (premultiplied) change by more than
+PIXEL_SAME, read twice: on the analysis thumbnail `video-loop` cuts by and on the frames as cut. A textured figure shown
+three times, encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`, changes no thumbnail pixel of a frame
+shown again by more than 0.008, 0.020 and 0.051, and 0.012 %, 0.049 % and 0.11 % of its frame's subject pixels by more
+than PIXEL_SAME. An arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the thumbnail's subject
+pixels (0.38 % of the frame's); a walker going away in a frame 280 px wide changes 4.9 % of the frame's in a step that
+moves none of the thumbnail's. A distance over the subject's mass (`nonloop.STABLE_MAX`, which reads a once cut's
+settled end) does not part them: the arm's pixel reads under it. A small part's move of a fraction of a pixel reads as
+the same picture, as a hold plays.
`fill` makes each run's cells again, between the run's first cell and the next pose, at their own times — the cells of a
run of three a third and two thirds of the way — so the cut keeps its length, its beat, its first and last cells and
@@ -68,15 +70,25 @@ def _thumbs(frames: Sequence[Image.Image]) -> np.ndarray:
return np.stack([_small_features(f).reshape(-1, 4) for f in frames])
+def _premultiplied(frame: Image.Image) -> np.ndarray:
+ a = np.asarray(frame.convert("RGBA"), dtype=np.float32) / 255.0
+ return np.concatenate([a[..., :3] * a[..., 3:], a[..., 3:]], axis=-1)
+
+
+def _same(a: np.ndarray, b: np.ndarray) -> bool:
+ """Whether at most CHANGED_MAX of the subject's pixels (alpha over half in either) change by more than PIXEL_SAME:
+ premultiplied RGBA, 0..1, pixels along the last axis."""
+ subject = int((np.maximum(a[..., 3], b[..., 3]) > 0.5).sum())
+ changed = int((np.abs(a - b).max(axis=-1) > PIXEL_SAME).sum())
+ return changed <= CHANGED_MAX * subject
+
+
def same_steps(frames: Sequence[Image.Image]) -> list[bool]:
- """For each step of `frames` (cell k to k + 1), whether the two show the same picture."""
+ """For each step of `frames` (cell k to k + 1), whether the two show the same picture: on the thumbnail and on the
+ frames as cut (see the module)."""
t = _thumbs(frames)
- out = []
- for a, b in zip(t, t[1:]):
- subject = int((np.maximum(a[:, 3], b[:, 3]) > 0.5).sum())
- changed = int((np.abs(a - b).max(axis=1) > PIXEL_SAME).sum())
- out.append(changed <= CHANGED_MAX * subject)
- return out
+ return [_same(t[k], t[k + 1]) and _same(_premultiplied(frames[k]), _premultiplied(frames[k + 1]))
+ for k in range(len(frames) - 1)]
def runs(same: Sequence[bool]) -> list[dict[str, int]]:
diff --git a/tests/video/test_held_fill.py b/tests/video/test_held_fill.py
index a93566f..a0224ef 100644
--- a/tests/video/test_held_fill.py
+++ b/tests/video/test_held_fill.py
@@ -302,6 +302,17 @@ def test_codec_copies_read_as_the_same_picture_and_the_slowest_motion_does_not()
assert held_fill.same_steps([still, noisy, planter(11)]) == [True, False]
+def test_a_whole_figure_moving_under_a_thumbnail_pixel_is_not_the_same_picture():
+ # A walker going away, a frame 280 px wide: its steps move a thousand of its pixels, and some move none of the
+ # analysis thumbnail's. The frame as cut is read too: a cut of it shows no held cell.
+ from tests.video.test_gait_fallback import walking_away
+
+ frames = [walking_away(k) for k in range(73)][24:48]
+ thumbs = held_fill._thumbs(frames)
+ assert any(held_fill._same(a, b) for a, b in zip(thumbs, thumbs[1:]))
+ assert held_fill.same_steps(frames) == [False] * 23
+
+
# A higher rate than the clip's: frames between, never frames shown again.