Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# SPDX-License-Identifier: Apache-2.0
"""Byte-identity guard for the extract-performance optimizations (plan
sprite-gen/extract-performance).
The hot paths `_grid_score_edges`/`_best_phase`, `_matte_ycc`,
`_flood_clear_background_ycc`, `_cleanup_alpha_ycc` and `_dominant_block_color`
were rewritten for speed under an absolute determinism contract: same input ->
byte-identical output. These tests pin that contract structurally by running a
**naive reference** implementation beside the optimized one and asserting exact
equality — so any future edit that changes a value, not just the golden run,
trips here.
For the grid scorer the reference is the *integer-exact* naive form, not the
original float reduction (plan `sprite-gen/best-phase-hotspot`, 2026-07-25).
The metric is unchanged; only its evaluation is: the old form accumulated
floats per pixel and lands a last-ulp apart from the on-paper rational value,
so the rational value — not the old float's bit pattern — is the truth, and the
optimized scorer is pinned bit for bit to the naive form of it.
"""
from __future__ import annotations
import math
from PIL import Image
from sprite_gen.frames import extract
def _synthetic_keyed(width: int = 60, height: int = 48) -> Image.Image:
"""Green-screen-ish RGBA: flat key bg + shaded key + subject blob + AA
fringe + an enclosed key-family pixel (connectivity) + spill band."""
img = Image.new("RGBA", (width, height), (0, 0, 0, 0))
px = img.load()
for y in range(height):
for x in range(width):
# base key background, slightly shaded by position (gradient noise)
g = 238 - ((x + y) % 7)
r = 11 + ((x * 3) % 5)
b = 27 + ((y * 2) % 5)
a = 255
# subject blob (a magenta-ish body) in the center
if 18 <= x <= 40 and 12 <= y <= 38:
r, g, b = 180 + (x % 20), 40 + (y % 15), 150 - (x % 12)
# spill band on the blob's left edge (key-direction chroma)
if x <= 22:
r, g, b = 120, 180, 90
# an enclosed key-family pixel deep inside the subject (must survive)
if x == 30 and y == 25:
r, g, b = 12, 236, 26
px[x, y] = (r, g, b, a)
return img
# --- reference (naive, pre-optimization) implementations --------------------
def _ref_cells(component, pitch, phase):
"""Cell-by-cell opaque pixels, in the scorer's iteration order."""
xs = extract._grid_edges(component.width, pitch[0], phase[0])
ys = extract._grid_edges(component.height, pitch[1], phase[1])
p = component.load()
for yi in range(len(ys) - 1):
for xi in range(len(xs) - 1):
acc = []
for y in range(ys[yi], min(ys[yi + 1], component.height)):
for x in range(xs[xi], min(xs[xi + 1], component.width)):
q = p[x, y]
if q[3] >= 128:
acc.append(q[:3])
yield acc
def _ref_grid_uniformity(component, pitch, phase):
"""Naive form of the integer-exact contract: the cell term is `T / n` with
`T = sum |n*v - s|` an exact integer, spelled out pixel by pixel with no
symmetry identity and no translate tables. Bit-identical to the optimized
scorer — same cell order, same single rounding per cell."""
total_dev = 0.0
total_n = 0
for acc in _ref_cells(component, pitch, phase):
n = len(acc)
if n < 2:
continue
s = [sum(c[k] for c in acc) for k in range(3)]
t = sum(abs(n * c[k] - s[k]) for c in acc for k in range(3))
total_dev += t / n
total_n += n
return (total_dev / total_n) if total_n else 1e9
def _ref_matte(source, key):
width, height = source.size
out = Image.new("RGBA", source.size, (0, 0, 0, 0))
src_pixels = source.load()
out_pixels = out.load()
_, key_cb, key_cr = extract.rgb_to_ycc(*key)
key_vb, key_vr = key_cb - 128.0, key_cr - 128.0
key_len = math.hypot(key_vb, key_vr)
for y in range(height):
for x in range(width):
red, green, blue, alpha = src_pixels[x, y]
if alpha == 0:
continue
luma, cb, cr = extract.rgb_to_ycc(red, green, blue)
dist = math.hypot(cb - key_cb, cr - key_cr)
coverage = extract.smoothstep(extract._YCC_CHROMA_IN, extract._YCC_CHROMA_OUT, dist)
if coverage <= 0:
continue
if key_len > 1 and dist < extract._YCC_DESPILL_BAND:
pixel_vb, pixel_vr = cb - 128.0, cr - 128.0
proj = (pixel_vb * key_vb + pixel_vr * key_vr) / key_len
if proj > 0:
weight = extract.smoothstep(
0.0, 1.0, (extract._YCC_DESPILL_BAND - dist) / extract._YCC_DESPILL_BAND
) * extract._YCC_DESPILL_SCALE
cb = 128.0 + (pixel_vb - key_vb / key_len * proj * weight)
cr = 128.0 + (pixel_vr - key_vr / key_len * proj * weight)
red, green, blue = extract.ycc_to_rgb(luma, cb, cr)
out_pixels[x, y] = (red, green, blue, int(alpha * coverage))
# naive border flood, matching pre-optimization semantics
_ref_flood(out, source, key_cb, key_cr)
return out
def _ref_flood(out, source, key_cb, key_cr):
width, height = source.size
if width < 3 or height < 3:
return
src_pixels = source.load()
out_pixels = out.load()
visited = bytearray(width * height)
stack = []
def push(x, y):
position = y * width + x
if visited[position]:
return
red, green, blue = src_pixels[x, y][:3]
_, cb, cr = extract.rgb_to_ycc(red, green, blue)
if math.hypot(cb - key_cb, cr - key_cr) <= extract._YCC_FLOOD_TOL:
visited[position] = 1
stack.append(position)
for x in range(width):
push(x, 0)
push(x, height - 1)
for y in range(height):
push(0, y)
push(width - 1, y)
while stack:
position = stack.pop()
x, y = position % width, position // width
red, green, blue, _ = out_pixels[x, y]
out_pixels[x, y] = (red, green, blue, 0)
if x > 0:
push(x - 1, y)
if x < width - 1:
push(x + 1, y)
if y > 0:
push(x, y - 1)
if y < height - 1:
push(x, y + 1)
def _ref_cleanup(image):
width, height = image.size
if width < 3 or height < 3:
return
before = image.getchannel("A").tobytes()
pixels = image.load()
def opaque(x, y):
if x < 0 or y < 0 or x >= width or y >= height:
return 0
return 1 if before[y * width + x] > extract._YCC_ALPHA_EMPTY else 0
for y in range(height):
for x in range(width):
neighbors = (
opaque(x - 1, y) + opaque(x + 1, y) + opaque(x, y - 1) + opaque(x, y + 1)
+ opaque(x - 1, y - 1) + opaque(x + 1, y - 1)
+ opaque(x - 1, y + 1) + opaque(x + 1, y + 1)
)
if before[y * width + x] > extract._YCC_ALPHA_EMPTY:
if neighbors == 0:
red, green, blue, _ = pixels[x, y]
pixels[x, y] = (red, green, blue, 0)
elif neighbors >= 7:
red, green, blue, _ = pixels[x, y]
pixels[x, y] = (red, green, blue, 255)
def _ref_dominant(opaque, detail_bias=False):
if len(opaque) == 1:
return opaque[0][:3]
def luma(p):
return p[0] * 299 + p[1] * 587 + p[2] * 114
lo = min(opaque, key=luma)
hi = max(opaque, key=luma)
centroids = [lo[:3], hi[:3]]
assign = [0] * len(opaque)
for _ in range(3):
for i, p in enumerate(opaque):
d0 = sum((p[c] - centroids[0][c]) ** 2 for c in range(3))
d1 = sum((p[c] - centroids[1][c]) ** 2 for c in range(3))
assign[i] = 0 if d0 <= d1 else 1
for cluster in (0, 1):
members = [p for i, p in enumerate(opaque) if assign[i] == cluster]
if members:
centroids[cluster] = tuple(sum(p[c] for p in members) // len(members) for c in range(3))
dominant = 0 if assign.count(0) >= assign.count(1) else 1
if detail_bias:
darker = 0 if luma(centroids[0]) <= luma(centroids[1]) else 1
share = assign.count(darker) / len(assign)
if (
darker != dominant
and share >= 0.40
and luma(centroids[darker]) < 70000
and luma(centroids[1 - darker]) - luma(centroids[darker]) > 50000
):
dominant = darker
members = [p for i, p in enumerate(opaque) if assign[i] == dominant]
return tuple(sum(p[c] for p in members) // len(members) for c in range(3))
# --- equivalence tests ------------------------------------------------------
def test_grid_uniformity_byte_identical_to_reference():
img = _synthetic_keyed()
for pitch in [(7.0, 7.0), (7.82, 8.28), (6.17, 6.32), (5.0, 9.0)]:
for phase in [(0.0, 0.0), (1.3, 2.9), (3.0, 3.0), (pitch[0] * 5 / 8, pitch[1] * 3 / 8)]:
ref = _ref_grid_uniformity(img, pitch, phase)
got = extract._grid_uniformity(img, pitch, phase)
# exact float equality — determinism contract, not approximate
assert got == ref, f"pitch={pitch} phase={phase}: {got!r} != {ref!r}"
def test_grid_rows_rejects_a_non_rgba_component():
"""The row index reads alpha at stride 4 — a 3-channel image would silently
read colour bytes as alpha, so it has to fail loudly instead."""
import pytest
with pytest.raises(ValueError, match="RGBA"):
extract._grid_rows(_synthetic_keyed().convert("RGB"))
def _sparse_alpha_grid() -> Image.Image:
"""12x12 / 4px cells, built to exercise the two edges `_synthetic_keyed` misses.
That fixture is opaque everywhere (alpha 255) and its smallest scored cell holds
3 opaque pixels, so the alpha cutoff and the `n < 2` guard never actually run —
mutating either survived the suite (demo-hero, 2026-07-25). Here:
- cell (0,0) holds **exactly two** opaque pixels of different colours, so its
deviation is non-zero and dropping it (`n < 3`) moves the total.
- cell (1,1) mixes alpha 127 and 128 in colours far apart, so shifting the
cutoff by one moves both the membership and the mean.
"""
img = Image.new("RGBA", (12, 12), (0, 0, 0, 0))
px = img.load()
px[0, 0] = (10, 20, 30, 255)
px[1, 0] = (200, 210, 220, 255) # cell (0,0): n == 2 exactly
px[4, 4] = (0, 0, 0, 128) # cell (1,1): on the cutoff — opaque
px[5, 4] = (255, 255, 255, 127) # cell (1,1): one below — transparent
px[6, 4] = (90, 40, 160, 255)
px[4, 5] = (30, 200, 70, 200)
for y in range(8, 12): # cell (2,2): a plain populated cell
for x in range(8, 12):
px[x, y] = (120 + x, 60 + y, 200 - x, 255)
return img
def test_grid_uniformity_honours_the_alpha_cutoff_and_the_two_pixel_floor():
"""Pins the cell-membership rules, not just the arithmetic — the reference
re-derives both from the pixels, so a drifted cutoff or floor shows up as a
score mismatch."""
img = _sparse_alpha_grid()
for phase in [(0.0, 0.0), (1.0, 2.0)]:
ref = _ref_grid_uniformity(img, (4.0, 4.0), phase)
got = extract._grid_uniformity(img, (4.0, 4.0), phase)
assert got == ref, f"phase={phase}: {got!r} != {ref!r}"
# the fixture is only meaningful if those cells actually reach the scorer
assert got != 1e9, "fixture scored nothing — the cells were all skipped"
def test_best_phase_byte_identical_to_reference():
img = _synthetic_keyed()
for pitch in [(7.0, 7.0), (7.82, 8.28), (6.17, 6.32)]:
# reference argmin over the same 8x8 grid, same tie-break (strict <)
best = (0.0, 0.0)
best_score = None
for i in range(8):
for j in range(8):
phase = (pitch[0] * i / 8, pitch[1] * j / 8)
score = _ref_grid_uniformity(img, pitch, phase)
if best_score is None or score < best_score:
best_score = score
best = phase
assert extract._best_phase(img, pitch) == best, f"pitch={pitch}"
def test_matte_and_flood_byte_identical_to_reference():
img = _synthetic_keyed()
key = (0, 255, 0)
ref = _ref_matte(img, key)
got, frac = extract._matte_ycc(img, key)
assert got.tobytes() == ref.tobytes()
# frac is derived from the matted alpha histogram — must match too
opaque = sum(ref.getchannel("A").histogram()[extract._YCC_ALPHA_EMPTY + 1:])
assert frac == opaque / (img.width * img.height)
def test_cleanup_alpha_byte_identical_to_reference():
img = _synthetic_keyed()
got, _ = extract._matte_ycc(img, (0, 255, 0))
ref = got.copy()
extract._cleanup_alpha_ycc(got)
_ref_cleanup(ref)
assert got.tobytes() == ref.tobytes()
def test_dominant_block_color_byte_identical_to_reference():
# deterministic pixel sets covering single, two-cluster, and detail-bias cases
cases = [
[(200, 30, 40)],
[(10, 10, 10), (240, 240, 240), (12, 8, 9), (250, 249, 248), (11, 11, 12)],
[(5, 5, 5)] * 3 + [(250, 250, 250)] * 4,
[(i * 7 % 256, i * 13 % 256, i * 29 % 256) for i in range(50)],
]
for opaque in cases:
for bias in (False, True):
assert extract._dominant_block_color(list(opaque), bias) == _ref_dominant(list(opaque), bias)