Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

refactor(chroma): the plate's key, video-frames' decontam modes and --alpha-mode choices, and a report's method read their declarations (MAGENTA, extract.AUTO/OFF/PALETTE, effect.ALPHA_MODES, CHROMA_YCBCR, TRANSPARENCY_NATIVE)

Soohong Kim220ba9569ded
diff --git a/sprite_gen/gen/chroma.py b/sprite_gen/gen/chroma.py
index fdb18cf..5b06c38 100644
--- a/sprite_gen/gen/chroma.py
+++ b/sprite_gen/gen/chroma.py
@@ -25,9 +25,11 @@ from PIL import Image
from sprite_gen._deps import np
from sprite_gen.frames import extract as extract_mod
from sprite_gen.frames.cutout import GREEN, KEY_TARGETS, MAGENTA
-from sprite_gen.frames.extract import remove_chroma_background_ycbcr
+from sprite_gen.frames.extract import CHROMA_YCBCR, remove_chroma_background_ycbcr
from sprite_gen.spec.runio import atomic_save_image
+from .base import TRANSPARENCY_NATIVE
+
KEYS: dict[str, dict[str, tuple[int, int, int]]] = {name: {"target": rgb} for name, rgb in KEY_TARGETS.items()}
@@ -250,7 +252,7 @@ def key_transparent(
stats: dict[str, Any] = {
"out": str(out_path),
"mode": "RGBA",
- "method": "ycbcr",
+ "method": CHROMA_YCBCR,
"size": f"{width}x{height}",
"key": key,
"keyed_pixels": keyed,
@@ -328,7 +330,7 @@ def verify_native_alpha(
stats: dict[str, Any] = {
"out": str(out_path),
"mode": "RGBA",
- "method": "native",
+ "method": TRANSPARENCY_NATIVE,
"size": f"{width}x{height}",
"alpha_zero_pct": alpha_zero_pct,
"partial_alpha_pct": round(partial / total * 100, 2) if total else 0.0,
diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.py
index e12371d..aee67ca 100644
--- a/sprite_gen/video/frames.py
+++ b/sprite_gen/video/frames.py
@@ -125,8 +125,8 @@ SPECK_APART = 0.1
# (olive on green), and the pass gives it the subject's colour back. Where it cannot run (a white
# key, a subject with no interior) the frames keep the matte's bytes and the report says why;
# brightness alpha has no key, so `auto` is off there.
-from sprite_gen.frames.extract import DECONTAM_MODES # noqa: E402 — the one declaration, under the name video-set reads
-DECONTAM_DEFAULT = "auto"
+from sprite_gen.frames.extract import AUTO, DECONTAM_MODES, OFF, PALETTE # noqa: E402 — the one declaration, under the name video-set reads
+DECONTAM_DEFAULT = AUTO
DECONTAM_FIT = "video"
DECONTAM_STAT_KEYS = ("changed_px", "refit_px", "tint_px", "recovered_px", "unexplained_px", "restored_px", "key_hue_capped_px",
"key_part_kept_px", "behind_kept_px", "held_px", "settled_px", "blending_px")
@@ -479,7 +479,7 @@ def key_frames(
from . import effect
if alpha_mode not in effect.ALPHA_MODES:
raise SystemExit(f"video-frames: unknown --alpha-mode {alpha_mode!r}")
- if alpha_mode == "brightness" and decontam == "palette":
+ if alpha_mode == "brightness" and decontam == PALETTE:
raise SystemExit("video-frames: brightness alpha does not use --decontam")
if alpha_mode == "chroma" and spill not in ("small", "full"):
raise SystemExit(f"video-frames: key_frames takes a resolved spill mode (small|full), got {spill!r}")
@@ -496,8 +496,8 @@ def key_frames(
shutil.rmtree(refused_dir(keyed_dir), ignore_errors=True)
work.rename(refused_dir(keyed_dir))
raise
- if alpha_mode == "brightness" and decontam == "auto":
- report["decontam"] = {"mode": "auto", "applied_frames": 0, "reason": BRIGHTNESS_NO_KEY}
+ if alpha_mode == "brightness" and decontam == AUTO:
+ report["decontam"] = {"mode": AUTO, "applied_frames": 0, "reason": BRIGHTNESS_NO_KEY}
shutil.rmtree(refused_dir(keyed_dir), ignore_errors=True)
work.rename(keyed_dir)
return report
@@ -533,7 +533,7 @@ def _key_chroma(raw_files: list[Path], keyed_dir: Path, *, key: str, check_edges
**({"edge_border": border} if policy == "border" else {}),
"rows": rows,
}
- if decontam != "off" and decontam_first is not None:
+ if decontam != OFF and decontam_first is not None:
report["decontam"] = {
"mode": decontam,
"fit": DECONTAM_FIT,
@@ -571,7 +571,7 @@ def _key_chroma(raw_files: list[Path], keyed_dir: Path, *, key: str, check_edges
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"), "specks": specks}
- if decontam != "off":
+ if decontam != OFF:
done = stats["decontam"]
if done.get("applied"):
if clip_palette is None:
@@ -643,7 +643,7 @@ def decontam_warning(decontam: dict[str, Any]) -> str | None:
or the guard kept the edge beside a small key-coloured part. None when there is nothing to look
at (the pass off, or brightness alpha)."""
mode = decontam.get("mode")
- if mode in (None, "off") or decontam.get("reason") == BRIGHTNESS_NO_KEY:
+ if mode in (None, OFF) or decontam.get("reason") == BRIGHTNESS_NO_KEY:
return None
if not decontam.get("applied_frames"):
return (f"decontam {mode} did not run ({decontam.get('reason')}): the frames are the matte's, "
@@ -702,7 +702,7 @@ def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool,
from . import effect
if alpha_mode not in effect.ALPHA_MODES:
raise SystemExit(f"video-frames: unknown --alpha-mode {alpha_mode!r}")
- if alpha_mode == "brightness" and decontam == "palette":
+ if alpha_mode == "brightness" and decontam == PALETTE:
raise SystemExit("video-frames: brightness alpha does not use --decontam")
if source_manifest is not None and reference is None:
raise SystemExit("video-frames: --source-manifest needs --reference (the source canvas)")
@@ -760,7 +760,8 @@ def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool,
def add_arguments(parser: argparse.ArgumentParser) -> None:
- parser.add_argument("--alpha-mode", choices=("chroma", "brightness"), default="chroma", help="chroma key (default), or emitted light on black: brightness alpha, unpremultiplied RGB, no speck/edge cleanup; dark smoke becomes faint")
+ from . import effect
+ parser.add_argument("--alpha-mode", choices=effect.ALPHA_MODES, default="chroma", help="chroma key (default), or emitted light on black: brightness alpha, unpremultiplied RGB, no speck/edge cleanup; dark smoke becomes faint")
parser.add_argument("--clip", required=True, type=Path, help="mp4 from `sprite-gen video`, or one made elsewhere from a `video-canvas` still (a video MCP such as ZCRE); an audio track and a cover image are left out")
parser.add_argument("--out-dir", required=True, type=Path, help="writes raw/ and keyed/ here; a refused run leaves keyed.refused/ and no keyed/")
parser.add_argument("--key", choices=("auto", "green", "magenta", "white"), default="auto", help="background key (auto reads the corners)")
diff --git a/sprite_gen/video/prop_plate.py b/sprite_gen/video/prop_plate.py
index 7c5ae7b..3638b3d 100644
--- a/sprite_gen/video/prop_plate.py
+++ b/sprite_gen/video/prop_plate.py
@@ -35,9 +35,9 @@ from typing import Any
from PIL import Image
from sprite_gen._deps import np
-from sprite_gen.frames.cutout import KEY_TARGETS
+from sprite_gen.frames.cutout import KEY_TARGETS, MAGENTA
-RGB = KEY_TARGETS["magenta"]
+RGB = KEY_TARGETS[MAGENTA]
HEIGHT = 0.49 # of the subject's height
WIDTH = 0.20
GAP = 0.84