Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(chroma): opt-in palette edge decontamination
Soohong Kim54e443473bd4
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.pyindex 08a6ea3..0dbe65f 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -91,6 +91,7 @@ def _add_extract(p: argparse.ArgumentParser) -> None:p.add_argument("--fringe-delta", type=float, default=18.0)p.add_argument("--fringe-unmix-reach", type=int, default=None)p.add_argument("--spill-max-fraction", type=float, default=None)+ p.add_argument("--decontam", choices=("off", "palette"), default=None)p.add_argument("--segmentation", choices=("components", "projection"), default=None)p.add_argument("--allow-slot-fallback", action="store_true")p.add_argument("--min-used-pixels", type=int, default=None)@@ -193,6 +194,7 @@ def _add_inspect(p: argparse.ArgumentParser) -> None:p.add_argument("--fringe-unmix-reach", type=int, default=None)p.add_argument("--spill-max-fraction", type=float, default=None)p.add_argument("--chroma-mode", choices=("rgb", "ycbcr"), default=None)+ p.add_argument("--decontam", choices=("off", "palette"), default=None)p.add_argument("--no-write", action="store_true")diff --git a/sprite_gen/frames/cutout.py b/sprite_gen/frames/cutout.pyindex 52e3cb1..384e334 100644--- a/sprite_gen/frames/cutout.py+++ b/sprite_gen/frames/cutout.py@@ -273,7 +273,8 @@ def _matte_route(def extract_route(image: Image.Image, kind: str, *, spill_max_fraction: float | None = None,spill_min_tint: float | None = None,- spill_require_hue: bool = False) -> tuple[Image.Image, dict[str, Any]]:+ spill_require_hue: bool = False, decontam: str = "off", decontam_fit: str = "still",+ decontam_palette: dict[str, Any] | None = None) -> tuple[Image.Image, dict[str, Any]]:"""Magenta/green key background → reuse the verified `extract` chroma engine (no drift).The engine keys from the background colour it detects on the borders@@ -282,26 +283,35 @@ def extract_route(image: Image.Image, kind: str, *, spill_max_fraction: float |detected colour is reported as `chroma_key_painted` for the audit trail.Public because `video-canvas` normalizes a still's background through thisexact 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."""from sprite_gen.frames.extract import detect_background_key_rgb, remove_chroma_backgroundtarget = KEY_TARGETS[kind]painted = detect_background_key_rgb(image, target)- extra: dict[str, float | bool] = {}+ extra: dict[str, Any] = {}if spill_max_fraction is not None:extra["spill_max_fraction"] = spill_max_fractionif spill_min_tint is not None:extra["spill_min_tint"] = spill_min_tintif spill_require_hue:extra["spill_require_hue"] = True+ decontam_stats: dict[str, Any] = {}+ if decontam != "off":+ extra.update(decontam=decontam, decontam_fit=decontam_fit, decontam_palette=decontam_palette,+ decontam_stats=decontam_stats)result = remove_chroma_background(image, target, _EXTRACT_KEY_THRESHOLD, _EXTRACT_FRINGE_THRESHOLD, _EXTRACT_FRINGE_DELTA, **extra)- return result.convert("RGBA"), {+ stats: dict[str, Any] = {"route": f"extract:{kind}","chroma_key": list(target),"chroma_key_painted": list(painted),}+ if decontam != "off":+ stats["decontam"] = decontam_stats+ return result.convert("RGBA"), statsdef cutout(@@ -317,18 +327,25 @@ def cutout(spill_max_fraction: float | None = None,spill_min_tint: float | None = None,spill_require_hue: bool = False,+ decontam: str = "off",+ decontam_fit: str = "still",+ decontam_palette: dict[str, Any] | None = None,) -> dict[str, Any]:"""Cut a uniform-background imported image to a clean transparent RGBA PNG.`key`: "auto" (detect from corners) | "white" (matte) | "magenta" | "green"(reuse the extract chroma engine). `spill_max_fraction` overrides the chromaengine's trapped-spill cluster cap and `spill_min_tint` its tint bar (None = the- engine default for either). Returns a stats dict. Raises SystemExit if+ engine default for either). `decontam="palette"` adds the engine's edge+ decontamination pass; it needs a chroma key, so on the white matte it fails+ rather than doing nothing. Returns a stats dict. Raises SystemExit ifthe key is unknown, the background cannot be located, or any transparent pixelkeeps non-zero RGB (No Silent Fallback)."""if key not in ("auto", "white", "magenta", "green"):raise SystemExit(f"cutout: unknown key {key!r}; expected one of auto|white|magenta|green")+ if decontam not in ("off", "palette"):+ raise SystemExit(f"cutout: unknown decontam {decontam!r}; expected off|palette")image = Image.open(input_path).convert("RGBA")width, height = image.size@@ -336,8 +353,13 @@ def cutout(route = _detect_key_kind(_corner_average(image)) if key == "auto" else keyif route in ("magenta", "green"):result, route_stats = extract_route(image, route, spill_max_fraction=spill_max_fraction,- spill_min_tint=spill_min_tint, spill_require_hue=spill_require_hue)+ spill_min_tint=spill_min_tint, spill_require_hue=spill_require_hue,+ decontam=decontam, decontam_fit=decontam_fit,+ decontam_palette=decontam_palette)else:+ if decontam != "off":+ raise SystemExit(f"cutout: --decontam {decontam} needs a chroma key background (magenta/green); "+ f"{input_path} routed to the white matte, which has no key colour to remove")result, route_stats = _matte_route(image, input_path, strength, band, erode, tolerance)out_path.parent.mkdir(parents=True, exist_ok=True)@@ -412,6 +434,13 @@ def add_arguments(p: Any) -> None:action="store_true",help="also write cyan/magenta/yellow verification composites next to the output",)+ p.add_argument(+ "--decontam",+ choices=["off", "palette"],+ default="off",+ help="chroma routes only: re-explain key-tinted edges with the subject's own colours "+ "(palette); off keeps the engine output byte-identical (default off)",+ )def run(**kwargs: object) -> int:@@ -428,6 +457,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 "off"),)import jsondiff --git a/sprite_gen/frames/decontam.py b/sprite_gen/frames/decontam.pynew file mode 100644index 0000000..3738639--- /dev/null+++ b/sprite_gen/frames/decontam.py@@ -0,0 +1,363 @@+# SPDX-License-Identifier: Apache-2.0+"""Edge decontamination: give a keyed edge the subject's own colour back (`decontam: "palette"`).++The chroma engine splits a key/subject blend using the key-tint score alone. That+assumes the subject colour carries no tint of its own, which holds for grey and+white and fails for saturated colours. A red hair strand blended a third of the+way into green scores as barely tinted, so it stays opaque and olive, and when+`despill_color` does reach it the recovery overshoots into orange (the warm bias+of the `1/(1-k)` gain). Video adds a second loss: 4:2:0 chroma subsampling has+already averaged the key into the colour of every strand one or two pixels wide,+so no amount of unmixing that pixel alone can find the red again. What survives+is the luma, which the codec keeps at full resolution.++This pass explains each edge pixel as a mix of the key background, measured+locally, with one colour the subject actually owns:++ observed = alpha * P + (1 - alpha) * B++P ranges over a small palette learned from the subject's confident interior.+The pixel takes the P whose line through B passes closest to the observation;+alpha is the projection onto that line. The colour written is P's chroma at the+observation's luma: the hue comes from the subject, the light and shade from+the pixel. With a key-free palette, the output cannot carry the key's hue at+all, and no channel gain is applied, so nothing can drift warm.++Guards, in order of the decision they make:++- *Background flank.* Keyed pixels within `FLANK_PX` of the subject may regain+ coverage (the faint sides of a strand the hard cut erased), above a noise+ floor measured on the background itself, and only when chained to the subject.+- *Unexplained.* A pixel no palette colour explains (a small gem of a colour the+ interior never shows) keeps the engine's bytes.+- *Opaque.* A band pixel that is closer to some palette colour as it is than the+ mix explains it (by `OPAQUE_MARGIN`, or three noise sigmas when the source is+ noisier) is ordinary shading, not a blend: it keeps the engine's bytes. Only+ when the subject owns no key-coloured material is a residual key hue on such a+ pixel capped (`KEY_HUE_TINT`), which lowers the keyed channel and never raises+ another.+- *Depth.* Coverage is refitted only within `alpha_depth` of the keyed region+ (the engine's unmix reach, same meaning). Deeper band pixels get colour only,+ so a key reflection on a solid surface is recoloured, not turned see-through.++A subject that owns key-coloured material (more than `KEY_MATERIAL_MAX_SHARE` of+its interior carries the key hue, the same test `video-frames --spill auto` runs+on its reference still) keeps that material in the palette; its edges are then+repainted with whatever explains them best, key colour included.++`fit="video"` chooses P on a 3x3 mean of the observation and averages the+projection alpha with a luma-only alpha where P and B differ in luma, because a+decoded video frame's chroma is blurred while its luma is not.++Everything here is integer-exact or a fixed sequence of float64 operations: no+random initialisation, no iteration-order dependence, the same input gives the+same bytes. The one learned component, the palette, is a histogram k-means with+a deterministic seed (greedy weighted farthest-point) and a fixed iteration count.+"""++from __future__ import annotations++from typing import Any++from sprite_gen._deps import np+from sprite_gen.frames.extract import _grow_chebyshev, _grow_into, _key_channel_split, _key_excess_field++DECONTAM_MODES = ("off", "palette")+DECONTAM_FITS = ("still", "video")++BAND_PX = 6 # subject pixels this close (Chebyshev) to the keyed background are re-examined+FLANK_PX = 3 # keyed pixels this close to the subject may regain coverage+BACKGROUND_RADIUS = 12 # local background = mean of keyed pixels in this box radius+PALETTE_SIZE = 32+PALETTE_BITS = 5 # histogram quantisation for the palette k-means+PALETTE_ITERATIONS = 10+KEY_HUE_TINT = 8.0 # the key-hue bar of the full spill pass (extract._SPILL_FULL_MIN_TINT)+KEY_MATERIAL_MAX_SHARE = 0.005 # the key-material share `video-frames --spill auto` tolerates+OPAQUE_MARGIN = 10.0 # a blend must explain the pixel this much better than "opaque as observed"+NOISE_SIGMAS = 3.0+MIN_RECOVERED_ALPHA = 0.06+LUMA_TRUST_ALPHA = 0.35 # below this coverage the observed luma is noise; lean on the palette+UNEXPLAINED_RATIO = 0.5+UNEXPLAINED_SLACK = 8.0+LUMA_SEPARATION = 24.0 # video fit: luma alpha only where P and B differ this much in luma+TINT_SHIFT = 8.0 # a tint moves the colour at least this far toward the key ...+TINT_RATIO = 2.0 # ... and at least this many times farther than the fit misses by+LUMA = np.array([0.299, 0.587, 0.114])+_CHUNK = 1 << 16+++def validate(mode: str, fit: str = "still") -> None:+ if mode not in DECONTAM_MODES:+ raise SystemExit(f"decontam: unknown mode {mode!r}; expected one of {', '.join(DECONTAM_MODES)}")+ if fit not in DECONTAM_FITS:+ raise SystemExit(f"decontam: unknown fit {fit!r}; expected one of {', '.join(DECONTAM_FITS)}")+++def _ring_depth(seed: np.ndarray, rings: int) -> np.ndarray:+ """Chebyshev distance to `seed`, counted ring by ring: 0 on it, rings + 1 beyond the last ring."""+ depth = np.full(seed.shape, rings + 1, dtype=np.uint8)+ depth[seed] = 0+ reached = seed+ for ring in range(1, rings + 1):+ grown = _grow_chebyshev(reached)+ depth[grown & ~reached] = ring+ reached = grown+ return depth+++def _box_sum(values: np.ndarray, radius: int) -> np.ndarray:+ """Sum over a (2r+1)^2 window, clipped at the image edge. Integer-valued input stays exact."""+ height, width = values.shape[:2]+ table = np.zeros((height + 1, width + 1) + values.shape[2:], dtype=np.float64)+ table[1:, 1:] = values.cumsum(0).cumsum(1)+ y0 = np.clip(np.arange(height) - radius, 0, height)+ y1 = np.clip(np.arange(height) + radius + 1, 0, height)+ x0 = np.clip(np.arange(width) - radius, 0, width)+ x1 = np.clip(np.arange(width) + radius + 1, 0, width)+ return table[y1][:, x1] - table[y0][:, x1] - table[y1][:, x0] + table[y0][:, x0]+++def local_background(rgb: np.ndarray, preferred: np.ndarray, fallback: np.ndarray, radius: int) -> np.ndarray:+ """Mean keyed colour within `radius`, from `preferred` pixels where any, else from `fallback`."""+ out = np.zeros(rgb.shape, dtype=np.float64)+ found = np.zeros(rgb.shape[:2], dtype=bool)+ for mask in (preferred, fallback):+ weight = _box_sum(mask.astype(np.float64), radius)+ total = _box_sum(rgb * mask[..., None], radius)+ fill = (weight > 0) & ~found+ out[fill] = total[fill] / weight[fill][:, None]+ found |= fill+ return out+++def learn_palette(samples: np.ndarray, size: int = PALETTE_SIZE) -> np.ndarray:+ """Deterministic weighted k-means over a 5-bit colour histogram of `samples` (N, 3)."""+ samples = np.asarray(samples, dtype=np.int64).reshape(-1, 3)+ shift = 8 - PALETTE_BITS+ q = samples >> shift+ code = (q[:, 0] << (2 * PALETTE_BITS)) | (q[:, 1] << PALETTE_BITS) | q[:, 2]+ bins = 1 << (3 * PALETTE_BITS)+ counts = np.bincount(code, minlength=bins)+ used = np.flatnonzero(counts)+ weight = counts[used].astype(np.float64)+ points = np.stack([np.bincount(code, weights=samples[:, c].astype(np.float64), minlength=bins)[used]+ for c in range(3)], axis=-1) / weight[:, None]+ centres = [(points * weight[:, None]).sum(0) / weight.sum()]+ nearest = ((points - centres[0]) ** 2).sum(-1)+ for _ in range(1, min(size, len(points))):+ pick = int(np.argmax(weight * nearest)) # greedy weighted farthest point; ties -> lowest bin+ if weight[pick] * nearest[pick] <= 0:+ break+ centres.append(points[pick])+ nearest = np.minimum(nearest, ((points - points[pick]) ** 2).sum(-1))+ centres = np.array(centres)+ for _ in range(PALETTE_ITERATIONS):+ label = ((points[:, None, :] - centres[None]) ** 2).sum(-1).argmin(1)+ for j in range(len(centres)):+ member = label == j+ if member.any():+ centres[j] = (points[member] * weight[member, None]).sum(0) / weight[member].sum()+ return centres+++def _cap_key_hue(rgb: np.ndarray, keyed_channels: list[int], unkeyed_channels: list[int], tint: float) -> np.ndarray:+ """Lower every keyed channel to at most (max unkeyed channel + tint). Never raises a channel."""+ out = np.array(rgb, dtype=np.float64, copy=True)+ ceiling = out[..., unkeyed_channels].max(axis=-1) + tint+ for channel in keyed_channels:+ out[..., channel] = np.minimum(out[..., channel], ceiling)+ return out+++def recolor_to_luma(colour: np.ndarray, luma: np.ndarray) -> np.ndarray:+ """`colour` moved to `luma`: darkened by scaling, brightened toward white. Hue is kept either way."""+ own = colour @ LUMA+ target = np.clip(luma, 0, 255)+ darker = target <= own+ scale = np.where(darker, target / np.maximum(own, 1e-6), 0.0)+ lift = np.where(darker, 0.0, (target - own) / np.maximum(255 - own, 1e-6))+ return np.where(darker[:, None], colour * scale[:, None], colour + lift[:, None] * (255 - colour))+++def _box3(rgb: np.ndarray, rows: np.ndarray, cols: np.ndarray) -> np.ndarray:+ """3x3 mean (edge-clamped) of `rgb` at the given pixels."""+ height, width = rgb.shape[:2]+ acc = np.zeros((len(rows), 3), dtype=np.float64)+ for dy in (-1, 0, 1):+ for dx in (-1, 0, 1):+ acc += rgb[np.clip(rows + dy, 0, height - 1), np.clip(cols + dx, 0, width - 1)]+ return acc / 9.0+++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`).++ Returns {"palette": (k, 3) float64, "keyfree": bool, "key_material_share": float}. A clip+ can learn this once and hand it to every frame, so the colours an edge may take do not+ change from frame to frame.+ """+ keyed_channels, unkeyed_channels = _key_channel_split(chroma_key)+ if not keyed_channels:+ raise SystemExit(f"decontam: 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")+ subject = ~keyed_mask+ interior = subject & (_ring_depth(keyed_mask, BAND_PX) > BAND_PX)+ confident = interior & (keyed[..., 3] == 255)+ confident_count = int(np.count_nonzero(confident))+ if confident_count == 0:+ raise SystemExit(f"decontam: 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; run without decontam")+ 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+ keyfree = key_material <= KEY_MATERIAL_MAX_SHARE+ samples = keyed[..., :3][confident & (excess <= KEY_HUE_TINT)] if keyfree else keyed[..., :3][confident]+ # whole RGB values: a palette is a set of colours, and integers survive a JSON report exactly,+ # so a clip can hand frame 1's palette to frame 97 through its report with no drift+ palette = np.round(learn_palette(samples))+ if keyfree:+ palette = _cap_key_hue(palette, keyed_channels, unkeyed_channels, KEY_HUE_TINT)+ return {"palette": palette, "keyfree": keyfree, "key_material_share": key_material}+++def palette_from_stats(stats: dict[str, Any]) -> dict[str, Any]:+ """The `subject_palette` a `decontaminate` call used, rebuilt from its stats."""+ return {"palette": np.asarray(stats["palette"], dtype=np.float64), "keyfree": bool(stats["palette_keyfree"]),+ "key_material_share": float(stats["key_material_share"])}+++def decontaminate(source_rgb: np.ndarray, keyed: np.ndarray, keyed_mask: np.ndarray,+ chroma_key: tuple[int, int, int], *, fit: str = "still", alpha_depth: int = 4,+ palette: dict[str, Any] | 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, `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.+ """+ validate("palette", fit)+ keyed_channels, unkeyed_channels = _key_channel_split(chroma_key)+ if not keyed_channels:+ raise SystemExit(f"decontam: 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")+ rgb = np.asarray(source_rgb, dtype=np.float64)[..., :3]+ out = np.array(keyed, dtype=np.uint8, copy=True)+ subject = ~keyed_mask+ 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+ palette_rgb = np.asarray(learned["palette"], dtype=np.float64)+ keyfree = bool(learned["keyfree"])+ key_material = float(learned["key_material_share"])++ far_background = keyed_mask & ~flank+ background = local_background(rgb, far_background, keyed_mask, BACKGROUND_RADIUS)+ if np.count_nonzero(far_background):+ residual = rgb[far_background] - background[far_background]+ sigma_luma = 1.4826 * float(np.median(np.abs(residual @ LUMA)))+ sigma_rgb = 1.4826 * float(np.median(np.linalg.norm(residual, axis=-1)))+ else:+ sigma_luma = sigma_rgb = 0.0+ margin = max(OPAQUE_MARGIN, NOISE_SIGMAS * sigma_rgb)++ rows, cols = np.nonzero(band | flank)+ alpha_new = np.zeros(len(rows))+ colour_new = np.zeros((len(rows), 3))+ blend = np.zeros(len(rows), dtype=bool)+ tinted = np.zeros(len(rows), dtype=bool)+ unexplained = np.zeros(len(rows), dtype=bool)+ for start in range(0, len(rows), _CHUNK):+ r = rows[start:start + _CHUNK]; c = cols[start:start + _CHUNK]+ obs = rgb[r, c]; bg = background[r, c]+ if fit == "video":+ choose_obs = _box3(rgb, r, c); choose_bg = _box3(background, r, c)+ else:+ choose_obs, choose_bg = obs, bg+ towards = choose_obs - choose_bg+ best = np.full(len(r), np.inf)+ pick = np.zeros(len(r), dtype=np.int64)+ opaque_distance = np.full(len(r), np.inf)+ for index, colour in enumerate(palette_rgb):+ line = colour - choose_bg+ length = np.maximum((line * line).sum(-1), 1e-9)+ along = np.clip((towards * line).sum(-1) / length, 0.0, 1.0)+ miss = np.linalg.norm(towards - along[:, None] * line, axis=-1)+ closer = miss < best+ best[closer] = miss[closer]+ pick[closer] = index+ opaque_distance = np.minimum(opaque_distance, np.linalg.norm(obs - colour, axis=-1))+ chosen = palette_rgb[pick]+ line = chosen - bg+ offset = obs - bg+ alpha = np.clip((offset * line).sum(-1) / np.maximum((line * line).sum(-1), 1e-9), 0.0, 1.0)+ if fit == "video":+ luma_gap = (chosen - bg) @ LUMA+ separated = np.abs(luma_gap) >= LUMA_SEPARATION+ luma_alpha = np.clip((offset @ LUMA) / np.where(separated, luma_gap, 1.0), 0.0, 1.0)+ alpha = np.where(separated, 0.5 * (alpha + luma_alpha), alpha)+ miss = np.linalg.norm(offset - alpha[:, None] * line, axis=-1)+ explained = miss <= UNEXPLAINED_RATIO * np.linalg.norm(offset, axis=-1) + UNEXPLAINED_SLACK+ in_flank = flank[r, c]+ is_blend = explained & (alpha < 1.0) & (in_flank | (miss + margin < opaque_distance))+ # a tint: displaced from its colour toward the key clearly more than the fit misses by, but+ # not by enough to prove partial coverage. Recoloured, coverage untouched.+ shift = (1.0 - alpha) * np.sqrt((line * line).sum(-1))+ is_tint = explained & ~is_blend & ~in_flank & (shift >= TINT_SHIFT) & (shift >= TINT_RATIO * miss)+ # coverage: refit within the unmix reach and on the flank; colour only deeper in the band+ refit = (in_flank | (depth[r, c] <= alpha_depth)) & ~is_tint+ floor = np.maximum(MIN_RECOVERED_ALPHA, NOISE_SIGMAS * sigma_luma / np.maximum(np.abs((chosen - bg) @ LUMA), 1e-6))+ alpha = np.where(in_flank & (alpha < floor), 0.0, alpha)+ coverage = np.where(refit, alpha, out[r, c, 3] / 255.0)+ # the colour's light: the observation with the fitted key share taken out, leaning on the+ # palette colour where coverage is too thin for the observed luma to mean much+ observed_luma = (obs @ LUMA - (1 - alpha) * (bg @ LUMA)) / np.maximum(alpha, 1e-3)+ trust = np.clip(alpha / LUMA_TRUST_ALPHA, 0.0, 1.0)+ target = trust * observed_luma + (1 - trust) * (chosen @ LUMA)+ alpha_new[start:start + len(r)] = coverage+ colour_new[start:start + len(r)] = recolor_to_luma(chosen, target)+ blend[start:start + len(r)] = is_blend | is_tint+ tinted[start:start + len(r)] = is_tint+ unexplained[start:start + len(r)] = ~explained++ alpha8 = np.clip(np.round(alpha_new * 255), 0, 255).astype(np.uint8)+ colour8 = np.clip(np.round(colour_new), 0, 255).astype(np.uint8)+ br, bc = rows[blend], cols[blend]+ out[br, bc, :3] = colour8[blend]+ out[br, bc, 3] = alpha8[blend]+ clamped = 0+ if keyfree:+ kept = ~blend & band[rows, cols] & (out[rows, cols, 3] > 0)+ kr, kc = rows[kept], cols[kept]+ kept_rgb = out[kr, kc, :3].astype(np.int32)+ hued = _key_excess_field(kept_rgb, keyed_channels, unkeyed_channels) > KEY_HUE_TINT+ capped = _cap_key_hue(kept_rgb[hued], keyed_channels, unkeyed_channels, KEY_HUE_TINT)+ out[kr[hued], kc[hued], :3] = np.clip(np.round(capped), 0, 255).astype(np.uint8)+ clamped = int(np.count_nonzero(hued))+ # recovered background coverage must chain to the subject+ visible = out[..., 3] > 0+ attached = _grow_into(subject & visible, visible)+ detached = flank & visible & ~attached+ out[detached] = 0+ out[out[..., 3] == 0] = 0+ recovered = int(np.count_nonzero(flank & (out[..., 3] > 0)))+ stats = {+ "mode": "palette",+ "fit": fit,+ "band_px": BAND_PX,+ "alpha_depth": int(alpha_depth),+ "flank_px": FLANK_PX,+ "palette_size": int(len(palette_rgb)),+ "palette_source": "frame" if palette is None else "given",+ "palette": [[int(v) for v in colour] for colour in palette_rgb],+ "palette_keyfree": bool(keyfree),+ "key_material_share": round(key_material, 5),+ "noise_sigma_rgb": round(sigma_rgb, 3),+ "opaque_margin": round(margin, 3),+ "refit_px": int(np.count_nonzero(blend & ~tinted)),+ "tint_px": int(np.count_nonzero(tinted)),+ "recovered_px": recovered,+ "unexplained_px": int(np.count_nonzero(unexplained & band[rows, cols])),+ "key_hue_capped_px": clamped,+ }+ return out, statsdiff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.pyindex 03da182..3797901 100644--- a/sprite_gen/frames/extract.py+++ b/sprite_gen/frames/extract.py@@ -391,6 +391,38 @@ _SPILL_MIN_TINT = 40.0# reference at this same threshold before choosing full correction._SPILL_FULL_MIN_TINT = 8.0DEFAULT_UNMIX_REACH = 4+DEFAULT_KEY_THRESHOLD = 96.0 # `--key-threshold` default; the YCbCr path's decontam geometry reuses it+++def hard_key_mask(source_rgb: np.ndarray, alpha: np.ndarray, chroma_key: tuple[int, int, int],+ painted_key: tuple[int, int, int], threshold: float) -> tuple[np.ndarray, np.ndarray]:+ """The hard cut: (keyed_mask, key_distance) for an (H, W, 3) int32 source.++ `key_distance` is the distance to the declared key, lowered to the distance to the+ painted colour for the pixels that colour may claim; `keyed_mask` is transparent+ input plus everything within `threshold` of it. One definition for the RGB matte and+ for the decontam pass that runs after either matte.+ """+ keyed_channels, unkeyed_channels = _key_channel_split(chroma_key)+ key_distance = _key_distance_field(source_rgb, chroma_key)+ if painted_key != tuple(chroma_key):+ # The painted colour's authority is border evidence, and a pixel deep+ # inside the frame has none. So its ball erases the *background*: the+ # pixels that carry the key's hue signature themselves, plus whatever+ # else inside the ball touches that keyed region (the antialiased rim+ # of the subject, whose blend with a lit subject colour lifts the+ # unkeyed channel over the signature bar). An isolated patch inside+ # the subject that merely resembles the painted colour is left alone:+ # hot pink (250, 77, 150) sits 46 from Grok's (216, 46, 147) magenta+ # and would otherwise be cut out of the subject. The declared key's+ # ball stays what it always was — a colour ball, position-blind.+ painted_distance = _key_distance_field(source_rgb, painted_key)+ in_ball = painted_distance <= threshold+ painted_keyed = in_ball & _border_key_candidate_field(source_rgb, keyed_channels, unkeyed_channels)+ painted_keyed |= in_ball & (key_distance <= threshold)+ painted_keyed = _grow_into(painted_keyed, in_ball)+ key_distance = np.where(painted_keyed, np.minimum(key_distance, painted_distance), key_distance)+ return (alpha == 0) | (key_distance <= threshold), key_distancedef key_material_pixels(image: Image.Image, chroma_key: tuple[int, int, int],@@ -435,6 +467,10 @@ def remove_chroma_background(spill_min_tint: float = _SPILL_MIN_TINT,spill_require_hue: bool = False,background_key: tuple[int, int, int] | None = None,+ decontam: str = "off",+ decontam_fit: str = "still",+ decontam_palette: dict[str, Any] | None = None,+ decontam_stats: dict[str, Any] | None = None,) -> Image.Image:"""Key `chroma_key` out of `image` (hard cut + soft-alpha fringe unmix + trapped-spill despill).@@ -442,7 +478,15 @@ def remove_chroma_background(default) detects it from the borders with `detect_background_key_rgb`;passing `chroma_key` itself pins the single-key behaviour (the frozenbyte-identity gate does that).++ `decontam="palette"` re-explains the edge afterwards with the subject's own+ colours (`sprite_gen.frames.decontam`); "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."""+ if decontam != "off":+ from sprite_gen.frames import decontam as decontam_module+ decontam_module.validate(decontam, decontam_fit)rgba = image.convert("RGBA")width, height = rgba.sizedata = np.array(rgba, dtype=np.uint8) # (H, W, 4); written back at the end@@ -468,26 +512,8 @@ def remove_chroma_background(# *is* the if/elif order it replaces — swapping the subject and in-band rows# changes the output wherever both hold at once (a wide --fringe-key-threshold# makes that reachable, and the gate has a case for it).- key_distance = _key_distance_field(source_rgb, chroma_key)- if painted_key != tuple(chroma_key):- # The painted colour's authority is border evidence, and a pixel deep- # inside the frame has none. So its ball erases the *background*: the- # pixels that carry the key's hue signature themselves, plus whatever- # else inside the ball touches that keyed region (the antialiased rim- # of the subject, whose blend with a lit subject colour lifts the- # unkeyed channel over the signature bar). An isolated patch inside- # the subject that merely resembles the painted colour is left alone:- # hot pink (250, 77, 150) sits 46 from Grok's (216, 46, 147) magenta- # and would otherwise be cut out of the subject. The declared key's- # ball stays what it always was — a colour ball, position-blind.- painted_distance = _key_distance_field(source_rgb, painted_key)- in_ball = painted_distance <= threshold- painted_keyed = in_ball & _border_key_candidate_field(source_rgb, keyed_channels, unkeyed_channels)- painted_keyed |= in_ball & (key_distance <= threshold)- painted_keyed = _grow_into(painted_keyed, in_ball)- key_distance = np.where(painted_keyed, np.minimum(key_distance, painted_distance), key_distance)+ keyed_mask, key_distance = hard_key_mask(source_rgb, data[..., 3], chroma_key, painted_key, threshold)source_tint = _key_tint_field(source_rgb, keyed_channels, unkeyed_channels)- keyed_mask = (data[..., 3] == 0) | (key_distance <= threshold)classes = np.select([keyed_mask, source_tint < fringe_delta, key_distance <= fringe_threshold],[_KEYED, _SUBJECT, _BLEND_IN_BAND],@@ -619,6 +645,11 @@ def remove_chroma_background()if coverage > 0:data[y, x] = (*despilled, alpha)+ if decontam != "off":+ data, stats = decontam_module.decontaminate(source_rgb, data, keyed_mask, chroma_key, fit=decontam_fit,+ alpha_depth=unmix_reach, palette=decontam_palette)+ if decontam_stats is not None:+ decontam_stats.update(stats)# Back into the converted copy rather than a fresh Image.fromarray, so the# returned image keeps the mode, size and `info` (icc profile, dpi) that# `convert` carried over from the caller's image.@@ -931,6 +962,11 @@ def remove_chroma_background_ycbcr(image: Image.Image,chroma_key: tuple[int, int, int],warnings: list[str] | None = None,+ *,+ decontam: str = "off",+ decontam_fit: str = "still",+ decontam_palette: dict[str, Any] | None = None,+ decontam_stats: dict[str, Any] | None = None,) -> Image.Image:"""Chrominance-plane matting with self-diagnostic pure-key rematte.@@ -941,7 +977,14 @@ def remove_chroma_background_ycbcr(symptom triggers a rematte with the declared pure key; the better resultwins and the fallback is reported through `warnings` (observable, neversilent).++ `decontam="palette"` then re-explains the edge exactly as the RGB path does,+ over this matte's output; its geometry is the RGB path's hard cut at the+ default `--key-threshold`, so both mattes share one definition of the edge."""+ if decontam != "off":+ from sprite_gen.frames import decontam as decontam_module+ decontam_module.validate(decontam, decontam_fit)def note(message: str) -> None:if warnings is not None:@@ -984,6 +1027,17 @@ def remove_chroma_background_ycbcr(out = retry_cleanup_alpha_ycc(out)+ if decontam != "off":+ source = np.array(rgba, dtype=np.uint8)+ source_rgb = source[..., :3].astype(np.int32)+ painted = detect_background_key_rgb(rgba, chroma_key)+ keyed_mask, _ = hard_key_mask(source_rgb, source[..., 3], chroma_key, painted, DEFAULT_KEY_THRESHOLD)+ data, stats = decontam_module.decontaminate(source_rgb, np.array(out, dtype=np.uint8), keyed_mask, chroma_key,+ fit=decontam_fit, alpha_depth=DEFAULT_UNMIX_REACH,+ palette=decontam_palette)+ if decontam_stats is not None:+ decontam_stats.update(stats)+ out.frombytes(data.tobytes())return out@@ -2524,6 +2578,13 @@ def _build_parser() -> argparse.ArgumentParser:"(ycbcr = chrominance-plane matting with border-mode key detection, ""despill and flood fill — perfectpixel-studio port; default rgb)",)+ parser.add_argument(+ "--decontam",+ choices=("off", "palette"),+ default=None,+ help="edge decontamination after the matte; overrides request chroma.decontam "+ "(palette = re-explain key-tinted edges with the subject's own colours; default off)",+ )parser.add_argument("--segmentation",choices=("components", "projection"),@@ -2894,12 +2955,22 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):)if chroma_mode not in ("rgb", "ycbcr"):raise SystemExit("chroma.mode must be 'rgb' or 'ycbcr'")+ decontam_mode = (+ args.decontam+ if args.decontam is not None+ else str(chroma_config.get("decontam", "off"))+ )+ if decontam_mode not in ("off", "palette"):+ raise SystemExit("chroma.decontam must be 'off' or 'palette'")effective_chroma = {**chroma_config,"mode": chroma_mode,"unmix_reach": unmix_reach,"spill_max_fraction": spill_max_fraction,}+ # 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_modeif effective_chroma != chroma_config:request["chroma"] = effective_chromaatomic_write_text(@@ -3065,7 +3136,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)+ strip = remove_chroma_background_ycbcr(opened, chroma_key, ycc_notes, decontam=decontam_mode)all_warnings.extend(f"{tag}: {note}" for note in ycc_notes)else:strip = remove_chroma_background(@@ -3076,6 +3147,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,)return separate_fused_poses(strip, frame_count, fit_config, args.segmentation, state)@@ -3482,7 +3554,8 @@ def engine_revision() -> str:# the same folder (extract=frames/, layout=spec/), so resolve layout by its# module file, not as a sibling of __file__.import sprite_gen.spec.layout as _layout_module- sources = (Path(__file__), Path(_layout_module.__file__))+ import sprite_gen.frames.decontam as _decontam_module+ sources = (Path(__file__), Path(_layout_module.__file__), Path(_decontam_module.__file__))key = tuple(source.stat().st_mtime_ns for source in sources)if _ENGINE_REVISION is None or _ENGINE_REVISION_KEY != key:digest = hashlib.sha256()diff --git a/sprite_gen/qa/inspect.py b/sprite_gen/qa/inspect.pyindex 54af949..7a6efcb 100644--- a/sprite_gen/qa/inspect.py+++ b/sprite_gen/qa/inspect.py@@ -40,6 +40,7 @@ def _build_parser() -> argparse.ArgumentParser:parser.add_argument("--fringe-unmix-reach", type=int, default=None)parser.add_argument("--spill-max-fraction", type=float, default=None)parser.add_argument("--chroma-mode", choices=("rgb", "ycbcr"), default=None)+ parser.add_argument("--decontam", choices=("off", "palette"), default=None)parser.add_argument("--no-write", action="store_true")return parser@@ -117,10 +118,11 @@ def _strip_for_state(run_dir: Path, request: dict[str, Any], state: str, args: aif args.spill_max_fraction is not Noneelse 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"))with Image.open(raw_path) as opened:if chroma_mode == "ycbcr":notes: list[str] = []- return extract.remove_chroma_background_ycbcr(opened, chroma_key, notes)+ return extract.remove_chroma_background_ycbcr(opened, chroma_key, notes, decontam=decontam)return extract.remove_chroma_background(opened,chroma_key,@@ -129,6 +131,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,)@@ -416,6 +419,7 @@ def _run(args: argparse.Namespace) -> int:fringe_unmix_reach=args.fringe_unmix_reach,spill_max_fraction=args.spill_max_fraction,chroma_mode=args.chroma_mode,+ decontam=args.decontam,)if not args.no_write:acquire_run_dir_lock(run_dir, "inspect_sprite_run")diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex 5368e96..510a12b 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -104,6 +104,7 @@ def run_item(facing: str = "right",facing_fix: str = "none",prepare_side: Callable[[Path], tuple[Path, dict]] | None = None,+ decontam: str = "off",) -> dict[str, Any]:if anchor == "motion-auto" and not loop_mod.profile_for(state).gait:raise SystemExit("video-set: --anchor motion-auto requires walk/run states")@@ -181,7 +182,7 @@ def run_item(if attempts[-1] != 0 or not clip.exists():raise SystemExit(f"clip generation failed after {len(attempts)} attempt(s); see {item_dir / 'clip.log'}")- fr = frames_mod.run_frames(clip, item_dir / "frames", key=key, allow_edge_contact=False, report_path=item_dir / "frames.report.json", spill=spill, reference=canvas_png)+ fr = frames_mod.run_frames(clip, item_dir / "frames", key=key, allow_edge_contact=False, report_path=item_dir / "frames.report.json", spill=spill, reference=canvas_png, decontam=decontam)result["frames"] = {k: fr[k] for k in ("fps", "frames", "alpha_zero_pct_min", "alpha_zero_pct_max")}result["frames"]["spill"] = fr.get("spill", {}).get("mode")lp = loop_mod.run_loop(Path(fr["keyed_dir"]), item_dir / "loop", fps=float(fr["fps"]), state=state, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX, name=item, report_path=item_dir / "loop.report.json", anchor=anchor)@@ -231,6 +232,7 @@ def run_set(spill: str = "auto",facing: str = "right",facing_fix: str = "none",+ decontam: str = "off",) -> dict[str, Any]:if anchor == "motion-auto" and any(not loop_mod.profile_for(state).gait for state in states):raise SystemExit("video-set: --anchor motion-auto requires walk/run states")@@ -260,7 +262,7 @@ def run_set(return prepared[base]with ThreadPoolExecutor(max_workers=max(1, concurrency)) as ex:- futures = {ex.submit(run_item, item=i, direction=d, state=s, base=bases[d], root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=facing, facing_fix=facing_fix, prepare_side=prepare_side): i for i, d, s in items}+ futures = {ex.submit(run_item, item=i, direction=d, state=s, base=bases[d], root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=facing, facing_fix=facing_fix, prepare_side=prepare_side, decontam=decontam): i for i, d, s in items}for fut in as_completed(futures):r = fut.result()results.append(r)@@ -303,6 +305,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--shape", choices=canvas_mod.SHAPES, help="force one canvas shape for every state (e.g. wide for a costume or arms that leave a 1:1 frame)")parser.add_argument("--anchor", choices=tuple(a for a in loop_mod.ANCHOR_MODES if a != "motion"), default="none", help="motion-auto: automatic regions, local period and XY correction (walk/run only); feet: remove in-canvas drift")parser.add_argument("--spill", choices=frames_mod.SPILL_MODES, default="auto", help="auto: judge key reflections from each item's canvas still (default); small / full: force")+ parser.add_argument("--decontam", choices=frames_mod.DECONTAM_MODES, default="off", help="passed to video-frames: palette re-explains key-tinted edges with the subject's own colours (default off)")parser.add_argument("--force", action="store_true", help="regenerate clips that already exist")@@ -315,6 +318,7 @@ def run(**kwargs: object) -> int:concurrency=int(kwargs.get("concurrency") or 3), force=bool(kwargs.get("force")), gap=float(kwargs.get("start_gap") or START_GAP_SECONDS),facing=str(kwargs.get("facing") or "right"), facing_fix=str(kwargs.get("facing_fix") or "none"),shape=(str(kwargs["shape"]) if kwargs.get("shape") else None), anchor=str(kwargs.get("anchor") or "none"), spill=str(kwargs.get("spill") or "auto"),+ decontam=str(kwargs.get("decontam") or "off"),)return 0 if not payload["failed"] else 1diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.pyindex 8862e7f..f921a14 100644--- a/sprite_gen/video/frames.py+++ b/sprite_gen/video/frames.py@@ -48,6 +48,12 @@ SPILL_FULL_FRACTION = 1.0 # every tinted cluster is spill, whatever its sizeSPILL_FULL_MIN_TINT = _SPILL_FULL_MIN_TINT # ... and whatever its strength (see extract.py)SPILL_REFERENCE_MAX = 0.005 # the still's own key material ≤ the engine's small-cluster share → fullEDGE_MAX_PIXELS = 0 # any opaque pixel on the top/left/right edge band = contact+# Edge decontamination (`sprite_gen.frames.decontam`). A decoded frame's chroma is blurred by+# 4:2:0 while its luma is not, so frames use the video fit. One palette serves the whole clip,+# learned on the first frame, so the colours an edge may take cannot change between frames.+DECONTAM_MODES = ("off", "palette")+DECONTAM_FIT = "video"+DECONTAM_STAT_KEYS = ("refit_px", "tint_px", "recovered_px", "unexplained_px", "key_hue_capped_px")def _require(binary: str) -> str:@@ -156,9 +162,16 @@ def key_frames(key: str = "auto",check_edges: bool = True,spill: str = "small",+ decontam: str = "off",) -> dict[str, Any]:if spill not in ("small", "full"):raise SystemExit(f"video-frames: key_frames takes a resolved spill mode (small|full), got {spill!r}")+ if decontam not in DECONTAM_MODES:+ raise SystemExit(f"video-frames: unknown --decontam {decontam!r}; expected one of {', '.join(DECONTAM_MODES)}")+ from sprite_gen.frames.decontam import palette_from_stats+ clip_palette: dict[str, Any] | None = None+ decontam_first: dict[str, Any] | None = None+ decontam_totals = {name: 0 for name in DECONTAM_STAT_KEYS}# Full correction lowers the tint threshold as well as lifting the size cap.spill_max = SPILL_FULL_FRACTION if spill == "full" else Nonespill_tint = SPILL_FULL_MIN_TINT if spill == "full" else None@@ -168,12 +181,21 @@ def key_frames(for src in raw_files:dst = keyed_dir / src.namestats = cutout(src, dst, key=key, spill_max_fraction=spill_max, spill_min_tint=spill_tint,- spill_require_hue=spill == "full")+ spill_require_hue=spill == "full", decontam=decontam, decontam_fit=DECONTAM_FIT,+ decontam_palette=clip_palette)image = Image.open(dst).convert("RGBA")hist = image.getchannel("A").histogram()w, h = image.sizealpha_zero_pct = round(100 * hist[0] / (w * h), 2)row = {"frame": src.name, "alpha_zero_pct": alpha_zero_pct, "route": stats.get("route")}+ if decontam != "off":+ done = stats["decontam"]+ if clip_palette is None:+ clip_palette = palette_from_stats(done)+ decontam_first = done+ row["decontam"] = {name: done[name] for name in DECONTAM_STAT_KEYS}+ for name in DECONTAM_STAT_KEYS:+ decontam_totals[name] += int(done[name])if check_edges:contact = edge_contact(image)if any(v > EDGE_MAX_PIXELS for v in contact.values()):@@ -192,6 +214,18 @@ def key_frames("edge_contacts": contacts,"rows": rows,}+ if decontam != "off" and decontam_first is not None:+ report["decontam"] = {+ "mode": decontam,+ "fit": DECONTAM_FIT,+ "palette_source": f"clip (learned on {rows[0]['frame']})",+ "palette": decontam_first["palette"],+ "palette_keyfree": decontam_first["palette_keyfree"],+ "key_material_share": decontam_first["key_material_share"],+ "totals": decontam_totals,+ }+ else:+ report["decontam"] = {"mode": decontam}if contacts and check_edges:raise SystemExit(_edge_contact_message(contacts))return report@@ -221,11 +255,13 @@ def _edge_contact_message(contacts: list[dict[str, Any]]) -> str:return message-def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool, report_path: Path | None, spill: str = "small", reference: Path | None = None) -> dict[str, Any]:+def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool, report_path: Path | None, spill: str = "small", reference: Path | None = None, decontam: str = "off") -> dict[str, Any]:if spill not in SPILL_MODES:raise SystemExit(f"video-frames: unknown --spill {spill!r}; expected one of {', '.join(SPILL_MODES)}")if spill == "auto" and reference is None:raise SystemExit("video-frames: --spill auto needs --reference (the still the clip was made from)")+ if decontam not in DECONTAM_MODES:+ raise SystemExit(f"video-frames: unknown --decontam {decontam!r}; expected one of {', '.join(DECONTAM_MODES)}")clip = clip.expanduser().resolve()if not clip.is_file():raise SystemExit(f"video-frames: clip not found: {clip}")@@ -235,7 +271,7 @@ def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool,keyed_dir = out_dir / "keyed"decision = decide_spill(Path(reference).expanduser().resolve(), key) if spill == "auto" else {"mode": spill, "reason": "explicit"}files = extract(clip, raw_dir)- report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"])+ report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"], decontam=decontam)payload = {"kind": "sprite-gen-video-frames-report", "clip": str(clip), "out_dir": str(out_dir), "raw_dir": str(raw_dir), "keyed_dir": str(keyed_dir), "key": key, "spill": decision, **meta, **report}target = (report_path or (out_dir / "frames.report.json")).expanduser().resolve()atomic_write_text(target, json.dumps(payload, ensure_ascii=False, indent=2) + "\n")@@ -251,12 +287,14 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--report", type=Path, help="report JSON (default <out-dir>/frames.report.json)")parser.add_argument("--spill", choices=SPILL_MODES, default="small", help="small: correct only small key-tinted clusters (default); full: every key tint in the subject is spill; auto: decide from --reference")parser.add_argument("--reference", type=Path, help="the still the clip was made from (required by --spill auto)")+ parser.add_argument("--decontam", choices=DECONTAM_MODES, default="off", help="off: the matte as is (default); palette: re-explain key-tinted edges with the subject's own colours (one palette per clip, video fit)")def run(**kwargs: object) -> int:payload = run_frames(Path(str(kwargs["clip"])), Path(str(kwargs["out_dir"])), key=str(kwargs.get("key") or "auto"),allow_edge_contact=bool(kwargs.get("allow_edge_contact")), report_path=kwargs.get("report"), # type: ignore[arg-type]- spill=str(kwargs.get("spill") or "small"), reference=kwargs.get("reference")) # type: ignore[arg-type]+ spill=str(kwargs.get("spill") or "small"), reference=kwargs.get("reference"), # type: ignore[arg-type]+ decontam=str(kwargs.get("decontam") or "off"))summary = {k: payload[k] for k in ("clip", "keyed_dir", "fps", "frames", "alpha_zero_pct_min", "alpha_zero_pct_max", "edge_contacts", "spill", "report")}print(json.dumps(summary, ensure_ascii=False, indent=2))return 0