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): reserve overhead space for attack canvases

Soohong Kimb64746921ced
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 colour
is refused — a non-flat background cannot be extended without guessing.
**The canvas owns key normalization.** Image models paint "`#00FF00`" a little
diff --git a/sprite_gen/video/canvas.py b/sprite_gen/video/canvas.py
index 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` on
image-to-video (2026-09-08 실측: a `3:4` request still returned 960x960). So the
canvas 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: str
ratio: 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 - h
else: # 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 - h
x = 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.py
index 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"))