Skip to content

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

7.1 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Tests for the matte-based `cutout` background remover (imported-image utility).

Synthetic fixtures are built in-process (no binary assets): an ivory canvas with
a centered green square, optionally carrying a pure-white highlight *inside* the
square. The interior highlight is the crux — a colour-only key would punch a hole
in it, but the corner flood-fill keys by position so it must survive.
"""

from __future__ import annotations

import ast
import json
from pathlib import Path

import pytest
from PIL import Image

from sprite_gen import cli
from sprite_gen.frames.cutout import cutout, estimate_background

IVORY = (248, 247, 242)
GREEN = (86, 133, 39)


def _make_icon(with_interior_white: bool = False) -> Image.Image:
    """128x128 ivory bg, centered 64x64 green square, optional white dot inside it."""
    img = Image.new("RGBA", (128, 128), IVORY + (255,))
    px = img.load()
    for y in range(32, 96):
        for x in range(32, 96):
            px[x, y] = GREEN + (255,)
    if with_interior_white:
        for y in range(56, 72):
            for x in range(56, 72):
                px[x, y] = (255, 255, 255, 255)  # pure white highlight buried in the object
    return img


def test_uniform_background_removed(tmp_path: Path) -> None:
    src = tmp_path / "icon.png"
    _make_icon().save(src)
    out = tmp_path / "icon_cutout.png"
    stats = cutout(src, out)

    result = Image.open(out).convert("RGBA")
    px = result.load()
    # corners (background) fully transparent
    for cx, cy in [(0, 0), (127, 0), (0, 127), (127, 127)]:
        assert px[cx, cy][3] == 0
    # object center fully opaque and still green
    r, g, b, a = px[64, 64]
    assert a == 255
    assert (r, g, b) == GREEN
    assert stats["keyed_pixels"] > 0


def test_interior_white_highlight_preserved(tmp_path: Path) -> None:
    """A pure-white region *inside* the object must not be keyed out (no pinhole)."""
    src = tmp_path / "icon_hl.png"
    _make_icon(with_interior_white=True).save(src)
    out = tmp_path / "icon_hl_cutout.png"
    cutout(src, out)

    px = Image.open(out).convert("RGBA").load()
    # the interior white dot stays opaque despite matching the ivory background colour
    r, g, b, a = px[64, 64]
    assert a == 255
    assert (r, g, b) == (255, 255, 255)


def test_white_check_composites_written(tmp_path: Path) -> None:
    src = tmp_path / "icon.png"
    _make_icon().save(src)
    out = tmp_path / "icon_cutout.png"
    check_dir = tmp_path / "checks"
    stats = cutout(src, out, white_check_dir=check_dir)
    assert "white_check" in stats
    for name in ("cyan", "magenta", "yellow"):
        assert (check_dir / f"icon_cutout_{name}.png").exists()


def test_the_cutout_command_writes_the_cut_beside_its_input_and_prints_what_it_wrote(tmp_path: Path, capsys) -> None:
    """`sprite-gen cutout` from its argv to its files: the cut under the default name beside the input, the three
    check composites beside the cut, and the printed stats naming them."""
    src = tmp_path / "icon.png"
    _make_icon().save(src)
    assert cli.main(["cutout", str(src), "--white-check"]) == 0
    out = tmp_path / "icon_cutout.png"
    checks = [tmp_path / f"icon_cutout_{name}.png" for name in ("cyan", "magenta", "yellow")]
    assert out.is_file() and all(check.is_file() for check in checks)
    px = Image.open(out).convert("RGBA").load()
    assert px[0, 0][3] == 0 and px[64, 64] == GREEN + (255,)
    printed = json.loads(capsys.readouterr().out)
    assert printed["out"] == str(out) and printed["route"] == "matte"
    assert printed["white_check"] == [str(check) for check in checks]


def test_missing_background_raises(tmp_path: Path) -> None:
    """A fully object-filled image (no locatable background corners) fails loudly."""
    src = tmp_path / "full.png"
    Image.new("RGBA", (64, 64), GREEN + (255,)).save(src)
    out = tmp_path / "full_cutout.png"
    with pytest.raises(SystemExit):
        cutout(src, out)


def test_estimate_background_from_corners(tmp_path: Path) -> None:
    img = _make_icon()
    assert estimate_background(img) == IVORY


# --- key-colour routing (imported images already on a magenta/green key) ------
# The routes themselves are checked where the keying is: `test_chroma_key_relative.py`
# (auto and explicit keys, the shared family rule) and `test_chroma_decontam.py` (a white
# background stays on the matte).


def test_unknown_key_raises(tmp_path: Path) -> None:
    src = tmp_path / "icon.png"
    _make_icon().save(src)
    with pytest.raises(SystemExit):
        cutout(src, tmp_path / "o.png", key="blue")


# --- the key colours and key names: one declaration each ------------------------

def _key_choices(verb: str) -> object:
    import argparse

    verbs = next(a for a in cli._build_parser()._actions if isinstance(a, argparse._SubParsersAction)).choices
    return next(a for a in verbs[verb]._actions if "--key" in a.option_strings).choices


@pytest.mark.parametrize("name", ["magenta", "green"])
def test_every_key_table_is_the_one_table(name: str) -> None:
    """The logo matte, slice-sheet and gen key a colour by `cutout.KEY_TARGETS`' own tuple, not a copy of it."""
    from sprite_gen.frames import cutout as cutout_mod, logo_matte, slice_sheet
    from sprite_gen.gen import chroma

    assert logo_matte.KEYS is cutout_mod.KEY_TARGETS
    assert slice_sheet.parse_chroma_key(name) is cutout_mod.KEY_TARGETS[name]
    assert chroma.KEYS[name]["target"] is cutout_mod.KEY_TARGETS[name]


def test_the_tables_kept_by_key_name_name_the_keys() -> None:
    from sprite_gen.frames import cutout as cutout_mod
    from sprite_gen.gen import chroma, logo

    assert set(chroma.KEY_BACKGROUND_TEXT) == set(logo.KEY_COLOUR_WORDS) == set(cutout_mod.KEY_TARGETS)


def test_no_table_keys_a_key_colour_by_its_spelling() -> None:
    """A table of the two key colours keyed on their text stays behind when `cutout.MAGENTA` or `GREEN` moves, and a
    reader that looks a key up in it by the name fails. (`WHITE_CHECK_COLORS` is the three primaries, not the keys.)"""
    from sprite_gen.frames import cutout as cutout_mod

    root = Path(cli.__file__).parent
    spelt = [f"{path.relative_to(root).as_posix()}:{node.lineno}" for path in sorted(root.rglob("*.py"))
             for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))) if isinstance(node, ast.Dict)
             if set(cutout_mod.KEY_TARGETS) <= {key.value for key in node.keys if isinstance(key, ast.Constant)}]
    assert spelt == []


def test_every_video_key_flag_reads_its_declaration() -> None:
    """video-canvas and video-set take `canvas.KEYS`, video-prompt the keys its redraw sentence is written for."""
    from sprite_gen.video import canvas, clip_prompt

    declared = {"video-canvas": canvas.KEYS, "video-set": canvas.KEYS, "video-prompt": clip_prompt.START_STILL_KEYS}
    assert [verb for verb, keys in declared.items() if _key_choices(verb) is not keys] == []


def test_the_cutout_key_flag_reads_cutout_keys() -> None:
    from sprite_gen.frames import cutout as cutout_mod

    assert _key_choices("cutout") is cutout_mod.KEYS
    assert cutout_mod.KEYS == ("auto", "white", "magenta", "green", "measured")  # spelt out: the routes take these