Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(chroma): a flat border in the key's hue is the key — border rule split from the interior family rule
Soohong Kim40a3094a64db
diff --git a/sprite_gen/frames/cutout.py b/sprite_gen/frames/cutout.pyindex e2b6bec..898d813 100644--- a/sprite_gen/frames/cutout.py+++ b/sprite_gen/frames/cutout.py@@ -112,15 +112,16 @@ def _corner_average(image: Image.Image) -> tuple[int, int, int]:def _detect_key_kind(color: tuple[int, int, int]) -> str:"""Classify a corner background colour into a route: magenta | green | white.- Saturated magenta/green keys — at whatever brightness the model painted- them (`extract.is_key_family`, the same rule the engine keys with) — route- to the extract engine; everything else (bright achromatic ivory/white, or- any low-saturation background) routes to the position-based matte.+ Saturated magenta/green keys — at whatever brightness or balance the model+ painted them (`extract.is_border_key_candidate`, the border rule the engine's+ detector shares: a corner colour is background evidence) — route to the+ extract engine; everything else (bright achromatic ivory/white, or any+ low-saturation background) routes to the position-based matte."""- from sprite_gen.frames.extract import is_key_family+ from sprite_gen.frames.extract import is_border_key_candidatefor kind, target in KEY_TARGETS.items():- if is_key_family(color, target):+ if is_border_key_candidate(color, target):return kindreturn "white"diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.pyindex 3606aba..a5ad2e1 100644--- a/sprite_gen/frames/extract.py+++ b/sprite_gen/frames/extract.py@@ -50,6 +50,10 @@ def edge_alpha_count(image: Image.Image, margin: int) -> int:return total+_KEY_CHANNEL_LIT = 192 # a channel the key saturates+_KEY_CHANNEL_DARK = 64 # a channel the key leaves dark — the one bar `is_key_family` / `is_border_key_candidate` reuse++def _key_channel_split(chroma_key: tuple[int, int, int]) -> tuple[list[int], list[int]]:"""Which channels the key saturates, and which it leaves dark.@@ -58,8 +62,8 @@ def _key_channel_split(chroma_key: tuple[int, int, int]) -> tuple[list[int], listint axis at all and come back as two empty lists; that emptiness is the oneswitch both callers read, and it turns off the unmix and spill passes."""- keyed_channels = [index for index, value in enumerate(chroma_key) if value >= 192]- unkeyed_channels = [index for index, value in enumerate(chroma_key) if value < 64]+ keyed_channels = [index for index, value in enumerate(chroma_key) if value >= _KEY_CHANNEL_LIT]+ unkeyed_channels = [index for index, value in enumerate(chroma_key) if value < _KEY_CHANNEL_DARK]if not keyed_channels or not unkeyed_channels:return [], []return keyed_channels, unkeyed_channels@@ -152,6 +156,16 @@ def _key_tint_field(rgb: np.ndarray, keyed_channels: list[int],return keyed_sum / len(keyed_channels) - unkeyed_sum / len(unkeyed_channels)+def _grow_into(seed: np.ndarray, allowed: np.ndarray) -> np.ndarray:+ """Every `allowed` pixel 8-connected to `seed` through `allowed` pixels (seed included)."""+ reached = seed & allowed+ while True:+ grown = _grow_chebyshev(reached) & allowed+ if not (grown & ~reached).any():+ return reached+ reached = grown++def _grow_chebyshev(mask: np.ndarray) -> np.ndarray:"""One step of 8-connected growth: the 3x3 neighborhood of every set pixel.@@ -178,9 +192,20 @@ def _grow_chebyshev(mask: np.ndarray) -> np.ndarray:# when that colour is the declared key's hue family, measures the hard cut from# it as well. Raising the radius instead would only move the cliff to the next# darker green; this removes the cliff for any brightness the model picks.-_KEY_FAMILY_MIN_KEYED = 64 # a keyed channel must at least read as lit (same bar as _key_channel_split's dark side)+_KEY_FAMILY_MIN_KEYED = _KEY_CHANNEL_DARK # a keyed channel must at least read as lit (the key split's dark bar)_KEY_FAMILY_MAX_UNKEYED_RATIO = 0.35 # unkeyed channels stay below this fraction of the dimmest keyed one_KEY_FAMILY_KEYED_BALANCE = 0.8 # for two-channel keys (magenta) the dimmer keyed channel keeps this share of the brighter+# Border candidate (2026-09-12): Grok paints #FF00FF as (216, 46, 147) / (225, 52, 155) /+# (236, 59, 161) — blue/red ≈ 0.68, under the 0.8 balance — so `is_key_family` said "not+# the key" for a colour that filled the whole border, the detector fell back to the+# declared key, and at ~120 from pure magenta the entire background survived. A flat+# border is already evidence of *background*; the balance rule exists to keep hot pink+# (250, 77, 150) and purple (213, 112, 246) inside the subject alive, and those two fail+# the border rule on a different axis: their unkeyed channel is lit (77, 112 >= 64), the+# painted keys' never is (46..59). So the border rule keeps the hue signature — keyed+# channels lit, unkeyed channels dark and saturated against the *brighter* keyed+# channel — and drops the balance between the keyed channels.+_BORDER_KEY_MAX_UNKEYED_RATIO = _KEY_FAMILY_MAX_UNKEYED_RATIO # against the brightest keyed channel, not the dimmest_KEY_DETECT_CORNER_DIV = 5 # corner patch = width/5 x height/5 (same sampling as the YCbCr path)_KEY_DETECT_MIN_FRACTION = 0.12 # family share of the samples needed to trust the detection_KEY_DETECT_BIN_SHIFT = 3 # RGB histogram bin width 8 — the mode bin, never a mean, picks the colour@@ -189,6 +214,8 @@ _KEY_DETECT_BIN_SHIFT = 3 # RGB histogram bin width 8 — the mode bin, never adef is_key_family(color: tuple[int, int, int], chroma_key: tuple[int, int, int]) -> bool:"""True when `color` is the key's hue at any brightness — a *variant of the key*.+ The *interior* rule: what a pixel with no border evidence has to be before+ it counts as key (the border rule is `is_border_key_candidate`).Brightness is free; saturation and hue are not. Every channel the keysaturates must read as lit (>= 64), the channels the key leaves dark muststay under 35% of the dimmest keyed channel, and a two-channel key keeps@@ -209,6 +236,58 @@ def is_key_family(color: tuple[int, int, int], chroma_key: tuple[int, int, int]))+def is_border_key_candidate(color: tuple[int, int, int], chroma_key: tuple[int, int, int]) -> bool:+ """True when a colour *found on a flat border* can be the key as the model painted it.++ The border rule — one function for every entry point that classifies the+ border: `detect_background_key_rgb`, `cutout --key auto`, `video-canvas`+ and the `video-frames` edge-contact split. A superset of `is_key_family`:+ everything the interior rule admits, plus colours that carry the key's hue+ *signature* without the keyed channels balancing — every keyed channel lit+ (>= 64), every unkeyed channel dark (< 64, the key split's own bar) and+ under 35% of the *brightest* keyed channel. So Grok's (216, 46, 147)+ magenta is a candidate; hot pink (250, 77, 150) and purple (213, 112, 246)+ are not (their green channel is lit), nor are ivory and cyan. The interior+ rule stays `is_key_family` — a pixel *inside* the frame has no border evidence.+ """+ keyed_channels, unkeyed_channels = _key_channel_split(chroma_key)+ if not keyed_channels:+ return False+ keyed_min = min(color[index] for index in keyed_channels)+ keyed_max = max(color[index] for index in keyed_channels)+ unkeyed_max = max(color[index] for index in unkeyed_channels)+ return is_key_family(color, chroma_key) or (+ keyed_min >= _KEY_FAMILY_MIN_KEYED+ and unkeyed_max < _KEY_CHANNEL_DARK+ and unkeyed_max <= keyed_max * _BORDER_KEY_MAX_UNKEYED_RATIO+ )+++def _key_family_field(rgb: np.ndarray, keyed_channels: list[int], unkeyed_channels: list[int]) -> np.ndarray:+ """Vector form of `is_key_family` — same three inequalities, same constants."""+ keyed_min = rgb[..., keyed_channels].min(axis=-1)+ keyed_max = rgb[..., keyed_channels].max(axis=-1)+ unkeyed_max = rgb[..., unkeyed_channels].max(axis=-1)+ return (+ (keyed_min >= _KEY_FAMILY_MIN_KEYED)+ & (unkeyed_max <= keyed_min * _KEY_FAMILY_MAX_UNKEYED_RATIO)+ & (keyed_min >= keyed_max * _KEY_FAMILY_KEYED_BALANCE)+ )+++def _border_key_candidate_field(rgb: np.ndarray, keyed_channels: list[int], unkeyed_channels: list[int]) -> np.ndarray:+ """Vector form of `is_border_key_candidate` — same inequalities, same constants."""+ keyed_min = rgb[..., keyed_channels].min(axis=-1)+ keyed_max = rgb[..., keyed_channels].max(axis=-1)+ unkeyed_max = rgb[..., unkeyed_channels].max(axis=-1)+ signature = (+ (keyed_min >= _KEY_FAMILY_MIN_KEYED)+ & (unkeyed_max < _KEY_CHANNEL_DARK)+ & (unkeyed_max <= keyed_max * _BORDER_KEY_MAX_UNKEYED_RATIO)+ )+ return _key_family_field(rgb, keyed_channels, unkeyed_channels) | signature++def _key_detect_sample_mask(height: int, width: int) -> np.ndarray:"""Corner patches (w/5 x h/5) plus the 1-px border — where the background lives."""mask = np.zeros((height, width), dtype=bool)@@ -234,8 +313,10 @@ def detect_background_key_rgb() -> tuple[int, int, int]:"""The flat background colour as the model actually painted it, or the declared key.- Samples the corner patches and the border, keeps the opaque pixels that are- the declared key's hue family (`is_key_family`), and — when they make up at+ Samples the corner patches and the border, keeps the opaque pixels that+ carry the declared key's hue signature (`is_border_key_candidate` — the+ border rule, which unlike the interior `is_key_family` does not demand the+ keyed channels balance), and — when they make up atleast 12% of the samples — returns the mean of the most populated 8-wideRGB histogram bin among them. The mode, never the mean of everything: ahandful of antialiased fringe pixels on the border must not drag an@@ -255,16 +336,7 @@ def detect_background_key_rgb(if not sample.any():return tuple(chroma_key) # type: ignore[return-value]rgb = data[..., :3].astype(np.int32)- # Vector form of `is_key_family` — same three inequalities, same constants.- keyed_min = rgb[..., keyed_channels].min(axis=-1)- keyed_max = rgb[..., keyed_channels].max(axis=-1)- unkeyed_max = rgb[..., unkeyed_channels].max(axis=-1)- family = (- sample- & (keyed_min >= _KEY_FAMILY_MIN_KEYED)- & (unkeyed_max <= keyed_min * _KEY_FAMILY_MAX_UNKEYED_RATIO)- & (keyed_min >= keyed_max * _KEY_FAMILY_KEYED_BALANCE)- )+ family = sample & _border_key_candidate_field(rgb, keyed_channels, unkeyed_channels)family_count = int(np.count_nonzero(family))if family_count < int(np.count_nonzero(sample)) * _KEY_DETECT_MIN_FRACTION:return tuple(chroma_key) # type: ignore[return-value]@@ -337,7 +409,22 @@ def remove_chroma_background(# makes that reachable, and the gate has a case for it).key_distance = _key_distance_field(source_rgb, chroma_key)if painted_key != tuple(chroma_key):- key_distance = np.minimum(key_distance, _key_distance_field(source_rgb, painted_key))+ # The painted colour's authority is border evidence, and a pixel deep+ # inside the frame has none. So its ball erases the *background*: the+ # pixels that carry the key's hue signature themselves, plus whatever+ # else inside the ball touches that keyed region (the antialiased rim+ # of the subject, whose blend with a lit subject colour lifts the+ # unkeyed channel over the signature bar). An isolated patch inside+ # the subject that merely resembles the painted colour is left alone:+ # hot pink (250, 77, 150) sits 46 from Grok's (216, 46, 147) magenta+ # and would otherwise be cut out of the subject. The declared key's+ # ball stays what it always was — a colour ball, position-blind.+ painted_distance = _key_distance_field(source_rgb, painted_key)+ in_ball = painted_distance <= threshold+ painted_keyed = in_ball & _border_key_candidate_field(source_rgb, keyed_channels, unkeyed_channels)+ painted_keyed |= in_ball & (key_distance <= threshold)+ painted_keyed = _grow_into(painted_keyed, in_ball)+ key_distance = np.where(painted_keyed, np.minimum(key_distance, painted_distance), key_distance)source_tint = _key_tint_field(source_rgb, keyed_channels, unkeyed_channels)keyed_mask = (data[..., 3] == 0) | (key_distance <= threshold)classes = np.select(diff --git a/sprite_gen/video/canvas.py b/sprite_gen/video/canvas.pyindex 45301ee..91e86ee 100644--- a/sprite_gen/video/canvas.py+++ b/sprite_gen/video/canvas.py@@ -14,7 +14,7 @@ extended without guessing.Image models paint "#00FF00" a little differently every time ((8, 166, 25) on2026-09-11), and the video model reproduces the input colour almost exactly. So-when the corners are a green/magenta key at *any* brightness, the flat+when the corners are a green/magenta key at *any* brightness or balance, the flatbackground is repainted to the exact declared key here — the pixels the`cutout` chroma matte erases become the pure key, the subject is untouched —and the padding uses that same pure key. A white/ivory base is padded with its@@ -33,7 +33,7 @@ from PIL import Imagefrom sprite_gen._deps import npfrom sprite_gen.frames.cutout import KEY_TARGETS, extract_route-from sprite_gen.frames.extract import is_key_family+from sprite_gen.frames.extract import is_border_key_candidatefrom sprite_gen.spec.runio import atomic_write_textSHAPE_SQUARE = "square"@@ -96,8 +96,9 @@ def corner_key(image: Image.Image) -> tuple[int, int, int]:def resolve_key(corner: tuple[int, int, int], key: str) -> str | None:"""Which chroma key the still is on: `green` | `magenta`, or None for a non-key (white/ivory) base.- `auto` classifies the flat corner colour with the engine's own family rule- (`is_key_family` — the key's hue at any brightness). An explicit green/magenta+ `auto` classifies the flat corner colour with the engine's own border rule+ (`is_border_key_candidate` — the key's hue signature at any brightness or+ balance; a flat corner is background evidence). An explicit green/magentathat the corners are not is refused rather than repainted blindly."""if key not in KEYS:@@ -106,10 +107,10 @@ def resolve_key(corner: tuple[int, int, int], key: str) -> str | None:return Noneif key == "auto":for kind, target in KEY_TARGETS.items():- if is_key_family(corner, target):+ if is_border_key_candidate(corner, target):return kindreturn None- if not is_key_family(corner, KEY_TARGETS[key]):+ if not is_border_key_candidate(corner, KEY_TARGETS[key]):raise SystemExit(f"video-canvas: --key {key} but the still's corners are {corner}, not a {key} key family colour; ""pass --key auto to let the corners decide or --key white for a non-chroma base"diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.pyindex 9b9d57e..248e109 100644--- a/sprite_gen/video/frames.py+++ b/sprite_gen/video/frames.py@@ -13,8 +13,9 @@ An opaque edge pixel is not always the subject. When the model painted the keya little off and part of that background survives the matte, the edge band is"touched" by leftover *background* (2026-09-11: a (8, 162, 24) green read as"framed too tight"). The check therefore classifies every contact pixel by its-raw colour — the declared key's hue family (`extract.is_key_family`) is-**residual background**, anything else is the **subject** — and the two fail+raw colour — the declared key's hue signature (`extract.is_border_key_candidate`,+the border rule: an edge pixel is border evidence) is **residual background**,+anything else is the **subject** — and the two failwith different messages: residual points at `video-canvas` normalization of thebase still, subject contact at a taller/wider canvas."""@@ -31,7 +32,7 @@ from typing import Anyfrom PIL import Imagefrom sprite_gen.frames.cutout import cutout-from sprite_gen.frames.extract import is_key_family+from sprite_gen.frames.extract import is_border_key_candidatefrom sprite_gen.spec.runio import atomic_write_textEDGE_ROWS = 4 # rows/cols inspected at each edge@@ -91,8 +92,9 @@ def edge_contact(image: Image.Image) -> dict[str, int]:def classify_edge_contact(raw: Image.Image, keyed: Image.Image, chroma_key: tuple[int, int, int] | None) -> dict[str, int]:"""Split the opaque edge-band pixels into `subject` and `residual` (leftover key background).- A contact pixel whose *raw* colour is the declared key's hue family is- background the matte failed to erase, not the subject. Without a chroma key+ A contact pixel whose *raw* colour carries the declared key's hue signature+ (`is_border_key_candidate`) is background the matte failed to erase, not the+ subject. Without a chroma key(matte route) every contact is the subject."""alpha = keyed.convert("RGBA").getchannel("A").load()@@ -106,7 +108,7 @@ def classify_edge_contact(raw: Image.Image, keyed: Image.Image, chroma_key: tuplfor x, y in band:if alpha[x, y] <= 0:continue- if chroma_key is not None and is_key_family(rgb[x, y], chroma_key):+ if chroma_key is not None and is_border_key_candidate(rgb[x, y], chroma_key):residual += 1else:subject += 1diff --git a/tests/frames/test_chroma_key_relative.py b/tests/frames/test_chroma_key_relative.pyindex c811e8f..d47452e 100644--- a/tests/frames/test_chroma_key_relative.py+++ b/tests/frames/test_chroma_key_relative.py@@ -322,6 +322,105 @@ def test_hot_pink_block_inside_the_subject_survives_a_grok_magenta_key() -> Noneassert subject_changed == 0, f"{subject_changed} subject px altered (hot-pink block must be untouched)"+from sprite_gen.frames.extract import is_border_key_candidate # noqa: E402+++ ("color", "key", "expected"),+ [+ ((216, 46, 147), MAGENTA, True), # Grok, 2026-09-11 (blue/red 0.68)+ ((225, 52, 155), MAGENTA, True),+ ((236, 59, 161), MAGENTA, True), # prop-fence-bamboo raw border+ ((230, 40, 170), MAGENTA, True), # variants a model could paint next+ ((200, 60, 140), MAGENTA, True),+ ((255, 0, 128), MAGENTA, True), # off-balance but unmistakably the key's hue on a border+ ((170, 8, 180), MAGENTA, True), # everything the interior rule admits, the border rule admits+ ((8, 162, 24), GREEN, True),+ ((20, 120, 25), GREEN, True),+ (HOT_PINK, MAGENTA, False), # unkeyed (green) channel lit: 77 >= 64+ (PURPLE, MAGENTA, False), # 112 >= 64+ ((0, 255, 255), GREEN, False), # cyan+ ((120, 255, 120), GREEN, False), # washed out+ ((30, 60, 30), GREEN, False), # keyed channel not lit+ ((70, 60, 65), MAGENTA, False), # dark grey-mauve: unkeyed dark but not saturated (60/70)+ ((248, 247, 242), MAGENTA, False),+ ((216, 46, 147), (128, 128, 128), False), # degenerate key has no candidates+ ],+)+def test_is_border_key_candidate(color: tuple[int, int, int], key: tuple[int, int, int], expected: bool) -> None:+ assert is_border_key_candidate(color, key) is expected+++def test_border_rule_is_a_superset_of_the_interior_rule_and_matches_its_vector_form() -> None:+ """Every interior-family colour is a border candidate (detection cannot regress), and the+ vectorised rule the detector and engine use agrees with the scalar one on a colour grid."""+ import itertools++ from sprite_gen._deps import np+ from sprite_gen.frames.extract import _border_key_candidate_field, _key_channel_split++ grid = list(itertools.product(range(0, 256, 17), repeat=3))+ for key in (GREEN, MAGENTA):+ scalar = [is_border_key_candidate(color, key) for color in grid]+ vector = _border_key_candidate_field(np.array(grid, dtype=np.int32), *_key_channel_split(key))+ assert vector.tolist() == scalar+ for color, border in zip(grid, scalar):+ if is_key_family(color, key):+ assert border, (color, key)++[email protected](("key", "key_rgb", "background"), GROK_MAGENTA_CASES)+def test_painted_key_ball_is_bounded_by_connectivity_to_the_background(+ key: str, key_rgb: tuple[int, int, int], background: tuple[int, int, int]+) -> None:+ """The cut around the painted colour erases the background it is connected to, not look-alikes inside the subject.++ Two patches of the same off-signature blend colour (the painted key mixed with+ a lit subject colour, as an antialiased rim is): one on the subject's rim, touching+ the background, and one buried inside the subject. The rim patch is background+ residue and goes; the buried patch has no border evidence and stays. The declared+ key's own ball is unchanged — position-blind — so a patch *within 96 of pure magenta*+ inside the subject is still erased, as it always was.+ """+ blend = tuple((b + s) // 2 for b, s in zip(background, HIGHLIGHT)) # e.g. (223, 128, 168): G lit, ~90 from bg+ assert not is_border_key_candidate(blend, key_rgb)+ assert color_dist(blend, background) <= _EXTRACT_KEY_THRESHOLD < color_dist(blend, key_rgb)+ source = make_flat_key_still(background)+ px = source.load()+ x0, y0, x1, y1 = SUBJECT_BOX+ for y in range(y0, y0 + 4): # rim patch: inside the subject box, touching the background above+ for x in range(x0 + 8, x0 + 24):+ px[x, y] = blend + (255,)+ for y in range(76, 88): # buried patch: surrounded by brown+ for x in range(76, 88):+ px[x, y] = blend + (255,)+ result = remove_chroma_background(+ source, key_rgb, _EXTRACT_KEY_THRESHOLD, _EXTRACT_FRINGE_THRESHOLD, _EXTRACT_FRINGE_DELTA+ )+ out = result.load()+ assert all(out[x, y][3] == 0 for y in range(y0, y0 + 4) for x in range(x0 + 8, x0 + 24)), "rim residue must be cut"+ assert all(out[x, y] == px[x, y] for y in range(76, 88) for x in range(76, 88)), "buried look-alike must survive"+ assert all(out[x, y][3] == 0 for y in range(SIZE) for x in range(SIZE) if not _in_subject(x, y)), "background gone"+++def color_dist(a: tuple[int, int, int], b: tuple[int, int, int]) -> float:+ return sum((p - q) ** 2 for p, q in zip(a, b)) ** 0.5+++def test_edge_contact_split_reads_grok_magenta_residue_as_residual() -> None:+ """`video-frames` edge classification uses the same border rule: leftover Grok magenta is residue, hot pink is subject."""+ from sprite_gen.video.frames import classify_edge_contact++ raw = Image.new("RGB", (40, 40), (110, 70, 50))+ keyed = Image.new("RGBA", (40, 40), (110, 70, 50, 255))+ for x in range(0, 10):+ raw.putpixel((x, 0), (216, 46, 147))+ raw.putpixel((x, 1), HOT_PINK)+ split = classify_edge_contact(raw, keyed, MAGENTA)+ assert split["residual"] == 10+ assert split["subject"] == 40 * 40 - 10 - (40 - 4 * 2) * (40 - 4) # every other band pixel is opaque subject++# --- real stills (opt-in) ---------------------------------------------------------------# Binary stills from image models are not committed (private data, and every regeneration# would pile up in the public history). Point SPRITE_GEN_CHROMA_REAL_STILLS at them to run