Skip to content

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

Merge main (v2.7.0-v2.8.1) into plan/chroma-hair-decontamination

Soohong Kime342bb99f2c7
diff --cc CHANGELOG.md
index c8206b1,a6f677f..f23ef30
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -2,10 -2,24 +2,28 @@@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
- ## Unreleased (v2.7.0)
++## Unreleased (v2.9.0)
+
+- Add opt-in edge decontamination, `--decontam auto|palette` (request `chroma.decontam` for the row extractor and `inspect`). After the matte, each edge pixel is explained as a blend of the locally measured key background with one colour from a palette learned on the subject's own interior. The colour written is that palette colour at the pixel's observed luma, so thin hair strands and outlines come back in the subject's hue: not green, and not the orange that despill's channel gain produces. `palette` demands the pass and fails where it cannot run; `auto` runs it wherever it applies and records why it did not elsewhere. Available on `cutout`, `gen --transparent` (chroma keying), `video-frames` / `video-set` (video fit, one palette per clip) and the row extractor. Every default stays `off`, which returns existing output byte for byte. On a procedural ground-truth set, key contamination at the edge falls from 22.5 % to 0.07 % on stills and from 33 % to 11 % on H.264 frames; halo against the true composite shrinks on dark and white backgrounds, and strand recall rises from 84 % to 99 % (stills) and from 82 % to 91 % (frames). Method, guards and limits: [docs/chroma-alpha.md](docs/chroma-alpha.md).
+
+ ## v2.8.1 - Tight clips pass their own edge and corner checks
+
+ - `video-frames --allow-subject-edge-contact` fails only on a frame where the key alone reaches the edge. A frame where the subject touches the edge carries key-tinted pixels beside it (its antialiased fringe, or the key reflected on metal) and is accepted with them, the same reading a mixed contact already had in the refusal message. Before, a few such pixels failed a tight clip as leftover background.
+ - `video-loop` keeps its 8 transparent columns on both sides of every cell even when the subject reaches the frame's side edge, so no cell corner is the subject and the GIF/WebP corner check holds. A crop that stays inside the frame is unchanged.
+
+ ## v2.8.0 - Tight framing for a fixed body height
+
+ - `video-canvas --fit tight` frames a still with no room for the motion: it drops the empty rows above and below the subject (keeping headroom of 4 % of the subject's height), keeps the still's width, and pads to the nearest framing the video model returns (9:16, 1:1, 16:9). The subject is never scaled or cut. A long, low subject in a square still becomes a 16:9 frame it fills, so a `--body-height` target is reached at a low clip resolution by scaling down rather than up. A motion that leaves the frame is clipped. The default `--fit state` is unchanged, and the report now says which `fit` framed it.
+ - `video-frames --allow-subject-edge-contact` accepts the subject at the frame edge and still refuses leftover key background there. The report's `edge_policy` names the rule that applied.
+ - `video-set --fit tight` frames every item that way and lets its subject reach the edge. It refuses `--shape`, and a cached canvas framed with another fit is not reused.
+ - `--body-height` measures the standing height on the clip's first frame, the base still's pose that every clip starts from. The tallest grounded frame, used before, is an attack's windup with the weapon overhead, and scaling that to the target made the character smaller in its attack than in its walk. The strip sidecar records `body_ref`, `body_src_h` (the standing height as filmed) and `scale`, so a strip whose cells were upscaled says so. Without a target nothing changes.
+
+ ## v2.7.0 - Timed attack clips pinned to their start
+
+ - Attack clips are timed strikes pinned to their start. `MOTION_TEXT["attack"]` asks for the same attack twice, each a windup, one strike in front, a held impact pose and a recovery to the exact starting stance with approximate times, keeps what the subject holds in the hand nearest the viewer, and forbids turning. The attack template drops the "evenly paced" line, keeps what the subject holds inside the frame and asks for crisp frames. `video-set` asks attack clips for 4 s by default (other states keep 3 s; `--duration` still sets one length for all) and passes the canvas as `--last-frame`, so the clip ends where it began. The item report records the clip's `duration` and `last_frame`.
+ - `build_prompt(..., motion=...)` accepts a caller's own motion paragraph in place of the built-in state sentence, keeping the engine's frame, camera, background and design rules.
+ - `video-set --body-height N` passes one standing-height target to every state's loop (`video-loop --body-height`), so a character comes out the same size in every state even though states use differently shaped canvases.
+
## v2.6.0 - Automatic local gait selection and XY motion correction
- In `motion-auto`, an uncertain fine XY search-boundary match can emit the selected frames unchanged only after the existing rendered-cell seam gate and animation checks pass. Reports and the CLI expose the rejected measurement and unapplied correction. Other failures and explicit `motion` registration remain strict.
diff --cc sprite_gen/video/batch.py
index 26ee644,2c79476..1513b74
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@@ -104,7 -153,8 +153,9 @@@ def run_item
facing: str = "right",
facing_fix: str = "none",
prepare_side: Callable[[Path], tuple[Path, dict]] | None = None,
+ body_height: int | None = None,
+ fit: str = "state",
+ 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")
@@@ -182,12 -236,11 +237,13 @@@
if attempts[-1] != 0 or not clip.exists():
raise SystemExit(f"clip generation failed after {len(attempts)} attempt(s); see {item_dir / 'clip.log'}")
- # the default call keeps its pre-decontam signature, so a stand-in for run_frames still fits
- # a tight frame is clipped on purpose; leftover key background still fails
- 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, allow_subject_edge_contact=fit == "tight")
++ # a tight frame is clipped on purpose; leftover key background still fails. The default
++ # call keeps its pre-decontam signature, so a stand-in for run_frames still fits
+ extra = {} if decontam == "off" else {"decontam": decontam}
- 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, **extra)
++ 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, allow_subject_edge_contact=fit == "tight", **extra)
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)
+ 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, body_height=body_height)
result["loop"] = {"kind": lp["cycle"].get("kind", "periodic"), "cycle": lp["cycle"]["length"], "period": lp["cycle"]["period_global"], "cycle_ratio": round(lp["cycle"]["ratio"], 3), "seam_ratio": lp["resampled_seam_ratio"], "n_out": lp["n_out"], "drift_px": lp["strip"].get("drift_px", 0), "gif": lp["gif"]["file"], "webp": lp["webp"]["file"], "strip": lp["strip"]["path"]}
result["loop"]["review_recommended"] = lp["cycle"].get("review_recommended", False)
result["loop"]["half_period_guard"] = lp["cycle"].get("half_period_guard")
@@@ -234,7 -287,8 +290,9 @@@ def run_set
spill: str = "auto",
facing: str = "right",
facing_fix: str = "none",
+ body_height: int | None = None,
+ fit: str = "state",
+ 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")
@@@ -264,7 -320,7 +324,7 @@@
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, decontam=decontam): 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, body_height=body_height, fit=fit): 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, body_height=body_height, fit=fit, decontam=decontam): i for i, d, s in items}
for fut in as_completed(futures):
r = fut.result()
results.append(r)
@@@ -307,7 -363,8 +367,9 @@@ def add_arguments(parser: argparse.Argu
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("--fit", choices=canvas_mod.FITS, default="state", help="state: each state's room for the motion (default); tight: no room, the subject fills the frame and a motion that leaves it is clipped (use with --body-height at a low --resolution)")
+ parser.add_argument("--body-height", type=int, default=None, help="scale every state's loop so the standing height is this many px (video-loop --body-height): one value for the whole set keeps the character the same size across states")
+ 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")
@@@ -320,7 -377,7 +382,8 @@@ 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"),
+ body_height=(int(kwargs["body_height"]) if kwargs.get("body_height") else None), fit=str(kwargs.get("fit") or "state"),
+ decontam=str(kwargs.get("decontam") or "off"),
)
return 0 if not payload["failed"] else 1
diff --cc sprite_gen/video/frames.py
index 1213a57,838e00d..7e33b61
--- a/sprite_gen/video/frames.py
+++ b/sprite_gen/video/frames.py
@@@ -163,7 -162,7 +169,8 @@@ def key_frames
key: str = "auto",
check_edges: bool = True,
spill: str = "small",
+ allow_subject: bool = False,
+ 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}")
@@@ -217,23 -197,19 +224,32 @@@
"alpha_zero_pct_min": min(r["alpha_zero_pct"] for r in rows),
"alpha_zero_pct_max": max(r["alpha_zero_pct"] for r in rows),
"edge_contacts": contacts,
+ "edge_policy": "off" if not check_edges else ("subject-allowed" if allow_subject else "refuse"),
"rows": rows,
}
+ if decontam != "off" and decontam_first is not None:
+ report["decontam"] = {
+ "mode": decontam,
+ "fit": DECONTAM_FIT,
+ "palette_source": f"clip (learned on {decontam_first['frame']})",
+ "palette": decontam_first["palette"],
+ "palette_keyfree": decontam_first["palette_keyfree"],
+ "key_material_share": decontam_first["key_material_share"],
+ "applied_frames": decontam_applied,
+ "totals": decontam_totals,
+ }
+ else:
+ report["decontam"] = {"mode": decontam, "applied_frames": 0}
if contacts and check_edges:
- raise SystemExit(_edge_contact_message(contacts))
+ if not allow_subject:
+ raise SystemExit(_edge_contact_message(contacts))
+ # Only a frame where the key alone reaches the edge is leftover background. Where the
+ # subject touches it too, the key-tinted pixels beside it are its antialiased fringe or
+ # a reflection of the key on it (a silver armour on green) — the same reading
+ # `_edge_contact_message` gives a mixed contact.
+ residual = [c for c in contacts if c["residual"] > 0 and c["subject"] == 0]
+ if residual:
+ raise SystemExit(_residual_message(residual))
return report
@@@ -261,7 -246,7 +286,7 @@@ def _edge_contact_message(contacts: lis
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, decontam: str = "off") -> 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, allow_subject_edge_contact: bool = False) -> 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, allow_subject_edge_contact: bool = False, 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:
@@@ -277,7 -260,7 +302,7 @@@
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"], decontam=decontam)
- report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"], allow_subject=allow_subject_edge_contact)
++ report = key_frames(files, keyed_dir, key=key, check_edges=not allow_edge_contact, spill=decision["mode"], allow_subject=allow_subject_edge_contact, 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")
@@@ -300,8 -283,8 +326,9 @@@ 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]
- allow_subject_edge_contact=bool(kwargs.get("allow_subject_edge_contact")))
++ allow_subject_edge_contact=bool(kwargs.get("allow_subject_edge_contact")),
+ 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")}
+ summary = {k: payload[k] for k in ("clip", "keyed_dir", "fps", "frames", "alpha_zero_pct_min", "alpha_zero_pct_max", "edge_contacts", "edge_policy", "spill", "report")}
print(json.dumps(summary, ensure_ascii=False, indent=2))
return 0