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(chroma): opt-in palette edge decontamination

Soohong Kim54e443473bd4
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 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.py
index 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 this
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.
"""
from sprite_gen.frames.extract import detect_background_key_rgb, remove_chroma_background
target = 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_fraction
if spill_min_tint is not None:
extra["spill_min_tint"] = spill_min_tint
if 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"), stats
def 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 chroma
engine'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 if
the key is unknown, the background cannot be located, or any transparent pixel
keeps 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 key
if 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 json
diff --git a/sprite_gen/frames/decontam.py b/sprite_gen/frames/decontam.py
new file mode 100644
index 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, stats
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.py
index 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.0
DEFAULT_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_distance
def 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 frozen
byte-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.size
data = 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 result
wins and the fallback is reported through `warnings` (observable, never
silent).
+
+ `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_mode
if effective_chroma != chroma_config:
request["chroma"] = effective_chroma
atomic_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.py
index 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: a
if args.spill_max_fraction is not None
else float(chroma_config.get("spill_max_fraction", 0.005))
)
+ decontam = args.decontam if args.decontam is not None else str(chroma_config.get("decontam", "off"))
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: a
args.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.py
index 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 1
diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.py
index 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 size
SPILL_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 → full
EDGE_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 None
spill_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.name
stats = 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.size
alpha_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