Skip to content

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

4.4 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""팔레트 = 절단 후 후처리 전용 불변식 (maintainer 확정 2026-07-20, plan
sprite-gen/per-frame-pixel-grid).

팔레트(락 포함)는 격자 검출·절단에 어떤 영향도 주면 안 된다. 같은 raw 를
전혀 다른 팔레트로 두 번 추출하면 절단선(input_grids)·프레임 콘텐츠
bbox·논리 크기는 완전히 동일하고 색만 달라져야 한다.
"""

import json
import random
from pathlib import Path

from PIL import Image

import sprite_gen.frames.extract as extract_module

MAGENTA = (255, 0, 255)


def _logical_art(width, height, seed):
    rng = random.Random(seed)
    art = Image.new("RGB", (width, height), MAGENTA)
    for y in range(height):
        for x in range(width):
            if rng.random() < 0.55:
                art.putpixel((x, y), (rng.randrange(30, 220), rng.randrange(30, 220), rng.randrange(30, 220)))
    return art


def _strip(frames, seed, pitch=8, logical=(20, 36), gap=40):
    frame = _logical_art(*logical, seed=seed).resize(
        (logical[0] * pitch, logical[1] * pitch), Image.Resampling.NEAREST)
    strip = Image.new("RGB", (frame.width * frames + gap * (frames + 1), frame.height + gap * 2), MAGENTA)
    for i in range(frames):
        strip.paste(frame, (gap + i * (frame.width + gap), gap))
    return strip


def _build_run(root: Path) -> Path:
    run_dir = root / "run"
    (run_dir / "raw").mkdir(parents=True)
    _strip(2, seed=7).save(run_dir / "raw" / "walk.png")
    request = {
        "version": 1,
        "kind": "sprite-gen-request",
        "engine": "component-row",
        "character": {"id": "palettebot", "description": "palette invariant fixture", "base_image": None},
        "cell": {"shape": "square", "width": 96, "height": 96, "safe_margin_x": 8,
                 "safe_margin_y": 8, "size": 96, "safe_margin": 8},
        "chroma_key": {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255], "selection": "fallback"},
        "states": {"walk": {"frames": 2, "fps": 8, "loop": True, "action": "palette fixture"}},
        "fit": {"pixel_unfake": True, "logical_height": 48},
    }
    (run_dir / "sprite-request.json").write_text(
        json.dumps(request, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    return run_dir


def _manifest(run_dir: Path) -> dict:
    return json.loads((run_dir / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))


def _grid_and_geometry(run_dir: Path) -> tuple:
    row = _manifest(run_dir)["rows"][0]
    geometry = []
    for rel in row["files"]:
        with Image.open(run_dir / rel) as im:
            alpha = im.getchannel("A")
            geometry.append((im.size, alpha.getbbox(), alpha.tobytes()))
    return row.get("input_grids"), geometry


def test_palette_never_touches_the_grid(tmp_path: Path) -> None:
    # run A: 자동 팔레트 산출. run B: 추출 전에 괴상한 2색 팔레트를 핀으로 강제.
    run_a = _build_run(tmp_path / "a")
    run_b = _build_run(tmp_path / "b")
    extract_module.write_pinned_palette(run_b, [(255, 0, 0), (0, 0, 255)], "test-pin")

    assert extract_module.run(run_dir=run_a) == 0
    assert extract_module.run(run_dir=run_b) == 0

    grids_a, geometry_a = _grid_and_geometry(run_a)
    grids_b, geometry_b = _grid_and_geometry(run_b)

    # 절단선 자체가 팔레트와 무관해야 한다 (검출 경로에 팔레트 참조 금지)
    assert grids_a == grids_b
    # 프레임 논리 크기·콘텐츠 bbox·알파(형상)까지 동일 — 색만 다르다
    for (size_a, bbox_a, alpha_a), (size_b, bbox_b, alpha_b) in zip(geometry_a, geometry_b):
        assert size_a == size_b
        assert bbox_a == bbox_b
        assert alpha_a == alpha_b

    # 팔레트는 실제로 적용됐어야 한다 (불변식이 '팔레트 무시'로 위장 통과하면 안 됨):
    # 2색(순적/순청) 강제 런의 불투명 픽셀은 그 두 색조뿐이다 — outline 후처리가
    # 색을 어둡게 만들 수 있으므로(예: (96,0,0)) 채널 패턴으로 판정한다.
    row_b = _manifest(run_b)["rows"][0]
    seen = set()
    for rel in row_b["files"]:
        with Image.open(run_b / rel) as im:
            for r, g, b, a in im.convert("RGBA").getdata():
                if a:
                    seen.add((r, g, b))
    assert seen
    for r, g, b in seen:
        is_reddish = g == 0 and b == 0
        is_bluish = r == 0 and g == 0
        assert is_reddish or is_bluish, (r, g, b)