Skip to content

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

9.4 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Synthetic pixel oracles for periodic cropping and RGBA quilting. The join measure, `inspect_tile`,
is also `pixel-draw`'s G4 tile seam (below)."""

import json

import numpy as np
import pytest
from PIL import Image

from sprite_gen.background.tile import inspect_tile, make_tile


def pattern(period=16, height=13, repeats=4):
    y, x = np.indices((height, period))
    angle = 2 * np.pi * x / period
    pixels = np.stack((90 + 60 * np.sin(angle) + y,
                       120 + 40 * np.cos(angle) + y * 2,
                       80 + 30 * np.sin(angle + y / 3),
                       np.full_like(x, 255)), axis=-1).astype(np.uint8)
    return Image.fromarray(np.tile(pixels, (1, repeats, 1)))


def test_periodic_pattern_keeps_exact_detail_and_does_not_mutate_input():
    source = pattern()
    before = source.tobytes()
    tile, report = make_tile(source, 16, overlap=5)
    left, top, right, bottom = report["source_crop"]
    assert (right - left, bottom - top) == (21, 13)
    assert tile.size == (16, 13)
    assert tile.mode == "RGBA"
    assert tile.tobytes() == source.crop((left, top, left + 16, bottom)).tobytes()
    assert source.tobytes() == before
    assert report["status"] == "pass"
    assert report["requires_visual_review"] is True
    assert report["search"]["evaluated_candidates"] <= report["search"]["candidate_limit"]
    json.dumps(report, allow_nan=False)


def test_minimum_error_seam_follows_a_connected_curved_match():
    pixels = np.full((7, 15, 4), (20, 40, 60, 255), dtype=np.uint8)
    pixels[:, 10:, :3] = 200
    expected = [0, 1, 2, 3, 2, 1, 0]
    for row, col in enumerate(expected):
        pixels[row, 10 + col, :3] = (20, 40, 60)
    _, report = make_tile(Image.fromarray(pixels), 10, overlap=5)
    assert report["quilt_seam"]["positions"] == expected
    assert report["quilt_seam"]["mean_squared_error"] == 0


def test_bounded_search_includes_last_available_crop():
    pixels = np.random.default_rng(12).integers(0, 256, (11, 100, 4), dtype=np.uint8)
    pixels[..., 3] = 255
    pixels[:, 96:100] = pixels[:, 84:88]
    _, report = make_tile(Image.fromarray(pixels), 12, overlap=4)
    assert report["source_crop"] == [84, 0, 100, 11]
    assert report["search"]["evaluated_candidates"] <= 32
    assert report["quilt_seam"]["mean_squared_error"] == 0


@pytest.mark.parametrize("overlap", [1, 4])
def test_alpha_silhouettes_copy_whole_pixels_and_select_tail_at_zero(overlap):
    period = 8
    y, x = np.indices((9, period + overlap))
    alpha = np.where(y > (x * 3) % 7, 255, np.where(y == (x * 3) % 7, 97, 0))
    pixels = np.stack((x * 11, y * 21, (x + y) * 7, alpha), axis=-1).astype(np.uint8)
    source = Image.fromarray(pixels)
    tiled, report = make_tile(source, period, overlap=overlap)
    result = np.asarray(tiled)
    assert np.array_equal(result[:, 0], pixels[:, period])
    assert np.array_equal(result[:, overlap:], pixels[:, overlap:period])
    seam = np.asarray(report["quilt_seam"]["positions"])
    assert np.all(np.abs(np.diff(seam)) <= 1)
    for row, cut in enumerate(seam):
        assert np.array_equal(result[row, :cut + 1], pixels[row, period:period + cut + 1])
        assert np.array_equal(result[row, cut + 1:], pixels[row, cut + 1:period])
    if overlap > 1:
        assert np.array_equal(result[:, overlap - 1], pixels[:, overlap - 1])
    assert set(np.unique(result[..., 3])) <= {0, 97, 255}
    assert source.tobytes() == pixels.tobytes()


def test_y_axis_is_transposed_x_quilting_with_real_crop_coordinates():
    source = pattern(period=9, height=7, repeats=3)
    x_tile, x_report = make_tile(source, 9, overlap=3)
    vertical = source.transpose(Image.Transpose.TRANSPOSE)
    y_tile, y_report = make_tile(vertical, 9, axis="y", overlap=3)
    assert y_tile.tobytes() == x_tile.transpose(Image.Transpose.TRANSPOSE).tobytes()
    l, t, r, b = x_report["source_crop"]
    assert y_report["source_crop"] == [t, l, b, r]
    assert y_report["axis"] == "y"
    assert y_report["edge_color_difference"] == x_report["edge_color_difference"]
    assert inspect_tile(y_tile, "y")["edge_color_difference"] == x_report["edge_color_difference"]


@pytest.mark.parametrize("period,overlap,axis", [
    (0, 2, "x"), (5, 0, "x"), (5, 5, "x"), (19, 2, "x"),
    (5, 2, "z"), (5.5, 2, "x"), (True, 2, "x"),
])
def test_impossible_geometry_is_rejected(period, overlap, axis):
    with pytest.raises((ValueError, TypeError)):
        make_tile(Image.new("RGBA", (20, 10)), period, overlap=overlap, axis=axis)


