Skip to content

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

4.0 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Whether a picture's background is really transparent is one judgment, `gen.chroma.alpha_verdict`
(docs/gen.md): `real-alpha` when at least 5 % of its pixels and half of its one-pixel border are
alpha 0, `no-alpha` when no pixel is, `ambiguous` between. `classify_raw_alpha` asks it of a generated
raw before a chroma key runs, and `pixel-draw`'s G3 of every frame it drew: a sprite or icon frame must
be `real-alpha`, with something drawn and its four corners clear; a tile frame `no-alpha`."""
from __future__ import annotations

import pytest
from PIL import Image

from sprite_gen.gen import chroma
from sprite_gen.gen import pixel_grid as pg
from sprite_gen.gen.pixel_gates import evaluate

INK, CLEAR = (40, 30, 46, 255), (0, 0, 0, 0)
FREE16 = pg.palette_rule("free")


def icon(size: int = 16):
    """A block of ink rows 3..12, columns 4..11, on a clear canvas."""
    return [[INK if 3 <= y <= 12 and 4 <= x <= 11 else CLEAR for x in range(size)] for y in range(size)]


@pytest.fixture
def calls(monkeypatch):
    """Every call to the judgment: the alpha band it was asked about and what it answered."""
    real, seen = chroma.alpha_verdict, []

    def recording(alpha):
        seen.append((alpha.copy(), real(alpha)))
        return seen[-1][1]

    monkeypatch.setattr(chroma, "alpha_verdict", recording)
    return seen


def test_a_generated_raw_is_read_by_it(tmp_path, calls):
    image = Image.new("RGBA", (20, 20), (255, 0, 255, 255))
    for y in range(4, 16):
        for x in range(4, 16):
            image.putpixel((x, y), (0, 0, 0, 0))
    path = tmp_path / "raw.png"
    image.save(path)
    stats = chroma.classify_raw_alpha(path)
    ((alpha, verdict),) = calls
    assert alpha.tobytes() == image.getchannel("A").tobytes()
    assert verdict == {"verdict": "ambiguous", "alpha_zero_pct": 36.0, "border_alpha_zero_pct": 0.0}
    assert stats == {"mode": "RGBA", "has_alpha_band": True, **verdict}


def test_g3_asks_it_of_every_frame(calls):
    frame = icon()
    gates = evaluate({"f": frame}, kind="icon", rule=FREE16, walk_cycle=False)
    ((alpha, verdict),) = calls
    assert alpha.tobytes() == pg.image_of(frame).getchannel("A").tobytes()
    assert verdict["verdict"] == "real-alpha"
    assert gates["G3"]["ok"] and gates["G3"]["frames"]["f"] == {
        "opaque_pixels": 80, "opaque_fraction": 0.3125, "corners_transparent": True, **verdict}


def test_g3_says_what_it_answers(monkeypatch):
    """Answer `ambiguous`: G3 fails a sprite on a clear canvas. Answer `real-alpha`: G3 fails a tile,
    which must be `no-alpha`, however opaque it is."""
    monkeypatch.setattr(chroma, "alpha_verdict",
                        lambda alpha: {"verdict": "ambiguous", "alpha_zero_pct": 1.0, "border_alpha_zero_pct": 50.0})
    sprite = evaluate({"f": icon()}, kind="sprite", rule=FREE16, walk_cycle=False)
    assert not sprite["ok"] and sprite["failed"] == ["G3"]
    monkeypatch.setattr(chroma, "alpha_verdict",
                        lambda alpha: {"verdict": "real-alpha", "alpha_zero_pct": 9.0, "border_alpha_zero_pct": 90.0})
    tile = evaluate({"tile": [[INK] * 8 for _ in range(8)]}, kind="tile", rule=FREE16, walk_cycle=False)
    assert not tile["ok"] and tile["failed"] == ["G3"]


def test_a_canvas_filled_but_for_half_its_border_has_no_transparent_background():
    """48 px of ink with its top row, its left column and its four corners clear: half the border is
    alpha 0, but 96 pixels are not 5 % of 2,304 - `ambiguous`, and G3 fails it."""
    size = 48
    frame = [[INK] * size for _ in range(size)]
    for x in range(size):
        frame[0][x] = CLEAR
    for y in range(size):
        frame[y][0] = CLEAR
    frame[size - 1][size - 1] = CLEAR
    gates = evaluate({"f": frame}, kind="icon", rule=FREE16, walk_cycle=False)
    measured = gates["G3"]["frames"]["f"]
    assert measured["corners_transparent"] and measured["border_alpha_zero_pct"] == 51.06
    assert measured["verdict"] == "ambiguous" and measured["alpha_zero_pct"] == 4.17
    assert not gates["ok"] and gates["failed"] == ["G3"]