Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat: route terminal-pose states and accept end-frame canvases
Soohong Kim375e51663843
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex 0dbcacb..9bb1b1f 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -39,6 +39,7 @@ from sprite_gen.video import align as align_modfrom sprite_gen.video import body_plan as body_modfrom sprite_gen.video.body_plan import Bodyfrom sprite_gen.video import rife as rife_mod+from sprite_gen.video import nonloopSTART_GAP_SECONDS = 2.0# Clip length the batch asks the video model for. 3 s holds two or more cycles of every@@ -436,13 +437,17 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:validate_facing(facing)view = VIEW_TEXT.get(direction, f"seen from the {direction}").format(facing=facing)turned = facing if direction in handed_mod.LATERAL_VIEWS else None- if state in ACTION_TEXT_STATES:+ if state in nonloop.STATES:+ template = "2D game sprite animation. The character {motion} The character is {view}. " + nonloop.COMMON_TEXT+ elif state in ACTION_TEXT_STATES:template = ACTION_COMMON_TEXTelif (state in PINNED_LOOP_STATES or (state in GAIT_STATES and direction in PINNED_GAIT_VIEWS)) if pinned is None else pinned:template = PINNED_LOOP_TEXTelse:template = COMMON_TEXTstands_on = body_mod.text(body_plan)+ if state in nonloop.STATES and body_plan:+ stands_on = " ".join((b.figure + ": " if b.figure else "") + nonloop.ANATOMY_TEXT.get(b.plan, "") for b in body_plan).strip()stands_on = f" {stands_on}" if stands_on else ""if direction == "back" and state in GAIT_STATES and not body_mod.biped(body_plan):stands_on += f" {BACK_GAIT_TEXT_ANY_BODY['scene' if body_mod.scene(body_plan) else 'one']}"@@ -464,6 +469,7 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:built_in = (VIEW_MOTION_TEXT[(state, direction)].format(facing=facing) if (state, direction) in VIEW_MOTION_TEXTelse IDLE_TEXT_ANY_BODY if state == "idle" and not body_mod.biped(body_plan)else ATTACK_TEXT_ANY_BODY if state == "attack" and not body_mod.biped(body_plan)+ else nonloop.MOTION_TEXT[state] if state in nonloop.STATESelse MOTION_TEXT.get(state, f"performs the '{state}' action in place, repeating at an even rhythm."))text = template.format(motion=built_in + stands_on, view=view)text = ((text.replace("The character", character, 1) if character else text)@@ -655,7 +661,12 @@ def run_item(still_provider: str | None = None,handed: list[Handed] | None = None,body_plan: list[Body] | None = None,+ end_frame: Path | None = None,) -> dict[str, Any]:+ if end_frame is not None and state not in nonloop.STATES:+ raise SystemExit("video-set: --end-frame requires a non-loop state")+ if state in nonloop.STATES and (fit == "tight" or anchor != "none"):+ raise SystemExit("video-set: non-loop states need --fit state and --anchor none to preserve the terminal pose")if walk_start not in WALK_START_MODES:raise SystemExit(f"video-set: --walk-start must be one of {', '.join(WALK_START_MODES)}")if anchor == "motion-auto" and not loop_mod.profile_for(state).gait:@@ -739,9 +750,14 @@ def run_item(# would be a second retry loop on top of the first, each of its POSTs a request._staggered_start(gap)pin = {"last_frame": canvas_png} if pins_last_frame(state, direction) else {}+ if end_frame is not None:+ with Image.open(end_frame) as final, Image.open(canvas_png) as initial:+ if final.size != initial.size or canvas_mod.corner_key(final) != canvas_mod.corner_key(initial):+ raise SystemExit("video-set: end frame must match the start canvas size and background key")+ pin = {"last_frame": end_frame}attempts = [video_runner(canvas_png, prompt, clip, clip_report, duration=duration, resolution=resolution,log=item_dir / "clip.log", **pin)]- result["clip"] = {"attempts": attempts, "duration": duration, "last_frame": pins_last_frame(state, direction)}+ result["clip"] = {"attempts": attempts, "duration": duration, "last_frame": str(end_frame) if end_frame is not None else pins_last_frame(state, direction)}if attempts[-1] != 0 or not clip.exists():raise SystemExit(f"clip generation failed after {len(attempts)} attempt(s); see {item_dir / 'clip.log'}")@@ -752,7 +768,7 @@ def run_item(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, body_height=body_height,- cycle_mode="pinned" if state in PINNED_LOOP_STATES else "auto",+ cycle_mode="once" if state in nonloop.STATES else "pinned" if state in PINNED_LOOP_STATES else "auto",facing=facing if direction in handed_mod.LATERAL_VIEWS else "right")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)@@ -938,7 +954,7 @@ def write_table(results: list[dict[str, Any]], path: Path, *, both: bool = Falsestatus += " (jump not repaired: no RIFE)"# a cut whose steps are known is two of them; one the step screen suspects may be onecycle = f"{lp['cycle']}" + (f" ({lp['steps']} steps)" if lp.get("steps") else " (one step?)" if lp.get("step_screen") else "")- lines.append(f"| {_view_label(r, both)} | {r['state']} | {lp.get('kind', 'periodic')} | {cycle} | {lp['period'] if lp['period'] is not None else '-'} | {lp['seam_ratio']:.2f} | {lp['n_out']} | {status} |")+ lines.append(f"| {_view_label(r, both)} | {r['state']} | {lp.get('kind', 'periodic')} | {cycle} | {lp['period'] if lp['period'] is not None else '-'} | {format(lp['seam_ratio'], '.2f') if lp['seam_ratio'] is not None else '-'} | {lp['n_out']} | {status} |")else:lines.append(f"| {_view_label(r, both)} | {r['state']} | - | - | - | - | - | FAIL: {r.get('error', '')[:80]} |")text = "\n".join(lines) + "\n"@@ -976,6 +992,7 @@ def run_set(handed: list[Handed] | None = None,align_feet: dict[str, str] | None = None,body_plan: list[Body] | None = None,+ end_frames: dict[str, Path] | None = None,) -> dict[str, Any]:"""`bases` maps a view to its still; `facing` is right, left or `right,left` (`facings_of`), and a view filmedboth ways is keyed `view@right` and `view@left` (`resolve_bases`). `handed` (`handedness.parse`) puts each@@ -1004,6 +1021,12 @@ def run_set(raise SystemExit(f"video-set: base still for '{direction}' not found: {base}")# (item, direction, state, facing, base); a set filmed both ways names a lateral item's facingitems = [(f"{d}-{f}-{s}" if both and f else f"{d}-{s}", d, s, f or facings[0], b) for d, f, b in views for s in states]+ for item, path in (end_frames or {}).items():+ selected = [state for name, _, state, _, _ in items if name == item]+ if not selected or selected[0] not in nonloop.STATES or not path.is_file():+ raise SystemExit(f"video-set: --end-frame {item} needs a non-loop item and an existing image")+ if any(s in nonloop.STATES for s in states) and (fit == "tight" or anchor != "none"):+ raise SystemExit("video-set: non-loop states need --fit state and --anchor none")aligned_items = [i for i, _, s, _, _ in items if align_cycles == "auto" and loop_mod.profile_for(s).gaitand sum(1 for _, _, s2, _, _ in items if s2 == s) >= 2]for item, foot in (align_feet or {}).items():@@ -1027,7 +1050,7 @@ def run_set(return prepare_sidewith ThreadPoolExecutor(max_workers=max(1, concurrency)) as ex:- futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, 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=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan): i for i, d, s, f, b in items}+ futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, 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=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan, **({"end_frame": end_frames[i]} if end_frames and i in end_frames else {})): i for i, d, s, f, b in items}for fut in as_completed(futures):r = fut.result()results.append(r)@@ -1069,12 +1092,23 @@ def _parse_bases(values: list[str]) -> dict[str, Path]:return bases+def _parse_end_frames(values: list[str]) -> dict[str, Path]:+ result = {}+ for value in values:+ item, sep, path = value.partition("=")+ if not sep or not item or not path or item in result:+ raise SystemExit("video-set: --end-frame expects each ITEM=PATH once")+ result[item] = Path(path).expanduser().resolve()+ return result++def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--base", action="append", default=[], help="direction=still.png (repeatable: side=..., front=..., back=...); filmed facing right,left, a side or diagonal view takes one still per facing: side@right=..., side@left=...")parser.add_argument("--facing", default="right", help="which way the side and diagonal views face, for both prompt and canvas: right (default), left, or right,left to film each of them both ways from a still drawn each way (no mirroring); ignored for front/back")parser.add_argument("--facing-fix", choices=facing_mod.FIXES, default="none", help="side inputs: record only (none, default), or opt into mirror (refused with --handed)")parser.add_argument("--handed", action="append", default=[], metavar="ITEM=SIDE [PART]", help="an asymmetric item on one of the character's own sides, e.g. 'the black smartwatch=left wrist' (repeatable): every clip prompt says where it is in its view and that it stays there")parser.add_argument("--body-plan", action="append", default=[], metavar="PLAN | FIGURE=PLAN", help="what the character stands on: biped (default), quadruped or legless; a scene of several figures names each, e.g. 'the man=biped' 'the horse=quadruped' (repeatable): no prompt names a part the body lacks")+ parser.add_argument("--end-frame", action="append", default=[], metavar="ITEM=PATH", help="non-loop item: terminal-pose canvas with the same size and key as the starting canvas (repeatable)")parser.add_argument("--states", default="idle,walk,run,jump,attack", help="comma list of motion states")parser.add_argument("--out-dir", required=True, type=Path, help="batch root; one folder per direction-state")parser.add_argument("--character", help="short subject phrase used in the prompts (e.g. 'The armored knight')")@@ -1102,6 +1136,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:def run(**kwargs: object) -> int:payload = run_set(+ end_frames=_parse_end_frames(list(kwargs.get("end_frame") or [])),bases=_parse_bases(list(kwargs.get("base") or [])), # type: ignore[arg-type]states=[s.strip() for s in str(kwargs.get("states") or "").split(",") if s.strip()],root=Path(str(kwargs["out_dir"])), character=kwargs.get("character"), # type: ignore[arg-type]diff --git a/sprite_gen/video/canvas.py b/sprite_gen/video/canvas.pyindex 8cddfc8..141ef9e 100644--- a/sprite_gen/video/canvas.py+++ b/sprite_gen/video/canvas.py@@ -78,6 +78,12 @@ STATE_CANVAS: dict[str, CanvasProfile] = {"cheer": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.30, 0.0, "arms raised and spread leave a 1:1 frame"),"wave": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.30, 0.0, "a raised waving arm leaves a 1:1 frame"),"celebrate": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.0, 0.30, 0.0, "same envelope as cheer"),+ "death": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.1, 0.32, 0.32, "room for the death terminal pose"),+ "fall": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.1, 0.32, 0.32, "room for the fall terminal pose"),+ "land": CanvasProfile(SHAPE_TALL, 3 / 4, 0.34, 0.0, 0.0, "room for the land terminal pose"),+ "cast": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.25, 0.25, 0.25, "room for the cast terminal pose"),+ "hurt_hold": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.1, 0.32, 0.32, "room for the hurt_hold terminal pose"),+ "transform": CanvasProfile(SHAPE_WIDE, 16 / 9, 0.25, 0.25, 0.25, "room for the transform terminal pose"),"default": CanvasProfile(SHAPE_SQUARE, 1.0, 0.0, 0.0, 0.0, "in-place motion fits the still's own frame"),}# `--shape wide` is not the attack row. It is forced on a state whose own row isdiff --git a/sprite_gen/video/clip_prompt.py b/sprite_gen/video/clip_prompt.pyindex ecf1815..15b2724 100644--- a/sprite_gen/video/clip_prompt.py+++ b/sprite_gen/video/clip_prompt.py@@ -19,6 +19,7 @@ from __future__ import annotationsimport argparseimport jsonimport sys+from pathlib import Pathfrom typing import Anyfrom sprite_gen.gen.facing import FACINGS@@ -26,6 +27,7 @@ from sprite_gen.gen import handedness as handed_modfrom sprite_gen.gen.handedness import Handedfrom sprite_gen.video import batch as batch_modfrom sprite_gen.video import body_plan as body_mod+from sprite_gen.video import nonloopfrom sprite_gen.video.body_plan import BodyDEFAULT_MODEL = "grok-imagine-video-1.5"@@ -35,7 +37,7 @@ START_STILL_KEYS = ("green", "magenta")def plan_prompt(*, direction: str, state: str, facing: str = "right", character: str | None = None,motion: str | None = None, model: str = DEFAULT_MODEL, last_frame: bool = True,unpinned: bool = False, duration: int | None = None, key: str = "green",- handed: list[Handed] | None = None, body_plan: list[Body] | None = None) -> dict[str, Any]:+ handed: list[Handed] | None = None, body_plan: list[Body] | None = None, end_frame: Path | None = None) -> dict[str, Any]:"""The prompt `video-set` would send for (direction, state), and how its clip is to be cut. `handed`(`handedness.parse`) adds where each asymmetric item is in this view, as `video-set --handed` does;`body_plan` (`body_plan.parse_all`) what the subject stands on, as `video-set --body-plan` does."""@@ -45,6 +47,11 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:raise SystemExit(f"video-prompt: --key must be one of {', '.join(START_STILL_KEYS)}, got {key!r}")if unpinned and last_frame:raise SystemExit("video-prompt: --unpinned goes with --no-last-frame (a source that can pin the end frame films it pinned)")+ if end_frame is not None:+ if state not in nonloop.STATES:+ raise SystemExit("video-prompt: --end-frame requires a non-loop state")+ if not last_frame:+ raise SystemExit("video-prompt: this source cannot pin an end frame")wants_pin = batch_mod.pins_last_frame(state, direction)warnings: list[str] = []pinned: bool | None = None@@ -63,13 +70,13 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:prompt = parts.text# the caller's own words (--character, --motion) against the engine's: a conflict is a warningwarnings += [note["text"] for note in parts.notes if note["kind"] == "conflict"]- cycle = "pinned" if pins and state in batch_mod.PINNED_LOOP_STATES else "auto"+ cycle = "once" if state in nonloop.STATES else "pinned" if pins and state in batch_mod.PINNED_LOOP_STATES else "auto"# as video-set places and cuts: a side or diagonal view takes the facing, front and back face rightcanvas_facing = loop_facing = facing if direction in handed_mod.LATERAL_VIEWS else "right"mid_step = batch_mod.starts_mid_step(state, direction, body_plan)still = "<dir>/walk-start.png" if mid_step else "<still.png>"duration = batch_mod.duration_for(state, duration)- end = ", end frame <dir>/canvas.png" if pins else ""+ end = f", end frame {end_frame}" if end_frame is not None else ", end frame <dir>/canvas.png" if pins else ""record: dict[str, Any] = {"kind": "sprite-gen-video-prompt","direction": direction,@@ -80,7 +87,7 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:"model": model,"prompt": prompt,"duration": duration,- "last_frame": "canvas" if pins else None,+ "last_frame": str(end_frame) if end_frame is not None else "canvas" if pins else None,"cycle": cycle,"commands": {"canvas": f"sprite-gen video-canvas --still {still} --state {state} --facing {canvas_facing} --out <dir>/canvas.png --report <dir>/canvas.report.json",@@ -114,6 +121,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--motion", help="the caller's own motion paragraph in place of the state's sentence (build_prompt(motion=...))")parser.add_argument("--model", default=DEFAULT_MODEL, help=f"clip model the prompt is for (default {DEFAULT_MODEL}); a Lite model calms a walk")parser.add_argument("--duration", type=int, help="seconds to ask for (default: the state's own, as video-set)")+ parser.add_argument("--end-frame", type=Path, help="non-loop terminal-pose canvas to pin instead of returning to the starting image")parser.add_argument("--no-last-frame", action="store_true", help="the clip source cannot pin an end frame (ZCRE's grok-imagine-video-1.5): states filmed pinned are refused")parser.add_argument("--unpinned", action="store_true", help="with --no-last-frame: film a pinned state without the pin, with a warning, instead of refusing it")parser.add_argument("--key", choices=START_STILL_KEYS, default="green", help="the still's chroma key, for a front or back walk's mid-step redraw sentence (default green)")@@ -122,6 +130,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:def run(**kwargs: object) -> int:record = plan_prompt(+ end_frame=kwargs.get("end_frame"),direction=str(kwargs["direction"]), state=str(kwargs["state"]), facing=str(kwargs.get("facing") or "right"),character=kwargs.get("character"), motion=kwargs.get("motion"), # type: ignore[arg-type]model=str(kwargs.get("model") or DEFAULT_MODEL), last_frame=not kwargs.get("no_last_frame"),