def test_smallest_quilt_and_single_scanline_are_supported():
    source = Image.new("RGBA", (3, 1), (11, 22, 33, 97))
    tiled, report = make_tile(source, 2, overlap=1)
    assert tiled.size == (2, 1)
    assert tiled.tobytes() == source.crop((0, 0, 2, 1)).tobytes()
    assert report["quilt_seam"]["positions"] == [0]
    json.dumps(report, allow_nan=False)


def test_inspection_measures_real_color_edge_against_interior():
    ramp = np.zeros((40, 64, 4), dtype=np.uint8)
    ramp[..., :3] = np.arange(64, dtype=np.uint8)[None, :, None] * 3
    ramp[..., 3] = 255
    report = inspect_tile(Image.fromarray(ramp))
    assert report["edge_color_difference"]["mean"] == pytest.approx(189)
    assert report["interior_color_difference"]["mean"] == pytest.approx(3)
    assert report["edge_to_interior_color_ratio"] == pytest.approx(63)
    assert report["status"] == "needs-review"
    assert report["review_reasons"]


def test_inspection_ignores_invisible_rgb_but_detects_alpha_break():
    pixels = np.zeros((20, 40, 4), dtype=np.uint8)
    pixels[:, 0, :3] = 255
    hidden = inspect_tile(Image.fromarray(pixels))
    assert hidden["edge_color_difference"]["max"] == 0
    assert hidden["seam_alpha_mismatch"]["max"] == 0
    pixels[:, -1, 3] = 255
    broken = inspect_tile(Image.fromarray(pixels))
    assert broken["seam_alpha_mismatch"]["mean"] == 255
    assert broken["status"] == "needs-review"
    assert any("alpha" in reason for reason in broken["review_reasons"])


def test_low_error_wrap_does_not_hide_bad_internal_quilt_cut():
    pixels = np.zeros((20, 40, 4), dtype=np.uint8)
    pixels[..., 3] = 255
    pixels[..., :3] = np.arange(40, dtype=np.uint8)[None, :, None] * 6
    tiled, report = make_tile(Image.fromarray(pixels), 32, overlap=8)
    assert report["edge_color_difference"]["mean"] == pytest.approx(6)
    assert report["quilt_seam"]["color_difference"]["mean"] > 150
    assert report["status"] == "needs-review"
    assert any("quilt" in reason for reason in report["review_reasons"])
    assert inspect_tile(tiled)["edge_color_difference"] == report["edge_color_difference"]


def test_inspection_handles_one_pixel_and_rejects_empty_or_bad_axis():
    report = inspect_tile(Image.new("RGBA", (1, 1)))
    assert report["status"] == "needs-review"
    json.dumps(report, allow_nan=False)
    for image, axis in [(Image.new("RGBA", (0, 3)), "x"),
                        (Image.new("RGBA", (2, 2)), "diagonal")]:
        with pytest.raises(ValueError):
            inspect_tile(image, axis)


GRASS, INK = (78, 144, 56, 255), (40, 30, 46, 255)


@pytest.fixture
def tile_calls(monkeypatch):
    """Every call to the join measure: the image and axis it was asked about, and what it answered."""
    from sprite_gen.background import tile as tile_module

    real, seen = tile_module.inspect_tile, []

    def recording(image, axis="x"):
        seen.append((image.copy(), axis, real(image, axis)))
        return seen[-1][2]

    monkeypatch.setattr(tile_module, "inspect_tile", recording)
    return seen


def test_pixel_draw_g4_asks_it_of_each_frame_along_both_axes(tile_calls):
    """`pixel-draw`'s G4 tile seam is this measure, asked of a tile frame along x and along y; what it
    says needs review warns, in its words, and nothing fails."""
    from sprite_gen.gen import pixel_grid as pg
    from sprite_gen.gen.pixel_gates import evaluate

    seam = [[GRASS if x < 7 else INK for x in range(8)] for _ in range(8)]
    gates = evaluate({"tile": seam}, kind="tile", rule=pg.palette_rule("free"), walk_cycle=False)
    assert [axis for _, axis, _ in tile_calls] == ["x", "y"]
    assert all(image.tobytes() == pg.image_of(seam).tobytes() for image, _, _ in tile_calls)
    x_report, y_report = (report for _, _, report in tile_calls)
    assert x_report["status"] == "needs-review" and y_report["status"] == "pass"
    assert gates["ok"] and gates["G4"]["warn"] and gates["G4"]["needs_review"] == ["tile x"]
    assert gates["G4"]["frames"] == {"tile": {"x": x_report, "y": y_report}}
    assert gates["warnings"] == ["G4 tile seam (look at tiled-3x3.png): tile x: "
                                 "Wrap edge color difference exceeds interior variation."]


def test_pixel_draw_g4_says_what_it_answers(monkeypatch):
    """Answer that every join needs review: G4 warns of a tile that wraps cleanly, and still passes it."""
    from sprite_gen.background import tile as tile_module
    from sprite_gen.gen import pixel_grid as pg
    from sprite_gen.gen.pixel_gates import evaluate

    real = tile_module.inspect_tile
    monkeypatch.setattr(tile_module, "inspect_tile", lambda image, axis="x": {
        **real(image, axis), "status": "needs-review", "review_reasons": ["Said so."]})
    flat = [[GRASS] * 8 for _ in range(8)]
    gates = evaluate({"tile": flat}, kind="tile", rule=pg.palette_rule("free"), walk_cycle=False)
    assert gates["ok"] and gates["G4"]["needs_review"] == ["tile x", "tile y"]
    assert gates["warnings"] == ["G4 tile seam (look at tiled-3x3.png): tile x: Said so.; tile y: Said so."]