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(decontam): cap only key-hued colours, so warm subjects survive magenta

Soohong Kim09c8569145ca
diff --git a/sprite_gen/frames/decontam.py b/sprite_gen/frames/decontam.py
index 34a0b2c..8d5cec1 100644
--- a/sprite_gen/frames/decontam.py
+++ b/sprite_gen/frames/decontam.py
@@ -36,8 +36,8 @@ Guards, in order of the decision they make:
mix explains it (by `OPAQUE_MARGIN`, or three noise sigmas when the source is
noisier) is ordinary shading, not a blend: it keeps the engine's bytes. Only
when the subject owns no key-coloured material is a residual key hue on such a
- pixel capped (`KEY_HUE_TINT`), which lowers the keyed channel and never raises
- another.
+ pixel capped (`KEY_HUE_TINT`), which lowers the keyed channels and never raises
+ one.
- *Tint.* Between the two: a pixel pushed from its colour toward the key by at
least `TINT_SHIFT`, and `TINT_RATIO` times more than the fit misses by, is
recoloured with its coverage left alone (a faint cast, not proven coverage).
@@ -169,11 +169,18 @@ def learn_palette(samples: np.ndarray, size: int = PALETTE_SIZE) -> np.ndarray:
def _cap_key_hue(rgb: np.ndarray, keyed_channels: list[int], unkeyed_channels: list[int], tint: float) -> np.ndarray:
- """Lower every keyed channel to at most (max unkeyed channel + tint). Never raises a channel."""
+ """Take the key hue out of the colours that carry it and leave every other colour alone.
+
+ A colour carries the key hue by the engine's own test (`_key_excess_field`: G - max(R, B)
+ for green, min(R, B) - G for magenta). Where that excess passes `tint`, the part beyond it
+ comes off every keyed channel alike: for green that is G <= max(R, B) + tint, for magenta
+ R and B come down together and whichever led keeps its lead. A red, a blue or a skin tone
+ under a magenta key has no key hue and is returned as it is. Never raises a channel.
+ """
out = np.array(rgb, dtype=np.float64, copy=True)
- ceiling = out[..., unkeyed_channels].max(axis=-1) + tint
+ over = np.maximum(_key_excess_field(out, keyed_channels, unkeyed_channels) - tint, 0.0)
for channel in keyed_channels:
- out[..., channel] = np.minimum(out[..., channel], ceiling)
+ out[..., channel] -= over
return out
diff --git a/tests/frames/test_chroma_decontam.py b/tests/frames/test_chroma_decontam.py
index 37656e4..5b6897f 100644
--- a/tests/frames/test_chroma_decontam.py
+++ b/tests/frames/test_chroma_decontam.py
@@ -280,6 +280,54 @@ def test_magenta_key_is_handled_by_the_same_pass():
assert before > 0.02 and after <= 0.5 * before
+# Grok's "magenta" comes back darker and bluer than the painted key (the values measured in
+# test_chroma_key_relative). Warm colours carry no magenta hue of their own (min(R, B) - G < 0).
+GROK_MAGENTA = (216, 46, 147)
+
+
+def test_key_hue_cap_touches_only_key_hued_colours():
+ colours = np.array([[110, 70, 50], [40, 70, 230], [232, 180, 150], [200, 40, 30], # no magenta hue
+ [210, 60, 120], [190, 150, 190], [60, 200, 70], [30, 110, 40]], np.float64)
+ green = decontam._cap_key_hue(colours, [1], [0, 2], 8.0)
+ classic = colours.copy()
+ classic[:, 1] = np.minimum(colours[:, 1], colours[:, [0, 2]].max(1) + 8) # G <= max(R, B) + 8
+ assert np.array_equal(green, classic)
+ magenta = decontam._cap_key_hue(colours, [0, 2], [1], 8.0)
+ assert np.array_equal(magenta[:4], colours[:4]) # warm, blue, skin and red are not magenta
+ assert magenta[4].tolist() == [158, 60, 68] # a red with a magenta cast stays red
+ assert magenta[5].tolist() == [158, 150, 158] # a grey with a magenta cast comes back grey
+ assert np.array_equal(magenta[6:], colours[6:]) and (magenta <= colours).all()
+
+
[email protected]("painted", [MAGENTA_PAINTED, GROK_MAGENTA], ids=["painted", "grok"])
+def test_magenta_key_leaves_an_opaque_warm_subject_alone(painted):
+ """A hard-edged brown square: nothing on its edge is a blend, so nothing may change."""
+ raw = np.full((128, 128, 3), painted, np.uint8)
+ raw[32:96, 32:96] = (110, 70, 50)
+ raw[56:72, 56:72] = (230, 210, 190)
+ off, _ = _key(raw, (255, 0, 255))
+ pal, stats = _key(raw, (255, 0, 255), decontam="palette")
+ assert stats["palette_keyfree"] is True
+ assert [110, 70, 50] in stats["palette"] and [230, 210, 190] in stats["palette"]
+ assert np.array_equal(pal, off)
+
+
[email protected]("video", [False, True], ids=["still", "4:2:0"])
+def test_magenta_key_keeps_a_skin_tone_and_cleans_its_edge(video):
+ F, A = _render(subject=(232, 180, 150), lineart=(90, 50, 40), highlight=(250, 215, 195))
+ raw = _composite_on(F, A, GROK_MAGENTA)
+ if video:
+ raw = _subsample_420(raw)
+ edge, interior = _edge(raw, (255, 0, 255))
+ off, _ = _key(raw, (255, 0, 255))
+ pal, stats = _key(raw, (255, 0, 255), decontam="palette", decontam_fit="video" if video else "still")
+ assert any(r > g + 40 for r, g, _b in stats["palette"]) # the skin tone is learned, not greyed toward G + 8
+ halo_off, halo_pal = _halo(off, F, A, edge), _halo(pal, F, A, edge)
+ assert halo_pal[0] <= 0.5 * halo_off[0] and halo_pal[1] <= 0.5 * halo_off[1]
+ assert _recall(pal, A, edge) >= _recall(off, A, edge)
+ assert np.array_equal(off[interior], pal[interior])
+
+
# --------------------------------------------------------------------------- guards
def test_subject_that_owns_key_material_keeps_it():