Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
"""`detect_background_key_rgb` reads the image a band of rows at a time and must answer as the
whole-image form does. `_whole_image_detect` is that form: every sample widened to int32 at
once, then `np.unique` over the bins. The banded form keeps a count and a channel sum per bin
instead, so a large still costs a histogram rather than an array of samples.
The whole-image form states the rule outright, so it changes with the rule: since the lean is
read against the declared key's cut (2026-10-21) it reads the candidates the rule admitted
before the lean first, then the lean only where the key's cut leaves the border's one
key-coloured background, and the banded form counts each of those sets per bin.
"""
from __future__ import annotations
import numpy as np
import pytest
from PIL import Image
from sprite_gen.frames.cutout import _corner_average
from sprite_gen.frames.extract import (_KEY_DETECT_BAND_ROWS, _KEY_DETECT_BIN_SHIFT, _KEY_DETECT_CORNER_DIV,
_KEY_DETECT_MIN_FRACTION, _border_key_candidate_field, _key_channel_split,
detect_background_key_rgb)
GREEN = (0, 255, 0)
MAGENTA = (255, 0, 255)
def _whole_image_mask(height: int, width: int) -> np.ndarray:
mask = np.zeros((height, width), dtype=bool)
if height == 0 or width == 0:
return mask
corner_w = width // _KEY_DETECT_CORNER_DIV
corner_h = height // _KEY_DETECT_CORNER_DIV
if corner_w < 2:
corner_w = width
if corner_h < 2:
corner_h = height
mask[:corner_h, :corner_w] = True
mask[:corner_h, width - corner_w:] = True
mask[height - corner_h:, :corner_w] = True
mask[height - corner_h:, width - corner_w:] = True
mask[0, :] = mask[-1, :] = True
mask[:, 0] = mask[:, -1] = True
return mask
def _whole_image_detect(image: Image.Image, chroma_key: tuple[int, int, int],
threshold: float | None = None) -> tuple[int, int, int]:
from sprite_gen.frames.extract import (DEFAULT_KEY_THRESHOLD, _KEY_DETECT_LEAN_LEFT_MIN_FRACTION,
_KEY_DETECT_NEIGHBOUR_BINS)
threshold = DEFAULT_KEY_THRESHOLD if threshold is None else threshold
keyed_channels, unkeyed_channels = _key_channel_split(chroma_key)
if not keyed_channels:
return tuple(chroma_key)
data = np.array(image.convert("RGBA"), dtype=np.uint8)
height, width = data.shape[:2]
sample = _whole_image_mask(height, width) & (data[..., 3] != 0)
if not sample.any():
return tuple(chroma_key)
total = int(np.count_nonzero(sample))
rgb = data[..., :3].astype(np.int32)
before = sample & _border_key_candidate_field(rgb, keyed_channels, unkeyed_channels, lean=False)
family = sample & _border_key_candidate_field(rgb, keyed_channels, unkeyed_channels)
if int(np.count_nonzero(before)) >= total * _KEY_DETECT_MIN_FRACTION:
return _mode_mean(rgb[before])[1]
if int(np.count_nonzero(family)) < total * _KEY_DETECT_MIN_FRACTION:
return tuple(chroma_key)
mode_bin, mean = _mode_mean(rgb[family])
near = (np.abs((rgb >> _KEY_DETECT_BIN_SHIFT) - np.asarray(mode_bin)) <= _KEY_DETECT_NEIGHBOUR_BINS).all(axis=-1)
distance = np.sqrt(((rgb - np.asarray(chroma_key)) ** 2).sum(axis=-1))
left = family & ~before & near & (distance > threshold)
if (int(np.count_nonzero(left)) >= total * _KEY_DETECT_LEAN_LEFT_MIN_FRACTION
and int(np.count_nonzero(family & ~near)) < total * _KEY_DETECT_MIN_FRACTION):
return mean
return tuple(chroma_key)
def _mode_mean(colors: np.ndarray) -> tuple[tuple[int, int, int], tuple[int, int, int]]:
"""(the most populated 8-wide bin, the mean of its members); the lowest bin on a tie."""
bins = (colors >> _KEY_DETECT_BIN_SHIFT).astype(np.int64)
slots = (bins[:, 0] << 16) | (bins[:, 1] << 8) | bins[:, 2]
values, inverse, counts = np.unique(slots, return_inverse=True, return_counts=True)
mode = int(np.argmax(counts))
members = colors[inverse == mode]
mean = members.sum(axis=0, dtype=np.int64) // len(members)
slot = int(values[mode])
return (slot >> 16, (slot >> 8) & 0xFF, slot & 0xFF), (int(mean[0]), int(mean[1]), int(mean[2]))
def _noisy(size: tuple[int, int], colour: tuple[int, int, int], spread: int, seed: int) -> np.ndarray:
rng = np.random.default_rng(seed)
base = np.asarray(colour, dtype=np.int16) + rng.integers(-spread, spread + 1, size=(size[1], size[0], 3))
return np.clip(base, 0, 255).astype(np.uint8)
def _images() -> list[tuple[str, Image.Image]]:
rng = np.random.default_rng(7)
out: list[tuple[str, Image.Image]] = []
for width, height in [(1, 1), (2, 3), (5, 4), (13, 9), (9, 131), (300, 7), (97, 301), (211, 5 * _KEY_DETECT_BAND_ROWS + 3)]:
painted = _noisy((width, height), (8, 162, 24), 9, width * 1000 + height)
subject = rng.integers(0, 256, size=(height, width, 3), dtype=np.uint8)
# a subject over the middle third: the corners and borders stay background
mixed = painted.copy()
mixed[height // 3: 2 * height // 3 + 1, width // 3: 2 * width // 3 + 1] = subject[height // 3: 2 * height // 3 + 1, width // 3: 2 * width // 3 + 1]
out.append((f"painted {width}x{height}", Image.fromarray(mixed)))
out.append((f"random {width}x{height}", Image.fromarray(subject)))
alpha = (rng.random((height, width)) > 0.4).astype(np.uint8) * 255
out.append((f"holes {width}x{height}", Image.fromarray(np.dstack([mixed, alpha]))))
# two clusters of equal size on the border: the tie goes to the lowest bin
tie = np.zeros((40, 40, 3), dtype=np.uint8)
tie[:, :20] = (8, 162, 24)
tie[:, 20:] = (8, 170, 24)
out.append(("tie", Image.fromarray(tie)))
# a tie between bins that order one way by red and the other by blue
tie[:, :20] = (8, 162, 40)
tie[:, 20:] = (16, 162, 24)
out.append(("tie across channels", Image.fromarray(tie)))
grok = _noisy((120, 90), (216, 46, 147), 6, 11)
out.append(("grok magenta", Image.fromarray(grok)))
# leaning greens past the declared key's cut, across it (the noise straddles it) and inside it, over several
# bands, and two of them on one border
for seed, (name, colour, spread) in enumerate((("leaning past the cut", (0, 200, 90), 3),
("leaning across the cut", (0, 206, 84), 4),
("leaning inside the cut", (0, 214, 80), 2))):
out.append((name, Image.fromarray(_noisy((150, 2 * _KEY_DETECT_BAND_ROWS + 9), colour, spread, 20 + seed))))
two = _noisy((90, 90), (0, 200, 90), 2, 31)
two[:, 60:] = (0, 120, 55)
out.append(("two leaning greens", Image.fromarray(two)))
out.append(("palette", Image.fromarray(_noisy((64, 80), (8, 162, 24), 12, 3)).convert("P")))
return out
@pytest.mark.parametrize("key", [GREEN, MAGENTA, (128, 128, 128)])
def test_banded_detection_answers_as_the_whole_image_form(key: tuple[int, int, int]) -> None:
for name, image in _images():
assert detect_background_key_rgb(image, key) == _whole_image_detect(image, key), name
def test_the_detected_colour_is_the_painted_one() -> None:
painted = Image.fromarray(_noisy((300, 2 * _KEY_DETECT_BAND_ROWS + 10), (8, 162, 24), 2, 5))
assert detect_background_key_rgb(painted, GREEN) != GREEN
r, g, b = detect_background_key_rgb(painted, GREEN)
assert abs(r - 8) <= 3 and abs(g - 162) <= 3 and abs(b - 24) <= 3
def test_corner_average_reads_any_mode_as_rgba() -> None:
for _, image in _images():
assert _corner_average(image) == _corner_average(image.convert("RGBA"))