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.9 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""동일색 런 최빈값 피치 추정기(perfectpixel unfake 이식)와 교차검증 경고를 고정한다.

detect_pixel_grid 는 정수 씨앗 ±0.75 창 안에서만 소수 피치를 정밀화하므로, 씨앗
로터리가 실패하면 참 피치가 창 밖에 놓여 조용히 틀린다 — 회귀 두 모드:

- y축 붕괴: 주인공 컴포넌트에서 y 피치가 x 값(29.52)으로 붕괴 (실측 30.56).
- 약수 오검출: 축별 소수 피치(29.5/30.6) 그림에서 두 축 모두 참값의 절반으로.

런 길이는 경계 히스토그램과 독립인 신호(경계 위치가 아니라 경계 사이 거리)라
세컨드 오피니언이 된다. 교차검증은 경고 전용 — 스냅 결과에 영향 0 을 여기서
비트 단위로 고정한다 (자동 교체 금지, No Silent Fallback).
"""
import json
import random

import pytest
from PIL import Image

import sprite_gen.frames.extract as extract_module
from sprite_gen.frames.extract import (
    crosscheck_pitch_runlen,
    detect_pixel_grid,
    estimate_pixel_grid_runlen,
)
from test_pitch_ground_truth import PALETTE, _logical_art

MAGENTA = (255, 0, 255)


def _upscale_axes(art: Image.Image, scale_x: float, scale_y: float) -> Image.Image:
    """축별 소수 배율 업스케일 — 비균등 리스케일된 AI 도트를 흉내낸다."""
    big = art.resize((art.width * 64, art.height * 64), Image.NEAREST)
    return big.resize((round(art.width * scale_x), round(art.height * scale_y)), Image.NEAREST)


def test_runlen_integer_pitch_is_exact():
    art = _logical_art(24, 40)
    for k in (8, 12, 16, 24):
        upscaled = art.resize((art.width * k, art.height * k), Image.NEAREST)
        estimate = estimate_pixel_grid_runlen(upscaled)
        assert abs(estimate[0] - k) < 0.01, f"k={k}: x={estimate[0]:.3f}"
        assert abs(estimate[1] - k) < 0.01, f"k={k}: y={estimate[1]:.3f}"


def test_runlen_recovers_fractional_per_axis_pitch():
    """소수 피치는 floor/ceil 런이 섞여 나오고, 그 가중 무게중심이 참값을 복원한다."""
    upscaled = _upscale_axes(_logical_art(24, 44), 29.5, 30.6)
    estimate = estimate_pixel_grid_runlen(upscaled)
    assert abs(estimate[0] - 29.5) < 0.2, f"x={estimate[0]:.3f}"
    assert abs(estimate[1] - 30.6) < 0.2, f"y={estimate[1]:.3f}"


def test_runlen_noise_is_inconclusive():
    """격자 없는 입력은 (1.0, 1.0) — 관측 가능하게 포기한다."""
    rng = random.Random(3)
    noise = Image.new("RGB", (200, 200))
    pixels = noise.load()
    for y in range(200):
        for x in range(200):
            pixels[x, y] = (rng.randrange(256), rng.randrange(256), rng.randrange(256))
    assert estimate_pixel_grid_runlen(noise) == (1.0, 1.0)


def test_runlen_small_image_is_inconclusive():
    art = _logical_art(24, 24).resize((24, 24), Image.NEAREST)
    assert estimate_pixel_grid_runlen(art) == (1.0, 1.0)


def test_crosscheck_quiet_when_estimators_agree():
    """detect 가 맞게 잡는 크기(블록 수 적음)에서는 경고 0 — 오경보 없음."""
    upscaled = _upscale_axes(_logical_art(18, 30), 29.5, 30.6)
    grid, _ = detect_pixel_grid(upscaled)
    assert abs(grid[0] - 29.5) < 0.4 and abs(grid[1] - 30.6) < 0.4, "전제: 검출 정상"
    assert crosscheck_pitch_runlen(grid, estimate_pixel_grid_runlen(upscaled)) == []


def test_crosscheck_quiet_on_integer_scales():
    art = _logical_art(24, 40)
    for k in (8, 12, 16, 24):
        upscaled = art.resize((art.width * k, art.height * k), Image.NEAREST)
        grid, _ = detect_pixel_grid(upscaled)
        notes = crosscheck_pitch_runlen(grid, estimate_pixel_grid_runlen(upscaled))
        assert notes == [], f"k={k}: {notes}"


def test_crosscheck_skips_unconfident_estimates():
    assert crosscheck_pitch_runlen((1.0, 1.0), (30.0, 30.0)) == []
    assert crosscheck_pitch_runlen((30.0, 30.0), (1.0, 1.0)) == []
    assert crosscheck_pitch_runlen((30.0, 31.0), (29.2, 30.4)) == []


def test_crosscheck_flags_divisor_misdetection():
    """약수 오검출 재현: 축별 소수 피치 29.5/30.6 에서 detect 가 두 축 다 절반으로.

    블록 수가 많아지면 어떤 정수 씨앗도 참 소수 피치의 ±0.75 창을 못 덮고, 정밀화가
    씨앗의 /2 약수 창에서 최대점을 찾는다. detect_pixel_grid 가 나중에 고쳐져 참값을
    잡게 되면 이 전제 assert 가 먼저 깨진다 — 그때는 픽스처를 더 어렵게 갱신할 것.
    """
    upscaled = _upscale_axes(_logical_art(20, 36, seed=11), 29.5, 30.6)
    grid, _ = detect_pixel_grid(upscaled)
    assert grid[0] < 20.0 and grid[1] < 20.0, f"전제: 약수 오검출 재현 (grid={grid})"

    runlen = estimate_pixel_grid_runlen(upscaled)
    assert abs(runlen[0] - 29.5) < 0.2 and abs(runlen[1] - 30.6) < 0.2

    notes = crosscheck_pitch_runlen(grid, runlen)
    divisor_notes = [note for note in notes if "divisor" in note]
    assert len(divisor_notes) == 2, notes
    assert any("x=" in note for note in divisor_notes)
    assert any("y=" in note for note in divisor_notes)


def test_crosscheck_flags_y_axis_collapse():
    """y축 붕괴 재현: x 는 정수 피치(29)라 씨앗이 잡지만, y 는 소수(30.3)+세로로 길어
    정수 씨앗이 전멸 → y 정밀화가 combined 씨앗(=x 값) 창에 갇혀 x 로 붕괴한다.
    회귀(주인공, y 29.52 vs 실측 30.56)와 같은 메커니즘.

    축차 3~4% 는 축별 규칙 임계 밑이라, AA 공통 바이어스가 상쇄되는 축비(y/x)
    규칙이 잡는다.
    """
    upscaled = _upscale_axes(_logical_art(28, 60, seed=5), 29.0, 30.3)
    grid, _ = detect_pixel_grid(upscaled)
    assert abs(grid[0] - 29.0) < 0.6, f"전제: x 정상 검출 (grid={grid})"
    assert abs(grid[1] - grid[0]) < 1.0 and abs(grid[1] - 30.3) > 0.4, (
        f"전제: y 가 x 로 붕괴 (grid={grid})"
    )

    runlen = estimate_pixel_grid_runlen(upscaled)
    assert abs(runlen[1] - 30.3) < 0.2, f"runlen y={runlen[1]:.3f}"

    notes = crosscheck_pitch_runlen(grid, runlen)
    assert any("axis ratio" in note for note in notes), notes


def _build_pixel_perfect_run(root):
    """crosscheck 가 발화하는 픽셀퍼펙트 런 디렉토리 (약수 오검출 픽스처 2프레임)."""
    run_dir = root / "run"
    (run_dir / "raw").mkdir(parents=True)
    frame = _upscale_axes(_logical_art(20, 36, seed=11), 29.5, 30.6)
    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": "crosscheckbot", "description": "runlen crosscheck 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 crosscheck fixture"}},
        "fit": {"pixel_unfake": True, "logical_height": 36},
    }
    (run_dir / "sprite-request.json").write_text(json.dumps(request, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    return run_dir


@pytest.mark.slow
def test_pipeline_reports_crosscheck_warning_without_touching_snap(tmp_path, monkeypatch, capsys):
    """통합 계약 두 가지를 한 픽스처로 고정한다.

    1. 오검출 런에서 crosscheck 경고가 report warnings 와 stderr 양쪽에 표면화된다.
    2. 경고 전용 — runlen 추정기를 중화(항상 확신 없음)해도 프레임이 비트 동일하다.
       스냅은 언제나 detect_pixel_grid 합의만 쓴다는 증명.
    """
    run_a = _build_pixel_perfect_run(tmp_path / "a")
    assert extract_module.run(run_dir=run_a) == 0
    captured = capsys.readouterr()
    manifest_a = json.loads((run_a / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))
    crosscheck_a = [w for w in manifest_a["warnings"] if "pitch crosscheck" in w]
    assert crosscheck_a, manifest_a["warnings"]
    assert "[pitch-crosscheck]" in captured.err

    monkeypatch.setattr(extract_module, "estimate_pixel_grid_runlen", lambda *args, **kwargs: (1.0, 1.0))
    run_b = _build_pixel_perfect_run(tmp_path / "b")
    assert extract_module.run(run_dir=run_b) == 0
    manifest_b = json.loads((run_b / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))
    assert [w for w in manifest_b["warnings"] if "pitch crosscheck" in w] == []

    frames_a = sorted((run_a / "frames").rglob("*.png"))
    frames_b = sorted((run_b / "frames").rglob("*.png"))
    assert frames_a and [f.relative_to(run_a) for f in frames_a] == [f.relative_to(run_b) for f in frames_b]
    for file_a, file_b in zip(frames_a, frames_b):
        assert file_a.read_bytes() == file_b.read_bytes(), f"{file_a.name} differs — crosscheck touched the snap"