Skip to content

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

12.2 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Regression tests for chroma-key alpha cleanup and auto key selection.

These guard three ways the extractor used to silently destroy real subject
colors:

1. ``remove_chroma_background`` ran a "neutralize key tint" pass on every pixel
   whose channels leaned toward the key's channels, *regardless of color
   distance* — so a saturated red/orange/blue subject was clamped toward
   olive/grey under a magenta key even though it sat >200 away from magenta.
   The destructive pass is gone; near-key antialias fringe is still cleaned.
2. ``choose_chroma_key`` ranked candidates by the 1st-percentile distance to
   subject pixels, which discards sub-1% features (eyes, gems, ear lamps): the
   auto key could look safe while its nearest subject pixel was still inside the
   extraction erase radius and would be deleted. Its guards are in
   ``test_chroma_key_auto.py``, beside the function.
3. The old fringe cut erased every pixel inside the fringe color band *anywhere
   in the image* — hot pink (~129 from magenta) and purple (~153) subjects fell
   in the band and were bleached wholesale. Soft-alpha unmix now treats boundary
   antialiasing as coverage while deeper interior subject pixels survive.
"""

from __future__ import annotations

import importlib.util
import sys
from pathlib import Path

import pytest
from PIL import Image

SCRIPTS_DIR = Path(__file__).resolve().parents[2] / "scripts"
if str(SCRIPTS_DIR) not in sys.path:
    sys.path.insert(0, str(SCRIPTS_DIR))


def _load(name: str):
    spec = importlib.util.spec_from_file_location(name, SCRIPTS_DIR / f"{name}.py")
    module = importlib.util.module_from_spec(spec)
    assert spec and spec.loader
    spec.loader.exec_module(module)
    return module


extract = _load("extract_sprite_row_frames")

MAGENTA = (255, 0, 255)
# extract_sprite_row_frames.py main() defaults
KEY_THRESHOLD = 96.0
FRINGE_THRESHOLD = 180.0
FRINGE_DELTA = 18.0
LEGACY_PEEL_DEPTH = 2

FIXTURES = Path(__file__).resolve().parent.parent / "fixtures"
MOE_FIXTURES = FIXTURES / "moe"

# Subject colors that sit inside the magenta key's fringe trap band — the
# position-blind fringe cut used to erase them wholesale. Both are ~129/~153
# from magenta, i.e. close enough to the key to be trapped, far enough to be
# real subject material.
HOT_PINK = (250, 77, 150)  # ~129 from magenta
PURPLE = (213, 112, 246)  # ~153 from magenta


def _key(pixel: tuple[int, int, int], chroma_key=MAGENTA):
    image = Image.new("RGBA", (1, 1), (*pixel, 255))
    out = extract.remove_chroma_background(
        image,
        chroma_key,
        threshold=KEY_THRESHOLD,
        fringe_threshold=FRINGE_THRESHOLD,
        fringe_delta=FRINGE_DELTA,
    )
    return out.getpixel((0, 0))


def _clean(image: Image.Image, chroma_key=MAGENTA) -> Image.Image:
    return extract.remove_chroma_background(
        image,
        chroma_key,
        threshold=KEY_THRESHOLD,
        fringe_threshold=FRINGE_THRESHOLD,
        fringe_delta=FRINGE_DELTA,
    )


def test_optional_chroma_tunables_are_keyword_only() -> None:
    image = Image.new("RGBA", (1, 1), (*MAGENTA, 255))
    with pytest.raises(TypeError):
        extract.remove_chroma_background(image, MAGENTA, KEY_THRESHOLD, FRINGE_THRESHOLD, FRINGE_DELTA, 2)


def _open_moe(name: str) -> Image.Image:
    with Image.open(MOE_FIXTURES / name) as opened:
        return opened.convert("RGBA")


def _fringe_peel_candidates(image: Image.Image, chroma_key: tuple[int, int, int]) -> list[tuple[int, int]]:
    """Pixels the legacy in-band peel would erase before soft-alpha unmix.

    Key distance is what the engine measures: the smaller of the distance to the
    declared key and to the background colour actually painted on the borders
    (`detect_background_key_rgb`) — the moe fixtures were painted a few units
    off the pure key, and the hard-cut sphere sits where the paint is.
    """
    width, height = image.size
    pixels = image.load()
    painted_key = extract.detect_background_key_rgb(image, chroma_key)
    classes = bytearray(width * height)
    keyed: list[int] = []

    def key_distance(color: tuple[int, int, int]) -> float:
        return min(extract.color_distance(color, chroma_key), extract.color_distance(color, painted_key))

    for y in range(height):
        for x in range(width):
            red, green, blue, alpha = pixels[x, y]
            index = y * width + x
            color = (red, green, blue)
            if alpha == 0 or key_distance(color) <= KEY_THRESHOLD:
                classes[index] = extract._KEYED
                keyed.append(index)
            elif extract.key_tint_score(color, chroma_key) < FRINGE_DELTA:
                classes[index] = extract._SUBJECT
            elif key_distance(color) <= FRINGE_THRESHOLD:
                classes[index] = extract._BLEND_IN_BAND
            else:
                classes[index] = extract._BLEND_OUT_OF_BAND

    frontier = keyed
    peeled: list[tuple[int, int]] = []
    for _ in range(LEGACY_PEEL_DEPTH):
        next_frontier = []
        for index in frontier:
            x = index % width
            y = index // width
            for dy in (-1, 0, 1):
                ny = y + dy
                if ny < 0 or ny >= height:
                    continue
                for dx in (-1, 0, 1):
                    nx = x + dx
                    if nx < 0 or nx >= width:
                        continue
                    neighbor = ny * width + nx
                    if classes[neighbor] != extract._BLEND_IN_BAND:
                        continue
                    classes[neighbor] = extract._KEYED
                    next_frontier.append(neighbor)
                    peeled.append((nx, ny))
        if not next_frontier:
            break
        frontier = next_frontier
    return peeled


def _heart_material_pixels(name: str, image: Image.Image) -> list[tuple[int, int]]:
    pixels = image.load()
    if name == "moe_heart.png":
        return [
            (x, y)
            for y in range(image.height)
            for x in range(image.width)
            if pixels[x, y][0] >= 240 and 60 <= pixels[x, y][1] <= 115 and 130 <= pixels[x, y][2] <= 175
        ]
    if name == "moe_mirror.png":
        return [
            (x, y)
            for y in range(image.height)
            for x in range(image.width)
            if pixels[x, y][0] <= 30 and 180 <= pixels[x, y][1] <= 225 and 105 <= pixels[x, y][2] <= 145
        ]
    raise AssertionError(f"no heart material mask for {name}")


MOE_PEEL_REMOVAL_CASES = [
    ("moe_heart.png", MAGENTA, 160, 260),
    ("moe_mirror.png", (0, 255, 0), 70, 120),
]


def test_moe_legacy_peel_band_becomes_soft_alpha_not_opaque_crust() -> None:
    for name, chroma_key, _min_mid_alpha, _max_mid_alpha in MOE_PEEL_REMOVAL_CASES:
        source = _open_moe(name)
        peeled = _fringe_peel_candidates(source, chroma_key)
        assert peeled, f"{name}: fixture lost the legacy peel band"

        out = _clean(source, chroma_key).load()
        transparent = [(x, y) for x, y in peeled if out[x, y][3] == 0]
        opaque = [(x, y) for x, y in peeled if out[x, y][3] == 255]
        assert not transparent, f"{name}: {len(transparent)} legacy peel pixels were still erased"
        assert not opaque, f"{name}: {len(opaque)} legacy peel pixels survived as opaque crust"


def test_moe_fixtures_keep_meaningful_mid_alpha_edges() -> None:
    for name, chroma_key, min_mid_alpha, max_mid_alpha in MOE_PEEL_REMOVAL_CASES:
        out = _clean(_open_moe(name), chroma_key)
        histogram = out.getchannel("A").histogram()
        mid_alpha = sum(histogram[1:255])
        assert min_mid_alpha <= mid_alpha <= max_mid_alpha, f"{name}: {mid_alpha} mid-alpha pixels"


def test_key_tinted_heart_material_survives_byte_identical() -> None:
    for name, chroma_key, _min_mid_alpha, _max_mid_alpha in MOE_PEEL_REMOVAL_CASES:
        source = _open_moe(name)
        material = _heart_material_pixels(name, source)
        assert material, f"{name}: fixture lost its heart material pixels"

        source_pixels = source.load()
        out = _clean(source, chroma_key).load()
        changed = [(x, y) for x, y in material if out[x, y] != source_pixels[x, y]]
        assert not changed, f"{name}: {len(changed)} heart material pixels changed, e.g. {changed[:5]}"


def test_despill_preserves_far_subject_colors() -> None:
    # All of these sit >200 color-distance away from magenta: they are the
    # subject, not key fringe, and must survive completely untouched.
    for pixel in [(196, 54, 38), (224, 96, 40), (208, 44, 40), (40, 70, 200)]:
        assert extract.color_distance(pixel, MAGENTA) > FRINGE_THRESHOLD
        assert _key(pixel) == (*pixel, 255), f"{pixel} was mangled by despill"


FRINGE = (147, 90, 157)  # magenta blended with a green subject edge


def test_boundary_fringe_gets_soft_alpha() -> None:
    # Green subject on magenta background with a one-pixel antialias fringe
    # ring between them: the background must go, the fringe becomes coverage,
    # and the subject must stay.
    assert extract.color_distance(FRINGE, MAGENTA) <= FRINGE_THRESHOLD
    assert extract.key_tint_score(FRINGE, MAGENTA) >= FRINGE_DELTA
    green = (60, 170, 70)
    image = Image.new("RGBA", (16, 16), (*MAGENTA, 255))
    pixels = image.load()
    for y in range(4, 12):
        for x in range(4, 12):
            pixels[x, y] = (*green, 255)
    for x in range(3, 13):  # fringe ring just outside the subject block
        for y in (3, 12):
            pixels[x, y] = (*FRINGE, 255)
            pixels[y, x] = (*FRINGE, 255)
    out = _clean(image).load()
    assert out[0, 0][3] == 0  # background gone
    assert 0 < out[3, 3][3] < 255 and 0 < out[12, 8][3] < 255  # fringe ring is soft alpha
    assert out[8, 8] == (*green, 255)  # subject intact


def test_isolated_fringe_band_pixel_is_subject_not_fringe() -> None:
    # The same fringe-band color *inside* a subject, nowhere near background,
    # is a real material color and must survive (this is what the old
    # position-blind cut destroyed).
    green = (60, 170, 70)
    image = Image.new("RGBA", (16, 16), (*green, 255))
    image.load()[8, 8] = (*FRINGE, 255)
    out = _clean(image).load()
    assert out[8, 8] == (*FRINGE, 255)


def test_key_tinted_subject_interior_survives() -> None:
    # Hot pink / purple blocks on a magenta background: only the edge layers
    # nearest the keyed-out background may become soft alpha; the interior must
    # keep its exact color.
    for subject in (HOT_PINK, PURPLE):
        distance = extract.color_distance(subject, MAGENTA)
        assert KEY_THRESHOLD < distance <= FRINGE_THRESHOLD  # inside the trap band
        assert extract.key_tint_score(subject, MAGENTA) >= FRINGE_DELTA
        image = Image.new("RGBA", (32, 32), (*MAGENTA, 255))
        pixels = image.load()
        for y in range(8, 24):
            for x in range(8, 24):
                pixels[x, y] = (*subject, 255)
        out = _clean(image).load()
        assert out[0, 0][3] == 0  # background gone
        # In-band unmix is bounded to the nearest two key-depth layers.
        for offset in range(8 + LEGACY_PEEL_DEPTH, 24 - LEGACY_PEEL_DEPTH):
            assert out[offset, offset] == (*subject, 255), f"{subject} interior erased at {offset}"


def _trap_band_subject(subject: tuple[int, int, int], size: int = 100, margin: int = 6) -> Image.Image:
    """A magenta-keyed canvas with a solid subject block whose color sits inside
    the key's fringe trap band. Generated deterministically so the fringe-survival
    guard needs no sample art shipped alongside the tests."""
    canvas = Image.new("RGBA", (size + 2 * margin, size + 2 * margin), (*MAGENTA, 255))
    pixels = canvas.load()
    for y in range(margin, margin + size):
        for x in range(margin, margin + size):
            pixels[x, y] = (*subject, 255)
    return canvas


def test_key_tinted_subject_opaque_pixels_do_not_regress() -> None:
    # A 100x100 in-band subject block is ~10k opaque pixels; interior is
    # untouchable and only the outer despill layers may go, so the vast majority
    # must remain opaque after cleanup.
    for subject in (HOT_PINK, PURPLE):
        out = _clean(_trap_band_subject(subject))
        opaque = out.getchannel("A").histogram()[255]
        assert opaque >= 9000, f"{subject}: opaque subject pixels regressed to {opaque}"