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): recover brightness without amplifying secondary casts

Soohong Kime83708fb2ebf
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 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 colours
tint 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-keyed
channel: `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/cyan
are not mistaken for green, or red/blue for magenta. The average-channel tint
metric 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 the
matte's 4-pixel edge-unmix band. Such contamination along an antialiased outline
is weak evidence of an intentional material. Bright green/magenta accents still
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.py
index 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 in
the channels and scores the key itself at `key_tint`, so k = tint/key_tint
recovers 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 - k
if 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_field
current_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 // width
red, 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.py
index 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