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.mdindex 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 thediff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.pyindex 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 Anyfrom 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 = 0for 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 += 1if 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.0stats: 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"] = warningsif 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 statsdiff --git a/tests/gen/test_gen.py b/tests/gen/test_gen.pyindex 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"] == 32keyed = Image.open(out).convert("RGBA")assert keyed.getpixel((0, 0))[3] == 0assert 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, monkeyppayload = 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"] == 0assert payload["elapsed_seconds"] == 1.23