Skip to content

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

test: slice-sheet keeps a sheet's relative scale and fits each cut whole (red)

Soohong Kimef0420260a00
diff --git a/tests/frames/test_slice_sheet_scale.py b/tests/frames/test_slice_sheet_scale.py
new file mode 100644
index 0000000..163da1f
--- /dev/null
+++ b/tests/frames/test_slice_sheet_scale.py
@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`slice-sheet --scale sheet` keeps the sizes a sheet was drawn at, `--fit contain` keeps every cut whole
+on its canvas, and the report states the factor, each cell's size and where its subject stands
+(docs/sheet-slicing.md "Props and icons"). Synthetic sheets only: solid boxes of known sizes."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from sprite_gen import cli
+from sprite_gen.compose import game_pack
+from sprite_gen.frames import slice_sheet as slice_module
+from sprite_gen.frames.slice_sheet import slice_sheet
+
+MAGENTA = (255, 0, 255)
+INK = (40, 60, 90)
+PROP = (60, 90, 140, 250)
+
+
+def chroma_sheet(path: Path, boxes, cell: int = 100) -> Path:
+ """One row of square cells on magenta, a solid ``(w, h)`` box centred in each, standing 6 px above the cell bottom."""
+ sheet = np.zeros((cell, cell * len(boxes), 3), dtype=np.uint8)
+ sheet[...] = MAGENTA
+ for index, (w, h) in enumerate(boxes):
+ x0, bottom = index * cell + (cell - w) // 2, cell - 6
+ sheet[bottom - h:bottom, x0:x0 + w] = INK
+ Image.fromarray(sheet).save(path)
+ return path
+
+
+def transparent_sheet(path: Path, boxes, cell: int = 100, haze: bool = False) -> Path:
+ """The same boxes on a sheet that is already transparent; ``haze`` rings each with faint alpha 6 px wide."""
+ pixels = np.zeros((cell, cell * len(boxes), 4), dtype=np.uint8)
+ for index, (w, h) in enumerate(boxes):
+ x0, bottom = index * cell + (cell - w) // 2, cell - 10
+ pixels[bottom - h:bottom, x0:x0 + w] = PROP
+ if haze:
+ solid = pixels[..., 3] > 0
+ near = np.zeros_like(solid)
+ for dy in range(-6, 7):
+ for dx in range(-6, 7):
+ near |= np.roll(np.roll(solid, dy, 0), dx, 1)
+ pixels[near & ~solid] = (200, 200, 220, 20)
+ Image.fromarray(pixels).save(path)
+ return path
+
+
+def opaque_box(image) -> tuple[int, int, int, int]:
+ """``(x0, y0, x1, y1)``, right and bottom exclusive, of the pixels at least half opaque."""
+ if isinstance(image, Path):
+ with Image.open(image) as opened:
+ image = opened.convert("RGBA")
+ solid = np.asarray(image.convert("RGBA"))[..., 3] >= 128
+ rows, cols = np.flatnonzero(solid.any(axis=1)), np.flatnonzero(solid.any(axis=0))
+ return int(cols[0]), int(rows[0]), int(cols[-1]) + 1, int(rows[-1]) + 1
+
+
+def report(out: Path, prefix: str = "") -> dict:
+ return json.loads((out / f"{prefix}slice-sheet.json").read_text())
+
+
+def test_sheet_scale_keeps_the_drawn_heights_relative_and_the_default_still_evens_them(tmp_path):
+ boxes = [(30, 80), (30, 40), (24, 20)]
+ sheet = chroma_sheet(tmp_path / "props.png", boxes)
+ common = dict(grid=(3, 1), canvas=(128, 192), baseline_y=180.0, target_height=120.0)
+ kept = slice_sheet(sheet, tmp_path / "sheet", MAGENTA, scale="sheet", **common)
+ data = report(tmp_path / "sheet")
+ assert data["scale"] == "sheet" and data["fit"] == "none"
+ assert data["factor"] == pytest.approx(120 / 80)
+ assert data["factor_from"] == {"rule": "target_height", "cell": "cell-0"}
+ for path, (w, h), cell in zip(kept, boxes, data["cells"]):
+ x0, y0, x1, y1 = opaque_box(path)
+ assert abs((y1 - y0) - h * 1.5) <= 1, path.name
+ assert abs((x1 - x0) - w * 1.5) <= 1, path.name
+ assert abs(y1 - 180) <= 1, path.name
+ assert cell["factor"] == pytest.approx(1.5)
+ assert cell["subject"] == {"sheet": {"w": w, "h": h}, "canvas": {"w": round(w * 1.5), "h": round(h * 1.5)}}
+ assert cell["clipped_px"] == 0
+ # the default is unchanged: every cell's main subject reaches the target height on its own factor
+ evened = slice_sheet(sheet, tmp_path / "cell", MAGENTA, **common)
+ data = report(tmp_path / "cell")
+ assert data["scale"] == "cell" and data["fit"] == "none"
+ assert data["factor"] is None and data["factor_from"] is None
+ for path, (w, h), cell in zip(evened, boxes, data["cells"]):
+ x0, y0, x1, y1 = opaque_box(path)
+ assert (y1 - y0) == 120, path.name
+ assert cell["factor"] == pytest.approx(120 / h) and cell["factor_from"] == "target_height"
+ explicit = slice_sheet(sheet, tmp_path / "explicit", MAGENTA, scale="cell", fit="none", **common)
+ assert [p.read_bytes() for p in explicit] == [p.read_bytes() for p in evened]
+
+
+def test_contain_keeps_a_two_to_one_subject_whole_on_a_square_canvas(tmp_path):
+ boxes = [(80, 40), (30, 60)]
+ sheet = chroma_sheet(tmp_path / "icons.png", boxes)
+ common = dict(grid=(2, 1), canvas=(96, 96), baseline_y=92.0, target_height=80.0)
+ slice_sheet(sheet, tmp_path / "none", MAGENTA, **common)
+ cut = report(tmp_path / "none")["cells"][0]
+ # the default scales the wide subject to 160 x 80 on a 96 px canvas: it still cuts it, and now says so
+ assert cut["clipped_px"] > 0 and cut["box"]["w"] > 96
+ whole = slice_sheet(sheet, tmp_path / "contain", MAGENTA, fit="contain", **common)
+ data = report(tmp_path / "contain")
+ assert data["fit"] == "contain"
+ wide, tall = data["cells"]
+ assert wide["clipped_px"] == tall["clipped_px"] == 0
+ assert wide["factor_from"] == "fit" and tall["factor_from"] == "target_height"
+ factor = wide["factor"]
+ assert factor < 80 / 40
+ x0, y0, x1, y1 = opaque_box(whole[0])
+ assert abs((x1 - x0) - 80 * factor) <= 1 and abs((y1 - y0) - 40 * factor) <= 1
+ assert x0 >= 0 and x1 <= 96 and abs(y1 - 92) <= 1
+ box = wide["box"]
+ assert box["x"] >= 0 and box["y"] >= 0 and box["x"] + box["w"] <= 96 and box["y"] + box["h"] <= 96
+ # a subject that fits keeps the height rule
+ x0, y0, x1, y1 = opaque_box(whole[1])
+ assert (y1 - y0) == 80 and tall["factor"] == pytest.approx(80 / 60)
+
+
+def test_sheet_scale_with_contain_takes_the_one_factor_every_cut_fits(tmp_path):
+ boxes = [(30, 80), (30, 20), (90, 30)]
+ sheet = chroma_sheet(tmp_path / "props.png", boxes)
+ written = slice_sheet(sheet, tmp_path / "out", MAGENTA, grid=(3, 1), canvas=(128, 128), baseline_y=124.0,
+ target_height=120.0, scale="sheet", fit="contain")
+ data = report(tmp_path / "out")
+ factor = data["factor"]
+ assert factor < 120 / 80
+ assert data["factor_from"] == {"rule": "fit", "cell": "cell-2"}
+ for path, (w, h), cell in zip(written, boxes, data["cells"]):
+ assert cell["factor"] == factor and cell["clipped_px"] == 0
+ x0, y0, x1, y1 = opaque_box(path)
+ assert abs((y1 - y0) - h * factor) <= 1, path.name
+ assert abs((x1 - x0) - w * factor) <= 1, path.name
+ assert x0 >= 0 and x1 <= 128 and abs(y1 - 124) <= 1, path.name
+ anchor_x, anchor_y = cell["anchor"]
+ assert abs(anchor_y - y1) <= 1 and abs(anchor_x - (x0 + x1) / 2) <= 1, path.name
+
+
+def test_sheet_scale_after_the_alpha_cleanup_keeps_the_drawn_heights_relative(tmp_path):
+ boxes = [(40, 60), (40, 30), (40, 15)]
+ sheet = transparent_sheet(tmp_path / "props.png", boxes, haze=True)
+ written = slice_sheet(sheet, tmp_path / "out", None, grid=(3, 1), canvas=(128, 192), baseline_y=180.0,
+ target_height=120.0, alpha_floor=64, scale="sheet", fit="contain")
+ data = report(tmp_path / "out")
+ assert data["alpha_cleanup"] == "alpha-cleanup.json"
+ assert (tmp_path / "out" / "alpha-cleanup.json").is_file()
+ heights = []
+ for path, (_w, h), cell in zip(written, boxes, data["cells"]):
+ x0, y0, x1, y1 = opaque_box(path)
+ assert abs((y1 - y0) - h * data["factor"]) <= 1, path.name
+ assert cell["clipped_px"] == 0
+ heights.append(y1 - y0)
+ # drawn 60 : 30 : 15, cut 4 : 2 : 1 within a pixel
+ assert abs(heights[0] - 2 * heights[1]) <= 2 and abs(heights[1] - 2 * heights[2]) <= 2
+
+
+def test_game_pack_images_keep_the_sliced_sizes_and_stand_on_the_reported_anchor(tmp_path):
+ boxes = [(30, 60), (30, 30), (80, 20)]
+ sheet = transparent_sheet(tmp_path / "props.png", boxes)
+ written = slice_sheet(sheet, tmp_path / "cells", None, grid=(3, 1), names=["post", "crate", "bench"],
+ prefix="prop_", canvas=(128, 96), baseline_y=92.0, target_height=84.0,
+ scale="sheet", fit="contain")
+ data = report(tmp_path / "cells", "prop_")
+ request = {"version": 2, "images": [
+ {"id": cell["name"], "source": f"cells/{cell['file']}", "display": {"height": 48},
+ "anchor": cell["anchor"], "footprint": "base"} for cell in data["cells"]]}
+ (tmp_path / "game.json").write_text(json.dumps(request), encoding="utf-8")
+ result = game_pack.pack(tmp_path / "game.json", tmp_path / "pack")
+ frames = {name: (page, record) for page in result["textures"] for name, record in page["frames"].items()}
+ for cell, (_w, h), path in zip(data["cells"], boxes, written):
+ entry = result["images"][cell["name"]]
+ # one canvas for every cell, so one display height scales them all by the same amount
+ assert entry["size"] == {"w": 64, "h": 48}
+ assert entry["anchor"] == pytest.approx([v * 0.5 for v in cell["anchor"]])
+ page, record = frames[entry["frame"]]
+ rect = record["frame"]
+ with Image.open(tmp_path / "pack" / page["image"]) as atlas:
+ frame = atlas.crop((rect["x"], rect["y"], rect["x"] + rect["w"], rect["y"] + rect["h"])).convert("RGBA")
+ x0, y0, x1, y1 = opaque_box(frame)
+ assert abs((y1 - y0) - h * data["factor"] * 0.5) <= 1, cell["name"]
+ anchor_x, anchor_y = entry["anchor"]
+ assert abs(anchor_y - y1) <= 1 and abs(anchor_x - (x0 + x1) / 2) <= 1, cell["name"]
+ footprint = entry["footprint"]
+ assert abs(footprint["y"] + footprint["h"] - anchor_y) <= 1, cell["name"]
+
+
+def test_cli_and_the_script_take_scale_and_fit(tmp_path):
+ sheet = chroma_sheet(tmp_path / "props.png", [(30, 80), (30, 20), (90, 30)])
+ flags = ["--sheet", str(sheet), "--chroma-key", "magenta", "--grid", "3x1", "--prefix", "prop_",
+ "--cell-width", "128", "--cell-height", "128", "--baseline-y", "124", "--target-height", "120",
+ "--scale", "sheet", "--fit", "contain"]
+ assert cli.main(["slice-sheet", "--out-dir", str(tmp_path / "cli"), *flags]) == 0
+ assert slice_module.main(["--out-dir", str(tmp_path / "script"), *flags]) == 0
+ for out in (tmp_path / "cli", tmp_path / "script"):
+ data = report(out, "prop_")
+ assert data["scale"] == "sheet" and data["fit"] == "contain"
+ assert [cell["file"] for cell in data["cells"]] == ["prop_cell-0.png", "prop_cell-1.png", "prop_cell-2.png"]
+ assert report(tmp_path / "cli", "prop_") == report(tmp_path / "script", "prop_")
+
+
[email protected]("change, message", [
+ ({"scale": "tallest"}, "scale"),
+ ({"fit": "cover"}, "fit"),
+ ({"fit": "contain", "baseline_y": 130.0, "target_height": 100.0}, "baseline"),
+])
+def test_bad_settings_are_refused(tmp_path, change, message):
+ sheet = chroma_sheet(tmp_path / "props.png", [(30, 80), (30, 20)])
+ settings = dict(grid=(2, 1), canvas=(128, 128), baseline_y=124.0, target_height=120.0)
+ settings.update(change)
+ with pytest.raises(ValueError, match=message):
+ slice_sheet(sheet, tmp_path / "out", MAGENTA, **settings)
+
+
+def test_contain_refuses_a_part_below_the_base_with_no_room_under_the_baseline(tmp_path):
+ sheet = np.zeros((100, 100, 3), dtype=np.uint8)
+ sheet[...] = MAGENTA
+ sheet[20:70, 35:65] = INK # the main subject
+ sheet[80:90, 45:55] = INK # a detached part below its base
+ Image.fromarray(sheet).save(tmp_path / "sheet.png")
+ common = dict(grid=(1, 1), canvas=(96, 96), target_height=60.0, noise_min=10)
+ with pytest.raises(ValueError, match="cell-0"):
+ slice_sheet(tmp_path / "sheet.png", tmp_path / "floor", MAGENTA, baseline_y=96.0, fit="contain", **common)
+ written = slice_sheet(tmp_path / "sheet.png", tmp_path / "room", MAGENTA, baseline_y=80.0, fit="contain", **common)
+ cell = report(tmp_path / "room")["cells"][0]
+ assert cell["clipped_px"] == 0 and cell["parts"] == 2
+ assert abs(cell["anchor"][1] - 80) <= 1
+ _x0, _y0, _x1, y1 = opaque_box(written[0])
+ assert 80 < y1 <= 96