Skip to content

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.py
index 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_candidate
for kind, target in KEY_TARGETS.items():
- if is_key_family(color, target):
+ if is_border_key_candidate(color, target):
return kind
return "white"
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.py
index 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], lis
tint axis at all and come back as two empty lists; that emptiness is the one
switch 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 a
def 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 key
saturates must read as lit (>= 64), the channels the key leaves dark must
stay 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 at
least 12% of the samples — returns the mean of the most populated 8-wide
RGB histogram bin among them. The mode, never the mean of everything: a
handful 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.py
index 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) on
2026-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 flat
background 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 Image
from sprite_gen._deps import np
from 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_candidate
from sprite_gen.spec.runio import atomic_write_text
SHAPE_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/magenta
that 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 None
if key == "auto":
for kind, target in KEY_TARGETS.items():
- if is_key_family(corner, target):
+ if is_border_key_candidate(corner, target):
return kind
return 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.py
index 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 key
a 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 fail
with different messages: residual points at `video-canvas` normalization of the
base still, subject contact at a taller/wider canvas.
"""
@@ -31,7 +32,7 @@ from typing import Any
from PIL import Image
from sprite_gen.frames.cutout import cutout
-from sprite_gen.frames.extract import is_key_family
+from sprite_gen.frames.extract import is_border_key_candidate
from sprite_gen.spec.runio import atomic_write_text
EDGE_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: tupl
for 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 += 1
else:
subject += 1
diff --git a/tests/frames/test_chroma_key_relative.py b/tests/frames/test_chroma_key_relative.py
index 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() -> None
assert 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