Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video): reserve overhead space for attack canvases
Soohong Kimb64746921ced
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7166009..b813e1e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- One-shot selection requires an observed departure and return with resting frames on both sides. Endpoint-relative motion can identify a return after a held strike, while truncated actions, stationary clips and incoherent jitter are refused. These pixel measurements do not establish anatomical correctness.- Loop selection and seam failures write structured reports with the rejected candidate, search window and repeat/return evidence. Successful reports explicitly record `status: passed`; undefined ratios are represented as JSON `null`.+- Attack canvases reserve overhead room as well as forward room for raised weapon swings. Wide padding now honors headroom while preserving 16:9 and the still pixels; idle, walk, run and jump defaults are unchanged.+## v2.5.2 - Cleaner video spill correction- Automatic spill selection distinguishes the key hue from yellow/cyan or red/blue material and discounts dark contamination in the reference matte edge band. Bright key-coloured details still count as material.diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex a0b7d24..f1230b1 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -36,12 +36,14 @@ is a property of the motion state, owned by one table (`STATE_CANVAS`):| State | Shape | Ratio | Room | Why ||---|---|---|---|---|| `jump` | tall | 3:4 | 34 % head-room above the still | airborne frames need height |-| `attack` | wide | 16:9 | 28 % in front (facing side) | swings and weapons extend forward |+| `attack` | wide | 16:9 | 35 % above the still, at least 28 % in front (facing side) | weapon swings rise overhead and extend in front || `projectile` | wide | 16:9 | 34 % in front | the projectile travels away || everything else | square | 1:1 | — | in-place motion fits the still |`--shape tall|wide|square` overrides the row; `--headroom` / `--lead` tune the room;-`--facing left` mirrors the wide layout. A still whose corners are not one flat colour+`--facing left` mirrors the wide layout. Headroom is a fraction of the full canvas+height; wide canvases grow both dimensions to preserve their ratio without shrinking+the still. A still whose corners are not one flat colouris refused — a non-flat background cannot be extended without guessing.**The canvas owns key normalization.** Image models paint "`#00FF00`" a littlediff --git a/sprite_gen/video/canvas.py b/sprite_gen/video/canvas.pyindex 09f889a..5a86da5 100644--- a/sprite_gen/video/canvas.py+++ b/sprite_gen/video/canvas.py@@ -4,7 +4,7 @@Grok Imagine keeps the input image's framing and ignores `aspect_ratio` onimage-to-video (2026-09-08 실측: a `3:4` request still returned 960x960). So thecanvas is decided HERE, on the still: a jump needs head-room above (tall), an-attack or projectile needs room in front (wide), everything else stays square.+attack needs room above and in front, a projectile needs room in front (wide), everything else stays square.The state -> canvas table below is the single owner of that rule; `--shape`overrides it per call.@@ -46,7 +46,7 @@ SHAPES = (SHAPE_SQUARE, SHAPE_TALL, SHAPE_WIDE)class CanvasProfile:shape: strratio: float # width / height- headroom: float # fraction of the canvas height kept empty ABOVE the subject (tall)+ headroom: float # fraction of the canvas height kept empty ABOVE the still (tall/wide)lead: float # fraction of the canvas width kept empty IN FRONT of the subject (wide)why: str@@ -55,7 +55,7 @@ class CanvasProfile:# states fall through to `default`.STATE_CANVAS: dict[str, CanvasProfile] = {"jump": CanvasProfile(SHAPE_TALL, 3 / 4, 0.34, 0.0, "airborne frames need head-room; hair clipped at 1:1"),- "attack": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.28, "weapon swings and projectiles extend in front"),+ "attack": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.35, 0.28, "weapon swings rise overhead and extend in front"),"projectile": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.34, "projectile travels away from the body"),# Raised-limb celebrations leave a square frame at the top corners; wide with a# symmetric margin keeps them inside (lead applies in front, the rest pads the back).@@ -191,7 +191,8 @@ def pad_canvas(canvas_w = max(w, round(canvas_h * profile.ratio))x, y = (canvas_w - w) // 2, canvas_h - helse: # wide: extra width goes in front of the facing direction; at least the profile ratio- canvas_w = max(w, round(w / (1 - front)), round(h * profile.ratio))+ required_h = max(h, round(h / (1 - head)))+ canvas_w = max(w, round(w / (1 - front)), round(required_h * profile.ratio))canvas_h = max(h, round(canvas_w / profile.ratio))y = canvas_h - hx = 0 if facing == "right" else canvas_w - w@@ -248,7 +249,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--state", help="motion state name (jump/attack/projectile/... — selects the canvas row)")parser.add_argument("--shape", choices=SHAPES, help="override the state's canvas shape")parser.add_argument("--facing", choices=("right", "left"), default="right", help="which way the subject faces (wide canvases add room in front)")- parser.add_argument("--headroom", type=float, help="tall: empty fraction above the subject (default from the profile)")+ parser.add_argument("--headroom", type=float, help="tall/wide: empty fraction of canvas height above the still (default from the profile)")parser.add_argument("--lead", type=float, help="wide: empty fraction in front of the subject (default from the profile)")parser.add_argument("--key", choices=KEYS, default="auto", help="chroma key of the still (auto reads the corners; green/magenta are normalized to the exact key; white pads with the corner colour)")parser.add_argument("--report", type=Path, help="write the canvas report JSON here")diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.pyindex a2b714d..b3297f9 100644--- a/tests/video/test_video_pipeline.py+++ b/tests/video/test_video_pipeline.py@@ -66,6 +66,41 @@ def test_wide_canvas_puts_room_in_front_of_the_facing(tmp_path: Path) -> None:assert abs(right.width / right.height - 16 / 9) < 0.02[email protected]("facing", ["right", "left"])+def test_attack_canvas_reserves_overhead_room_and_reports_placement(tmp_path: Path, facing) -> None:+ still = _still(tmp_path)+ out = tmp_path / "attack.png"+ report = tmp_path / "attack.json"+ rep = canvas_mod.run_canvas(still, out, state="attack", shape=None,+ facing=facing, headroom=None, lead=None, report_path=report)+ image = Image.open(out)+ x, y = rep["offset"]+ assert rep["headroom"] > 0 and y >= round(image.height * rep["headroom"]) - 1+ assert abs(image.width / image.height - 16 / 9) < 0.01+ assert image.crop((x, y, x + 120, y + 160)).tobytes() == Image.open(still).tobytes()+ assert image.crop((0, 0, image.width, y)).getextrema() == ((0, 0), (255, 255), (0, 0))+ assert json.loads(report.read_text()) == rep+ assert rep["why"] == "weapon swings rise overhead and extend in front"+ # An explicit zero still gives the pre-headroom wide layout.+ zero, zero_rep = canvas_mod.pad_canvas(Image.open(still), canvas_mod.profile_for("attack"), headroom=0)+ assert zero.size == (284, 160) and zero_rep["offset"] == [0, 0]++[email protected]("state,size,offset", [+ ("walk", (160, 160), (20, 0)),+ ("idle", (160, 160), (20, 0)),+ ("run", (160, 160), (20, 0)),+ ("jump", (182, 242), (31, 82)),+])+def test_nonattack_canvas_defaults_preserve_pixels(tmp_path: Path, state, size, offset) -> None:+ still = Image.open(_still(tmp_path))+ actual, rep = canvas_mod.pad_canvas(still, canvas_mod.profile_for(state))+ expected = Image.new("RGB", size, GREEN)+ expected.paste(still, offset)+ assert actual.size == expected.size and actual.tobytes() == expected.tobytes()+ assert rep["offset"] == list(offset)++def test_square_canvas_never_shrinks_and_refuses_non_flat_corners(tmp_path: Path) -> None:still = Image.open(_still(tmp_path))out, rep = canvas_mod.pad_canvas(still, canvas_mod.profile_for("walk"))