Skip to content

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

8.0 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Compose a QA-approved manual frame subset into a selected cycle.

This is for cases where generation produces a larger row, but motion QA finds
that only a human-selected subset is usable. The original extracted frame files
remain the source; this script writes a small selected-cycle manifest plus GIF
and contact-sheet previews.
"""

from __future__ import annotations

import argparse
import hashlib
import json
from pathlib import Path

from PIL import Image, ImageDraw

from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.curate.curation import CURATION_FILENAME, apply_pixel_edits, apply_transform, frame_variant, load_curation, pixel_snap_scale, source_frame_index, state_pixel_ops, state_plan
from sprite_gen.spec.layout import row_frame_rel, state_frame_total
from sprite_gen.frames.extract import require_frames_manifest
from sprite_gen.qa.preview import flatten
from sprite_gen.util.gif_utils import delay_ticks_to_duration_ms, save_clean_gif
from sprite_gen.spec.runio import read_guard, relative_posix, load_request
from sprite_gen.util.console import utf8_streams


def sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def parse_frames(value: str) -> list[int]:
    frames = [int(part.strip()) for part in value.split(",") if part.strip()]
    if not frames:
        raise argparse.ArgumentTypeError("at least one frame number is required")
    if any(frame <= 0 for frame in frames):
        raise argparse.ArgumentTypeError("frame numbers are 1-based and must be positive")
    return frames


def load_frame(
    run_dir: Path,
    row: dict,
    user_frame: int,
    transform: dict[str, float] | None = None,
    cell_size: tuple[int, int] | None = None,
    variant: str = "pixel",
    snap_scale: int | None = None,
    pixel_ops: dict | None = None,
) -> tuple[Path, Image.Image]:
    path = run_dir / row_frame_rel(row, user_frame - 1, variant)
    if not path.is_file():
        raise SystemExit(f"missing selected frame {user_frame}: {path}")
    image = apply_pixel_edits(Image.open(path).convert("RGBA"), pixel_ops)
    if transform and cell_size:
        image = apply_transform(image, transform, cell_size,
                                snap_scale=snap_scale if variant == "pixel" else None)
    return path, image


def contact_sheet(frames: list[tuple[int, Image.Image]], gap: int = 4, label_height: int = 24) -> Image.Image:
    cell_width = max(frame.width for _number, frame in frames)
    cell_height = max(frame.height for _number, frame in frames)
    width = len(frames) * cell_width + (len(frames) + 1) * gap
    height = cell_height + label_height + gap * 2
    sheet = Image.new("RGB", (width, height), (255, 255, 255))
    draw = ImageDraw.Draw(sheet)
    x = gap
    for number, frame in frames:
        draw.rectangle((x, gap, x + cell_width - 1, gap + label_height - 1), fill=(24, 24, 24))
        draw.text((x + 6, gap + 5), f"frame {number}", fill=(255, 255, 255))
        sheet.paste(flatten(frame), (x, gap + label_height))
        x += cell_width + gap
    return sheet


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--run-dir", required=True, type=Path)
    parser.add_argument("--state", required=True)
    parser.add_argument("--frames", type=parse_frames, help="1-based frame numbers, for example 2,3,4,5; defaults to curation.json selection")
    parser.add_argument("--name", required=True, help="output basename under qa/, without extension")
    parser.add_argument("--duration-ms", type=int, default=190)
    parser.add_argument("--delay-ticks", type=int, help="GIF delay in 1/100 second ticks; overrides --duration-ms")
    parser.add_argument("--note", default="")
    return parser


def _run(args: argparse.Namespace):

    run_dir = args.run_dir.expanduser().resolve()
    # Reader isolation: read manifest + request + curation + frames under one shared read_guard so
    # a concurrent publish swap never yields a mid-swap/partial read (runio.read_guard ↔ publish_guard).
    with read_guard(run_dir):
        return _run_guarded(args, run_dir)


def _run_guarded(args, run_dir):
    frames_manifest = require_frames_manifest(run_dir)  # fail loud if this generation's manifest is absent/corrupt
    rows_by_state = {row["state"]: row for row in frames_manifest.get("rows", [])}
    qa_dir = run_dir / "qa"
    qa_dir.mkdir(parents=True, exist_ok=True)

    request = load_request(run_dir)
    cell = request["cell"]
    cell_size = (
        int(cell.get("width", cell.get("size", 0))),
        int(cell.get("height", cell.get("size", 0))),
    )
    default_count = state_frame_total(request, args.state)
    curation = load_curation(run_dir)
    ordered, transforms = state_plan(curation, args.state, default_count)

    # explicit --frames (1-based) wins; otherwise use the curation.json selection.
    if args.frames is not None:
        user_frames = args.frames
    else:
        user_frames = [index + 1 for index in ordered]

    selected = [
        # 파일은 원본 프레임(복제 인스턴스면 소스)을 읽고, 변형/픽셀편집은 인스턴스 번호로 조회
        load_frame(run_dir, rows_by_state[args.state],
                   source_frame_index(curation, args.state, number - 1, default_count) + 1,
                   transforms.get(number - 1), cell_size,
                   frame_variant(curation, args.state), pixel_snap_scale(request),
                   state_pixel_ops(curation, args.state).get(number - 1))
        for number in user_frames
    ]
    frame_paths = [path for path, _image in selected]
    frames = [(number, image) for number, (_path, image) in zip(user_frames, selected)]

    duration_ms = delay_ticks_to_duration_ms(args.delay_ticks) if args.delay_ticks else max(1, args.duration_ms)
    gif_path = qa_dir / f"{args.name}.gif"
    save_clean_gif(
        [frame for _number, frame in frames],
        gif_path,
        duration_ms=duration_ms,
        loop=0,
    )

    contact_path = qa_dir / f"{args.name}-contact.png"
    contact_sheet(frames).save(contact_path)

    manifest = {
        "version": 1,
        "kind": "sprite-gen-selected-cycle",
        "run_dir": str(run_dir),
        "state": args.state,
        "name": args.name,
        "selected_user_frames": user_frames,
        "selected_zero_based_frames": [frame - 1 for frame in user_frames],
        "selection_source": "explicit-frames" if args.frames is not None else CURATION_FILENAME,
        "transforms_applied": {str(n - 1): transforms[n - 1] for n in user_frames if (n - 1) in transforms},
        "duration_ms": duration_ms,
        "delay_ticks": round(duration_ms / 10),
        "loop": True,
        "note": args.note,
        "outputs": {
            "gif": relative_posix(gif_path, run_dir),
            "contact": relative_posix(contact_path, run_dir),
        },
        "source_frames": [
            {
                "user_frame": user_frame,
                "zero_based_frame": user_frame - 1,
                "path": relative_posix(path, run_dir),
                "sha256": sha256(path),
            }
            for user_frame, path in zip(user_frames, frame_paths)
        ],
    }
    manifest_path = qa_dir / f"{args.name}.json"
    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")

    print(
        json.dumps(
            {
                "ok": True,
                "manifest": str(manifest_path),
                "gif": str(gif_path),
                "contact": str(contact_path),
            },
            ensure_ascii=False,
            indent=2,
        )
    )
    return 0



def run(**kwargs: object):
    return _run(namespace_from_kwargs(_build_parser(), kwargs))

def main() -> int:
    utf8_streams()
    parser = _build_parser()
    args = parser.parse_args()
    return _run(args)


if __name__ == "__main__":
    raise SystemExit(main())