Skip to content

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

feat(gen): --layout-guide attaches a one-slot layout guide to a single image

Soohong Kim0d8f81031f6e
diff --git a/sprite_gen/gen/__init__.py b/sprite_gen/gen/__init__.py
index 743b126..16f8133 100644
--- a/sprite_gen/gen/__init__.py
+++ b/sprite_gen/gen/__init__.py
@@ -28,7 +28,7 @@ CLI:
[--ref REF.png ...] [--transparent [--alpha-mode auto|native|chroma]
[--chroma-key magenta|green]] [--white-check CHECK.png] [--model ID]
[--aspect-ratio 1:1] [--quality low|medium|high|xhigh|max|auto]
- [--resolution 1k|1.5k|2k]
+ [--resolution 1k|1.5k|2k] [--layout-guide]
[--report REPORT.json] [--keep-session]
"""
@@ -87,6 +87,52 @@ HARD_DEFAULT_PROVIDER = "codex"
EXPLICIT_ONLY_PROVIDERS = ("openai",)
_CODEX_PROBE_TIMEOUT_SECONDS = 15
+# `--layout-guide`: the one-slot form of the guide `prepare` draws for every row
+# (`draw_guide`, the same 9.4 % safe margin), attached after the caller's refs. A
+# single still drawn without it fills its frame top to bottom, and a tall subject
+# then has nothing above the head for an in-place motion to bob into.
+LAYOUT_GUIDE_LONG_EDGE = 1024
+LAYOUT_GUIDE_NAME = "layout-guide.png"
+LAYOUT_GUIDE_TEXT = (
+ "Layout: the last attached image is a layout guide, not part of the character. It shows the frame, "
+ "its inner safe area (the blue box) and the center line. Draw the whole character inside the inner "
+ "safe area, centered on the center line, with clear empty background between the top of the head "
+ "(hair, hats, ears and raised props included) and the top edge, and between the feet and the bottom "
+ "edge. Keep at least 10% of the image height as empty background above the highest point of the "
+ "character, and at least 5% below the feet. Do not reproduce the layout guide itself: no boxes, guide "
+ "lines, center marks, labels, guide colors or the guide's grey background may appear in the output."
+)
+
+
+def layout_guide_size(aspect_ratio: str | None) -> tuple[int, int]:
+ """The guide's pixels for the requested ratio, long edge {LAYOUT_GUIDE_LONG_EDGE}; square without one.
+
+ Only the proportions matter to the model, so the size is the ratio's own and not a
+ provider's output size (codex has none to ask for).
+ """
+ if aspect_ratio in (None, "", "auto"):
+ return LAYOUT_GUIDE_LONG_EDGE, LAYOUT_GUIDE_LONG_EDGE
+ try:
+ width_part, height_part = str(aspect_ratio).split(":")
+ width, height = float(width_part), float(height_part)
+ if width <= 0 or height <= 0:
+ raise ValueError
+ except ValueError as exc:
+ raise SystemExit(f"gen: --layout-guide cannot read aspect ratio {aspect_ratio!r}") from exc
+ scale = LAYOUT_GUIDE_LONG_EDGE / max(width, height)
+ return round(width * scale), round(height * scale)
+
+
+def draw_layout_guide(path: Path, aspect_ratio: str | None) -> dict[str, Any]:
+ """Draws the one-slot guide at `path` and answers its cell (size and safe margins)."""
+ # Imported here: `prepare` owns the row guide and pulls in the row machinery.
+ from .prepare import draw_guide, normalize_cell
+
+ width, height = layout_guide_size(aspect_ratio)
+ cell = normalize_cell({"width": width, "height": height}, width, None)
+ draw_guide(path, 1, cell)
+ return cell
+
def _make_provider(name: str, *, keep_session: bool):
if name == "codex":
@@ -258,6 +304,7 @@ def generate_image(
keep_session: bool = False,
workdir: Path | None = None,
decontam: str = "off",
+ layout_guide: bool = False,
) -> GenResult:
"""Generate one image and return a GenResult. Raises SystemExit on any failure."""
if decontam not in ("off", "auto", "palette"):
@@ -283,7 +330,9 @@ def generate_image(
strategy: str | None = None
strategy_source: str | None = None
if transparent:
- strategy, strategy_source = resolve_transparency_strategy(backend, alpha_mode, refs=refs)
+ # The layout guide is an attached image as much as a --ref is: the same step down applies.
+ attached_for_strategy = [*refs, Path(LAYOUT_GUIDE_NAME)] if layout_guide else refs
+ strategy, strategy_source = resolve_transparency_strategy(backend, alpha_mode, refs=attached_for_strategy)
if decontam == "palette" and strategy != TRANSPARENCY_CHROMA:
# before the provider is called: a paid generation must not end in this refusal
raise SystemExit(f"gen: --decontam removes a chroma key; this image would use {strategy} alpha "
@@ -301,10 +350,18 @@ def generate_image(
raw = workdir / "raw.png"
try:
+ guide_cell: dict[str, Any] | None = None
+ attached = list(refs)
+ if layout_guide:
+ guide = workdir / LAYOUT_GUIDE_NAME
+ guide_cell = draw_layout_guide(guide, aspect_ratio)
+ # Last, so "the last attached image" in the prompt is the guide whatever the caller attached.
+ attached.append(guide)
+ prompt += "\n\n" + LAYOUT_GUIDE_TEXT
request = GenRequest(
prompt=prompt,
raw=raw,
- refs=refs,
+ refs=attached,
model=model,
aspect_ratio=aspect_ratio,
quality=quality,
@@ -370,7 +427,8 @@ def generate_image(
alpha=alpha_stats,
chroma=chroma_stats,
extra={**run.extra, **({"trim_alpha": trim_stats} if trim_stats else {}),
- **({"facing": facing_report} if facing_report else {})},
+ **({"facing": facing_report} if facing_report else {}),
+ **({"layout_guide": guide_cell} if guide_cell else {})},
)
finally:
if owns_workdir:
@@ -420,6 +478,7 @@ def _run(args: argparse.Namespace) -> int:
keep_session=args.keep_session,
workdir=args.workdir,
decontam=str(getattr(args, "decontam", None) or "off"),
+ layout_guide=bool(getattr(args, "layout_guide", False)),
)
payload = result.to_dict()
# `provider` in the payload is always the backend that actually generated the
@@ -534,6 +593,15 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--facing", choices=(*facing_mod.FACINGS, "preserve"), default="preserve", help="with --ref: required direction; preserve (default) leaves prompt and pixels unchanged")
parser.add_argument("--facing-fix", choices=facing_mod.FIXES, default="none", help="with --ref and --facing: record only (none, default), or opt into mirror / one regen")
parser.add_argument("--trim-alpha", action="store_true", help="with --transparent: crop the published PNG to its opaque bbox so the bottom edge is the foot line (margins reported)")
+ parser.add_argument(
+ "--layout-guide",
+ action="store_true",
+ help=(
+ "attach a one-slot layout guide (frame, inner safe area at the row guide's 9.4 %% margin, "
+ "center line) after any --ref and ask for the whole subject inside the safe area, with room "
+ "above the head and below the feet; drawn for --aspect-ratio, square without one"
+ ),
+ )
parser.add_argument("--white-check", type=Path, help="write a white-composite check image")
parser.add_argument("--keep-session", action="store_true", help="codex: do not delete the rollout jsonl")
parser.add_argument("--report", type=Path, help="write the generation report JSON here")
diff --git a/tests/gen/test_layout_guide.py b/tests/gen/test_layout_guide.py
new file mode 100644
index 0000000..f2b2aac
--- /dev/null
+++ b/tests/gen/test_layout_guide.py
@@ -0,0 +1,108 @@
+# 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)
+
+
+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.
+ assert guide.getpixel((300, margin)) == SAFE_BLUE
+ assert guide.getpixel((margin, 512)) == 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)
+ assert report["extra"]["layout_guide"] == {
+ "shape": "square", "width": 1024, "height": 1024,
+ "safe_margin_x": margin, "safe_margin_y": margin, "size": 1024, "safe_margin": margin,
+ }
+ # 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")