Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

18.8 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Gates G2..G6 and G8 of `pixel-draw` on recorded answers (tests/fixtures/pixel_draw) and on grids
made to break exactly one rule. G2, G3 and G6 fail a candidate; G4, G5 and the walk check only warn.
G3, G4, G5 and G8 ask the engine's own judgments, each tested with its owner: G3 the transparent
background of `gen.chroma.alpha_verdict` (tests/gen/test_alpha_verdict.py), G4 the join measure of
`background.tile.inspect_tile` (tests/background/test_tile.py), G5 the lone pixels of
`frames.extract.isolated_dots` (tests/frames/test_isolated_dots.py), and G8 the safe area of
`frames.extract.safe_area_fit` (tests/frames/test_safe_area_fit.py) - a frame past the physical cap
warns, one past the safe area within the cap is an info line - and a sprite whose feet are off the
floor row warns. The `*-safe-area-pass` answers were drawn under the safe-area prompt; the other
recorded sprites when the prompt asked to fill the canvas."""
from __future__ import annotations

from pathlib import Path

import pytest

from sprite_gen.gen import pixel_gates, prepare
from sprite_gen.gen import pixel_grid as pg
from sprite_gen.gen.pixel_gates import evaluate, g6_frames

FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "pixel_draw"
WALK = ("walk1", "walk2", "walk3", "walk4")
FOURDIR = ("down", "up", "left", "right")
FREE16 = pg.palette_rule("free")

INK, SKIN, GRASS = (40, 30, 46, 255), (240, 192, 152, 255), (78, 144, 56, 255)
CLEAR = (0, 0, 0, 0)


def frames_of(name: str, size: int, frames: tuple[str, ...]):
    grid, issues = pg.parse_answer((FIXTURES / name).read_text(encoding="utf-8"), "chargrid", size, size, frames)
    assert issues == []
    return {f: pg.frame_pixels(grid, f) for f in frames}


def blob(size: int = 8, top: int = 2, bottom: int = 5, fill=INK):
    """A transparent square with an opaque block rows top..bottom, columns 2..size-3."""
    return [[fill if top <= y <= bottom and 2 <= x <= size - 3 else CLEAR for x in range(size)] for y in range(size)]


def test_recorded_sprite_passes_every_gate():
    gates = evaluate(frames_of("sprite-16-safe-area-pass.txt", 16, ("sprite",)), kind="sprite", rule=FREE16,
                     walk_cycle=False)
    assert gates["ok"] and gates["failed"] == [] and gates["warnings"] == [] and gates["info"] == []
    assert gates["G2"]["colors_used"] <= 16
    assert gates["G3"]["frames"]["sprite"]["corners_transparent"]
    assert gates["G3"]["frames"]["sprite"]["verdict"] == "real-alpha"
    assert gates["G5"]["isolated_pixels"] == 0 and "G6" not in gates and "G4" not in gates
    assert gates["G8"]["frames"]["sprite"]["bbox"] == [3, 1, 12, 14] and gates["G8"]["floor_row"] == 14


def test_recorded_tile_is_opaque_and_repeats():
    gates = evaluate(frames_of("tile-16-pass.txt", 16, ("tile",)), kind="tile", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and gates["G3"]["frames"]["tile"]["opaque_fraction"] == 1.0 and gates["info"] == []
    assert gates["G3"]["frames"]["tile"]["verdict"] == "no-alpha"
    assert gates["G4"]["needs_review"] == [] and not gates["G4"]["warn"]
    assert {axis: report["status"] for axis, report in gates["G4"]["frames"]["tile"].items()} == {"x": "pass", "y": "pass"}


def test_g2_counts_colours_against_the_limit_and_the_fixed_set():
    frames = frames_of("sprite-16-safe-area-pass.txt", 16, ("sprite",))
    used = evaluate(frames, kind="sprite", rule=FREE16, walk_cycle=False)["G2"]["colors_used"]
    few = evaluate(frames, kind="sprite", rule=pg.palette_rule("free:4"), walk_cycle=False)
    assert not few["ok"] and few["failed"] == ["G2"] and few["G2"]["colors_used"] == used
    pico = evaluate(frames, kind="sprite", rule=pg.palette_rule("pico8"), walk_cycle=False)
    assert not pico["ok"] and pico["G2"]["off_palette"]
    exact = pg.palette_rule(",".join(sorted({"#{:02X}{:02X}{:02X}".format(*p[:3])
                                             for row in frames["sprite"] for p in row if p[3]})))
    assert evaluate(frames, kind="sprite", rule=exact, walk_cycle=False)["G2"]["ok"]


# The opaque border and the tile's hole are `alpha_verdict`'s, tested in tests/gen/test_alpha_verdict.py.
@pytest.mark.parametrize("frame,kind", [
    ([[INK] + [CLEAR] * 7] + [[CLEAR] * 8 for _ in range(7)], "sprite"),   # an opaque corner
    ([[CLEAR] * 8 for _ in range(8)], "sprite"),                            # nothing drawn
])
def test_g3_alpha_failures(frame, kind):
    gates = evaluate({"f": frame}, kind=kind, rule=FREE16, walk_cycle=False)
    assert not gates["ok"] and "G3" in gates["failed"]


def test_recorded_four_directions_stand_on_one_line():
    gates = evaluate(frames_of("fourdir-16-pass.txt", 16, FOURDIR), kind="sprite", rule=FREE16, walk_cycle=False)
    assert gates["G6"]["ok"] and gates["G6"]["identical_pairs"] == []
    assert len(set(gates["G6"]["baselines"].values())) == 1 and "walk" not in gates["G6"]
    # drawn to fill the canvas: plume to boots 16 rows, where a 16 px cell has 15 above its bottom margin
    assert gates["ok"] and gates["failed"] == [] and gates["info"] == []
    assert gates["warnings"] == [
        "G8: frames exceed the physical cap 16x15 (reroll candidates): down:12x16, up:12x16, left:10x16, right:10x16",
        "G8 the feet are not on the floor row (the safe area's bottom row): down 1 px below it, up 1 px below it, "
        "left 1 px below it, right 1 px below it"]


def test_recorded_walk_passes_with_the_weak_leg_warning():
    gates = evaluate(frames_of("walk-32-safe-area-pass.txt", 32, WALK), kind="sprite", rule=FREE16, walk_cycle=True)
    g6 = gates["G6"]
    assert gates["ok"] and g6["ok"] and g6["height_spread"] == 1  # the passing pose is a pixel higher
    assert g6["rule"] == "motion"  # a walk cycle is a motion
    assert g6["walk"]["warn"] and g6["walk"]["ratio"] < 0.4
    assert [w[:30] for w in gates["warnings"]] == ["G6 weak leg alternation: the c"] and gates["info"] == []
    assert set(g6["baselines"].values()) == {gates["G8"]["floor_row"]} == {28}  # row 29 of 32, counted from 1


def test_g6_failures():
    low, high, tall = blob(), blob(top=1, bottom=4), blob(top=0, bottom=5)
    assert not g6_frames({"a": low, "b": [row[:] for row in low]}, walk_cycle=False)["ok"]  # the same frame twice
    shifted = g6_frames({"a": low, "b": high}, walk_cycle=False)
    assert not shifted["ok"] and shifted["baselines"] == {"a": 5, "b": 4}
    spread = g6_frames({"a": low, "b": [r[:] for r in tall]}, walk_cycle=False)
    assert spread["height_spread"] == 2 and not spread["ok"]
    gates = evaluate({"a": low, "b": [row[:] for row in low]}, kind="sprite", rule=FREE16, walk_cycle=False)
    assert gates["failed"] == ["G6"]


# ----------------------------------------------------------------------------- G8 safe area

def canvas(size: int = 32):
    return [[CLEAR] * size for _ in range(size)]


def paint(frame, x0: int, y0: int, x1: int, y1: int, fill=INK):
    """`frame` with columns x0..x1 of rows y0..y1 opaque (inclusive)."""
    for y in range(y0, y1 + 1):
        for x in range(x0, x1 + 1):
            frame[y][x] = fill
    return frame


def figure(size: int = 32):
    """A body filling the safe area's height: at 32 px columns 8..23 of rows 3..28, the 26x26 box's
    rows from top to the floor row."""
    m = int(size * prepare.DEFAULT_SAFE_MARGIN_RATIO)
    return paint(canvas(size), size // 4, m, size - 1 - size // 4, size - 1 - m)


# `normalize_cell` is `int(width * RATIO)` with no branch on the size; the 0 px margin is its own test below.
@pytest.mark.parametrize("size,margin,inner", [(32, 3, 26)])
def test_the_safe_area_is_the_engines(size, margin, inner):
    area = pixel_gates.safe_area(size, size)
    cell = prepare.normalize_cell({"width": size, "height": size}, size, None)
    assert area["margin"] == [margin, margin] == [cell["safe_margin_x"], cell["safe_margin_y"]]
    assert margin == int(size * prepare.DEFAULT_SAFE_MARGIN_RATIO)
    assert area["size"] == [inner, inner]
    assert area["box"] == [margin, margin, size - 1 - margin, size - 1 - margin]
    assert area["floor_row"] == size - 1 - margin  # where prepare's fit grounds a frame: the safe area's last row


def test_the_safe_area_follows_prepares_ratio(monkeypatch):
    monkeypatch.setattr(prepare, "DEFAULT_SAFE_MARGIN_RATIO", 0.125)
    assert pixel_gates.safe_area(32, 32)["margin"] == [4, 4]
    assert pixel_gates.safe_area(32, 16)["margin"] == [4, 2]  # an edited grid need not be square


def test_g8_passes_a_body_inside_the_safe_area():
    gates = evaluate({"f": figure()}, kind="sprite", rule=FREE16, walk_cycle=False)
    g8 = gates["G8"]
    assert gates["ok"] and gates["warnings"] == [] and gates["info"] == [] and not g8["warn"]
    assert g8["margin"] == [3, 3] and g8["safe_area"] == [26, 26] and g8["physical_cap"] == [32, 29]
    assert g8["floor_row"] == 28 and g8["over_cap"] == [] and g8["past_safe_area"] == []
    assert g8["frames"]["f"] == {"bbox": [8, 3, 23, 28], "size": [16, 26], "body_box": [8, 3, 23, 28]}


# The side blades take the thin-tip path and the bottom tail the floor path, each tested below.
@pytest.mark.parametrize("stroke,info", [
    ((15, 0, 15, 2), ["f:16x29"]),    # a staff to the top edge: 29 rows, past the safe area, within the cap
])
def test_g8_never_fails_a_pose_that_reaches_the_canvas_edge(stroke, info):
    """The safe area is a target for the body's size, not a wall: a pose may reach the canvas edge."""
    frame = paint(figure(), *stroke)
    gates = evaluate({"f": frame}, kind="sprite", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and gates["failed"] == [] and gates["warnings"] == []
    assert gates["info"] == [f"G8: frames exceed the safe area 26x26 but fit within the margin zone (informational, "
                             f"no action): {where}" for where in info]


def test_g8_lets_a_thin_tip_into_the_margin():
    frame = paint(figure(), 24, 15, 30, 15)  # a blade from the body's right side to 2 px past the safe area
    gates = evaluate({"f": frame}, kind="sprite", rule=FREE16, walk_cycle=False)
    measure = gates["G8"]["frames"]["f"]
    assert gates["ok"] and gates["warnings"] == [] and gates["info"] == []
    assert measure["bbox"] == [8, 3, 30, 28] and measure["body_box"] == [8, 3, 23, 28]


def test_g8_warns_a_frame_past_the_physical_cap():
    """The cap is the canvas's width and its height less the margin under the floor row: 32x29 at 32 px."""
    over = paint(figure(), 20, 0, 20, 29)  # a staff from the top edge to a row under the floor row: 30 rows
    for kind in ("sprite", "icon"):  # the same judgment for both
        gates = evaluate({"f": over}, kind=kind, rule=FREE16, walk_cycle=False)
        assert gates["ok"] and gates["failed"] == [] and gates["G8"]["warn"] and gates["info"] == []
        assert "ok" not in gates["G8"]
        assert gates["G8"]["over_cap"] == ["f"] and gates["G8"]["frames"]["f"]["body_box"][3] == 28
        assert gates["warnings"] == ["G8: frames exceed the physical cap 32x29 (reroll candidates): f:16x30"]


def test_g8_warns_a_sprite_off_the_floor_row():
    floating = paint(canvas(), 8, 3, 23, 26)
    gates = evaluate({"a": floating, "b": paint(canvas(), 9, 3, 23, 26)}, kind="sprite", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and gates["G6"]["ok"] and gates["G8"]["warn"] and gates["info"] == []
    assert gates["warnings"] == ["G8 the feet are not on the floor row (the safe area's bottom row): "
                                 "a 2 px above it, b 2 px above it"]
    below = evaluate({"f": paint(canvas(), 8, 3, 23, 29)}, kind="sprite", rule=FREE16, walk_cycle=False)
    assert below["ok"] and below["warnings"] == [
        "G8 the feet are not on the floor row (the safe area's bottom row): f 1 px below it"]
    assert below["info"] == ["G8: frames exceed the safe area 26x26 but fit within the margin zone (informational, "
                             "no action): f:16x27"]
    icon = evaluate({"f": floating}, kind="icon", rule=FREE16, walk_cycle=False)
    assert icon["warnings"] == [] and icon["G8"]["floor_row"] is None


def test_g8_reads_the_floor_from_the_body_not_a_tip_below_it():
    staff = paint(figure(), 20, 29, 20, 30)  # a staff's foot 2 px into the bottom margin, the feet on the floor row
    gates = evaluate({"f": staff}, kind="sprite", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and gates["warnings"] == []
    assert gates["G8"]["frames"]["f"]["bbox"][3] == 30 and gates["G8"]["frames"]["f"]["body_box"][3] == 28


def test_g8_below_a_one_pixel_margin_the_safe_area_and_the_cap_are_the_canvas():
    plus = paint(paint(canvas(8), 3, 0, 4, 7), 0, 3, 7, 4)  # touches every side, corners clear
    gates = evaluate({"f": plus}, kind="icon", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and gates["warnings"] == [] and gates["info"] == []
    assert gates["G8"]["margin"] == [0, 0] and gates["G8"]["safe_area"] == [8, 8] and gates["G8"]["physical_cap"] == [8, 8]


def test_g8_leaves_tiles_alone():
    gates = evaluate({"tile": [[GRASS] * 32 for _ in range(32)]}, kind="tile", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and "G8" not in gates and gates["info"] == []


def test_a_recorded_blade_reaches_into_the_margin_and_the_body_stays_inside():
    frames = frames_of("attack-32-safe-area-pass.txt", 32, ("attack1", "attack2", "attack3", "attack4"))
    gates = evaluate(frames, kind="sprite", rule=FREE16, walk_cycle=False)
    measures = gates["G8"]["frames"]
    assert gates["ok"] and gates["warnings"] == [] and gates["info"] == []
    assert measures["attack1"]["bbox"][0] == 2 and measures["attack3"]["bbox"][2] == 29  # the blade, 1 px past it
    assert all(3 <= m["body_box"][0] and m["body_box"][2] <= 28 and m["body_box"][3] == 28 for m in measures.values())


def test_g6_measures_the_frames_inside_the_safe_area():
    """What reaches into the margin - a staff raised in one frame, a spark in another - is G8's to
    judge; G6 compares the figures inside the safe area."""
    still, raised = figure(), paint(figure(), 20, 1, 20, 2)  # the staff 2 px into the top margin
    g6 = evaluate({"a": still, "b": raised}, kind="sprite", rule=FREE16, walk_cycle=False)["G6"]
    assert g6["ok"] and g6["heights"] == {"a": 26, "b": 26} and g6["baselines"] == {"a": 28, "b": 28}
    taller = paint(canvas(), 8, 5, 23, 28)  # the body itself 2 px shorter inside the safe area
    assert not evaluate({"a": still, "b": taller}, kind="sprite", rule=FREE16, walk_cycle=False)["G6"]["ok"]


def test_a_recorded_staff_and_spark_in_the_margin_pass():
    """Drawn under the safe-area prompt: the staff pulled back reaches 2 px into the top margin and the
    spark 1 px, the figure is the same height in every frame. The two frames they make taller or wider
    than the safe area are an info line."""
    frames = frames_of("attack-32-margin-detail.txt", 32, ("attack1", "attack2", "attack3", "attack4"))
    gates = evaluate(frames, kind="sprite", rule=FREE16, walk_cycle=False)
    assert gates["ok"] and gates["warnings"] == [] and gates["G6"]["height_spread"] == 0
    assert gates["info"] == ["G8: frames exceed the safe area 26x26 but fit within the margin zone (informational, "
                             "no action): attack2:19x28, attack3:26x27"]
    assert [m["bbox"][1] for m in gates["G8"]["frames"].values()] == [3, 1, 2, 3]


def test_g8_reads_a_frames_opaque_box_off_the_image_paths_judgment(monkeypatch):
    """The opaque box G8 sizes a frame by is `frames.extract.solid_alpha_bbox` (alpha at least 128), the
    box the image path crops a sprite to — one measure, not a second count of opaque rows here."""
    from sprite_gen.frames import extract

    real, seen = extract.solid_alpha_bbox, []

    def recording(image, threshold=128):
        seen.append((image.getchannel("A").tobytes(), threshold))
        return real(image, threshold)

    monkeypatch.setattr(extract, "solid_alpha_bbox", recording)
    frame = blob(size=16, top=3, bottom=12)
    g8 = evaluate({"f": frame}, kind="sprite", rule=FREE16, walk_cycle=False)["G8"]
    assert seen == [(pg.image_of(frame).getchannel("A").tobytes(), pixel_gates.OPAQUE_MIN)]
    assert g8["frames"]["f"]["bbox"] == [2, 3, 13, 12] and g8["frames"]["f"]["size"] == [12, 10]
    # What it answers is what G8 measures: a box it says is wider is a wider frame.
    monkeypatch.setattr(extract, "solid_alpha_bbox", lambda image, threshold=128: (0, 3, 16, 13))
    g8 = evaluate({"f": frame}, kind="sprite", rule=FREE16, walk_cycle=False)["G8"]
    assert g8["frames"]["f"]["bbox"] == [0, 3, 15, 12] and g8["frames"]["f"]["size"] == [16, 10]


# ----------------------------------------------------------------------------- G6 of one motion

def lifted(frame, rows: int):
    """`frame` drawn `rows` rows higher."""
    return frame[rows:] + [[CLEAR] * len(frame[0]) for _ in range(rows)]


def test_g6_of_a_motion_lets_a_raised_arm_and_a_hold_through_and_still_fails_the_ground():
    """One motion (`--motion`, or a walk cycle): the frames must stand on one ground row, but an arm
    raised over the head changes the height with the pose - its height, mass and breadth part, so the
    image path's size reading (`gait_fallback.size_change`) says the body did not grow - and a frame
    drawn twice is a hold."""
    side = paint(paint(canvas(), 8, 10, 23, 28), 24, 14, 25, 20)  # a body and an arm at its side
    raised = paint(paint(canvas(), 8, 10, 23, 28), 24, 3, 25, 9)  # the same arm over the head
    frames = {"a": side, "b": raised, "c": [r[:] for r in raised]}
    still = evaluate(frames, kind="sprite", rule=FREE16, walk_cycle=False)
    assert still["failed"] == ["G6"]  # without --motion, as before
    gates = evaluate(frames, kind="sprite", rule=FREE16, walk_cycle=False, motion=True)
    g6 = gates["G6"]
    assert gates["ok"] and g6["ok"] and g6["rule"] == "motion"
    assert g6["heights"] == {"a": 19, "b": 26, "c": 26} and g6["posed"] == ["b", "c"] and g6["resized"] == []
    assert g6["size_change"]["b"]["change"] == 0.0 and g6["holds"] == [["b", "c"]]
    assert not any(w.startswith("G6") for w in gates["warnings"])
    assert [line for line in gates["info"] if line.startswith("G6")] == [
        "G6 the height changes with the pose, not the body's size (informational, no action): b 26 px, c 26 px "
        "against a 19 px",
        "G6 frames drawn the same, a hold (informational, no action): b=c"]
    off = evaluate({**frames, "d": lifted(frames["a"], 2)}, kind="sprite", rule=FREE16, walk_cycle=False, motion=True)
    assert off["failed"] == ["G6"] and off["G6"]["baselines"]["d"] == 26


def test_g6_of_a_motion_warns_a_body_drawn_larger():
    small = paint(canvas(), 10, 12, 21, 28)
    large = paint(canvas(), 8, 7, 23, 28)
    gates = evaluate({"a": small, "b": large}, kind="sprite", rule=FREE16, walk_cycle=False, motion=True)
    g6 = gates["G6"]
    assert gates["ok"] and g6["resized"] == ["b"] and g6["posed"] == []
    assert g6["size_change"]["b"]["change"] > 0.25
    assert [w for w in gates["warnings"] if w.startswith("G6")] == [
        "G6 the body changes size, not only its pose - its height, mass and breadth all grow or shrink by more "
        "than a pixel: b +29% against a"]