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): keep decontam opt-in on stills

Soohong Kimbb01a6390472
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7f5b41e..c8206b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased (v2.7.0)
-- Add opt-in edge decontamination, `decontam: "palette"`. After the matte, each edge pixel is explained as a blend of the locally measured key background with one colour from a palette learned on the subject's own interior. The colour written is that palette colour at the pixel's observed luma, so thin hair strands and outlines come back in the subject's hue: not green, and not the orange that despill's channel gain produces. `cutout` and `gen --transparent` (chroma keying) now run it by default (`--decontam auto`: wherever it applies, with the reason recorded where it does not); `--decontam off` returns their previous output byte for byte, and `--decontam palette` demands the pass and fails where it cannot run. `video-frames` / `video-set` (video fit, one palette per clip) and the row extractor (request `chroma.decontam`, also read by `inspect`) keep `off` as their default. On a procedural ground-truth set, key contamination at the edge falls from 22.5 % to 0.07 % on stills and from 33 % to 11 % on H.264 frames; halo against the true composite shrinks on dark and white backgrounds, and strand recall rises from 84 % to 99 % (stills) and from 82 % to 91 % (frames). Method, guards and limits: [docs/chroma-alpha.md](docs/chroma-alpha.md).
+- Add opt-in edge decontamination, `--decontam auto|palette` (request `chroma.decontam` for the row extractor and `inspect`). After the matte, each edge pixel is explained as a blend of the locally measured key background with one colour from a palette learned on the subject's own interior. The colour written is that palette colour at the pixel's observed luma, so thin hair strands and outlines come back in the subject's hue: not green, and not the orange that despill's channel gain produces. `palette` demands the pass and fails where it cannot run; `auto` runs it wherever it applies and records why it did not elsewhere. Available on `cutout`, `gen --transparent` (chroma keying), `video-frames` / `video-set` (video fit, one palette per clip) and the row extractor. Every default stays `off`, which returns existing output byte for byte. On a procedural ground-truth set, key contamination at the edge falls from 22.5 % to 0.07 % on stills and from 33 % to 11 % on H.264 frames; halo against the true composite shrinks on dark and white backgrounds, and strand recall rises from 84 % to 99 % (stills) and from 82 % to 91 % (frames). Method, guards and limits: [docs/chroma-alpha.md](docs/chroma-alpha.md).
## v2.6.0 - Automatic local gait selection and XY motion correction
diff --git a/docs/chroma-alpha.md b/docs/chroma-alpha.md
index cb64bc9..19c2988 100644
--- a/docs/chroma-alpha.md
+++ b/docs/chroma-alpha.md
@@ -60,7 +60,7 @@ When unsure, let `--chroma-key auto` sample the base. It excludes the detected f
2. **Soft-alpha unmix** — key-tinted blends near the keyed region are separated into despilled RGB + **partial alpha**: the blend model `observed = (1-k)·subject + k·key` is solved from the key-tint score, so antialiased silhouettes keep their coverage ramp instead of collapsing into a binary staircase. In-band blends (inside `--fringe-key-threshold`) are eligible only at key-distance `<= 2`; out-of-band blends use `--fringe-unmix-reach` (default 4). This preserves deeper key-tinted material while fixing trapped blend pockets between hair strands.
3. **Trapped-spill despill** — a small connected cluster of key-tinted pixels (≤ `--spill-max-fraction` of the subject, default 0.005) containing at least one strongly tinted pixel is generator spill, wherever it sits: its color is corrected in place with alpha kept (no pinholes). Large key-tinted regions are intentional material and are never touched; marginally warm subject colors (skin) never qualify.
-A fourth pass, edge decontamination (`decontam`, below; opt-in for sprite rows through `chroma.decontam`), then re-explains the edge with the subject's own colours.
+An opt-in fourth pass, edge decontamination (`decontam`, below), then re-explains the edge with the subject's own colours.
The unmix/spill tunables live in the run's `sprite-request.json` under `chroma` (`unmix_reach`, `spill_max_fraction`) — the extractor reads them from there, CLI flags override, and the effective values are written back to the request so every run records what produced it. Then it extracts connected components and writes fresh transparent cells. The pixel-unfake path is unaffected: it binarizes alpha downstream (α ≥ 128 → opaque), so soft-alpha input degrades gracefully. This is intentionally closer to hatch-pet than to simple `magick -transparent`.
@@ -91,7 +91,7 @@ B is the key background measured locally (mean of keyed pixels within 12 px). P
| The pixel | Outcome |
|---|---|
| no palette colour explains it (a colour the interior never shows), or, in the still fit, the explanation misses its luma (outline ink darker than any blend) | engine bytes |
-| closer to a palette colour as observed than the blend explains it (margin 10, or 3 noise sigmas of the background) | engine bytes; with a key-free palette, a leftover key hue is capped (keyed channel ≤ largest other channel + 8), which never raises a channel |
+| closer to a palette colour as observed than the blend explains it (margin 10, or 3 noise sigmas of the background) | engine bytes; with a key-free palette, a leftover key hue (every keyed channel above every other by more than 8) loses the excess beyond 8 on its keyed channels, which never raises a channel and leaves colours without the key hue alone (a red or a skin tone under magenta is not magenta) |
| pushed toward the key clearly more than the fit misses by, but not proven partial coverage | colour only |
| a blend within the unmix reach (`chroma.unmix_reach`, default 4) | alpha and colour |
| a blend deeper in the 6 px band | colour only, so a key reflection on a solid surface is recoloured rather than made see-through |
@@ -105,8 +105,8 @@ Three modes: `palette` runs the pass and fails loud where it cannot (no key hue,
| Entry point | Default | Flag |
|---|---|---|
-| `sprite-gen cutout IMAGE` | `auto` (chroma routes; the white matte records that it has no key colour) | `--decontam off\|auto\|palette` |
-| `sprite-gen gen … --transparent` | `auto` (chroma strategy; native alpha is left alone) | `--decontam off\|auto\|palette`; `palette` is refused before the provider is called when it cannot apply |
+| `sprite-gen cutout IMAGE` | `off` | `--decontam off\|auto\|palette` (chroma routes; on the white matte `auto` records that it has no key colour and `palette` is refused) |
+| `sprite-gen gen … --transparent` | `off` | `--decontam off\|auto\|palette` (chroma strategy; `auto` leaves native alpha alone, `palette` is refused before the provider is called when it cannot apply) |
| `sprite-gen video-frames`, `video-set` | `off` | `--decontam off\|auto\|palette` |
| row extractor (`extract`, `inspect`) | `off` | request `chroma.decontam`, or `--decontam` to override; written back to the request once in play |
@@ -123,7 +123,7 @@ Measured on a procedural ground-truth set (red strands 0.5–3 px wide, outline
| H.264 frames | RGB engine + `--spill full` | 33.2 % | 12.79 / 12.43 | 82.1 % |
| H.264 frames | + `decontam` (video fit) | 10.8 % | 9.38 / 8.73 | 91.4 % |
-**Defaults.** Stills cut by `cutout` and `gen --transparent` default to `auto`: on stills the pass removes nearly all key contamination with a smaller halo and more strand coverage, and `off` gives the previous output back byte for byte. The row extractor stays `off`: its frames are a derived cache that `heal` re-derives from raw, so a changed default would silently rewrite every existing run, and pixel-art rows binarize alpha downstream anyway. `video-frames` / `video-set` stay `off` (see the video numbers above).
+**Defaults.** Every entry point defaults to `off`, which returns the engine's output byte for byte; pass `--decontam auto` (or `palette`) to use the pass. Stills defaulted to `auto` for a while during development. The full test suite then caught a regression on Grok's darker magenta: the key-hue cap greyed the warm colours of the palette, so a hard-edged brown square lost its opaque edge. The cap is fixed and tested, but the measurements above use a green key, so the default stays `off`. The row extractor stays `off` in any case: its frames are a derived cache that `heal` re-derives from raw, so a changed default would silently rewrite every existing run, and pixel-art rows binarize alpha downstream anyway. `video-frames` / `video-set` stay `off` (see the video numbers above).
Limitations:
@@ -131,6 +131,7 @@ Limitations:
- In video a thin strand's chroma is gone before keying, so its colour is chosen from blurred chroma; strands come back in the hair's hue, sometimes a shade darker or paler than drawn.
- A subject that owns key-coloured material keeps it in its palette, and its edges are repainted with whatever explains them best, key colour included. Keep the default when that material matters.
- The pixel-unfake path binarizes alpha downstream, so on pixel-art rows only edge colours change.
+- The measurements are on a green key. On magenta the pass is covered by synthetic tests (teal, skin-toned and hard-edged warm subjects, the painted key and Grok's darker one), not by a benchmark.
## Related
diff --git a/sprite_gen/frames/cutout.py b/sprite_gen/frames/cutout.py
index b9c9348..c07da05 100644
--- a/sprite_gen/frames/cutout.py
+++ b/sprite_gen/frames/cutout.py
@@ -327,7 +327,7 @@ def cutout(
spill_max_fraction: float | None = None,
spill_min_tint: float | None = None,
spill_require_hue: bool = False,
- decontam: str = "auto",
+ decontam: str = "off",
decontam_fit: str = "still",
decontam_palette: dict[str, Any] | None = None,
) -> dict[str, Any]:
@@ -337,9 +337,9 @@ def cutout(
(reuse the extract chroma engine). `spill_max_fraction` overrides the chroma
engine's trapped-spill cluster cap and `spill_min_tint` its tint bar (None = the
engine default for either). `decontam` is the engine's edge decontamination
- pass: "auto" (the default) runs it on chroma routes where it applies and records
- why not elsewhere; "palette" demands it and fails where it cannot run (the white
- matte has no key colour to remove); "off" keeps the matte as it is. Returns a
+ pass: "off" (the default) keeps the matte as it is; "auto" runs it on chroma routes
+ where it applies and records why not elsewhere; "palette" demands it and fails where
+ it cannot run (the white matte has no key colour to remove). Returns a
stats dict. Raises SystemExit if the key is unknown, the background cannot be
located, or any transparent pixel keeps non-zero RGB (No Silent Fallback).
"""
@@ -441,10 +441,10 @@ def add_arguments(p: Any) -> None:
p.add_argument(
"--decontam",
choices=["off", "auto", "palette"],
- default="auto",
+ default="off",
help="edge decontamination on chroma routes: re-explain key-tinted edges (hair strands, outlines) "
- "with the subject's own colours. auto (default) runs it where it applies and records why not "
- "elsewhere; palette demands it; off keeps the chroma engine's output as it was before",
+ "with the subject's own colours. off (default) keeps the chroma engine's output; auto runs it "
+ "where it applies and records why not elsewhere; palette demands it",
)
@@ -462,7 +462,7 @@ def run(**kwargs: object) -> int:
erode=float(kwargs.get("erode", ERODE_DEFAULT)), # type: ignore[arg-type]
tolerance=int(kwargs.get("tolerance", CHROMA_TOLERANCE)), # type: ignore[arg-type]
white_check_dir=out_path.parent if white_check else None,
- decontam=str(kwargs.get("decontam") or "auto"),
+ decontam=str(kwargs.get("decontam") or "off"),
)
import json
diff --git a/sprite_gen/gen/__init__.py b/sprite_gen/gen/__init__.py
index 01aceab..743b126 100644
--- a/sprite_gen/gen/__init__.py
+++ b/sprite_gen/gen/__init__.py
@@ -257,7 +257,7 @@ def generate_image(
trim_alpha: bool = False,
keep_session: bool = False,
workdir: Path | None = None,
- decontam: str = "auto",
+ decontam: str = "off",
) -> GenResult:
"""Generate one image and return a GenResult. Raises SystemExit on any failure."""
if decontam not in ("off", "auto", "palette"):
@@ -419,7 +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 "auto"),
+ decontam=str(getattr(args, "decontam", None) or "off"),
)
payload = result.to_dict()
# `provider` in the payload is always the backend that actually generated the
@@ -525,10 +525,10 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument(
"--decontam",
choices=("off", "auto", "palette"),
- default="auto",
+ default="off",
help="chroma keying: re-explain key-tinted edges (hair strands, outlines) with the subject's own "
- "colours after the matte. auto (default) runs it where it applies (chroma strategy, a subject "
- "interior); palette demands it; off publishes the matte as it is",
+ "colours after the matte. off (default) publishes the matte as it is; auto runs it where it "
+ "applies (chroma strategy, a subject interior); palette demands it",
)
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")
diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.py
index 5dd503f..4aa10d9 100644
--- a/sprite_gen/gen/chroma.py
+++ b/sprite_gen/gen/chroma.py
@@ -42,14 +42,14 @@ def key_transparent(
*,
key: str = "magenta",
white_check: Path | None = None,
- decontam: str = "auto",
+ 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).
`decontam` is the edge decontamination pass after the matte, reported under
- `decontam`: "auto" (the default) runs it where it applies, "palette" demands it,
- "off" publishes the matte as it is. Raises SystemExit before publishing if no
+ `decontam`: "off" (the default) publishes the matte as it is, "auto" runs it where
+ it applies, "palette" demands it. 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:
diff --git a/tests/frames/test_chroma_decontam.py b/tests/frames/test_chroma_decontam.py
index 5b6897f..f9fd6ff 100644
--- a/tests/frames/test_chroma_decontam.py
+++ b/tests/frames/test_chroma_decontam.py
@@ -170,19 +170,19 @@ def test_off_is_the_engine_byte_for_byte():
assert stats == {}
-def test_cutout_defaults_to_auto_and_off_is_the_engine(tmp_path: Path):
+def test_cutout_default_is_off_and_auto_runs_where_it_applies(tmp_path: Path):
F, A = _render()
src = tmp_path / "raw.png"
raw = _composite_on(F, A, GREEN_PAINTED)
Image.fromarray(raw).save(src)
default = cutout(src, tmp_path / "default.png", key="green")
- off = cutout(src, tmp_path / "off.png", key="green", decontam="off")
+ auto = cutout(src, tmp_path / "auto.png", key="green", decontam="auto")
palette = cutout(src, tmp_path / "palette.png", key="green", decontam="palette")
- assert default["decontam"]["mode"] == "auto" and default["decontam"]["applied"] is True
- assert "decontam" not in off
+ assert "decontam" not in default
engine = np.array(remove_chroma_background(Image.fromarray(raw), (0, 255, 0), *KEY_ARGS))
- assert np.array_equal(np.array(Image.open(tmp_path / "off.png")), engine)
- assert np.array_equal(np.array(Image.open(tmp_path / "default.png")), np.array(Image.open(tmp_path / "palette.png")))
+ assert np.array_equal(np.array(Image.open(tmp_path / "default.png")), engine)
+ assert auto["decontam"]["mode"] == "auto" and auto["decontam"]["applied"] is True
+ assert np.array_equal(np.array(Image.open(tmp_path / "auto.png")), np.array(Image.open(tmp_path / "palette.png")))
assert palette["decontam"]["mode"] == "palette"
@@ -191,15 +191,15 @@ def test_auto_reports_why_it_did_not_run(tmp_path: Path):
img = Image.new("RGB", (64, 64), (250, 250, 248))
ImageDraw.Draw(img).ellipse([16, 16, 48, 48], fill=(200, 40, 40))
img.save(tmp_path / "white.png")
- stats = cutout(tmp_path / "white.png", tmp_path / "white-out.png", key="auto")
+ stats = cutout(tmp_path / "white.png", tmp_path / "white-out.png", key="auto", decontam="auto")
assert stats["route"] == "matte" and stats["decontam"] == {
"mode": "auto", "applied": False, "reason": "the white matte has no key colour to remove"}
# a subject with no interior to learn from: auto keys it as before and says why
bar = np.full((80, 160, 3), GREEN_PAINTED, np.uint8)
bar[38:41, 20:140] = HAIR
Image.fromarray(bar).save(tmp_path / "bar.png")
- auto = cutout(tmp_path / "bar.png", tmp_path / "bar-auto.png", key="green")
- cutout(tmp_path / "bar.png", tmp_path / "bar-off.png", key="green", decontam="off")
+ auto = cutout(tmp_path / "bar.png", tmp_path / "bar-auto.png", key="green", decontam="auto")
+ cutout(tmp_path / "bar.png", tmp_path / "bar-off.png", key="green")
assert auto["decontam"]["applied"] is False and "deeper than" in auto["decontam"]["reason"]
assert np.array_equal(np.array(Image.open(tmp_path / "bar-auto.png")), np.array(Image.open(tmp_path / "bar-off.png")))
with pytest.raises(SystemExit, match="no subject pixel lies deeper"):
@@ -485,9 +485,9 @@ def test_gen_decontam_runs_after_the_ycbcr_matte_and_reports(tmp_path: Path, mon
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",
- decontam="off") == 0
- assert _gen(tmp_path, monkeypatch, provider) == 0 # the default: auto
+ # the default publishes the matte as it is; auto adds the pass
+ assert _gen(tmp_path, monkeypatch, provider, out=tmp_path / "off.png", report=tmp_path / "off.json") == 0
+ assert _gen(tmp_path, monkeypatch, provider, decontam="auto") == 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"]
@@ -519,7 +519,7 @@ def test_gen_decontam_needs_a_transparent_image(tmp_path: Path, monkeypatch):
assert provider.calls == 0
-def test_gen_default_auto_leaves_native_alpha_and_opaque_images_alone(tmp_path: Path, monkeypatch):
+def test_gen_auto_leaves_native_alpha_and_opaque_images_alone(tmp_path: Path, monkeypatch):
from sprite_gen.gen import base as gen_base
class _Native(_FakeKeyProvider):
@@ -533,10 +533,11 @@ def test_gen_default_auto_leaves_native_alpha_and_opaque_images_alone(tmp_path:
return gen_base.ProviderRun(provider=self.name, elapsed_seconds=0.1, model=request.model)
native = _Native(gen_base.TRANSPARENCY_NATIVE)
- assert _gen(tmp_path, monkeypatch, native, out=tmp_path / "native.png", report=tmp_path / "native.json") == 0
+ assert _gen(tmp_path, monkeypatch, native, out=tmp_path / "native.png", report=tmp_path / "native.json",
+ decontam="auto") == 0
payload = json.loads((tmp_path / "native.json").read_text())
assert payload["alpha"]["strategy"] == "native" and payload["chroma"] is None
opaque = _FakeKeyProvider(gen_base.TRANSPARENCY_CHROMA)
assert _gen(tmp_path, monkeypatch, opaque, transparent=False, out=tmp_path / "opaque.png",
- report=tmp_path / "opaque.json") == 0
+ report=tmp_path / "opaque.json", decontam="auto") == 0
assert opaque.calls == 1 and json.loads((tmp_path / "opaque.json").read_text())["chroma"] is None
diff --git a/tests/gen/test_gen.py b/tests/gen/test_gen.py
index 9785fc2..666435d 100644
--- a/tests/gen/test_gen.py
+++ b/tests/gen/test_gen.py
@@ -430,7 +430,7 @@ def test_chroma_key_transparent_rejects_zero_percent_alpha(
src = tmp_path / "src.png"
Image.new("RGBA", (512, 512), (20, 30, 40, 255)).save(src)
- def ineffective_matte(image, chroma_key, warnings, **_decontam):
+ def ineffective_matte(image, chroma_key, warnings):
result = image.convert("RGBA")
result.putpixel((0, 0), (0, 0, 0, 0))
return result
@@ -769,7 +769,7 @@ def test_generate_image_zero_percent_alpha_fails_without_success_report(
monkeypatch.setattr(
chroma_mod,
"remove_chroma_background_ycbcr",
- lambda image, chroma_key, warnings, **_decontam: image.convert("RGBA"),
+ lambda image, chroma_key, warnings: image.convert("RGBA"),
)
out = tmp_path / "asset.png"