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: reject ineffective transparent generation

Soohong Kim069bad3c35d0
diff --git a/docs/gen.md b/docs/gen.md
index 82d8ce8..b84c5eb 100644
--- a/docs/gen.md
+++ b/docs/gen.md
@@ -74,10 +74,12 @@ sprite-gen gen \
Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image.py …` (same args).
- **Non-transparent**: the raw PNG (chroma background included) is copied to `--out`.
-- **`--transparent`**: the raw is keyed to clean RGBA via the ported transparent
- contract (`sprite_gen/gen/chroma.py`). Generate on a solid `#FF00FF` (or `#00FF00`)
- background — pick the key by subject colour (magenta subjects → green key). Any
- transparent pixel that still carries non-zero RGB **fails loudly** (No Silent Fallback).
+- **`--transparent`**: the raw is keyed to clean RGBA through the frame extractor's
+ canonical YCbCr matte (`remove_chroma_background_ycbcr`). Generate on a `#FF00FF`
+ (or `#00FF00`) background — pick the key by subject colour (magenta subjects →
+ green key). Gradients and texture within that chroma family are supported. A result
+ with `alpha_zero_pct: 0.0`, or any transparent pixel that still carries non-zero
+ RGB, **fails loudly before the output or success report is published** (No Silent Fallback).
- The pre-chroma raw is preserved next to the destination as `<out>.raw.png` for audit.
- `--report` writes a `sprite-gen-image-report` JSON: provider, prompt, out/raw paths,
`raw_bytes`, `elapsed_seconds`, `session_id` (codex), the chroma stats, and the
diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.py
index 12ccc17..d4d2a1e 100644
--- a/sprite_gen/gen/chroma.py
+++ b/sprite_gen/gen/chroma.py
@@ -1,13 +1,10 @@
# SPDX-License-Identifier: Apache-2.0
"""Deterministic chroma-key -> transparent PNG contract for generated images.
-Ported verbatim in behaviour from the standalone `image-gen` skill helper
-(`scripts/chroma_key_transparent.py`, MIT, aldegad/image-gen). `image_gen` /
-Grok Imagine alpha output is not reliable, so the canonical transparent contract
-is: generate on a solid `#FF00FF` magenta or `#00FF00` green background, then key
-it out here. Removes the key colour, clears RGB for fully-transparent pixels, and
-neutralises semi-transparent chroma fringe. No silent success — transparent
-pixels that still carry non-zero RGB raise loudly.
+`image_gen` / Grok Imagine alpha output is not reliable, so generated key
+backgrounds are routed through the same YCbCr matte used by frame extraction.
+No silent success: an output with no measurable transparent area, or transparent
+pixels that retain RGB, fails before any output is published.
"""
from __future__ import annotations
@@ -17,27 +14,14 @@ from typing import Any
from PIL import Image
-KEYS: dict[str, dict[str, int | tuple[int, int, int]]] = {
- "magenta": {"target": (255, 0, 255), "min_primary": 170, "max_opposite": 115, "min_delta": 70},
- "green": {"target": (0, 255, 0), "min_primary": 170, "max_opposite": 115, "min_delta": 70},
-}
-
-
-def is_key_pixel(r: int, g: int, b: int, key: str, min_primary: int, max_opposite: int, min_delta: int) -> bool:
- if key == "magenta":
- return r >= min_primary and b >= min_primary and g <= max_opposite and (r - g) >= min_delta and (b - g) >= min_delta
- return g >= min_primary and r <= max_opposite and b <= max_opposite and (g - r) >= min_delta and (g - b) >= min_delta
-
+from sprite_gen.frames.extract import remove_chroma_background_ycbcr
+from sprite_gen.spec.runio import atomic_save_image
-def is_fringe_pixel(r: int, g: int, b: int, key: str, threshold: int) -> bool:
- if key == "magenta":
- return (r - g) > threshold and (b - g) > threshold
- return (g - r) > threshold and (g - b) > threshold
-
-def neutralize_fringe(r: int, g: int, b: int, a: int, key: str) -> tuple[int, int, int, int]:
- neutral = g if key == "magenta" else max(r, b)
- return (neutral, neutral, neutral, max(0, a // 3))
+KEYS: dict[str, dict[str, tuple[int, int, int]]] = {
+ "magenta": {"target": (255, 0, 255)},
+ "green": {"target": (0, 255, 0)},
+}
def write_white_check(image: Image.Image, path: Path) -> None:
@@ -51,78 +35,70 @@ def key_transparent(
out_path: Path,
*,
key: str = "magenta",
- min_primary: int | None = None,
- max_opposite: int | None = None,
- min_delta: int | None = None,
- fringe_threshold: int = 4,
- fringe_alpha_max: int = 239,
- fringe_cleanup: bool = True,
white_check: Path | None = None,
) -> dict[str, Any]:
- """Key a solid-chroma-background PNG to a clean transparent RGBA PNG.
+ """Key a chroma-background PNG to a clean transparent RGBA PNG.
Returns a stats dict (keyed/fringe/cleaned pixel counts, alpha_zero_pct).
- Raises SystemExit if any transparent pixel keeps non-zero RGB (No Silent
- Fallback: a "transparent" result that still leaks the key colour is a defect).
+ Raises SystemExit before publishing if no measurable transparent area was
+ made, or if a transparent pixel keeps non-zero RGB.
"""
if key not in KEYS:
raise SystemExit(f"chroma: unknown key {key!r}; expected one of {sorted(KEYS)}")
- defaults = KEYS[key]
- min_primary = int(defaults["min_primary"]) if min_primary is None else min_primary
- max_opposite = int(defaults["max_opposite"]) if max_opposite is None else max_opposite
- min_delta = int(defaults["min_delta"]) if min_delta is None else min_delta
-
- image = Image.open(input_path).convert("RGBA")
+ source = Image.open(input_path).convert("RGBA")
+ source_pixels = source.load()
+ warnings: list[str] = []
+ image = remove_chroma_background_ycbcr(source, KEYS[key]["target"], warnings)
pixels = image.load()
width, height = image.size
- keyed = fringe = cleaned_rgb = 0
-
+ total = width * height
+ alpha_zero = stale_rgb = keyed = fringe = cleaned_rgb = 0
for y in range(height):
for x in range(width):
r, g, b, a = pixels[x, y]
- if a and is_key_pixel(r, g, b, key, min_primary, max_opposite, min_delta):
- pixels[x, y] = (0, 0, 0, 0)
- keyed += 1
- continue
+ source_a = source_pixels[x, y][3]
if a == 0:
+ alpha_zero += 1
+ if source_a > 0:
+ keyed += 1
if r or g or b:
pixels[x, y] = (0, 0, 0, 0)
cleaned_rgb += 1
- continue
- if fringe_cleanup and 0 < a <= fringe_alpha_max and is_fringe_pixel(r, g, b, key, fringe_threshold):
- pixels[x, y] = neutralize_fringe(r, g, b, a, key)
+ elif source_a > a:
fringe += 1
- out_path.parent.mkdir(parents=True, exist_ok=True)
- image.save(out_path)
+ for r, g, b, a in image.getdata():
+ if a == 0 and (r or g or b):
+ stale_rgb += 1
- if white_check is not None:
- white_check.parent.mkdir(parents=True, exist_ok=True)
- write_white_check(image, white_check)
-
- total = width * height
- alpha_zero = stale_rgb = 0
- for y in range(height):
- for x in range(width):
- r, g, b, a = pixels[x, y]
- if a == 0:
- alpha_zero += 1
- if r or g or b:
- stale_rgb += 1
+ alpha_zero_pct = round(alpha_zero / total * 100, 2) if total else 0.0
stats: dict[str, Any] = {
"out": str(out_path),
"mode": "RGBA",
+ "method": "ycbcr",
"size": f"{width}x{height}",
"key": key,
"keyed_pixels": keyed,
"fringe_pixels": fringe,
"cleaned_transparent_rgb_pixels": cleaned_rgb,
- "alpha_zero_pct": round(alpha_zero / total * 100, 2) if total else 0.0,
+ "alpha_zero_pct": alpha_zero_pct,
"stale_transparent_rgb_pixels": stale_rgb,
}
+ if warnings:
+ stats["warnings"] = warnings
if white_check is not None:
stats["white_check"] = str(white_check)
+ if alpha_zero_pct == 0.0:
+ raise SystemExit(
+ f"chroma: generated 0.0% transparent pixels for {key} key; refusing successful transparent output"
+ )
if stale_rgb:
raise SystemExit(f"chroma: transparent pixels still contain non-zero RGB ({stale_rgb} px) in {out_path}")
+
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+ atomic_save_image(image, out_path)
+ if white_check is not None:
+ white_check.parent.mkdir(parents=True, exist_ok=True)
+ write_white_check(image, white_check)
return stats
diff --git a/tests/gen/test_gen.py b/tests/gen/test_gen.py
index 3a3e41d..4bf1804 100644
--- a/tests/gen/test_gen.py
+++ b/tests/gen/test_gen.py
@@ -337,20 +337,83 @@ def test_grok_prompt_switches_on_refs(tmp_path: Path) -> None:
def test_chroma_key_transparent_clears_magenta(tmp_path: Path) -> None:
src = tmp_path / "src.png"
img = Image.new("RGBA", (6, 6), (255, 0, 255, 255))
- img.putpixel((2, 2), (10, 20, 30, 255)) # a real subject pixel
+ for y in range(2, 4):
+ for x in range(2, 4):
+ img.putpixel((x, y), (245, 245, 245, 255))
img.save(src)
out = tmp_path / "out.png"
stats = chroma_mod.key_transparent(src, out, key="magenta", white_check=tmp_path / "check.png")
assert stats["mode"] == "RGBA"
assert stats["stale_transparent_rgb_pixels"] == 0
- assert stats["keyed_pixels"] == 35 # 36 - 1 subject pixel
+ assert stats["keyed_pixels"] == 32
keyed = Image.open(out).convert("RGBA")
assert keyed.getpixel((0, 0))[3] == 0
assert keyed.getpixel((2, 2))[3] == 255
+ ("key", "background", "subject"),
+ [
+ (
+ "magenta",
+ lambda x, y: (238 - (x % 7), 124 + ((x + y) % 31), 229 - (y % 5), 255),
+ (20, 220, 60, 255),
+ ),
+ (
+ "green",
+ lambda x, y: (124 + ((x + y) % 31), 238 - (x % 7), 129 + (y % 5), 255),
+ (220, 20, 200, 255),
+ ),
+ ],
+)
+def test_chroma_key_transparent_removes_textured_gradient_background(
+ tmp_path: Path,
+ key: str,
+ background,
+ subject: tuple[int, int, int, int],
+) -> None:
+ src = tmp_path / f"{key}-gradient.png"
+ image = Image.new("RGBA", (96, 64))
+ pixels = image.load()
+ for y in range(image.height):
+ for x in range(image.width):
+ pixels[x, y] = background(x, y)
+ for y in range(20, 44):
+ for x in range(32, 64):
+ pixels[x, y] = subject
+ image.save(src)
+
+ out = tmp_path / f"{key}-out.png"
+ stats = chroma_mod.key_transparent(src, out, key=key)
+
+ keyed = Image.open(out).convert("RGBA")
+ assert stats["alpha_zero_pct"] > 50.0
+ assert keyed.getpixel((0, 0))[3] == 0
+ assert keyed.getpixel((48, 32))[3] == 255
+
+
+def test_chroma_key_transparent_rejects_zero_percent_alpha(
+ tmp_path: Path,
+ monkeypatch,
+) -> None:
+ src = tmp_path / "src.png"
+ Image.new("RGBA", (512, 512), (20, 30, 40, 255)).save(src)
+
+ def ineffective_matte(image, chroma_key, warnings):
+ result = image.convert("RGBA")
+ result.putpixel((0, 0), (0, 0, 0, 0))
+ return result
+
+ monkeypatch.setattr(chroma_mod, "remove_chroma_background_ycbcr", ineffective_matte)
+
+ out = tmp_path / "out.png"
+ with pytest.raises(SystemExit, match=r"0\.0% transparent pixels"):
+ chroma_mod.key_transparent(src, out, key="magenta")
+ assert not out.exists()
+
+
class _FakeProvider:
name = "fake"
@@ -363,6 +426,41 @@ class _FakeProvider:
return gen_base.ProviderRun(provider=self.name, elapsed_seconds=1.23, model=request.model)
+def test_generate_image_zero_percent_alpha_fails_without_success_report(
+ tmp_path: Path,
+ monkeypatch,
+) -> None:
+ fake = _FakeProvider()
+ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
+ monkeypatch.setattr(
+ chroma_mod,
+ "remove_chroma_background_ycbcr",
+ lambda image, chroma_key, warnings: image.convert("RGBA"),
+ )
+
+ out = tmp_path / "asset.png"
+ report = tmp_path / "report.json"
+ with pytest.raises(SystemExit, match=r"0\.0% transparent pixels"):
+ gen.run(
+ provider="fake",
+ prompt="a mushroom",
+ out=out,
+ ref=[],
+ model=None,
+ aspect_ratio=None,
+ transparent=True,
+ chroma_key="magenta",
+ white_check=None,
+ keep_session=False,
+ report=report,
+ prompt_file=None,
+ workdir=None,
+ )
+
+ assert not out.exists()
+ assert not report.exists()
+
+
def test_generate_image_orchestrates_report_and_raw_keep(tmp_path: Path, monkeypatch) -> None:
fake = _FakeProvider()
monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
@@ -391,6 +489,7 @@ def test_generate_image_orchestrates_report_and_raw_keep(tmp_path: Path, monkeyp
payload = json.loads(report.read_text(encoding="utf-8"))
assert payload["provider"] == "fake"
assert payload["transparent"] is True
+ assert payload["chroma"]["method"] == "ycbcr"
assert payload["chroma"]["stale_transparent_rgb_pixels"] == 0
assert payload["elapsed_seconds"] == 1.23