Skip to content

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

5.6 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""`gen --layout-guide`: the one-slot form of the row layout guide on a single image.

A still drawn without it fills its frame top to bottom; the guide asks for the
row guide's safe padding around the whole subject. Offline, with a fake provider
that records what it was handed while the workdir still exists.
"""

from __future__ import annotations

import json
from pathlib import Path

import pytest
from PIL import Image

from sprite_gen import gen
from sprite_gen.gen import base as gen_base
from sprite_gen.gen.base import GenRequest
from sprite_gen.gen.prepare import DEFAULT_SAFE_MARGIN_RATIO

SAFE_BLUE = (0x2F, 0x80, 0xED)
CROWN_ORANGE = (0xFF, 0x7A, 0x00)
FLOOR_TEAL = (0x00, 0xA7, 0xA7)


class _RecordingProvider:
    name = "fake"
    transparency = gen_base.TRANSPARENCY_NATIVE

    def __init__(self) -> None:
        self.requests: list[GenRequest] = []
        self.attached: list[Image.Image] = []

    def generate(self, request: GenRequest, workdir: Path):
        self.requests.append(request)
        self.attached = [Image.open(ref).copy() for ref in request.refs]
        Image.new("RGBA", (8, 8), (0, 255, 0, 255)).save(request.raw)
        return gen_base.ProviderRun(provider=self.name, elapsed_seconds=0.1, model=request.model)


def _run(tmp_path: Path, monkeypatch, **overrides) -> tuple[_RecordingProvider, dict]:
    fake = _RecordingProvider()
    monkeypatch.setattr(gen, "_make_provider", lambda name, *, keep_session: fake)
    report = tmp_path / "report.json"
    kwargs = dict(provider="fake", prompt="a tall knight, full body", out=tmp_path / "still.png", report=report)
    kwargs.update(overrides)
    assert gen.run(**kwargs) == 0
    return fake, json.loads(report.read_text(encoding="utf-8"))


def test_attaches_a_one_slot_guide_with_the_row_margin_and_asks_for_room_around_the_subject(tmp_path, monkeypatch):
    fake, report = _run(tmp_path, monkeypatch, layout_guide=True, aspect_ratio="1:1")

    request = fake.requests[0]
    assert len(request.refs) == 1
    guide = fake.attached[0].convert("RGB")
    assert guide.size == (1024, 1024)
    margin = int(1024 * DEFAULT_SAFE_MARGIN_RATIO)
    # The inner safe box sits the row guide's margin in from every edge, on the guide's grey; the crown
    # and floor lines lie one more margin inside it, off its edges.
    assert guide.getpixel((margin, 512)) == SAFE_BLUE
    assert guide.getpixel((300, margin)) == SAFE_BLUE
    assert guide.getpixel((300, 2 * margin)) == CROWN_ORANGE
    assert guide.getpixel((300, 1023 - 2 * margin)) == FLOOR_TEAL
    assert guide.getpixel((300, 1023 - margin)) == SAFE_BLUE
    assert guide.getpixel((300, margin // 2)) == (0xF6, 0xF6, 0xF6)
    assert request.prompt.startswith("a tall knight, full body\n\n")
    assert request.prompt.endswith(gen.layout_guide_text(report["extra"]["layout_guide"]))
    assert report["extra"]["layout_guide"] == {
        "shape": "square", "width": 1024, "height": 1024,
        "safe_margin_x": margin, "safe_margin_y": margin, "size": 1024, "safe_margin": margin,
        "crown_y": 2 * margin, "floor_y": 1023 - 2 * margin,
    }
    # The lines' places in the words are the ones drawn: 192 / 1024 and 831 / 1024 of the frame.
    assert "top of the skull on the orange line, 19% of the frame height from the top" in request.prompt
    assert "lowest supporting sole on the teal line, 81% from the top" in request.prompt
    assert "span of 62% of the frame height" in request.prompt
    # The report's refs are the caller's; the guide is the report's own field.
    assert report["refs"] == []


def test_goes_after_the_callers_references_so_the_prompt_can_call_it_the_last(tmp_path, monkeypatch):
    upload = tmp_path / "upload.png"
    Image.new("RGB", (300, 500), (200, 30, 30)).save(upload)
    fake, report = _run(tmp_path, monkeypatch, layout_guide=True, ref=[upload])

    assert [image.size for image in fake.attached] == [(300, 500), (1024, 1024)]
    assert "the last attached image is a layout guide" in fake.requests[0].prompt
    assert report["refs"] == [str(upload.resolve())]


def test_takes_the_requested_ratio(tmp_path, monkeypatch):
    fake, report = _run(tmp_path, monkeypatch, layout_guide=True, aspect_ratio="9:16")

    assert fake.attached[0].size == (576, 1024)
    assert report["extra"]["layout_guide"]["safe_margin_x"] == int(576 * DEFAULT_SAFE_MARGIN_RATIO)
    assert report["extra"]["layout_guide"]["safe_margin_y"] == int(1024 * DEFAULT_SAFE_MARGIN_RATIO)


def test_changes_nothing_when_not_asked_for(tmp_path, monkeypatch):
    fake, report = _run(tmp_path, monkeypatch)

    assert fake.requests[0].refs == []
    assert fake.requests[0].prompt == "a tall knight, full body"
    assert "layout_guide" not in report.get("extra", {})


def test_counts_as_an_attached_image_for_transparency(tmp_path, monkeypatch):
    fake, report = _run(tmp_path, monkeypatch, layout_guide=True, transparent=True, chroma_key="green")

    assert fake.requests[0].native_alpha is False
    assert report["alpha"]["strategy"] == "chroma"
    assert report["alpha"]["strategy_source"] == "refs-attached"


def test_refuses_a_ratio_it_cannot_read(tmp_path, monkeypatch):
    with pytest.raises(SystemExit, match="cannot read aspect ratio"):
        _run(tmp_path, monkeypatch, layout_guide=True, aspect_ratio="tall")


def test_the_flag_alone_is_still_the_figure_guide():
    parser = gen._build_parser()
    assert parser.parse_args(["--out", "x.png", "--layout-guide"]).layout_guide == "figure"
    assert parser.parse_args(["--out", "x.png", "--layout-guide", "figure"]).layout_guide == "figure"
    assert parser.parse_args(["--out", "x.png"]).layout_guide is None