Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(chroma): recover brightness without amplifying secondary casts
Soohong Kime83708fb2ebf
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex d13690d..1411098 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -151,10 +151,17 @@ model (observed = (1−k)·subject + k·key, solved for the subject), so colourstint are untouched. `small` keeps the conservative tint threshold of 40; `full` lowers it to 8.For `full`, a key hue requires every keyed channel to exceed every non-keyedchannel: `G − max(R, B)` for green, `min(R, B) − G` for magenta. This same-excess drives correction strength and the `auto` reference check, so yellow/cyan+excess selects pixels for correction and drives the `auto` reference check, so yellow/cyanare not mistaken for green, or red/blue for magenta. The average-channel tintmetric remains unchanged in `small` and the edge matte.+The blend fraction still uses the linear average-channel tint, not hue excess.+Full correction recovers mean brightness but does not amplify colour differences+within the keyed or non-keyed channel group. Otherwise a small red/blue imbalance+can become a strong secondary cast when much of the observed colour is key light.+This is bounded colour recovery, not reconstruction of the original material:+blue or purple already present without the key hue remains unchanged.+The `auto` reference test discounts dark pixels (all channels below 64) in thematte's 4-pixel edge-unmix band. Such contamination along an antialiased outlineis weak evidence of an intentional material. Bright green/magenta accents stilldiff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.pyindex a5677e1..03da182 100644--- a/sprite_gen/frames/extract.py+++ b/sprite_gen/frames/extract.py@@ -84,22 +84,37 @@ def despill_color(chroma_key: tuple[int, int, int],key_tint: float,tint: float,+ *,+ chroma_groups: tuple[list[int], list[int]] | None = None,) -> tuple[float, tuple[int, int, int]]:"""Estimate the key fraction of a blend pixel and remove it from the RGB.Blend model: observed = (1-k)*subject + k*key. key_tint_score is linear inthe channels and scores the key itself at `key_tint`, so k = tint/key_tintrecovers a subject estimate whose own tint score is ~0. Returns the- subject coverage (1-k) and the despilled color.+ subject coverage (1-k) and the despilled color. Opaque full-spill correction+ supplies the declared key's `chroma_groups` to limit chroma gain: recover+ mean brightness but do not magnify channel differences within either group.+ Small colour errors otherwise become strong secondary casts when coverage+ is small. Groups come from the declared key, even if the painted key is dim."""k = min(tint / key_tint, 1.0)coverage = 1.0 - kif coverage <= 0:return 0.0, (0, 0, 0)- red, green, blue = (- min(255, max(0, round((color[index] - k * chroma_key[index]) / coverage)))- for index in range(3)- )+ unmixed = [(color[index] - k * chroma_key[index]) / coverage for index in range(3)]+ if chroma_groups is not None:+ for channels in chroma_groups:+ if not channels:+ continue+ mean = sum(unmixed[index] for index in channels) / len(channels)+ observed_mean = sum(color[index] for index in channels) / len(channels)+ for index in channels:+ # Preserve observed differences, including with a slightly+ # impure painted key; subtracting its channel imbalance here+ # would manufacture another cast in otherwise neutral pixels.+ unmixed[index] = mean + color[index] - observed_mean+ red, green, blue = (min(255, max(0, round(value))) for value in unmixed)return coverage, (red, green, blue)@@ -553,8 +568,6 @@ def remove_chroma_background(# the image, and a pixel it despilled is no longer a spill candidate.spill_field = _key_excess_field if spill_require_hue else _key_tint_fieldcurrent_tint = spill_field(data[..., :3].astype(np.int32), keyed_channels, unkeyed_channels)- spill_key_tint = float(spill_field(np.asarray(painted_key, dtype=np.int32),- keyed_channels, unkeyed_channels))# Candidacy and acceptance read the same bar: a cluster can never be accepted# below `spill_min_tint`, so admitting only pixels at or above `fringe_delta`# would silently keep the lowered bar from reaching anything when it is the@@ -594,8 +607,15 @@ def remove_chroma_background(y = index // widthred, green, blue, alpha = (int(value) for value in data[y, x])color = (red, green, blue)+ # Hue excess decides *whether* this is spill. It is nonlinear+ # and cannot estimate a blend fraction: G-max(R,B) drives G+ # to the larger channel, turning a slight blue bias into cyan.+ # Use the linear tint axis for unmixing and bound the gain on+ # the remaining chroma when treating opaque full-spill pixels.coverage, despilled = despill_color(- color, painted_key, spill_key_tint, tints_left[index]+ color, painted_key, key_tint,+ key_tint_score(color, chroma_key) if spill_require_hue else tints_left[index],+ chroma_groups=(keyed_channels, unkeyed_channels) if spill_require_hue else None,)if coverage > 0:data[y, x] = (*despilled, alpha)diff --git a/tests/video/test_spill_hue_evidence.py b/tests/video/test_spill_hue_evidence.pyindex 490bff8..37fa247 100644--- a/tests/video/test_spill_hue_evidence.py+++ b/tests/video/test_spill_hue_evidence.py@@ -21,6 +21,8 @@ def _reference(path: Path, key: str, color: tuple[int, int, int], *, fringe=Fals@pytest.mark.parametrize('key,color', [('green', (235, 210, 65)), # yellow: green exceeds the mean, but not red('green', (65, 210, 235)), # cyan: green exceeds the mean, but not blue+ ('green', (30, 70, 180)), # blue material is not green spill+ ('green', (180, 70, 30)), # red material is not green spill('magenta', (220, 80, 65)), # red: red/blue mean is not evidence of magenta('magenta', (65, 80, 220)), # blue])@@ -64,3 +66,63 @@ def test_a_bright_thin_green_detail_at_the_outline_is_material(tmp_path):ImageDraw.Draw(im).rectangle((24, 24, 135, 135), outline=(160, 180, 165), width=2)im.save(source)assert frames.decide_spill(source, 'green')['mode'] == 'small'++[email protected]('key,color', [+ ('green', (72, 230, 80)),+ ('green', (80, 230, 72)),+ ('magenta', (220, 80, 212)),+])+def test_full_does_not_amplify_colour_noise_into_another_hue(tmp_path, key, color):+ source = _reference(tmp_path/'ref.png', key, color)+ frames.key_frames([source], tmp_path/'out', key=key, check_edges=False, spill='full')+ r, g, b, a = Image.open(tmp_path/'out/ref.png').getpixel((80, 80))+ assert a == 255+ # Removing a strong key cast must not magnify a small red/blue difference+ # into saturated cyan, blue, or orange on otherwise neutral material.+ assert abs(r-b) <= abs(color[0]-color[2]) + 1+ assert abs(g-(r+b)/2) <= 1+ # Merely capping green would leave this pale subject dark.+ assert (r+g+b)/3 > 2 * min(color)++[email protected]('key,color,expected', [+ ('green', (80, 165, 80), (120, 120, 120, 255)),+ ('magenta', (165, 80, 165), (120, 120, 120, 255)),+])+def test_full_still_recovers_brightness_from_a_neutral_key_blend(tmp_path, key, color, expected):+ source = _reference(tmp_path/'ref.png', key, color)+ frames.key_frames([source], tmp_path/'out', key=key, check_edges=False, spill='full')+ assert Image.open(tmp_path/'out/ref.png').getpixel((80, 80)) == expected++[email protected]('key,color', [+ ('green', (70, 210, 150)),+ ('green', (150, 210, 70)),+ ('magenta', (210, 70, 150)),+])+def test_full_keeps_non_key_colour_differences_instead_of_turning_everything_grey(tmp_path, key, color):+ source = _reference(tmp_path/'ref.png', key, color)+ frames.key_frames([source], tmp_path/'out', key=key, check_edges=False, spill='full')+ r, g, b, a = Image.open(tmp_path/'out/ref.png').getpixel((80, 80))+ assert a == 255+ assert abs((r-b)-(color[0]-color[2])) <= 1+ assert abs(g-(r+b)/2) <= 1++[email protected]('key,painted,color', [+ ('green', (6, 250, 0), (80, 220, 90)),+ ('green', (6, 170, 0), (100, 160, 110)),+ ('magenta', (250, 6, 240), (210, 100, 200)),+ ('magenta', (220, 40, 150), (180, 140, 170)),+])+def test_an_imperfect_painted_key_cannot_introduce_a_secondary_cast(tmp_path, key, painted, color):+ source = tmp_path/'painted.png'+ im = Image.new('RGB', (160, 160), painted)+ ImageDraw.Draw(im).rectangle((24, 24, 135, 135), fill=color)+ im.save(source)+ frames.key_frames([source], tmp_path/'out', key=key, check_edges=False, spill='full')+ r, g, b, a = Image.open(tmp_path/'out/painted.png').getpixel((80, 80))+ assert a == 255+ assert abs((r-b)-(color[0]-color[2])) <= 1+ assert abs(g-(r+b)/2) <= 1