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): tight clips pass their own edge and corner checks

Soohong Kim8d1712d8f8c7
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 42d2ac1..cf8e5da 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -156,8 +156,10 @@ touches the edge (a key-tinted blend pixel with low alpha), so a "framed too tig
message with a small residual count is still a framing problem, not a key problem.
`--allow-edge-contact` turns the whole check off. `--allow-subject-edge-contact`
accepts only the subject at the edge — the clipping a `--fit tight` canvas chooses —
-and still fails on leftover key background, which is a keying defect whatever the
-framing. Contacts stay in the report either way, with `edge_policy` saying which rule
+and still fails a frame where the key alone reaches the edge, which is a keying defect
+whatever the framing. A frame where the subject touches the edge passes with the
+key-tinted pixels beside it (fringe, or the key reflected on metal): the same reading the
+refusal message gives a mixed contact. Contacts stay in the report either way, with `edge_policy` saying which rule
applied (`refuse`, `subject-allowed`, `off`).
## 3a. Spill — key colour the model painted into the subject
@@ -316,7 +318,8 @@ Outputs:
- `cycle/frame-NNN.png` — the cycle frames, RGB under alpha 0 scrubbed, detached specks
below 1 % of the body erased.
-- `<name>.strip.png` + `<name>.strip.json` — a horizontal strip (union-cropped, **no bottom
+- `<name>.strip.png` + `<name>.strip.json` — a horizontal strip (union-cropped with 8 transparent
+ columns on each side even where the subject reaches the frame's side edge, **no bottom
pad** so feet meet the floor, bottom-aligned, ≤ 64 cells **and ≤ 32 000 px wide** because
Chrome refuses images near 32 767 px — the cap is on pixels, so a 650 px cell allows 49
cells and the meta says `subsampled`; ≤ 520 px tall) with `frames · w · h · body_h · delay_ms ·
diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.py
index 8f5f7ad..838e00d 100644
--- a/sprite_gen/video/frames.py
+++ b/sprite_gen/video/frames.py
@@ -20,8 +20,10 @@ with different messages: residual points at `video-canvas` normalization of the
base still, subject contact at a taller/wider canvas.
`--allow-subject-edge-contact` accepts the second and keeps the first: a clip made
-from a `video-canvas --fit tight` frame is clipped on purpose, but leftover key
-background at the edge is still a keying defect. The contacts stay in the report.
+from a `video-canvas --fit tight` frame is clipped on purpose, but a frame where only
+leftover key background reaches the edge is still a keying defect. A frame where the
+subject touches the edge carries key-tinted fringe pixels beside it and is accepted with
+them. The contacts stay in the report.
"""
from __future__ import annotations
@@ -201,7 +203,11 @@ def key_frames(
if contacts and check_edges:
if not allow_subject:
raise SystemExit(_edge_contact_message(contacts))
- residual = [c for c in contacts if c["residual"] > 0]
+ # Only a frame where the key alone reaches the edge is leftover background. Where the
+ # subject touches it too, the key-tinted pixels beside it are its antialiased fringe or
+ # a reflection of the key on it (a silver armour on green) — the same reading
+ # `_edge_contact_message` gives a mixed contact.
+ residual = [c for c in contacts if c["residual"] > 0 and c["subject"] == 0]
if residual:
raise SystemExit(_residual_message(residual))
return report
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 5f09f9a..8159ba2 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -577,9 +577,12 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,
boxes = [b for b in boxes if b]
if not boxes:
raise SystemExit("video-loop: every cycle frame is fully transparent")
- left = max(0, min(b[0] for b in boxes) - 8)
+ # The side margins may reach past the frame: a subject allowed to touch the left or right
+ # edge (video-frames --allow-subject-edge-contact) still gets its 8 transparent columns,
+ # so no cell corner is ever the subject. `crop` fills outside the frame with alpha 0.
+ left = min(b[0] for b in boxes) - 8
top = max(0, min(b[1] for b in boxes) - 8)
- right = min(frames[0].width, max(b[2] for b in boxes) + 8)
+ right = max(b[2] for b in boxes) + 8
bottom = max(b[3] for b in boxes)
# body_h = the STANDING height: the tallest frame whose feet touch the floor. A median
# over the whole cycle undercounts a jump (crouch + airborne frames dominate) and then
diff --git a/tests/video/test_fit_tight.py b/tests/video/test_fit_tight.py
index ffad90c..20cb953 100644
--- a/tests/video/test_fit_tight.py
+++ b/tests/video/test_fit_tight.py
@@ -144,13 +144,22 @@ def test_subject_contact_passes_when_allowed_and_stays_in_the_report(tmp_path: P
assert report["edge_contacts"] and all(c["subject"] > 0 for c in report["edge_contacts"])
-def test_leftover_background_still_fails_when_the_subject_is_allowed(tmp_path: Path) -> None:
- files = _frames(tmp_path, residual=True, touch_top=True)
+def test_leftover_background_alone_at_the_edge_still_fails_when_the_subject_is_allowed(tmp_path: Path) -> None:
+ files = _frames(tmp_path, residual=True, touch_top=False)
with pytest.raises(SystemExit, match="leftover chroma background") as info:
frames_mod.key_frames(files, tmp_path / "keyed", key="green", allow_subject=True)
assert "framed too tight" not in str(info.value)
+def test_key_tinted_pixels_beside_a_touching_subject_are_accepted_with_it(tmp_path: Path) -> None:
+ """A subject at the edge brings key-tinted pixels with it — its antialiased fringe, or the
+ key reflected on metal. Only a frame where the key alone reaches the edge is background."""
+ files = _frames(tmp_path, residual=True, touch_top=True)
+ report = frames_mod.key_frames(files, tmp_path / "keyed", key="green", allow_subject=True)
+ assert report["edge_policy"] == "subject-allowed"
+ assert all(c["subject"] > 0 and c["residual"] > 0 for c in report["edge_contacts"])
+
+
def test_the_default_policy_is_unchanged(tmp_path: Path) -> None:
files = _frames(tmp_path, residual=False, touch_top=True)
with pytest.raises(SystemExit, match="framed too tight"):
@@ -206,3 +215,28 @@ def test_video_set_fit_tight_reaches_canvas_and_frames(tmp_path: Path, monkeypat
with pytest.raises(SystemExit, match="--fit tight"):
batch_mod.run_set(bases={"side": base}, states=["attack"], root=tmp_path / "set2", character=None, duration=None,
resolution="480p", key="green", concurrency=1, force=False, gap=0.0, video_runner=video, fit="tight", shape="wide")
+
+
+# --- loop: a subject at the side edge keeps transparent cell corners -----------------------
+
+
+def test_a_subject_touching_the_side_edge_still_gets_transparent_cell_margins(tmp_path: Path) -> None:
+ """The union crop used to stop at the frame edge, so a subject allowed to touch it put
+ opaque pixels on the cell's corner and the GIF check refused the run."""
+ from sprite_gen.video import loop as loop_mod
+ from tests.video.test_video_pipeline import _gait_frames
+
+ files = _gait_frames(tmp_path, period=12, n=72)
+ for path in files: # something held low reaches the left edge of every frame
+ im = Image.open(path)
+ for y in range(52, 58):
+ for x in range(0, 26):
+ im.putpixel((x, y), (120, 120, 120, 255))
+ im.save(path)
+ rep = loop_mod.run_loop(tmp_path / "keyed", tmp_path / "out", fps=24.0, state="walk", min_len=None, max_len=None,
+ n_out=8, seam_max=9.0, name="w", report_path=None, body_height=48)
+ assert rep["gif"]["corners_transparent"] is True
+ strip = Image.open(tmp_path / "out" / "w.strip.png").convert("RGBA")
+ w = rep["strip"]["w"]
+ alpha = np.asarray(strip.getchannel("A"))
+ assert (alpha[:, :7] == 0).all() and (alpha[:, w - 7:w] == 0).all() # the 8 px side margins, scaled 1:1