Skip to content

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

14.7 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""AI 프레임 보간 — 한 상태의 두 프레임 사이 중간(in-between) 프레임을 만들어 테이크로 기록한다.

파이프라인 도크트린과의 관계: "AI 개입은 raw 생성 한 곳뿐" — 보간도 raw 단계의
AI 생성이다. 산출물은 최종 프레임이 아니라 **테이크 raw** (`raw/<state>.takes/<label>.png`
+ request `states.<state>.takes`) 로 기록되고, 논리 프레임은 언제나 기존 결정론
추출 경로(크로마 제거 → 컴포넌트 → 격자 스냅 → 팔레트)가 굽는다.

백엔드 = **생성형** (`sprite_gen.gen`: codex `image_gen` / grok Imagine, 기본 codex).
플로우 기반 VFI(RIFE)는 파기했다 (maintainer 확정 2026-07-17): 외형이 변하는 픽셀아트
보간에서 VFI 는 구조적으로 크로스페이드(블러 잔상)를 내고, 3-way 실측 비교
(hero down_action 팔스윙: codex/grok/RIFE)에서 생성형이 중간 포즈를 깨끗한
픽셀로 그려내 압승했다 — 근거 시트 `tween-3way-compare.png` (트레이 2026-07-17).

인증 전제 (GUI 버튼 포함): 생성은 항상 **서버 머신의 provider CLI** (`codex`/`grok`)
가 수행한다 — 브라우저·웹뷰에는 어떤 자격증명도 지나가지 않는다. 해당 CLI 가
이 머신에 설치·로그인(ChatGPT OAuth / xAI OAuth)되어 있어야 하며, 미인증이면
provider 가 요란하게 실패하고 그 메시지가 CLI/뷰 상태줄에 그대로 표면화된다.
설정 절차는 [`docs/gen.md`](../docs/gen.md), 보간 관점 가이드는
[`docs/frame-interpolation.md`](../docs/frame-interpolation.md).

사용:
    python3 scripts/interpolate_frames.py --run-dir <run> --state down_idle \
        --between 1 2 [--provider codex|grok] [--t 0.5] [--label blink_mid] [--extract]

- `--between A B`: 그 상태 primary 스트립의 프레임 인덱스 두 개 (추출된 컴포넌트 순서).
- `--provider`: 생성 백엔드 (기본 codex — 3-way 비교 승자).
- `--t`: 보간 시점 (기본 0.5 = 정중앙). 프롬프트의 포즈 배분 문구로 반영된다.
- `--label`: 테이크 라벨 (기본 `tween_<A>_<B>_t<t>`). 같은 라벨 재실행 = 같은 파일
  덮어쓰기 (멱등).
- `--extract`: 기록 후 **전체 배치** 재추출까지 수행. 부분 추출은 run-wide 팔레트가
  배치 구성에 따라 달라지므로(CHANGELOG v1.56.17 known limitation) 전체 배치만 지원.
