Skip to content

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

15.9 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Pixel-perfect twins share the pp footprint + curated transforms re-snap to the grid.

1. plain/orig twins are fitted into the pixel-perfect frame's content bbox, so the
   curator's toggle compares pixel quality at the same size (no size jump).
2. apply_transform(snap_scale=s) re-quantizes a curated move/rotate onto the fixed
   logical grid — a pixel-variant bake can never produce off-grid smear.
"""

import json
import random

from PIL import Image

import sprite_gen.frames.extract as extract_module
from sprite_gen.curate.curation import apply_transform

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 _build_pp_run(root):
    """2-frame pixel-perfect fixture: logical art upscaled by an integer pitch."""
    run_dir = root / "run"
    (run_dir / "raw").mkdir(parents=True)
    pitch = 8
    frame = _logical_art(20, 36, seed=7).resize((20 * pitch, 36 * pitch), Image.Resampling.NEAREST)
    gap = 40
    strip = Image.new("RGB", (frame.width * 2 + gap * 3, frame.height + gap * 2), MAGENTA)
    strip.paste(frame, (gap, gap))
    strip.paste(frame, (frame.width + gap * 2, gap))
    strip.save(run_dir / "raw" / "walk.png")
    request = {
        "version": 1,
        "kind": "sprite-gen-request",
        "engine": "component-row",
        "character": {"id": "snapbot", "description": "pixel snap 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": "synthetic snap 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 _conform_request(run_dir, conform):
    """cell 48 (pp_scale=1, cap 42) + logical_height 30 < art's native 36 logical."""
    import json as _json
    request = _json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
    request["cell"] = {"shape": "square", "width": 48, "height": 48,
                      "safe_margin_x": 6, "safe_margin_y": 6, "size": 48, "safe_margin": 6}
    request["fit"]["logical_height"] = 30
    if conform is not None:
        request["fit"]["conform"] = conform
    (run_dir / "sprite-request.json").write_text(_json.dumps(request), encoding="utf-8")


def _walk_frame0_height(run_dir) -> int:
    im = Image.open(run_dir / "frames" / "walk" / "frame-0.png").convert("RGBA")
    bb = im.getchannel("A").getbbox()
    return bb[3] - bb[1]


def test_default_keeps_native_logical_size(tmp_path) -> None:
    """The output keeps the snapped native logical size (36) even though
    logical_height is 30 — only the physical cap (42) is enforced.

    There is no contract squeeze to opt into: `fit.conform` was removed
    (maintainer 2026-07-14/17) and declaring it now fails loudly — see
    `test_conform_flag_rejected` in this file."""
    run_dir = _build_pp_run(tmp_path)
    _conform_request(run_dir, conform=None)
    assert extract_module.run(run_dir=run_dir) == 0
    height = _walk_frame0_height(run_dir)
    assert height > 30, f"native size squeezed by default: {height}"
