Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
refactor(kinds): a request's, a video-frames report's, a cycle-align report's and an unpack source's kind each take one name, and video-canvas writes prop_plate.CANVAS_REPORT, the kind it is read by
Soohong Kim127dfd9fa125
diff --git a/scripts/dev/source_restoration_demo.py b/scripts/dev/source_restoration_demo.pyindex d951ed6..8af29ee 100644--- a/scripts/dev/source_restoration_demo.py+++ b/scripts/dev/source_restoration_demo.py@@ -44,7 +44,7 @@ from sprite_gen.frames.cutout import GREEN, KEY_TARGETSfrom sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.util.resample import resize_cellfrom sprite_gen.video import loop-from sprite_gen.video.frames import drop_specks+from sprite_gen.video.frames import REPORT_KIND as FRAMES_REPORT_KIND, drop_specksfrom sprite_gen.video.interpolation_quality import OUTLINE_WARN, SMEAR_WARNfrom sprite_gen.video.playback import Playback, visible_bytesfrom sprite_gen.video.restoration import ARTIFACT_SUFFIXES@@ -182,7 +182,7 @@ def write_source(out: Path) -> dict[str, Path]:"-map_metadata", "-1", str(clip)], check=True)report = out / "source" / "frames.json"report.write_text(json.dumps({- "kind": "sprite-gen-video-frames-report", "fps": FPS, "frames": N, "width": SW, "height": SH,+ "kind": FRAMES_REPORT_KIND, "fps": FPS, "frames": N, "width": SW, "height": SH,"stream_index": 0, "key": GREEN,"note": "synthetic: the keyed frames are drawn by scripts/dev/source_restoration_demo.py, not keyed from the clip"},indent=2) + "\n")diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.pyindex b2b9d01..a2db123 100644--- a/sprite_gen/frames/unpack_atlas.py+++ b/sprite_gen/frames/unpack_atlas.py@@ -39,6 +39,7 @@ from sprite_gen.curate.curation import imported_ref_rolefrom sprite_gen.spec.runio import (LOCK_FILENAME,REQUEST_FILENAME,+ REQUEST_KIND,acquire_run_dir_lock,atomic_save_image,atomic_write_text,@@ -53,6 +54,7 @@ from sprite_gen.frames.cutout import KEY_TARGETS, MAGENTAfrom sprite_gen.util.console import utf8_streamsfrom sprite_gen.util.hexcolor import format_hex+UNPACK_SOURCE_KIND = "sprite-gen-unpack-source"ALPHA_THRESHOLD = 16 # a pixel counts as content above this alphaMIN_GUTTER = 1 # a fully-empty line of >= this many px separates frames@@ -248,7 +250,7 @@ def write_run(request = {"version": 1,- "kind": "sprite-gen-request",+ "kind": REQUEST_KIND,"engine": "component-row","character": {"id": run_dir.name, "description": f"unpacked from atlas ({layout_source})"},"cell": {"shape": "rect" if cell_w != cell_h else "square", "width": cell_w, "height": cell_h, "size": cell_w, "safe_margin": 0},@@ -262,7 +264,7 @@ def write_run()source_doc = {"version": 1,- "kind": "sprite-gen-unpack-source",+ "kind": UNPACK_SOURCE_KIND,"layout_source": layout_source,"cell": {"width": cell_w, "height": cell_h},**provenance,@@ -366,7 +368,7 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[strfirst_dir = groups[0]["paths"][0].parentrequest = {"version": 1,- "kind": "sprite-gen-request",+ "kind": REQUEST_KIND,"engine": "component-row","character": {"id": run_dir.name, "description": f"imported PNG set from {first_dir}"},"cell": {"shape": "square" if cell_w == cell_h else "rect", "width": cell_w, "height": cell_h, "size": cell_w, "safe_margin": 0},@@ -383,7 +385,7 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str)atomic_write_text(out_dir / "unpack-source.json",- json.dumps({"version": 1, "kind": "sprite-gen-unpack-source", "layout_source": "imported-pngs",+ json.dumps({"version": 1, "kind": UNPACK_SOURCE_KIND, "layout_source": "imported-pngs","cell": {"width": cell_w, "height": cell_h}, "source_dir": str(first_dir),"files": source_files, "labels": source_labels,"groups": [str(g["name"]) for g in groups],diff --git a/sprite_gen/gen/prepare.py b/sprite_gen/gen/prepare.pyindex acd52aa..b9aa059 100644--- a/sprite_gen/gen/prepare.py+++ b/sprite_gen/gen/prepare.py@@ -25,7 +25,7 @@ from sprite_gen.curate.anchor import anchor_ref_relfrom sprite_gen.frames.cutout import GREEN, KEY_TARGETS, MAGENTAfrom sprite_gen.frames.extract import color_distancefrom sprite_gen.spec.layout import TAXONOMY, guide_rel, prompt_rel, raw_rel-from sprite_gen.spec.runio import REQUEST_FILENAME+from sprite_gen.spec.runio import REQUEST_FILENAME, REQUEST_KINDfrom sprite_gen.spec.subject import SUBJECTSfrom sprite_gen.video import body_plan as body_modfrom sprite_gen.video.body_plan import Body@@ -1068,7 +1068,7 @@ def _run(args: argparse.Namespace):chroma_key = choose_chroma_key(base_dest, args.chroma_key)request = {"version": 1,- "kind": "sprite-gen-request",+ "kind": REQUEST_KIND,"engine": "component-row","character": {"id": args.character_id,diff --git a/sprite_gen/spec/runio.py b/sprite_gen/spec/runio.pyindex b166d2b..2c68fe7 100644--- a/sprite_gen/spec/runio.py+++ b/sprite_gen/spec/runio.py@@ -923,6 +923,7 @@ def atomic_write_set(payloads: "dict[Path, bytes | str]") -> None:# 하나면 스키마 이관을 걸 자리도 하나다 — 열여덟 곳에 같은 이관 코드를 흩뿌리면 그중 하나가# 빠진 날 조용히 두 진실이 생긴다.REQUEST_FILENAME = "sprite-request.json"+REQUEST_KIND = "sprite-gen-request"# 은퇴한 키 -> 현행 키. "pixel perfect" 는 광의 통용어(UI 정합·충돌판정)의 오용이었고, 이# 파이프라인이 실제로 하는 일의 정확한 명칭은 커뮤니티 속칭 "unfake"(unfake.js 유래)다diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex e69d67b..32e4d0d 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -112,6 +112,7 @@ from sprite_gen.video import rife as rife_modfrom sprite_gen.video.interpolation_quality import CROSSFADE_LOOK, GHOST_WARN, SMEAR_WARN, OUTLINE_WARN, clean_beside, faults, ghost_screen, looksfrom sprite_gen.util.console import utf8_streams+REPORT_KIND = "sprite-gen-video-cycle-align-report"SNAP = 0.03 # a sample time within this of a source frame takes that frameSOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop againRATE_TOLERANCE = 0.002 # frame rates read back from the strip metadata agree within this@@ -1312,7 +1313,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:" — or add --multi-cycle warn to align the set as it is (docs/loop-repair.md section 4)")if report_path is not None:loop_mod.write_loop_report(report_path.expanduser().resolve(), {- "kind": "sprite-gen-video-cycle-align-report", "applied": False, "refused": "cycle-suspects", "why": message, "command": command,+ "kind": REPORT_KIND, "applied": False, "refused": "cycle-suspects", "why": message, "command": command,"multi_cycle": multi_cycle, "lengths": [len(f) for f in sources], "fps": round(fps, 4), "suspects": suspects,"cycles_given": {str(loops[i][0]): k for i, k in given.items()}, "feet_given": {str(loops[i][0]): f for i, f in told.items()}})raise CycleSuspects(message, suspects, command)@@ -1403,7 +1404,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:+ ". Stopped before anything was rewritten (--same-foot refuse)")if report_path is not None:loop_mod.write_loop_report(report_path.expanduser().resolve(), {- "kind": "sprite-gen-video-cycle-align-report", "applied": False, "refused": RETAKE_FEET_REASON, "why": message,+ "kind": REPORT_KIND, "applied": False, "refused": RETAKE_FEET_REASON, "why": message,"same_foot": [{"dir": str(d), "name": meta_path.name[: -len(".strip.json")], **r["same_foot"]} for d, meta_path, r in twice],"lengths": [len(f) for f in sources], "fps": round(fps, 4)})raise SystemExit(message)@@ -1437,7 +1438,7 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:for r in rows if r["start_foot"] is None and r["view"] is not None]warnings += [f"{r['dir'] if shared else r['name']}: --foot says {r['foot_given'][0]} lands on its larger strike, its view's "f"{r['foot']['cue']} said {r['foot_disagrees'][0]}; started as given" for r in rows if r.get("foot_disagrees")]- report = {"kind": "sprite-gen-video-cycle-align-report", "applied": True, "length": target,+ report = {"kind": REPORT_KIND, "applied": True, "length": target,"length_rule": "requested" if length is not None else "median","between": between, "start_foot": start_foot, "retake": retakes, "warnings": warnings,"lengths": lengths, "multi_cycle": multi_cycle, "suspects": suspects, "unnamed_feet": unnamed,diff --git a/sprite_gen/video/canvas.py b/sprite_gen/video/canvas.pyindex 4291d6a..52b4ce0 100644--- a/sprite_gen/video/canvas.py+++ b/sprite_gen/video/canvas.py@@ -457,7 +457,7 @@ def run_canvas(tmp.replace(out)if state == "effect":report["end_frame"] = str(effect.empty_end(out, out.with_name(out.stem + ".end.png")))- payload = {"kind": "sprite-gen-video-canvas-report", "still": str(still), "out": str(out), "state": state, **report}+ payload = {"kind": plate_mod.CANVAS_REPORT, "still": str(still), "out": str(out), "state": state, **report}if report_path is not None:atomic_write_text(report_path.expanduser().resolve(), json.dumps(payload, ensure_ascii=False, indent=2) + "\n")return payloaddiff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.pyindex aee67ca..ea19dee 100644--- a/sprite_gen/video/frames.py+++ b/sprite_gen/video/frames.py@@ -131,6 +131,7 @@ 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")BRIGHTNESS_NO_KEY = "brightness alpha has no key colour to remove"+REPORT_KIND = "sprite-gen-video-frames-report"def _require(binary: str) -> str:@@ -734,7 +735,7 @@ def run_frames(clip: Path, out_dir: Path, *, key: str, allow_edge_contact: bool,decision = ({"mode": "off", "reason": "brightness alpha"} if alpha_mode == "brightness" elsedecide_spill(Path(reference).expanduser().resolve(), key) if spill == "auto" else {"mode": spill, "reason": "explicit"})files = extract(clip, raw_dir, meta["stream_index"])- head = {"kind": "sprite-gen-video-frames-report", "clip": str(clip), "out_dir": str(out_dir), "raw_dir": str(raw_dir)}+ head = {"kind": REPORT_KIND, "clip": str(clip), "out_dir": str(out_dir), "raw_dir": str(raw_dir)}try: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, alpha_mode=alpha_mode, plate=plate)except KeyingRefused as refused: