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.0 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Compose component-row frames into a game atlas and runtime manifest."""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path
from typing import Any

from PIL import Image

from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.effects.breathe import anatomy_report, fit_breathe_pattern, phase_frame, resolve_anatomy
from sprite_gen.curate.curation import apply_pixel_edits, apply_transform, edit_index, frame_variant, load_curation, pixel_snap_scale, source_frame_index, state_breathe, state_pixel_ops, state_plan
from sprite_gen.spec.layout import row_frame_rel, state_frame_total
from sprite_gen.frames.extract import HEAL_HEALED, HEAL_NOTES, heal_run, require_frames_manifest
from sprite_gen.spec.runio import acquire_run_dir_lock, atomic_save_image, atomic_write_text, load_request
from sprite_gen.spec.subject import default_min_used_pixels
from sprite_gen.util.console import utf8_streams


def alpha_nonzero_count(image: Image.Image) -> int:
    return sum(image.getchannel("A").histogram()[1:])


def cell_geometry(cell: dict[str, Any]) -> tuple[int, int]:
    width = int(cell.get("width", cell.get("size", 0)))
    height = int(cell.get("height", cell.get("size", 0)))
    if width <= 0 or height <= 0:
        raise SystemExit("cell width/height must be positive in sprite-request.json")
    return width, height


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--run-dir", required=True, type=Path)
    parser.add_argument("--atlas", default="sprite-sheet-alpha.png")
    parser.add_argument("--manifest", default="manifest.json")
    parser.add_argument("--report", default="sprite-sheet-alpha.report.json")
    # None = derive from the request's subject + drawable cell geometry
    # (sprite_gen.spec.subject); the flag is an explicit override only.
    parser.add_argument("--min-used-pixels", type=int, default=None)
    return parser


def _run(args: argparse.Namespace):

    run_dir = args.run_dir.expanduser().resolve()
    # 소비 전 파생 캐시 자가치유 (실시간 계약): 합성이 굽는 것 = 항상 현재 엔진의
    # 프레임. heal 은 서브프로세스 추출로 락을 따로 잡으므로 compose 락 획득 전에.
    heal_report = heal_run(run_dir)
    for note in heal_report[HEAL_NOTES]:
        print(f"[heal] {note}", file=sys.stderr)
    if heal_report[HEAL_HEALED]:
        print(f"[heal] re-derived stale rows: {', '.join(heal_report[HEAL_HEALED])}", file=sys.stderr)
    acquire_run_dir_lock(run_dir, "compose_sprite_atlas")
    request = load_request(run_dir)
    if args.min_used_pixels is None:
        args.min_used_pixels = default_min_used_pixels(request)
    frames_manifest = require_frames_manifest(run_dir)  # fail loud if absent/corrupt/not-ok
    rows_by_state = {row["state"]: row for row in frames_manifest.get("rows", [])}

    states = list(request["states"])
    cell_width, cell_height = cell_geometry(request["cell"])
    cell_size = (cell_width, cell_height)

    # curation.json is an optional non-destructive sidecar. When absent, every
    # state uses all extracted frames in order with identity transform.
    curation = load_curation(run_dir)
    plans = {
        state: state_plan(curation, state, state_frame_total(request, state))
        for state in states
    }
    # 'plain' = pre-unfake twin (curator toggle off). Resolved per state
    # (per-row curator toggle > run-wide default). Fail loud when the twin is
    # missing — a plain bake must never silently fall back to pixel.
    variants = {state: frame_variant(curation, state) for state in states}
    # pixel-variant rows of a fit.pixel_unfake run re-snap curated transforms to the
    # logical grid (plain rows keep the smooth bake, `transform_cell` — they are not grid art).
    snap_scale = pixel_snap_scale(request)

    # 아틀라스 셀 재사용 (maintainer 승인 2026-07-16): 같은 (원본 프레임, 변형, 픽셀편집)으로
    # 구워지는 인스턴스는 칸 하나를 공유한다 — 프레임 복제·루프딜레이가 텍스처를
    # 늘리지 않는다. frame_layout.rows 의 rect 목록은 인스턴스(재생) 순서 그대로이고
    # 재사용 시 같은 rect 가 반복된다 (Aseprite JSON 과 동형 패턴 — 소비자는 지금처럼
    # 프레임 인덱스 → rect 샘플링만 하면 된다).
    def _instance_key(state: str, frame_index: int, phase: float = 0.0) -> tuple:
        source_index = source_frame_index(curation, state, frame_index, state_frame_total(request, state))
        edit_idx = edit_index(curation, state, frame_index)  # 링크 복제 = 원본 편집 truth (셀 공유)
        transform_key = json.dumps(plans[state][1].get(edit_idx), sort_keys=True)
        ops_key = json.dumps(state_pixel_ops(curation, state).get(edit_idx), sort_keys=True)
        return (source_index, transform_key, ops_key, phase)

    # 호흡 후처리 레이어 (사이드카, maintainer 확정 2026-07-18 루프-맞춤): 재생 위치 =
    # (프레임, 위상), 길이 = 기존 시퀀스 그대로 (루프 불변 — fit_breathe_pattern 이
    # breaths 회를 시퀀스에 딱 떨어지게 배분). 텍스처 칸은 유니크 (프레임×위상)만.
    #
    # 위상은 연속값이지만 **반복된다**: breaths 회가 시퀀스에 딱 떨어지므로 슬롯 i 와
    # i + seq_len/breaths 는 수학적으로 같은 위상이고, `fit_breathe_pattern` 이 정수
    # 나머지를 먼저 취해 그 둘을 비트 동일한 double 로 만든다. 그래서 칸 재사용이
    # 살아 있다 — 18슬롯 3호흡이면 유니크 칸 6개다. (분자를 정수로 접지 않으면 표현
    # 노이즈로 14칸이 되어 바이트 동일한 칸이 8개 중복 구워졌다, validator 검증 2026-07-25.)
    def _positions(state: str) -> list[tuple[int, float]]:
        ordered = plans[state][0]
        cfg = state_breathe(curation, state)
        if not cfg or not ordered:
            return [(i, 0.0) for i in ordered]
        pattern = fit_breathe_pattern(len(ordered), cfg)
        return [(ordered[i], pattern[i]) for i in range(len(ordered))]

    positions_by_state = {state: _positions(state) for state in states}
    breathe_by_state = {state: state_breathe(curation, state) for state in states}

    columns = max(
        max(1, len({_instance_key(state, i, ph) for i, ph in positions_by_state[state]}))
        for state in states
    )
    atlas = Image.new("RGBA", (columns * cell_width, len(states) * cell_height), (0, 0, 0, 0))
    frame_layout: dict[str, Any] = {
        "sheetWidth": atlas.width,
        "sheetHeight": atlas.height,
        "cellWidth": cell_width,
        "cellHeight": cell_height,
        "rows": {},
    }
    animation: dict[str, Any] = {
        "cellWidth": cell_width,
        "cellHeight": cell_height,
        "columns": columns,
        "rows": {},
    }
    errors: list[str] = []
    cells: list[dict[str, Any]] = []

    for row_index, state in enumerate(states):
        entry = request["states"][state]
        ordered, transforms = plans[state]
        positions = positions_by_state[state]
        breathe_cfg = breathe_by_state[state]
        variant = variants[state]
        frames = []
        row_source_frames: list[Image.Image] = []   # 호흡 적용 **직전** 프레임 (관측용)
        row_anatomy = None                          # 줄 전체가 공유하는 한 벌 (첫 프레임에서 확정)
        baked: dict[tuple, dict[str, Any]] = {}  # instance key -> shared rect
        for frame_index, breathe_phase in positions:
            key = _instance_key(state, frame_index, breathe_phase)
            reused = baked.get(key)
            if reused is not None:
                frames.append(reused)
                cells.append({"state": state, "frame": frame_index, "reuses": True, **reused})
                continue
            # 파일 위치의 SSoT 는 manifest row 의 files — 패턴 조립 금지 (택소노미/flat 공용).
            # 복제 인스턴스는 원본 프레임 파일을 읽는다 (변형/픽셀편집은 인스턴스 인덱스 소유).
            source_index = source_frame_index(curation, state, frame_index, state_frame_total(request, state))
            frame_path = run_dir / row_frame_rel(rows_by_state[state], source_index, variant)
            if not frame_path.is_file():
                errors.append(f"missing frame ({variant} variant): {frame_path}")
                continue
            edit_idx = edit_index(curation, state, frame_index)
            with Image.open(frame_path) as opened:
                source = apply_pixel_edits(opened.convert("RGBA"), state_pixel_ops(curation, state).get(edit_idx))
            if source.size != cell_size:
                errors.append(f"{frame_path} is {source.width}x{source.height}; expected {cell_width}x{cell_height}")
            # apply the human curation transform (identity when uncurated)
            frame = apply_transform(source, transforms.get(edit_idx), cell_size,
                                    snap_scale=snap_scale if variant == "pixel" else None)
            if breathe_cfg:
                row_source_frames.append(frame)
                if row_anatomy is None:
                    # 해부는 캐릭터 속성이라 줄 전체가 한 벌을 쓴다 — 프레임마다 다시 재면
                    # 경계가 흔들려 강체 구간이 프레임 간 같은 구간이 아니게 되고,
                    # 사이드카 한 벌로 그리는 프리뷰와도 갈린다 (validator 실측 2026-07-25).
                    row_anatomy = resolve_anatomy(frame, breathe_cfg)
                # 호흡 위상은 최종 셀 픽셀 위 결정론 봉투 워프 — 팔레트·격자 불변.
                # **위상 0 도 굽는다.** 구 분할선 방식에선 위상 0 이 항등이라 건너뛰어도
                # 됐지만 봉투에선 아니다: 진행파 지연(lag) 때문에 t=0 에서도 윗행은
                # wave(-lag*u) 만큼 변형된다. 건너뛰면 그 칸만 원본이 되어 아틀라스가
                # 매 루프 시작에서 튀고 GIF 굽기와 그림이 갈린다 (validator 검증 2026-07-25).
                frame = phase_frame(frame, breathe_cfg, breathe_phase, row_anatomy)
            nontransparent = alpha_nonzero_count(frame)
            if nontransparent < args.min_used_pixels:
                errors.append(f"{state} frame {frame_index} is too sparse ({nontransparent})")
            left = len(baked) * cell_width
            top = row_index * cell_height
            atlas.alpha_composite(frame, (left, top))
            rect = {"x": left, "y": top, "w": cell_width, "h": cell_height}
            baked[key] = rect
            frames.append(rect)
            cells.append({"state": state, "frame": frame_index, "nontransparent_pixels": nontransparent, **rect})

        frame_layout["rows"][state] = frames
        # durations_ms: 프레임별 표시 시간 계약 (지금은 fps 등간격 — 프레임별 편집
        # UI 가 생기면 여기만 비등간격으로 채워진다). 소비자는 이 배열이 있으면
        # fps 대신 이것을 따른다.
        duration_ms = max(1, round(1000.0 / (float(entry.get("fps", 6)) or 6.0)))
        animation["rows"][state] = {
            "row": row_index,
            "frames": len(positions),
            "fps": int(entry.get("fps", 6)),
            # 프레임별 지속시간은 프레임 복제가 담당한다 (maintainer 확정 2026-07-18 —
            # 복제는 아틀라스 셀 공유라 부하 0; per-frame duration 이중 진실 금지).
            # 전체 속도는 state fps 하나로 조정한다.
            "durations_ms": [duration_ms] * len(positions),
            "loop": bool(entry.get("loop", True)),
            "frame_variant": variant,
        }
        if breathe_cfg:
            # 자가 복구가 돌았는지, 프레임마다 경계가 달라졌는지 관측 (원칙 6).
            animation["rows"][state]["breathe"] = anatomy_report(row_source_frames, breathe_cfg) \
                if row_source_frames else None

    # top-level summary: uniform value when every row agrees, else 'mixed'
    # (per-row truth lives in animation.rows.<state>.frame_variant).
    unique_variants = set(variants.values())
    variant_summary = unique_variants.pop() if len(unique_variants) == 1 else "mixed"

    report = {
        "ok": not errors,
        "engine": "component-row",
        "curation_applied": curation is not None,
        "frame_variant": variant_summary,
        "errors": errors,
        "atlas": args.atlas,
        "manifest": args.manifest,
        "cell": request["cell"],
        "states": states,
        "cells": cells,
        "frame_layout": frame_layout,
    }

    report_path = run_dir / args.report
    atomic_write_text(report_path, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
    if errors:
        print(json.dumps({k: v for k, v in report.items() if k != "cells"}, ensure_ascii=False, indent=2))
        return 1

    atlas_path = run_dir / args.atlas
    atomic_save_image(atlas, atlas_path)
    manifest = {
        "characterId": request["character"]["id"],
        "engine": "component-row",
        "game_input": args.atlas,
        "degraded_static_fallback": False,
        "curation_applied": curation is not None,
        "frame_variant": variant_summary,
        "sprite_sheet_alpha": args.atlas,
        "sprite_sheet_alpha_report": args.report,
        "base_image": request["character"].get("base_image"),
        "cell": request["cell"],
        "chroma_key": request["chroma_key"],
        "animation": animation,
        "frame_layout": frame_layout,
    }
    atomic_write_text(run_dir / args.manifest, json.dumps(manifest, ensure_ascii=False, indent=2) + "\n")
    print(json.dumps({"ok": True, "atlas": str(atlas_path), "manifest": str(run_dir / args.manifest)}, 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())