def _blocks_uniform(image: Image.Image, scale: int) -> bool:
    px = image.load()
    for by in range(image.height // scale):
        for bx in range(image.width // scale):
            first = px[bx * scale, by * scale]
            for dy in range(scale):
                for dx in range(scale):
                    if px[bx * scale + dx, by * scale + dy] != first:
                        return False
    return True


def test_apply_transform_snap_keeps_grid() -> None:
    """A fractional move + rotation on a 2px-block frame stays block-uniform when snapped."""
    scale = 2
    cell = (64, 64)
    frame = Image.new("RGBA", cell, (0, 0, 0, 0))
    art = _logical_art(20, 24, seed=3).convert("RGBA").resize((40, 48), Image.Resampling.NEAREST)
    frame.alpha_composite(art, (12, 10))
    assert _blocks_uniform(frame, scale)

    moved = apply_transform(frame, {"dx": 0.7, "dy": -1.3, "rotate": 9.0, "scale": 1.05}, cell, snap_scale=scale)
    assert moved.size == frame.size
    assert moved.getbbox() is not None
    assert _blocks_uniform(moved, scale), "snapped bake must stay on the logical grid"

    smeared = apply_transform(frame, {"dx": 0.7, "dy": -1.3, "rotate": 9.0, "scale": 1.05}, cell)
    assert not _blocks_uniform(smeared, scale), "unsnapped BICUBIC control should break blocks"


def test_twins_share_pixel_perfect_footprint(tmp_path) -> None:
    run_dir = _build_pp_run(tmp_path)
    assert extract_module.run(run_dir=run_dir) == 0

    manifest = json.loads((run_dir / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))
    row = manifest["rows"][0]
    assert row["ok"], row
    assert row.get("plain_files"), "pixel-perfect run must save plain twins"

    for index in range(2):
        pixel = Image.open(run_dir / "frames" / "walk" / f"frame-{index}.png").convert("RGBA")
        plain = Image.open(run_dir / "frames" / "walk" / f"frame-{index}.plain.png").convert("RGBA")
        pb = pixel.getchannel("A").getbbox()
        lb = plain.getchannel("A").getbbox()
        assert pb is not None and lb is not None
        # same footprint: identical box within grid-rounding tolerance (contain fit)
        for a, b in zip(pb, lb):
            assert abs(a - b) <= 2, f"frame {index}: pixel bbox {pb} vs plain bbox {lb}"

    # detected input grid (the actual cut lines) is recorded per frame, mapped into
    # cell coords: the lattice must cover the plain twin's content bbox.
    grids = row.get("input_grids")
    assert grids and len(grids) == 2
    for index, grid in enumerate(grids):
        assert grid and grid["x"] and grid["y"], f"frame {index}: missing input grid"
        plain = Image.open(run_dir / "frames" / "walk" / f"frame-{index}.plain.png").convert("RGBA")
        lb = plain.getchannel("A").getbbox()
        assert grid["x"][0] <= lb[0] + 2 and grid["x"][-1] >= lb[2] - 2
        assert grid["y"][0] <= lb[1] + 2 and grid["y"][-1] >= lb[3] - 2
        # ~one logical pixel per cut cell: line count tracks the sprite's logical size
        assert len(grid["x"]) - 1 >= 10 and len(grid["y"]) - 1 >= 20
        if row.get("orig_files"):
            orig = Image.open(run_dir / "frames" / "walk" / "orig" / f"frame-{index}.png").convert("RGBA")
            scale = orig.width // pixel.width
            assert scale >= 2
            ob = orig.getchannel("A").getbbox()
            # 관용치 2 논리픽셀 -> **1** 로 조인다 (실측 근거: 2026-07-25 계측 10조합에서 실제
            # 어긋남은 0.0 논리픽셀, plan sprite-gen/grid-record-exactness). 0 으로 두지 않는
            # 이유는 이 파일이 conform/native·물리캡 등 여러 fit 경로를 함께 돌려서다 — 정확
            # 일치 단정은 경로를 고정한 tests/test_grid_record_exactness.py 가 소유하고,
            # 여기는 그 경로들 전체의 회귀 안전망으로 1픽셀 여유만 남긴다.
            for a, b in zip(ob, tuple(v * scale for v in pb)):
                assert abs(a - b) <= scale, f"frame {index}: orig bbox {ob} vs pixel bbox x{scale}"


def test_partial_generation_view_tolerance(tmp_path) -> None:
    """부분 생성(일부 상태만 추출) 세대: 관찰자(뷰)는 allow_pending_states 로 통과,
    소비자 기본 게이트는 여전히 fail-loud."""
    import json as _json
    import pytest as _pytest
    from sprite_gen.frames.extract import load_consistent_frames_manifest
    run_dir = _build_pp_run(tmp_path)
    request = _json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
    request["states"]["walk2"] = dict(request["states"]["walk"])  # 아직 raw 없는 두 번째 상태
    (run_dir / "sprite-request.json").write_text(_json.dumps(request), encoding="utf-8")
    assert extract_module.run(run_dir=run_dir, states="walk") == 0
    manifest = load_consistent_frames_manifest(run_dir, allow_pending_states=True)
    assert [r["state"] for r in manifest["rows"]] == ["walk"]
    with _pytest.raises(SystemExit, match="incomplete generation"):
        load_consistent_frames_manifest(run_dir)


def test_apply_pixel_edits_sidecar() -> None:
    """픽셀 편집 사이드카: 칠하기/지우기 합성, 원본 불변, 손상 키 무시."""
    from sprite_gen.curate.curation import apply_pixel_edits
    frame = Image.new("RGBA", (8, 8), (10, 20, 30, 255))
    out = apply_pixel_edits(frame, {"1,1": "#ff0000", "2,2": None, "bad": "#000000", "99,0": "#000000"})
    assert out.getpixel((1, 1)) == (255, 0, 0, 255)
    assert out.getpixel((2, 2)) == (0, 0, 0, 0)
    assert out.getpixel((3, 3)) == (10, 20, 30, 255)
    assert frame.getpixel((1, 1)) == (10, 20, 30, 255)  # 원본 불변
    assert apply_pixel_edits(frame, None) is frame


def test_padded_component_no_ghost_bottom_row() -> None:
    """회귀 2026-07-14 회귀 (down_idle blink 발밑 1px 돌출, maintainer 발견).

    component_group_image 의 4px 투명 패딩 + 위상 추정 노이즈(참 lead 4 를 2.8 로
    측정 → _grid_edges 가 0 으로 스냅) 조합이 격자를 패딩만큼 위로 밀었다. 꼬리에
    자투리 셀이 생기고, 발바닥 블록의 쪼개진 하단 + 문턱 근처 알파(~134) 프린지가
    유령 픽셀로 응고해 최종 프레임 발밑에 1px 이 돌출했다. 스냅 전 알파 bbox 로
    조이면(tighten_components) 콘텐츠가 블록 정수배가 되어 격자가 등분으로 떨어진다.
    """
    pitch = 13.213
    blocks_w, blocks_h = 8, 6
    pad = 4
    solid_h = round(blocks_h * pitch) - 1  # 마지막 블록의 1px 은 프린지가 채운다 (회귀 기하)
    width = round(blocks_w * pitch)
    comp = Image.new("RGBA", (width + pad * 2, solid_h + 1 + pad * 2), (0, 0, 0, 0))
    for y in range(solid_h):
        for x in range(width):
            comp.putpixel((pad + x, pad + y), (60, 90, 180, 255))
    for x in range(width):  # 문턱(128) 살짝 위의 접지 프린지 — 육안으론 거의 안 보인다
        comp.putpixel((pad + x, pad + solid_h), (60, 90, 180, 134))

    noisy_phase = (2.8, 2.8)  # 참 lead=4 인데 lead-스냅 문턱(pitch/4=3.3) 아래로 측정된 회귀 값

    # 버그 경로 재현: 패딩째 스냅하면 유령 바닥 행이 응고한다 (테스트가 무는지 자기검증)
    buggy = extract_module.grid_snap_downscale(comp, (pitch, pitch), True, noisy_phase)
    assert buggy.getbbox()[3] > blocks_h

    tight = extract_module.tighten_components([comp])[0]
    assert tight.size == (width, solid_h + 1)
    fixed = extract_module.grid_snap_downscale(tight, (pitch, pitch), True, noisy_phase)
    bbox = fixed.getbbox()
    assert bbox[3] - bbox[1] == blocks_h, f"ghost row survived: {fixed.size} bbox={bbox}"


def test_fringe_does_not_inflate_grid() -> None:
    """회귀 2026-07-17 회귀 (synthetic_fixture_a pp 부스러기/디테일 뭉개짐, maintainer 발견).

    크로마 제거가 남긴 sub-128 AA 프린지가 any-alpha `getbbox()` 크롭에 포함되면
    격자 원점이 프린지 폭만큼 밀리고 `_grid_edges` 셀 개수 반올림이 한 칸 는다 —
    모든 셀이 참 블록을 빗겨 샘플링해 색이 섞이고, 실루엣 밖 부스러기 열이 응고한다.
    tighten_components 는 solid alpha bbox(α>=128) 로 조여 프린지를 격자 계산
    밖으로 밀어낸다 (grid_snap_downscale/binarize_alpha 와 동일 불투명 기준).
    """
    pitch = 12
    blocks_w, blocks_h = 12, 10
    lut = [(200, 60, 60), (60, 200, 60), (60, 60, 200), (220, 160, 40),
           (240, 230, 210), (90, 50, 20), (20, 20, 20), (120, 160, 220)]

    def block_color(bx: int, by: int) -> tuple[int, int, int]:
        return lut[(bx * 7 + by * 3) % len(lut)]

    solid_w, solid_h = blocks_w * pitch, blocks_h * pitch
    fringe_left, fringe_top = 7, 5
    comp = Image.new("RGBA", (fringe_left + solid_w, fringe_top + solid_h), (0, 0, 0, 0))
    for y in range(solid_h):
        for x in range(solid_w):
            comp.putpixel((fringe_left + x, fringe_top + y), block_color(x // pitch, y // pitch) + (255,))
    for y in range(comp.height):  # 남는 자리 전부 문턱 미만(α=90) 프린지
        for x in range(comp.width):
            if comp.getpixel((x, y))[3] == 0:
                comp.putpixel((x, y), (30, 30, 30, 90))

    def snap(image: Image.Image) -> Image.Image:
        grid, phase = extract_module.detect_pixel_grid(image)
        return extract_module.grid_snap_downscale(image, grid, True, phase)

    def exact(out: Image.Image) -> bool:
        return out.size == (blocks_w, blocks_h) and all(
            out.getpixel((bx, by))[:3] == block_color(bx, by)
            for by in range(blocks_h) for bx in range(blocks_w))

    # 버그 경로 재현: any-alpha bbox 크롭(프린지 포함)은 격자가 부푼다 (테스트가 무는지 자기검증)
    buggy = snap(comp.crop(comp.getbbox()))
    assert not exact(buggy), f"buggy path unexpectedly clean: {buggy.size}"

    tight = extract_module.tighten_components([comp])[0]
    assert tight.size == (solid_w, solid_h), f"tighten kept fringe: {tight.size}"
    fixed = snap(tight)
    assert exact(fixed), f"solid-bbox snap not exact: {fixed.size}"


def test_shared_palette_preserves_rare_saturated_color() -> None:
    """회귀 2026-07-17 회귀 (synthetic_fixture_a 금색 머리끈·목걸이 실종, maintainer 발견).

    run-wide 팔레트 기본 24 는 다상태 배치에서 희소 포인트 컬러를 굶겼다 —
    population median-cut 이 큰 색군들을 쫓느라 0.2% 금색 클러스터를 이웃 박스에
    흡수한다 (실측: hero 36상태 배치 24색에서 금색 최근접 ΔRGB 59, 48색 5.5).
    기본 48 상향의 회귀 가드: 뚜렷한 색군 30개 + 희소 금색에서 기본 크기가
    금색을 보존해야 한다.
    """
    frame = Image.new("RGBA", (128, 75), (0, 0, 0, 0))
    clusters = [((k * 53) % 200, (k * 97) % 200, (k * 151) % 200) for k in range(30)]
    i = 0
    for y in range(75):
        for x in range(128):
            c = clusters[min(29, (y // 15) * 6 + (x // 22))]
            j = (i * 31) % 17 - 8
            frame.putpixel((x, y), tuple(max(0, min(255, v + j)) for v in c) + (255,))
            i += 1
    gold = (240, 158, 45)
    for y in range(4):
        for x in range(4):
            frame.putpixel((x, y), gold + (255,))

    def nearest(palette: list, c: tuple) -> float:
        return min(((e[0] - c[0]) ** 2 + (e[1] - c[1]) ** 2 + (e[2] - c[2]) ** 2) ** 0.5 for e in palette)

    starved = extract_module.build_shared_palette([frame], 24)
    assert nearest(starved, gold) > 30, "starvation setup lost its bite — recalibrate the fixture"
    healthy = extract_module.build_shared_palette([frame], 48)
    assert nearest(healthy, gold) <= 8, f"default-size palette still starves gold: {nearest(healthy, gold):.1f}"


def test_conform_flag_rejected(tmp_path) -> None:
    """maintainer 확정 2026-07-14/17 회귀: fit.conform 은 제거됐다 — 선언되어 있으면 요란한 거부.

    옵트인 잔재는 제거된 결정(강제 눌림 금지)이 플래그 하나로 되살아나는 회귀
    경로였다 (회귀 2026-07-17: 높이 통일 시도가 이 플래그로 재발)."""
    import pytest as _pytest
    run_dir = _build_pp_run(tmp_path)
    request = json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
    request["fit"]["conform"] = True
    (run_dir / "sprite-request.json").write_text(json.dumps(request), encoding="utf-8")
    with _pytest.raises(SystemExit, match="fit.conform was removed"):
        extract_module.run(run_dir=run_dir)