Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(gen): --decontam for chroma-keyed stills
Soohong Kimf5ac828fbcaf
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.pyindex 3797901..4191e75 100644--- a/sprite_gen/frames/extract.py+++ b/sprite_gen/frames/extract.py@@ -2971,6 +2971,7 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):# Recorded once it is in play, so a run keyed before decontam existed keeps its request bytes.if decontam_mode != "off" or "decontam" in chroma_config:effective_chroma["decontam"] = decontam_mode+ decontam_kwargs = {} if decontam_mode == "off" else {"decontam": decontam_mode}if effective_chroma != chroma_config:request["chroma"] = effective_chromaatomic_write_text(@@ -3136,7 +3137,7 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):with Image.open(raw_path) as opened:if chroma_mode == "ycbcr":ycc_notes: list[str] = []- strip = remove_chroma_background_ycbcr(opened, chroma_key, ycc_notes, decontam=decontam_mode)+ strip = remove_chroma_background_ycbcr(opened, chroma_key, ycc_notes, **decontam_kwargs)all_warnings.extend(f"{tag}: {note}" for note in ycc_notes)else:strip = remove_chroma_background(@@ -3147,7 +3148,7 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):args.fringe_delta,unmix_reach=unmix_reach,spill_max_fraction=spill_max_fraction,- decontam=decontam_mode,+ **decontam_kwargs,)return separate_fused_poses(strip, frame_count, fit_config, args.segmentation, state)diff --git a/sprite_gen/gen/__init__.py b/sprite_gen/gen/__init__.pyindex 7780b1a..a3787b6 100644--- a/sprite_gen/gen/__init__.py+++ b/sprite_gen/gen/__init__.py@@ -257,8 +257,13 @@ def generate_image(trim_alpha: bool = False,keep_session: bool = False,workdir: Path | None = None,+ decontam: str = "off",) -> GenResult:"""Generate one image and return a GenResult. Raises SystemExit on any failure."""+ if decontam not in ("off", "palette"):+ raise SystemExit(f"gen: unknown --decontam {decontam!r}; expected off|palette")+ if decontam != "off" and not transparent:+ raise SystemExit("gen: --decontam applies to the chroma key of a --transparent image; add --transparent")prompt = (prompt or "").strip()if not prompt:raise SystemExit("gen: empty prompt; pass --prompt or --prompt-file")@@ -279,6 +284,10 @@ def generate_image(strategy_source: str | None = Noneif transparent:strategy, strategy_source = resolve_transparency_strategy(backend, alpha_mode, refs=refs)+ if decontam != "off" and strategy != TRANSPARENCY_CHROMA:+ # before the provider is called: a paid generation must not end in this refusal+ raise SystemExit(f"gen: --decontam removes a chroma key; this image would use {strategy} alpha "+ "(pass --alpha-mode chroma to key it instead)")if strategy_source == STRATEGY_SOURCE_REFS:print(f"[gen] {len(refs)} reference image(s) attached — using chroma keying instead of "@@ -327,7 +336,8 @@ def generate_image(**chroma_mod.verify_native_alpha(raw, out, white_check=white_check),}elif strategy == TRANSPARENCY_CHROMA:- chroma_stats = chroma_mod.key_transparent(raw, out, key=chroma_key, white_check=white_check)+ chroma_stats = chroma_mod.key_transparent(raw, out, key=chroma_key, white_check=white_check,+ decontam=decontam)alpha_stats = {"strategy": TRANSPARENCY_CHROMA, "strategy_source": strategy_source, **chroma_stats}else:shutil.copyfile(raw, out)@@ -409,6 +419,7 @@ def _run(args: argparse.Namespace) -> int:trim_alpha=bool(getattr(args, "trim_alpha", False)),keep_session=args.keep_session,workdir=args.workdir,+ decontam=str(getattr(args, "decontam", None) or "off"),)payload = result.to_dict()# `provider` in the payload is always the backend that actually generated the@@ -511,6 +522,13 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:"native forces native alpha and is refused on a provider that cannot return alpha"),)+ parser.add_argument(+ "--decontam",+ choices=("off", "palette"),+ default="off",+ help="chroma keying only: re-explain key-tinted edges (hair strands, outlines) with the subject's "+ "own colours after the matte (palette); off keeps the matte as is (default off)",+ )parser.add_argument("--chroma-key", choices=sorted(chroma_mod.KEYS), default="magenta")parser.add_argument("--facing", choices=(*facing_mod.FACINGS, "preserve"), default="preserve", help="with --ref: required direction; preserve (default) leaves prompt and pixels unchanged")parser.add_argument("--facing-fix", choices=facing_mod.FIXES, default="none", help="with --ref and --facing: record only (none, default), or opt into mirror / one regen")diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.pyindex a6c7ffa..7c6a08a 100644--- a/sprite_gen/gen/chroma.py+++ b/sprite_gen/gen/chroma.py@@ -42,19 +42,24 @@ def key_transparent(*,key: str = "magenta",white_check: Path | None = None,+ decontam: str = "off",) -> dict[str, Any]:"""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 before publishing if no measurable transparent area was- made, or if a transparent pixel keeps non-zero RGB.+ `decontam="palette"` adds the edge decontamination pass after the matte and+ reports it under `decontam`. 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)}")source = Image.open(input_path).convert("RGBA")source_pixels = source.load()warnings: list[str] = []- image = remove_chroma_background_ycbcr(source, KEYS[key]["target"], warnings)+ decontam_stats: dict[str, Any] = {}+ # the default call keeps its pre-decontam signature, so a caller's matte stand-in still fits+ extra = {} if decontam == "off" else {"decontam": decontam, "decontam_stats": decontam_stats}+ image = remove_chroma_background_ycbcr(source, KEYS[key]["target"], warnings, **extra)pixels = image.load()width, height = image.sizetotal = width * height@@ -93,6 +98,8 @@ def key_transparent(}if warnings:stats["warnings"] = warnings+ if decontam != "off":+ stats["decontam"] = decontam_statsif white_check is not None:stats["white_check"] = str(white_check)if alpha_zero_pct == 0.0:diff --git a/sprite_gen/qa/inspect.py b/sprite_gen/qa/inspect.pyindex 7a6efcb..bc1359b 100644--- a/sprite_gen/qa/inspect.py+++ b/sprite_gen/qa/inspect.py@@ -119,10 +119,11 @@ def _strip_for_state(run_dir: Path, request: dict[str, Any], state: str, args: aelse float(chroma_config.get("spill_max_fraction", 0.005)))decontam = args.decontam if args.decontam is not None else str(chroma_config.get("decontam", "off"))+ decontam_kwargs = {} if decontam == "off" else {"decontam": decontam}with Image.open(raw_path) as opened:if chroma_mode == "ycbcr":notes: list[str] = []- return extract.remove_chroma_background_ycbcr(opened, chroma_key, notes, decontam=decontam)+ return extract.remove_chroma_background_ycbcr(opened, chroma_key, notes, **decontam_kwargs)return extract.remove_chroma_background(opened,chroma_key,@@ -131,7 +132,7 @@ def _strip_for_state(run_dir: Path, request: dict[str, Any], state: str, args: aargs.fringe_delta,unmix_reach=unmix_reach,spill_max_fraction=spill_max_fraction,- decontam=decontam,+ **decontam_kwargs,)diff --git a/tests/frames/test_chroma_decontam.py b/tests/frames/test_chroma_decontam.pyindex 72ecef1..1f0f1e0 100644--- a/tests/frames/test_chroma_decontam.py+++ b/tests/frames/test_chroma_decontam.py@@ -368,7 +368,76 @@ def test_cli_exposes_the_flag_on_every_entry_point():parser = cli._build_parser()for argv in (["cutout", "x.png", "--decontam", "palette"],+ ["gen", "--out", "x.png", "--transparent", "--decontam", "palette"],["video-frames", "--clip", "c.mp4", "--out-dir", "o", "--decontam", "palette"],["extract", "--run-dir", "r", "--decontam", "palette"],["inspect", "--run-dir", "r", "--decontam", "palette"]):assert parser.parse_args(argv).decontam == "palette"+++# --------------------------------------------------------------------------- gen (YCbCr matte)++class _FakeKeyProvider:+ """Paints the hair scene on a green key, the way a chroma-strategy provider returns it."""++ name = "fake"++ def __init__(self, transparency: str) -> None:+ self.transparency = transparency+ self.calls = 0++ def generate(self, request, workdir):+ from sprite_gen.gen import base as gen_base++ self.calls += 1+ F, A = _render()+ Image.fromarray(_composite_on(F, A, GREEN_PAINTED)).save(request.raw)+ return gen_base.ProviderRun(provider=self.name, elapsed_seconds=0.1, model=request.model)+++def _gen(tmp_path: Path, monkeypatch, provider, **overrides) -> int:+ from sprite_gen import gen++ monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: provider)+ kwargs = dict(provider="fake", prompt="a red-haired girl", out=tmp_path / "girl.png", ref=[], model=None,+ aspect_ratio=None, transparent=True, alpha_mode="auto", chroma_key="green", white_check=None,+ keep_session=False, report=tmp_path / "girl.json", prompt_file=None, workdir=None)+ kwargs.update(overrides)+ return gen.run(**kwargs)+++def test_gen_decontam_runs_after_the_ycbcr_matte_and_reports(tmp_path: Path, monkeypatch):+ from sprite_gen.gen import base as gen_base++ provider = _FakeKeyProvider(gen_base.TRANSPARENCY_CHROMA)+ assert _gen(tmp_path, monkeypatch, provider, out=tmp_path / "off.png", report=tmp_path / "off.json") == 0+ assert _gen(tmp_path, monkeypatch, provider, decontam="palette") == 0+ off = json.loads((tmp_path / "off.json").read_text())+ on = json.loads((tmp_path / "girl.json").read_text())+ assert "decontam" not in off["chroma"]+ assert on["chroma"]["decontam"]["mode"] == "palette" and on["chroma"]["decontam"]["changed_px"] > 0+ raw = np.array(Image.open(tmp_path / "girl.png.raw.png").convert("RGB"))+ _, interior = _edge(raw)+ before, after = np.array(Image.open(tmp_path / "off.png")), np.array(Image.open(tmp_path / "girl.png"))+ assert np.array_equal(before[interior], after[interior])+ F, A = _render()+ edge, _ = _edge(raw)+ assert _toward_key(after, F, A, edge) <= 0.5 * _toward_key(before, F, A, edge)+++def test_gen_decontam_refuses_native_alpha_before_generating(tmp_path: Path, monkeypatch):+ from sprite_gen.gen import base as gen_base++ provider = _FakeKeyProvider(gen_base.TRANSPARENCY_NATIVE)+ with pytest.raises(SystemExit, match="removes a chroma key"):+ _gen(tmp_path, monkeypatch, provider, decontam="palette")+ assert provider.calls == 0 # refused before a paid generation+++def test_gen_decontam_needs_a_transparent_image(tmp_path: Path, monkeypatch):+ from sprite_gen.gen import base as gen_base++ provider = _FakeKeyProvider(gen_base.TRANSPARENCY_CHROMA)+ with pytest.raises(SystemExit, match="add --transparent"):+ _gen(tmp_path, monkeypatch, provider, transparent=False, decontam="palette")+ assert provider.calls == 0