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(decontam): the palette can be learned without pixels the caller marks as not the subject's (`not_subject`, `decontam_not_subject`), None keeping every output as it was

Soohong Kim2af587db9a75
diff --git a/sprite_gen/frames/cutout.py b/sprite_gen/frames/cutout.py
index 023029b..bf80c16 100644
--- a/sprite_gen/frames/cutout.py
+++ b/sprite_gen/frames/cutout.py
@@ -39,12 +39,15 @@ from __future__ import annotations
from collections import deque
from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
from PIL import Image
from sprite_gen.frames import extract as extract_mod
+if TYPE_CHECKING:
+ from sprite_gen._deps import np
+
# Matte defaults converged on a 4-icon reference set (tree/bench/flower/lamp, ivory bg).
STRENGTH_DEFAULT = 45 # LO: colour distance at/below which a border pixel is fully background
HI_OFFSET = 60 # HI = STRENGTH + HI_OFFSET: distance at/above which a pixel is fully opaque
@@ -338,6 +341,7 @@ def extract_route(image: Image.Image, kind: str, *, spill_max_fraction: float |
decontam_palette: dict[str, Any] | None = None, decontam_edge_band: int = 0,
background_key: tuple[int, int, int] | None = None,
decontam_history: dict[str, Any] | None = None,
+ decontam_not_subject: np.ndarray | None = None,
measure_unrecognised: bool = True) -> tuple[Image.Image, dict[str, Any]]:
"""Magenta/green key background → reuse the verified `extract` chroma engine (no drift).
@@ -352,7 +356,8 @@ def extract_route(image: Image.Image, kind: str, *, spill_max_fraction: float |
exact matte, so the canvas and `video-frames` agree by construction.
`decontam` is the engine's edge decontamination pass (`extract.remove_chroma_background`);
what it did comes back under `decontam` in the stats. `decontam_history` is a clip's record of
- its last frame for the video fit, handed on to the pass.
+ its last frame for the video fit, handed on to the pass, and `decontam_not_subject` the pixels the
+ pass learns the subject's palette without (`decontaminate`'s `not_subject`).
A background the engine does not recognise as the ``kind`` key (`key_recognised`: a muted or
shifted colour, or a key behind dark edge strips) is keyed by the measured matte instead, its
@@ -381,7 +386,7 @@ def extract_route(image: Image.Image, kind: str, *, spill_max_fraction: float |
if decontam != extract_mod.OFF:
extra.update(decontam=decontam, decontam_fit=decontam_fit, decontam_palette=decontam_palette,
decontam_stats=decontam_stats, decontam_edge_band=decontam_edge_band,
- decontam_history=decontam_history)
+ decontam_history=decontam_history, decontam_not_subject=decontam_not_subject)
# the colour detected above, not a second detection of the same borders
result = remove_chroma_background(
image, target, _EXTRACT_KEY_THRESHOLD, _EXTRACT_FRINGE_THRESHOLD, _EXTRACT_FRINGE_DELTA,
@@ -415,6 +420,7 @@ def cutout(
decontam_palette: dict[str, Any] | None = None,
decontam_edge_band: int = 0,
decontam_history: dict[str, Any] | None = None,
+ decontam_not_subject: np.ndarray | None = None,
measure_unrecognised: bool = True,
refuse_empty: bool = True,
) -> dict[str, Any]:
@@ -432,7 +438,9 @@ def cutout(
it cannot run (the white matte has no key colour to remove). `decontam_edge_band`
keeps what the matte left transparent along the top, left and right edges
transparent (`video-frames` passes its edge band), and `decontam_history` carries a
- clip's last frame to the next (`video-frames` keeps one per clip). `measure_unrecognised`
+ clip's last frame to the next (`video-frames` keeps one per clip). `decontam_not_subject` is the
+ pixels the pass learns the subject's palette without (`video-frames --prop-plate` passes the
+ plate's place on the frame it learns it on). `measure_unrecognised`
is handed to `extract_route`, and `refuse_empty=False` leaves a cut with nothing transparent
to the caller (`video-frames` passes both False: it refuses such frames itself, with its own
report and guidance). Returns a stats dict. Raises SystemExit if the key is unknown, the background cannot be
@@ -457,7 +465,8 @@ def cutout(
spill_min_tint=spill_min_tint, spill_require_hue=spill_require_hue,
decontam=decontam, decontam_fit=decontam_fit,
decontam_palette=decontam_palette, decontam_edge_band=decontam_edge_band,
- decontam_history=decontam_history, measure_unrecognised=measure_unrecognised)
+ decontam_history=decontam_history, decontam_not_subject=decontam_not_subject,
+ measure_unrecognised=measure_unrecognised)
else:
if decontam == extract_mod.PALETTE:
raise SystemExit(f"cutout: --decontam {decontam} needs a chroma key background (magenta/green); "
diff --git a/sprite_gen/frames/decontam.py b/sprite_gen/frames/decontam.py
index c2eb38e..9668254 100644
--- a/sprite_gen/frames/decontam.py
+++ b/sprite_gen/frames/decontam.py
@@ -461,21 +461,30 @@ def _blend_calls(last: dict[str, Any] | None, rows: np.ndarray, cols: np.ndarray
return np.concatenate([rgb, 255.0 * a[:, None]], axis=1), state
-def not_applicable(keyed: np.ndarray, keyed_mask: np.ndarray, chroma_key: tuple[int, int, int]) -> str | None:
+def _interior(keyed_mask: np.ndarray, not_subject: np.ndarray | None) -> np.ndarray:
+ """The subject's interior: deeper than `BAND_PX` inside the keyed silhouette, `not_subject` left out."""
+ interior = ~keyed_mask & (_ring_depth(keyed_mask, BAND_PX) > BAND_PX)
+ return interior if not_subject is None else interior & ~not_subject
+
+
+def not_applicable(keyed: np.ndarray, keyed_mask: np.ndarray, chroma_key: tuple[int, int, int],
+ not_subject: np.ndarray | None = None) -> str | None:
"""Why the pass cannot run on this image, or None when it can."""
keyed_channels, _ = _key_channel_split(chroma_key)
if not keyed_channels:
return (f"key {tuple(chroma_key)} has no key hue (needs saturated and dark channels); "
"edge decontamination only applies to chroma keys such as green or magenta")
- interior = ~keyed_mask & (_ring_depth(keyed_mask, BAND_PX) > BAND_PX)
+ interior = _interior(keyed_mask, not_subject)
if not np.count_nonzero(interior & (keyed[..., 3] == 255)):
return (f"no subject pixel lies deeper than {BAND_PX} px inside the keyed silhouette, "
"so there is no interior to learn the subject's colours from")
return None
-def subject_palette(keyed: np.ndarray, keyed_mask: np.ndarray, chroma_key: tuple[int, int, int]) -> dict[str, Any]:
- """The subject's colours, learned from its confident interior (opaque, deeper than `BAND_PX`).
+def subject_palette(keyed: np.ndarray, keyed_mask: np.ndarray, chroma_key: tuple[int, int, int],
+ not_subject: np.ndarray | None = None) -> dict[str, Any]:
+ """The subject's colours, learned from its confident interior (opaque, deeper than `BAND_PX`), the pixels
+ `not_subject` marks left out (a prop plate standing as opaque as the subject: `video-frames --prop-plate`).
Returns {"palette": (k, 3) float64, "keyfree": bool, "key_material_share": float,
"material_spread": float}, the last being how far the interior itself sits from the
@@ -483,13 +492,11 @@ def subject_palette(keyed: np.ndarray, keyed_mask: np.ndarray, chroma_key: tuple
and hand it to every frame, so the colours an edge may take do not change from frame to
frame. Raises SystemExit when `not_applicable` says why it cannot.
"""
- reason = not_applicable(keyed, keyed_mask, chroma_key)
+ reason = not_applicable(keyed, keyed_mask, chroma_key, not_subject)
if reason is not None:
raise SystemExit(f"decontam: {reason}; run without decontam")
keyed_channels, unkeyed_channels = _key_channel_split(chroma_key)
- subject = ~keyed_mask
- interior = subject & (_ring_depth(keyed_mask, BAND_PX) > BAND_PX)
- confident = interior & (keyed[..., 3] == 255)
+ confident = _interior(keyed_mask, not_subject) & (keyed[..., 3] == 255)
confident_count = int(np.count_nonzero(confident))
excess = _key_excess_field(keyed[..., :3].astype(np.int32), keyed_channels, unkeyed_channels)
key_material = float(np.count_nonzero(confident & (excess > KEY_HUE_TINT))) / confident_count
@@ -516,14 +523,16 @@ def decontaminate(source_rgb: np.ndarray, keyed: np.ndarray, keyed_mask: np.ndar
chroma_key: tuple[int, int, int], *, fit: str = "still", alpha_depth: int = 4,
palette: dict[str, Any] | None = None, mode: str = PALETTE,
source_alpha: np.ndarray | None = None, edge_band: int = 0,
- history: dict[str, Any] | None = None) -> tuple[np.ndarray, dict[str, Any]]:
+ history: dict[str, Any] | None = None,
+ not_subject: np.ndarray | None = None) -> tuple[np.ndarray, dict[str, Any]]:
"""Re-explain the edge of an already keyed image. Returns (RGBA uint8, stats).
`source_rgb` (H, W, 3) is the frame as generated and `source_alpha` (H, W) its own
coverage (None: opaque), `keyed` (H, W, 4) the engine's output for it and `keyed_mask`
the engine's hard-cut background (transparent input included). Interior pixels
(deeper than `BAND_PX`) are returned byte-identical.
- `palette` is a `subject_palette` result to reuse (a clip's); None learns this frame's.
+ `palette` is a `subject_palette` result to reuse (a clip's); None learns this frame's, without the
+ pixels `not_subject` marks (None: every pixel the matte kept is the subject's).
`edge_band` (px) keeps what the matte left transparent along the top, left and right
edges transparent (*Frame edge*); 0 leaves the frame edge to the pass like anywhere else.
`history` (video fit) is a dict a clip hands to every frame in order: the pass reads the
@@ -536,7 +545,7 @@ def decontaminate(source_rgb: np.ndarray, keyed: np.ndarray, keyed_mask: np.ndar
if mode == OFF:
raise SystemExit("decontam: decontaminate() called with mode 'off'")
if palette is None:
- reason = not_applicable(keyed, keyed_mask, chroma_key)
+ reason = not_applicable(keyed, keyed_mask, chroma_key, not_subject)
if reason is not None:
if mode == PALETTE:
raise SystemExit(f"decontam: {reason}; run without decontam")
@@ -550,7 +559,7 @@ def decontaminate(source_rgb: np.ndarray, keyed: np.ndarray, keyed_mask: np.ndar
depth = _ring_depth(keyed_mask, BAND_PX)
band = subject & (depth <= BAND_PX)
flank = keyed_mask & (_ring_depth(subject, FLANK_PX) <= FLANK_PX)
- learned = subject_palette(out, keyed_mask, chroma_key) if palette is None else palette
+ learned = subject_palette(out, keyed_mask, chroma_key, not_subject) if palette is None else palette
palette_rgb = np.asarray(learned["palette"], dtype=np.float64)
keyfree = bool(learned["keyfree"])
key_material = float(learned["key_material_share"])
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.py
index 7ec8c3f..5fea007 100644
--- a/sprite_gen/frames/extract.py
+++ b/sprite_gen/frames/extract.py
@@ -668,6 +668,7 @@ def remove_chroma_background(
decontam_stats: dict[str, Any] | None = None,
decontam_edge_band: int = 0,
decontam_history: dict[str, Any] | None = None,
+ decontam_not_subject: np.ndarray | None = None,
) -> Image.Image:
"""Key `chroma_key` out of `image` (hard cut + soft-alpha fringe unmix + trapped-spill despill).
@@ -682,7 +683,8 @@ def remove_chroma_background(
why not elsewhere); "off" (the default) returns exactly what the passes above produce. `decontam_stats`, when given, receives what
that pass did; `decontam_palette` reuses a palette learned elsewhere,
`decontam_edge_band` keeps the frame edge as the matte left it (`decontaminate`'s `edge_band`),
- and `decontam_history` is a clip's record of its last frame for the video fit (`decontaminate`'s `history`).
+ `decontam_history` is a clip's record of its last frame for the video fit (`decontaminate`'s `history`),
+ and `decontam_not_subject` the pixels a palette is learned without (`decontaminate`'s `not_subject`).
"""
if decontam != OFF:
from sprite_gen.frames import decontam as decontam_module
@@ -850,7 +852,7 @@ def remove_chroma_background(
data, stats = decontam_module.decontaminate(source_rgb, data, keyed_mask, chroma_key, fit=decontam_fit,
alpha_depth=unmix_reach, palette=decontam_palette, mode=decontam,
source_alpha=source_alpha, edge_band=decontam_edge_band,
- history=decontam_history)
+ history=decontam_history, not_subject=decontam_not_subject)
if decontam_stats is not None:
decontam_stats.update(stats)
# Back into the converted copy rather than a fresh Image.fromarray, so the