Skip to content

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.py
index 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_chroma
atomic_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__.py
index 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 = None
if 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.py
index 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.size
total = width * height
@@ -93,6 +98,8 @@ def key_transparent(
}
if warnings:
stats["warnings"] = warnings
+ if decontam != "off":
+ stats["decontam"] = decontam_stats
if 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.py
index 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: a
else 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: a
args.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.py
index 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