"""

from __future__ import annotations

import argparse
import json
import shutil
import sys
import tempfile
from pathlib import Path
from typing import Any, Callable

from PIL import Image

from sprite_gen.frames.extract import (extract_component_images, register_row_frames,
                      remove_chroma_background_ycbcr, tighten_components)
from sprite_gen.gen.base import PROVIDER_CODEX, PROVIDER_GROK
from sprite_gen.spec.layout import raw_rel, take_raw_rel
from sprite_gen.spec.runio import load_request, write_request
from sprite_gen.util.console import utf8_streams

PROVIDERS = (PROVIDER_CODEX, PROVIDER_GROK)
# 보간 자기 기본값 — 3-way 실측 비교 승자 (docs/frame-interpolation.md). gen 의 HARD_DEFAULT_PROVIDER 와 따로 정한다.
DEFAULT_PROVIDER = PROVIDER_CODEX

# interpolator 시그니처: (img0 RGB, img1 RGB, t, prompt) -> mid RGB. 테스트는 스텁을 주입한다.
Interpolator = Callable[[Image.Image, Image.Image, float, str], Image.Image]


def gen_interpolator(provider: str = DEFAULT_PROVIDER) -> Interpolator:
    """생성형 in-between interpolator — 두 정합 프레임을 ref 로 물려 중간 포즈를 그리게 한다."""
    if provider not in PROVIDERS:
        raise SystemExit(f"unknown interpolation provider: {provider} (choose from {PROVIDERS})")
    from sprite_gen.gen import generate_image

    def run(img0: Image.Image, img1: Image.Image, t: float, prompt: str) -> Image.Image:
        workdir = Path(tempfile.mkdtemp(prefix="sprite-gen-tween-"))
        try:
            ref_a = workdir / "ref-a.png"
            ref_b = workdir / "ref-b.png"
            out = workdir / "mid.png"
            img0.save(ref_a)
            img1.save(ref_b)
            generate_image(provider, prompt, out, refs=[ref_a, ref_b])
            with Image.open(out) as image:
                return image.convert("RGB").copy()
        finally:
            shutil.rmtree(workdir, ignore_errors=True)

    return run


def tween_prompt(request: dict[str, Any], t: float) -> str:
    """보간 생성 프롬프트 — request 의 캐릭터/크로마 진실에서 결정론으로 조립한다."""
    character = str(request.get("character", {}).get("description") or "the same character")
    chroma = request["chroma_key"]
    if abs(t - 0.5) < 1e-9:
        blend = "the precise halfway in-between of A and B"
    else:
        nearer = "A" if t < 0.5 else "B"
        blend = (f"the in-between of A and B at t={t:g} on the A->B motion "
                 f"(closer to {nearer})")
    return (
        "Pixel art animation IN-BETWEEN frame task. Reference image 1 is frame A and "
        "reference image 2 is frame B of the same character's animation. "
        f"Draw exactly ONE full-body pose that is {blend}: limbs and body positioned "
        "between the two reference poses. "
        f"Character identity must match the references exactly ({character}). "
        "Same clean pixel-art style, same pixel block size, same scale, and same "
        "position in the canvas as the references. "
        f"Flat solid chroma {chroma['name']} {chroma['hex']} background filling the "
        "entire canvas. No shadows, no text, no labels, no frame borders, no arrows, "
        "no multiple panels — exactly one figure on the flat background."
    )


def aligned_pair_on_chroma(
    strip: Image.Image, frame_count: int, index_a: int, index_b: int,
    chroma_rgb: tuple[int, int, int],
) -> tuple[Image.Image, Image.Image]:
    """스트립에서 두 프레임 컴포넌트를 뽑아 상체 정합(register) 후 같은 캔버스에 앉힌다.

    정합이 핵심이다: 정적인 몸 픽셀이 두 ref 에서 같은 위치에 있어야 생성 모델이
    "움직인 부위만 다른 같은 그림 두 장" 으로 읽는다. 배경은 요청 크로마 단색 —
    생성 결과도 같은 배경을 유지하도록 프롬프트가 요구하고, 추출의 크로마 제거가
    그대로 처리한다."""
    cleaned = remove_chroma_background_ycbcr(strip, chroma_rgb)
    components = extract_component_images(cleaned, frame_count)
    if not components:
        raise SystemExit(f"could not extract {frame_count} components from the strip")
    for index in (index_a, index_b):
        if not 0 <= index < len(components):
            raise SystemExit(f"frame index {index} out of range 0..{len(components) - 1}")
    tight = tighten_components(components)
    pair = register_row_frames([tight[index_a], tight[index_b]])
    width, height = pair[0].size
    padded_w = (width + 31) // 32 * 32
    padded_h = (height + 31) // 32 * 32
    outputs = []
    for frame in pair:
        canvas = Image.new("RGBA", (padded_w, padded_h), chroma_rgb + (255,))
        canvas.alpha_composite(frame, ((padded_w - width) // 2, padded_h - height))
        outputs.append(canvas.convert("RGB"))
    return outputs[0], outputs[1]


def _chroma_content_bbox(image: Image.Image, chroma_rgb: tuple[int, int, int],
                         tolerance: int = 60) -> tuple[int, int, int, int] | None:
    """크로마 단색 배경 위 피사체의 bbox — 크로마와 충분히 다른 픽셀만 콘텐츠로 센다."""
    rgb = image.convert("RGB")
    pixels = rgb.load()
    mask = Image.new("L", rgb.size, 0)
    out = mask.load()
    cr, cg, cb = chroma_rgb
    for y in range(rgb.height):
        for x in range(rgb.width):
            r, g, b = pixels[x, y]
            if abs(r - cr) + abs(g - cg) + abs(b - cb) > tolerance:
                out[x, y] = 255
    return mask.getbbox()


def normalize_tween_scale(mid: Image.Image, img0: Image.Image, img1: Image.Image,
                          chroma_rgb: tuple[int, int, int]) -> Image.Image:
    """생성된 중간 프레임을 참조 쌍의 스케일에 맞춘다 (raw 단계 전처리, 결정론).

    RIFE 시절엔 입출력 캔버스가 같아 스케일이 보장됐지만, 생성형은 모델이 피사체를
    다른 크기로 그릴 수 있다 (회귀 2026-07-17: tween 이 32×58 로 나와 형제 28×48
    보다 14% 커짐 — 재생 시 프레임에서 캐릭터가 튐, maintainer 발견). 참조 두 장의 콘텐츠
    높이 평균을 목표로 중간 프레임의 콘텐츠 높이를 리스케일하고, 참조와 같은 크로마
    캔버스에 바닥 정렬로 다시 앉힌다. 이후의 픽셀 언페이크 추출이 격자를 다시 굽는다."""
    ref_boxes = [_chroma_content_bbox(im, chroma_rgb) for im in (img0, img1)]
    mid_box = _chroma_content_bbox(mid, chroma_rgb)
    if not all(ref_boxes) or not mid_box:
        raise SystemExit("tween scale normalization failed: could not find content on the chroma background")
    target_h = sum(b[3] - b[1] for b in ref_boxes) / 2.0
    mid_h = mid_box[3] - mid_box[1]
    factor = target_h / mid_h
    content = mid.convert("RGB").crop(mid_box)
    scaled = content.resize((max(1, round(content.width * factor)),
                             max(1, round(content.height * factor))),
                            Image.Resampling.LANCZOS)
    canvas = Image.new("RGB", img0.size, chroma_rgb)
    left = (canvas.width - scaled.width) // 2
    top = canvas.height - scaled.height - (img0.height - ref_boxes[0][3])  # 참조와 같은 바닥선
    canvas.paste(scaled, (left, max(0, top)))
    return canvas


def write_take(run_dir: Path, request: dict[str, Any], state: str, label: str,
               image: Image.Image) -> Path:
    """중간 프레임을 테이크 raw 로 기록하고 request 의 takes 선언을 갱신한다 (멱등).

    Isolation (2026-07-19): 생성 동안 다른 쓰기(다른 행 리롤/fps 수정)가 있었을 수
    있으므로, 시작 시점 request 객체가 아니라 publish_guard 안에서 fresh 재독으로만
    takes 를 갱신한다 — lost update 방지 (reroll.record_take 와 같은 계약)."""
    from sprite_gen.spec.runio import publish_guard

    rel = take_raw_rel(request, state, label)
    target = run_dir / rel
    target.parent.mkdir(parents=True, exist_ok=True)
    image.save(target)
    with publish_guard(run_dir):
        # 락 안 fresh 재독도 게이트 경유 — 이관 판정·두 키 hard fail 이 한 곳에만 있어야 한다
        # (게이트는 읽기만 한다).
        fresh = load_request(run_dir)
        takes = fresh["states"][state].setdefault("takes", [])
        entry = next((t for t in takes if t.get("label") == label), None)
        if entry is None:
            takes.append({"label": label, "frames": 1})
        else:
            entry["frames"] = 1
        # 쓰기도 게이트 경유 — 테이크 기록이 디스크 스키마를 바꾸지 않는다 (reroll 과 동일).
        write_request(run_dir, fresh)
    return target


def interpolate_between(run_dir: Path | str, state: str, index_a: int, index_b: int,
                        t: float = 0.5, label: str | None = None,
                        provider: str = DEFAULT_PROVIDER,
                        interpolator: Interpolator | None = None) -> Path:
    """두 프레임 사이 중간 프레임을 만들어 테이크로 기록한다. 반환 = 테이크 raw 경로."""
    run_dir = Path(run_dir)
    # 읽기는 게이트만 (`load_request`): raw 로 읽으면 은퇴 키 런에서 이관이 비껴간다 —
    # 리롤에서 실제로 났던 회귀와 같은 클래스다 (validator R1).
    request = load_request(run_dir)
    if state not in request.get("states", {}):
        raise SystemExit(f"unknown state: {state}")
    if not 0.0 < t < 1.0:
        raise SystemExit(f"t must be inside (0, 1): {t}")
    strip_path = run_dir / raw_rel(request, state)
    if not strip_path.is_file():
        raise SystemExit(f"raw strip missing: {strip_path}")
    chroma_rgb = tuple(request["chroma_key"]["rgb"])
    frame_count = int(request["states"][state]["frames"])
    strip = Image.open(strip_path).convert("RGBA")
    img0, img1 = aligned_pair_on_chroma(strip, frame_count, index_a, index_b, chroma_rgb)
    run = interpolator or gen_interpolator(provider)
    mid = run(img0, img1, t, tween_prompt(request, t))
    mid = normalize_tween_scale(mid, img0, img1, chroma_rgb)
    label = label or f"tween_{index_a}_{index_b}_t{t:g}".replace(".", "p")
    if "/" in label or label.startswith("."):
        raise SystemExit(f"take label must be filesystem-safe: {label!r}")
    target = write_take(run_dir, request, state, label, mid)
    print(f"[interpolate] take written: {target.relative_to(run_dir)} "
          f"(state={state}, frames {index_a}<->{index_b}, t={t})")
    return target


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--run-dir", required=True)
    parser.add_argument("--state", required=True)
    parser.add_argument("--between", nargs=2, type=int, required=True,
                        metavar=("FROM", "TO"), help="primary 스트립의 프레임 인덱스 두 개")
    parser.add_argument("--provider", choices=PROVIDERS, default=DEFAULT_PROVIDER,
                        help="생성 백엔드 (기본 codex — 3-way 실측 비교 승자)")
    parser.add_argument("--t", type=float, default=0.5, help="보간 시점 (0..1, 기본 0.5)")
    parser.add_argument("--label", default=None, help="테이크 라벨 (기본 tween_<A>_<B>_t<t>)")
    parser.add_argument("--extract", action="store_true",
                        help="기록 후 전체 배치 재추출까지 수행 (부분 추출은 팔레트 배치 결합 때문에 지원하지 않음)")
    return parser


def main(argv: list[str] | None = None) -> int:
    utf8_streams()
    args = _build_parser().parse_args(argv)
    interpolate_between(args.run_dir, args.state, args.between[0], args.between[1],
                        t=args.t, label=args.label, provider=args.provider)
    if args.extract:
        from sprite_gen.frames import extract as extract_module
        code = extract_module.run(run_dir=Path(args.run_dir))
        if code != 0:
            return code
        print("[interpolate] full-batch re-extraction done")
    else:
        # 인터프리터는 sys.executable 로 찍는다 — 이 힌트는 붙여넣어 바로 실행되는
        # 명령이고, 전역 `python3` 는 이 패키지의 의존(NumPy/Pillow)이 없는 다른
        # 인터프리터일 수 있다 (SKILL.md "실행 인터프리터" 게이트).
        print("[interpolate] next: re-extract the FULL batch so the shared palette stays "
              f"consistent -> {sys.executable} -m sprite_gen.frames.extract --run-dir {args.run_dir}")
    return 0


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