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(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.py
index 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_TARGETS
from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.util.resample import resize_cell
from 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_specks
from sprite_gen.video.interpolation_quality import OUTLINE_WARN, SMEAR_WARN
from sprite_gen.video.playback import Playback, visible_bytes
from 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.py
index 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_role
from 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, MAGENTA
from sprite_gen.util.console import utf8_streams
from sprite_gen.util.hexcolor import format_hex
+UNPACK_SOURCE_KIND = "sprite-gen-unpack-source"
ALPHA_THRESHOLD = 16 # a pixel counts as content above this alpha
MIN_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[str
first_dir = groups[0]["paths"][0].parent
request = {
"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.py
index 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_rel
from sprite_gen.frames.cutout import GREEN, KEY_TARGETS, MAGENTA
from sprite_gen.frames.extract import color_distance
from 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_KIND
from sprite_gen.spec.subject import SUBJECTS
from sprite_gen.video import body_plan as body_mod
from 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.py
index 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.py
index 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_mod
from sprite_gen.video.interpolation_quality import CROSSFADE_LOOK, GHOST_WARN, SMEAR_WARN, OUTLINE_WARN, clean_beside, faults, ghost_screen, looks
from 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 frame
SOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop again
RATE_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.py
index 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 payload
diff --git a/sprite_gen/video/frames.py b/sprite_gen/video/frames.py
index 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" else
decide_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: