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.pyindex 023029b..bf80c16 100644--- a/sprite_gen/frames/cutout.py+++ b/sprite_gen/frames/cutout.py@@ -39,12 +39,15 @@ from __future__ import annotationsfrom collections import dequefrom pathlib import Path-from typing import Any+from typing import TYPE_CHECKING, Anyfrom PIL import Imagefrom 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 backgroundHI_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 orshifted 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 bordersresult = 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 edgestransparent (`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 transparentto the caller (`video-frames` passes both False: it refuses such frames itself, with its ownreport 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.pyindex 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.ndarrayreturn 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: tupleand hand it to every frame, so the colours an edge may take do not change from frame toframe. 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.ndarchroma_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 owncoverage (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 rightedges 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.ndarif 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.ndardepth = _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 palettepalette_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.pyindex 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 whatthat 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