Skip to content

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

8.8 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Regression tests for soft-alpha edges and trapped interior chroma blends.

Reproduction (moe raws, 2026-07-08): a mint-green-hair character keyed on
magenta and a crimson-hair character keyed on green both extracted with

1. **Binary alpha** — ``remove_chroma_background`` either erases a pixel to
   ``(0, 0, 0, 0)`` or leaves it fully opaque; no partial alpha is ever
   produced, so every antialiased silhouette edge collapses into a hard
   staircase (mid-alpha pixel count was exactly 0 on both raws).
2. **Trapped key-tint residue** — key/subject blend pixels caught between
   hair strands survive cleanup. Measured on these fixtures: the survivors
   sit 1-4 layers from keyed-out pixels, but (a) dark blends drift 181-265
   color-distance from the key — outside the fringe band — so the band test
   rejects them, and (b) blend pockets run up to 4 layers deep while the old
   in-band peel only removed the nearest 2 layers.

The fixtures are 1/8-size NEAREST copies of the repro raws (1024x1536 ->
128x192), same recipe as ``tests/fixtures/accident/``:
``Image.open(raw).convert("RGB").resize((w // 8, h // 8), Image.NEAREST)``.
Source raws: moe-test ``raw-green.png`` (magenta key) / ``raw-red.png``
(green key), generated at cell 1024x1536, idle single frame.

Partial alpha on both keys is pinned on the sibling moe fixtures
(``test_chroma_extraction.py::test_moe_fixtures_keep_meaningful_mid_alpha_edges``).
The second test pins the v1.10.1 guardrail from the other side: on these
fixtures, pixels deeper than any plausible fringe peel must come out
byte-identical. The one sanctioned interior treatment is the trapped-spill
despill (third test): a *small* cluster with a strongly key-tinted pixel,
buried inside the subject, is generator spill and gets its color corrected
in place (alpha kept — no pinholes); marginally warm subject colors (skin)
and large key-tinted material regions are never touched.
"""

from __future__ import annotations

import importlib.util
import sys
from collections import deque
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")

# extract_sprite_row_frames.py main() defaults
KEY_THRESHOLD = 96.0
FRINGE_THRESHOLD = 180.0
FRINGE_DELTA = 18.0

# Blend pockets in the repro raws run up to 4 layers deep, so a fix may
# legitimately unmix beyond the old 2-layer in-band band for out-of-band
# pixels. Pixels beyond this margin from every keyed pixel are unambiguously
# subject interior and must never be altered, whatever the fix does at the
# boundary.
INTERIOR_MARGIN = 8

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

MAGENTA = (255, 0, 255)
GREEN = (0, 255, 0)

CASES = [
    pytest.param("moe_green.png", MAGENTA, id="magenta-key"),
    pytest.param("moe_red.png", GREEN, id="green-key"),
]


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


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


def _is_key_tinted(color: tuple[int, int, int], chroma_key: tuple[int, int, int]) -> bool:
    """The plan's residue detector: every keyed channel clears every unkeyed
    channel by more than 40 (for magenta: r-g>40 and b-g>40)."""
    keyed = [index for index, value in enumerate(chroma_key) if value >= 192]
    unkeyed = [index for index, value in enumerate(chroma_key) if value < 64]
    return min(color[index] for index in keyed) - max(color[index] for index in unkeyed) > 40


def _keyed_distance_map(image: Image.Image, chroma_key: tuple[int, int, int]) -> list[int | None]:
    """8-connected BFS distance from every pixel to the nearest keyed pixel."""
    width, height = image.size
    pixels = image.load()
    distance: list[int | None] = [None] * (width * height)
    frontier: deque[int] = deque()
    for y in range(height):
        for x in range(width):
            red, green, blue, alpha = pixels[x, y]
            if alpha == 0 or extract.color_distance((red, green, blue), chroma_key) <= KEY_THRESHOLD:
                distance[y * width + x] = 0
                frontier.append(y * width + x)
    while frontier:
        index = frontier.popleft()
        x = index % width
        y = index // width
        for dy in (-1, 0, 1):
            for dx in (-1, 0, 1):
                nx, ny = x + dx, y + dy
                if 0 <= nx < width and 0 <= ny < height:
                    neighbor = ny * width + nx
                    if distance[neighbor] is None:
                        distance[neighbor] = distance[index] + 1
                        frontier.append(neighbor)
    return distance


@pytest.mark.parametrize("name, chroma_key", CASES)
def test_no_key_tint_residue_survives_cleanup(name: str, chroma_key) -> None:
    # ② Key/subject blends trapped between hair strands must not survive as
    # visible key-colored specks, whether they touch the outer background or
    # sit inside an enclosed hole.
    source = _open(name)
    source_pixels = source.load()
    distance = _keyed_distance_map(source, chroma_key)
    width, height = source.size
    trapped = [
        (x, y)
        for y in range(height)
        for x in range(width)
        if 0 < (distance[y * width + x] or 0) <= 4
        and _is_key_tinted(source_pixels[x, y][:3], chroma_key)
    ]
    assert trapped, f"{name}: fixture lost its key-blend pixels; fixture is wrong"

    out = _clean(source, chroma_key).load()
    residue = [
        ((x, y), out[x, y][:3])
        for y in range(height)
        for x in range(width)
        if out[x, y][3] > 0 and _is_key_tinted(out[x, y][:3], chroma_key)
    ]
    assert not residue, f"{name}: {len(residue)} key-tint pixels survived, e.g. {residue[:5]}"


@pytest.mark.parametrize("name, chroma_key", CASES)
def test_deep_interior_subject_pixels_survive_untouched(name: str, chroma_key) -> None:
    # ③ v1.10.1 guardrail: on these fixtures every pixel beyond a plausible
    # peel of the keyed regions (outer background *and* interior holes) must
    # come out byte-identical — the fixtures carry no strong-tint spill
    # cluster deeper than INTERIOR_MARGIN, so nothing deeper may change. In
    # particular this pins that marginally key-leaning subject colors (skin
    # under a magenta key scores tint 19-21) are never "despilled".
    source = _open(name)
    source_pixels = source.load()
    distance = _keyed_distance_map(source, chroma_key)
    width, height = source.size
    interior = [
        (x, y)
        for y in range(height)
        for x in range(width)
        if (distance[y * width + x] or 0) > INTERIOR_MARGIN
    ]
    assert interior, f"{name}: fixture has no deep-interior pixels; fixture is wrong"

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


def test_trapped_spill_strand_is_despilled_in_place() -> None:
    # ④ Generator spill: a small, strongly key-tinted streak buried deep in
    # the subject (a green strand inside crimson hair at full resolution sits
    # 20+ px from any keyed pixel) is unreachable by any boundary peel. It
    # must be color-corrected in place — tint removed, alpha kept, so the
    # sprite gets no pinhole — while the untinted subject around it stays
    # byte-identical.
    subject = (60, 170, 70)
    spill = (190, 60, 170)  # dist ~123 from magenta (past the hard cut), tint 120
    assert extract.color_distance(spill, MAGENTA) > KEY_THRESHOLD
    assert extract.key_tint_score(spill, MAGENTA) > 40

    image = Image.new("RGBA", (64, 64), (*MAGENTA, 255))
    pixels = image.load()
    for y in range(4, 60):
        for x in range(4, 60):
            pixels[x, y] = (*subject, 255)
    streak = [(x, y) for y in range(28, 36) for x in range(30, 33)]  # 3x8, depth > 8
    for x, y in streak:
        pixels[x, y] = (*spill, 255)

    out = _clean(image, MAGENTA).load()
    for x, y in streak:
        red, green, blue, alpha = out[x, y]
        assert alpha == 255, f"spill despill must keep alpha, got {alpha} at {(x, y)}"
        assert not _is_key_tinted((red, green, blue), MAGENTA), f"tint survived at {(x, y)}"
    assert out[20, 32] == (*subject, 255)  # deep untinted subject untouched