Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# SPDX-License-Identifier: Apache-2.0
"""`handed-check` on drawn figures: a body with two arms and a blue watch screen on its own left wrist.
Each view is drawn as it should look (the table below, written out by hand), passes, and turned over
(as a set that mirrors its left-hand views would) fails — the check catches a mirror by itself."""
import json
import subprocess
import sys
from pathlib import Path
import pytest
from PIL import Image, ImageDraw, ImageOps
from sprite_gen.gen import handedness as h
from sprite_gen.qa import handed
WATCH = h.parse("the black smartwatch=left wrist")
BLUE = (30, 90, 235)
W, H = 200, 320
# Where the watch is drawn for each (view, facing): on the arm at the picture's left / right, on the
# near arm (a side view, in front of the body) or nowhere (a side view, behind the body). "far" is the far
# arm of a right-facing side view swung forward, out in front of the body, the watch in view on it.
DRAWN = {
("front", None): "right", ("back", None): "left",
("front_diagonal", "right"): "right", ("front_diagonal", "left"): "right",
("back_diagonal", "right"): "left", ("back_diagonal", "left"): "left",
("side", "right"): "hidden", ("side", "left"): "near",
}
VIEWS = list(DRAWN)
# The side compare and the near/far rules do not depend on which side of the figure is shown, so the
# back views repeat what the front ones prove; `tests/gen/test_handedness.py` holds the whole table.
PASS_VIEWS = [(view, facing) for view, facing in VIEWS if not view.startswith("back")]
def figure(where: str, *, swing: int = 0, screen: int = 12, outline_split: bool = False) -> Image.Image:
"""A keyed figure: head and body, two arms, and the watch screen drawn `where`."""
im = Image.new("RGBA", (W, H), (0, 0, 0, 0))
d = ImageDraw.Draw(im)
d.ellipse((60, 20, 140, 100), fill=(240, 240, 240, 255), outline=(20, 20, 20, 255), width=3)
d.rounded_rectangle((65, 95, 135, 250), 20, fill=(240, 240, 240, 255), outline=(20, 20, 20, 255), width=3)
d.rectangle((70, 250, 92, 300), fill=(240, 240, 240, 255))
d.rectangle((108, 250, 130, 300), fill=(240, 240, 240, 255))
arms = {"left": (40 + swing, 110, 62 + swing, 210), "right": (138 - swing, 110, 160 - swing, 210)}
if where == "near":
arms = {"near": (92 + swing, 120, 112 + swing, 215)}
if where == "far":
arms = {"far": (140 + swing, 120, 162 + swing, 215)}
for box in arms.values():
d.rectangle(box, fill=(235, 235, 235, 255), outline=(20, 20, 20, 255), width=2)
if where in arms:
x0, _, x1, _ = arms[where]
cx = (x0 + x1) // 2
d.rectangle((cx - screen // 2, 185, cx + screen // 2, 185 + screen), fill=BLUE + (255,))
if outline_split:
d.line((cx, 185, cx, 185 + screen), fill=(20, 20, 20, 255), width=1)
return im
def loop(where: str, n: int = 6) -> list[Image.Image]:
return [figure(where, swing=s) for s in (0, 2, 4, 6, 4, 2)[:n]]
def check(frames, view, facing, **kw):
return handed.check(frames, item=WATCH, view=view, facing=facing, marker=BLUE, **kw)
@pytest.mark.parametrize("view,facing", PASS_VIEWS)
def test_each_view_drawn_as_its_handedness_says_passes(view, facing) -> None:
report = check(loop(DRAWN[(view, facing)]), view, facing)
assert report["ok"], report["fails"]
assert report["expect"] == h.placement("left", view, facing)
assert check(loop(DRAWN[(view, facing)]), view, facing, references=[figure("right")])["ok"]
# The rows reach each way a mirror fails: the wrong picture side (front, a diagonal) and a side view turned
# over both ways round (near for far, far for near). The back views and the other diagonal direction reach
# the same branches in `handed.check`.
@pytest.mark.parametrize("view,facing,as_view,as_facing", [
("front", None, "front", None),
("side", "right", "side", "left"), # E turned over for W: the watch stays hidden
("front_diagonal", "right", "front_diagonal", "left"), # SE for SW: the watch jumps to the picture's left
("side", "left", "side", "right"),
])
def test_a_mirrored_view_fails(view, facing, as_view, as_facing) -> None:
"""The counterexample: the right-facing view turned over, checked as the left-facing one, fails."""
mirrored = [ImageOps.mirror(f) for f in loop(DRAWN[(view, facing)])]
reference = [figure("right")] # the front view: the watch in full view
report = check(mirrored, as_view, as_facing, references=reference)
assert not report["ok"]
def test_the_wrong_wrist_in_a_side_view_is_caught_by_where_it_shows() -> None:
"""Facing right, the left wrist is the far one. A far arm's watch shows only out in front of the body, where
the arm swings forward; a full screen over the body's centre is on the near arm, the wrong wrist."""
frames = loop("near")
caught = check(frames, "side", "right")
assert not caught["ok"] and "the item is on the near arm" in caught["fails"][0]["why"][0]
assert not check(frames, "side", "right", references=[figure("right")])["ok"]
# against a reference, a sliver of the far watch peeking past the body is not judged for where it is
sliver = check([figure("near", screen=4)], "side", "right", references=[figure("right")])
assert sliver["ok"]
def test_a_far_arms_watch_in_view_while_the_arm_is_forward_passes() -> None:
"""The far wrist's watch, whole, in the frames where that arm is out in front of the body: what a side walk
should look like. 2.22.0 failed every such frame ("in full view on the far side") against a reference."""
walk = [figure("hidden")] * 3 + [figure("far", swing=s) for s in (0, 3, 6)]
for references in (None, [figure("right")]):
report = check(walk, "side", "right", references=references, state="walk")
assert report["ok"], report["fails"]
assert report["rules"]["far_shown"] == {"checked": True, "min": 0.25, "shown": 3, "frames": 6, "ok": True}
assert report["rules"]["far_in_front"]["limb"] == "arm" and "far_hidden" not in report["rules"]
assert report["per_frame"][3]["blobs"][0]["ahead"] >= handed.FAR_FRONT_MIN
# turned over to face left it is the near arm's, and shows in too few frames for one
mirrored = check([ImageOps.mirror(f) for f in walk], "side", "left", state="walk")
assert not mirrored["ok"] and mirrored["rules"]["near_shown"] == {"min": 0.75, "shown": 3, "frames": 6, "ok": False}
def test_a_walk_that_never_shows_the_far_arms_watch_fails_and_other_states_are_not_judged() -> None:
hidden = loop("hidden")
walk = check(hidden, "side", "right", state="walk")
assert not walk["ok"] and walk["fails"] == [] and walk["rules"]["far_shown"]["ok"] is False
assert check([figure("hidden")] * 7 + [figure("far")], "side", "right", state="run")["ok"] is False # 1 of 8
idle = check(hidden, "side", "right", state="idle")
assert idle["ok"] and idle["rules"]["far_shown"]["checked"] is False and "idle" in idle["rules"]["far_shown"]["why"]
unsaid = check(hidden, "side", "right")
assert unsaid["ok"] and "no --state" in unsaid["rules"]["far_shown"]["why"]
def test_a_far_part_that_does_not_swing_keeps_the_hidden_rule() -> None:
"""A pin on the far side of the head stays behind it: in full view there, it is on the wrong side."""
pin = h.parse("the star pin=left side of the head")
frames = loop("near")
unchecked = handed.check(frames, item=pin, view="side", facing="right", marker=BLUE, state="walk")
assert unchecked["ok"] and unchecked["rules"]["far_hidden"]["checked"] is False and "far_shown" not in unchecked["rules"]
caught = handed.check(frames, item=pin, view="side", facing="right", marker=BLUE, references=[figure("right")])
assert not caught["ok"] and "on the far side" in caught["fails"][0]["why"][0]
def test_a_far_sliver_turned_over_is_not_the_near_item_shown() -> None:
"""Facing right, the far wrist's watch may show as a sliver as the arm swings. Turned over to face left,
that sliver is on the arm behind the body — the own right wrist, the wrong one — and the near wrist is
bare. A side view has no picture side, so only size against a reference tells the two apart; without
one the near side's size is reported unchecked, not passed as checked."""
reference = [figure("right")]
right = [figure("near", swing=s, screen=4) for s in (0, 2, 4, 6, 4, 2)]
assert check(right, "side", "right", references=reference)["ok"]
mirrored = [ImageOps.mirror(f) for f in right]
caught = check(mirrored, "side", "left", references=reference)
assert not caught["ok"] and caught["fails"] == []
assert caught["rules"]["near_shown"] == {"min": 0.75, "shown": 0, "frames": 6, "ok": False}
assert caught["rules"]["near_whole"]["checked"] is True and caught["frames_shown"] == 0
unchecked = check(mirrored, "side", "left")
assert unchecked["rules"]["near_whole"] == {"checked": False, "why": "no --reference: the item seen whole is unknown"}
# the near watch drawn in full counts as shown against the same reference
drawn = check(loop("near"), "side", "left", references=reference)
assert drawn["ok"] and drawn["rules"]["near_shown"]["shown"] == 6
def test_the_item_in_two_places_fails_and_a_split_screen_is_one() -> None:
both = figure("right")
d = ImageDraw.Draw(both)
d.rectangle((45, 185, 57, 197), fill=BLUE + (255,))
report = check([both], "front", None)
assert not report["ok"] and "2 places" in report["fails"][0]["why"][0]
assert check([figure("right", outline_split=True)], "front", None)["ok"]
# a few tinted pixels elsewhere (a clip's colour blocks on an outline) are a speck, not a second watch
speck = figure("right")
ImageDraw.Draw(speck).rectangle((45, 185, 49, 189), fill=BLUE + (255,))
report = check([speck], "front", None)
assert report["ok"] and len(report["per_frame"][0]["specks"]) == 1
def test_a_near_item_hidden_in_most_frames_fails() -> None:
frames = [figure("near")] + [figure("hidden")] * 3
report = check(frames, "side", "left")
assert not report["ok"] and report["rules"]["near_shown"] == {"min": 0.75, "shown": 1, "frames": 4, "ok": False}
# a diagonal's near side keeps the half: its picture side tells the arms apart
assert check([figure("right")] * 2 + [figure("hidden")] * 2, "front_diagonal", "left")["rules"]["near_shown"]["min"] == 0.5
def test_unusable_inputs_are_refused() -> None:
with pytest.raises(SystemExit, match="saturated colour"):
handed.check([figure("right")], item=WATCH, view="front", facing=None, marker=(128, 128, 128))
with pytest.raises(SystemExit, match="no transparent pixels"):
check([Image.new("RGBA", (10, 10), (255, 255, 255, 255))], "front", None)
with pytest.raises(SystemExit, match="#RRGGBB"):
handed.parse_marker("blue")
with pytest.raises(SystemExit, match="no --reference shows the marker"):
check([figure("hidden")], "side", "right", references=[figure("hidden")])
def test_cli_reads_a_strip_writes_a_board_and_exits_on_a_mirror(tmp_path) -> None:
def strip(frames, name):
sheet = Image.new("RGBA", (W * len(frames), H), (0, 0, 0, 0))
for i, f in enumerate(frames):
sheet.paste(f, (i * W, 0))
path = tmp_path / f"{name}.strip.png"
sheet.save(path)
(tmp_path / f"{name}.strip.json").write_text(json.dumps({"frames": len(frames), "w": W, "h": H}))
return path
good = strip(loop("right"), "sw")
bad = strip([ImageOps.mirror(f) for f in loop("right")], "sw-mirrored")
base = [sys.executable, "-m", "sprite_gen.cli", "handed-check", "--direction", "front_diagonal", "--facing", "left",
"--handed", "the black smartwatch=left wrist", "--marker", "#1e5aeb"]
ok = subprocess.run([*base, "--strip", str(good), "--board", str(tmp_path / "ok.png"),
"--report", str(tmp_path / "ok.json")], capture_output=True, encoding="utf-8")
assert ok.returncode == 0, ok.stderr
assert json.loads(ok.stdout)["ok"] and (tmp_path / "ok.png").is_file()
assert json.loads((tmp_path / "ok.json").read_text())["frames"] == 6
no = subprocess.run([*base, "--strip", str(bad)], capture_output=True, encoding="utf-8")
assert no.returncode == 1 and "on the picture's left, expected its right" in no.stderr
def test_a_bare_strap_on_the_far_arm_is_caught_only_with_strap() -> None:
"""Facing left, the watch is on the near arm; its strap alone on the far arm (no screen, behind the body's
edge) is the item in a second place. The screen colour cannot see it; `strap` can. Outlines stay out."""
frame = figure("near")
ImageDraw.Draw(frame).rectangle((128, 186, 142, 200), fill=(15, 15, 15, 255))
assert check([frame], "side", "left")["ok"]
caught = check([frame], "side", "left", strap=(20, 20, 20), zone=(0.5, 0.8))
assert not caught["ok"] and "without its marker" in caught["fails"][0]["why"][0]
assert check([figure("near")], "side", "left", strap=(20, 20, 20), zone=(0.5, 0.8))["ok"]
outside = check([frame], "side", "left", strap=(20, 20, 20), zone=(0.0, 0.45))
# outside the zone nothing is looked at: no strap, and the near screen counts as hidden
assert outside["per_frame"][0]["straps"] == [] and outside["rules"]["near_shown"]["ok"] is False
with pytest.raises(SystemExit, match="--zone"):
check([frame], "side", "left", zone=(0.8, 0.5))