Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(background): background-tile --axis xy, seamless both ways in one run
Soohong Kim01da534a859b
diff --git a/docs/asset-tools.md b/docs/asset-tools.mdindex 6251458..cd029b3 100644--- a/docs/asset-tools.md+++ b/docs/asset-tools.md@@ -25,11 +25,21 @@ Generate and remove the key with the existing tools, then run the tile command osprite-gen background-tile --source frontage.png --axis x --period 512 --overlap 32 --out tile.png```-`--axis x|y` chooses the repeat direction. `--period` is the output length in source pixels; `--overlap` is the input overlap used to find a low-error quilting seam. Input must contain enough pixels for the requested period and overlap. The tool preserves RGBA, writes a new PNG and `<out-stem>.report.json`, and never overwrites its source. `--report` changes the JSON destination.+`--axis x|y|xy` chooses the repeat direction. `--period` is the output length in source pixels; `--overlap` is the input overlap used to find a low-error quilting seam. Input must contain enough pixels for the requested period and overlap. The tool preserves RGBA, writes a new PNG and `<out-stem>.report.json`, and never overwrites its source. `--report` changes the JSON destination.The report measures the join against ordinary interior differences, including alpha and colour over light/dark backgrounds. It records the selected seam and source crop. A numerical join score does not prove that architecture or silhouettes repeat convincingly: inspect at least two adjacent copies. The tool does not invent missing roofs, perspective or scenery.-Python APIs: `make_tile(image, period, *, axis="x", overlap=32)` and `inspect_tile(image, axis="x")` in `sprite_gen.background.tile`. The former returns the image and report; the latter only measures. `inspect_tile` is the one measure of a tile's join: [`pixel-draw`](pixel-draw.md#gates)'s G4 tile seam asks it of a drawn tile along x and along y and warns where it says `needs-review`.+### Both axes: a ground tile++```bash+sprite-gen background-tile --source ground.png --axis xy --period 960 --overlap 64 --out ground-tile.png+```++`--axis xy` makes one square tile, `--period` on each side, that repeats in both directions; the source needs `period + overlap` pixels on both axes. It quilts along x, then along y. The second quilt cannot break the first one's join: its seam's two ends meet across the x wrap, so they may differ by one step at most, like any two neighbouring rows of a seam. Two separate `--axis x` and `--axis y` runs have no such rule, and the second run's report measures only its own axis.++The report measures the finished tile on both axes. `axes.x` and `axes.y` each hold that axis's join measurement (`edge_color_difference`, `seam_alpha_mismatch`, their interior baselines and thresholds), its quilt seam and search, and its own `status` and `review_reasons`. The top-level `status` is `needs-review` when either axis is, and every top-level reason is prefixed with its axis (`y: Internal quilt color difference exceeds source interior variation.`). `source_crop` and `core_crop` are `[x0, y0, x1, y1]` boxes in the source. Look at a 2 × 2 repeat of the tile before using it.++Python APIs: `make_tile(image, period, *, axis="x", overlap=32)`, `inspect_tile(image, axis="x")` and `inspect_tile_xy(image)` in `sprite_gen.background.tile`. The first returns the image and report (`axis="xy"` included); the others only measure, `inspect_tile_xy` both joins of a tile in the report shape above without the quilt fields. `inspect_tile` is the one measure of a tile's join: [`pixel-draw`](pixel-draw.md#gates)'s G4 tile seam asks it of a drawn tile along x and along y and warns where it says `needs-review`.## Shared asset inputdiff --git a/sprite_gen/background/tile.py b/sprite_gen/background/tile.pyindex 9b2268a..4771fdd 100644--- a/sprite_gen/background/tile.py+++ b/sprite_gen/background/tile.py@@ -7,6 +7,11 @@ overlap B replaces part of the leading overlap A along a connected seam.Every output pixel is copied intact from A or B, including its original alpha.There is no resampling, blur, compositing, or colour interpolation.+``axis="xy"`` quilts along x, then along y with a cyclic seam: the second seam's+two ends, which meet across the x wrap, may differ by one step at most, so the+second pass cannot break the join the first one made. Its report measures both+joins of the finished tile.+Reports describe local pixel differences, not semantic continuity of a painting.Inspect repeated tiles visually even when the numerical checks pass."""@@ -120,16 +125,22 @@ def inspect_tile(image: Image.Image, axis: str = "x") -> dict[str, Any]:}-def _minimum_seam(error: Any) -> tuple[Any, float]:+def _minimum_seam(error: Any, cyclic: bool = False) -> tuple[Any, float]:"""Minimum accumulated error, with neighbouring rows moving at most one px.``cut`` is the LAST B pixel, not the first A pixel. In particular cut=0must copy B at x=0: the wrap then joins adjacent source pixels P-1 and P.Reserve the overlap's final column for A when overlap > 1. A one-columnoverlap necessarily copies B there and switches to A at the next column.++ ``cyclic``: the first and last rows are neighbours too (they meet across the+ other axis's wrap), so the seam's two ends may differ by one step at most.+ One search per starting column, all at once."""height, overlap = error.shapewidth = max(1, overlap - 1)+ if cyclic and height > 1:+ return _cyclic_seam(error[:, :width].astype(np.float64))costs = error[0, :width].astype(np.float64)steps = np.zeros((height, width), dtype=np.int8)for row in range(1, height):@@ -146,27 +157,34 @@ def _minimum_seam(error: Any) -> tuple[Any, float]:return seam, score+def _cyclic_seam(error: Any) -> tuple[Any, float]:+ height, width = error.shape+ costs = np.full((width, width), np.inf)+ costs[np.arange(width), np.arange(width)] = error[0]+ steps = np.zeros((height, width, width), dtype=np.int8)+ blocked = np.full((width, 1), np.inf)+ for row in range(1, height):+ left = np.concatenate((blocked, costs[:, :-1]), axis=1)+ right = np.concatenate((costs[:, 1:], blocked), axis=1)+ steps[row][(left < costs) & (left <= right)] = -1+ steps[row][(right < costs) & (right < left)] = 1+ costs = np.minimum(costs, np.minimum(left, right)) + error[row]+ start_column, end_column = np.indices((width, width))+ final = np.where(np.abs(start_column - end_column) <= 1, costs, np.inf)+ start, end = divmod(int(np.argmin(final)), width)+ seam = np.empty(height, dtype=np.int32)+ seam[-1] = end+ for row in range(height - 1, 0, -1):+ seam[row - 1] = seam[row] + steps[row, start, seam[row]]+ return seam, float(final[start, end] / height)++def _crop_box(start: int, length: int, cross: int, axis: str) -> list[int]:return [start, 0, start + length, cross] if axis == "x" else [0, start, cross, start + length]-def make_tile(- image: Image.Image, period: int, *, axis: str = "x", overlap: int = 32,-) -> tuple[Image.Image, dict[str, Any]]:- """Return an RGBA tile and JSON-safe report, leaving ``image`` untouched.-- The tile is ``period`` pixels along ``axis`` with the other dimension- unchanged. At most MAX_CANDIDATES evenly spaced crop starts are evaluated,- including both endpoints. The seam search is exact within each candidate,- but the bounded crop search does not claim a global optimum.- """- for name, value in (("period", period), ("overlap", overlap)):- if isinstance(value, bool) or not isinstance(value, Integral):- raise TypeError(f"{name} must be an integer")- period, overlap = int(period), int(overlap)- if period < 2 or not 1 <= overlap < period:- raise ValueError("geometry requires period >= 2 and 1 <= overlap < period")- pixels = _pixels(image, axis)+def _quilt(pixels: Any, period: int, overlap: int, axis: str, *, cyclic: bool = False) -> tuple[Any, dict[str, Any]]:+ """Quilt one axis of axis-oriented pixels (the tiling axis is dimension 1)."""height, length, _ = pixels.shapeslack = length - period - overlapif slack < 0:@@ -184,7 +202,7 @@ def make_tile(# independent equally weighted channel. Selection still copies raw RGBA.a[..., :3] *= a[..., 3:] / 255b[..., :3] *= b[..., 3:] / 255- seam, score = _minimum_seam(np.square(a - b).mean(axis=-1))+ seam, score = _minimum_seam(np.square(a - b).mean(axis=-1), cyclic)if score < best_score:best_score, best_start, best_seam = score, int(start), seamassert best_seam is not None@@ -192,19 +210,21 @@ def make_tile(result = crop[:, :period].copy()use_b = np.arange(overlap)[None, :] <= best_seam[:, None]result[:, :overlap] = np.where(use_b[..., None], crop[:, period:], crop[:, :overlap])- tile = Image.fromarray(result if axis == "x" else result.transpose(1, 0, 2))- report = inspect_tile(tile, axis)# The wrap is now a natural source adjacency. It can pass while the new# internal cut is bad, so inspect that cut separately against SOURCE detail.- # Include vertical mask transitions as well as each row's horizontal cut.+ # Include vertical mask transitions as well as each row's horizontal cut;+ # a cyclic seam also turns between its last and first rows.rows = np.arange(height)seam_color, seam_alpha = _differences(result[rows, best_seam], result[rows, best_seam + 1])reference_color, reference_alpha = _differences(crop[:, :-1], crop[:, 1:])turn_rows = np.flatnonzero(np.diff(best_seam))+ turn_next = turn_rows + 1+ if cyclic and height > 1 and best_seam[-1] != best_seam[0]:+ turn_rows, turn_next = np.append(turn_rows, height - 1), np.append(turn_next, 0)if turn_rows.size:- turn_cols = np.maximum(best_seam[turn_rows], best_seam[turn_rows + 1])- turn_color, turn_alpha = _differences(result[turn_rows, turn_cols], result[turn_rows + 1, turn_cols])+ turn_cols = np.maximum(best_seam[turn_rows], best_seam[turn_next])+ turn_color, turn_alpha = _differences(result[turn_rows, turn_cols], result[turn_next, turn_cols])seam_color = np.concatenate((seam_color, turn_color))seam_alpha = np.concatenate((seam_alpha, turn_alpha))vertical_color, vertical_alpha = _differences(crop[:-1], crop[1:])@@ -213,17 +233,14 @@ def make_tile(quilt_color, quilt_alpha = _stats(seam_color), _alpha_stats(seam_alpha)reference_color_stats, reference_alpha_stats = _stats(reference_color), _alpha_stats(reference_alpha)quilt_color_limits, quilt_alpha_limits = _limits(reference_color_stats), _limits(reference_alpha_stats)+ reasons = []if _exceeds(quilt_color, quilt_color_limits):- report["review_reasons"].append("Internal quilt color difference exceeds source interior variation.")+ reasons.append("Internal quilt color difference exceeds source interior variation.")if _exceeds(quilt_alpha, quilt_alpha_limits):- report["review_reasons"].append("Internal quilt alpha mismatch exceeds source interior variation.")- report.update({- "status": "needs-review" if report["review_reasons"] else "pass",- "method": "crop-overlap-minimum-error-quilt",- "source_size": list(image.size),- "source_crop": _crop_box(best_start, period + overlap, height, axis),- "core_crop": _crop_box(best_start, period, height, axis),- "overlap": overlap,+ reasons.append("Internal quilt alpha mismatch exceeds source interior variation.")+ return result, {+ "start": best_start,+ "reasons": reasons,"search": {"evaluated_candidates": int(starts.size), "candidate_limit": MAX_CANDIDATES,"available_crops": slack + 1, "strategy": "evenly-spaced including endpoints"},"quilt_seam": {@@ -234,10 +251,101 @@ def make_tile("source_interior_alpha_difference": reference_alpha_stats,"thresholds": {"color": quilt_color_limits, "alpha": quilt_alpha_limits},},+ }+++def _geometry(period: Any, overlap: Any) -> tuple[int, int]:+ for name, value in (("period", period), ("overlap", overlap)):+ if isinstance(value, bool) or not isinstance(value, Integral):+ raise TypeError(f"{name} must be an integer")+ period, overlap = int(period), int(overlap)+ if period < 2 or not 1 <= overlap < period:+ raise ValueError("geometry requires period >= 2 and 1 <= overlap < period")+ return period, overlap+++def make_tile(+ image: Image.Image, period: int, *, axis: str = "x", overlap: int = 32,+) -> tuple[Image.Image, dict[str, Any]]:+ """Return an RGBA tile and JSON-safe report, leaving ``image`` untouched.++ The tile is ``period`` pixels along ``axis`` with the other dimension+ unchanged; with ``axis="xy"`` it is ``period`` pixels square. At most+ MAX_CANDIDATES evenly spaced crop starts are evaluated per axis, including+ both endpoints. The seam search is exact within each candidate, but the+ bounded crop search does not claim a global optimum.+ """+ period, overlap = _geometry(period, overlap)+ if axis == "xy":+ return _make_tile_xy(image, period, overlap)+ pixels = _pixels(image, axis)+ height = pixels.shape[0]+ result, quilt = _quilt(pixels, period, overlap, axis)+ tile = Image.fromarray(result if axis == "x" else result.transpose(1, 0, 2))+ report = inspect_tile(tile, axis)+ report["review_reasons"].extend(quilt["reasons"])+ start = quilt["start"]+ report.update({+ "status": "needs-review" if report["review_reasons"] else "pass",+ "method": "crop-overlap-minimum-error-quilt",+ "source_size": list(image.size),+ "source_crop": _crop_box(start, period + overlap, height, axis),+ "core_crop": _crop_box(start, period, height, axis),+ "overlap": overlap,+ "search": quilt["search"],+ "quilt_seam": quilt["quilt_seam"],+ })+ return tile, report+++def _make_tile_xy(image: Image.Image, period: int, overlap: int) -> tuple[Image.Image, dict[str, Any]]:+ source = _pixels(image, "x")+ height, width, _ = source.shape+ for axis, length in (("x", width), ("y", height)):+ if length < period + overlap:+ raise ValueError(+ f"source has {length} pixels along {axis}; period + overlap requires {period + overlap}"+ )+ across, x_quilt = _quilt(source, period, overlap, "x")+ down, y_quilt = _quilt(across.transpose(1, 0, 2), period, overlap, "y", cyclic=True)+ tile = Image.fromarray(np.ascontiguousarray(down.transpose(1, 0, 2)))+ x0, y0 = x_quilt["start"], y_quilt["start"]+ report = inspect_tile_xy(tile)+ for axis, quilt in (("x", x_quilt), ("y", y_quilt)):+ measured = report["axes"][axis]+ measured["review_reasons"].extend(quilt["reasons"])+ measured["status"] = "needs-review" if measured["review_reasons"] else "pass"+ measured.update(search=quilt["search"], quilt_seam=quilt["quilt_seam"])+ report["review_reasons"] = [f"{axis}: {reason}" for axis in ("x", "y")+ for reason in report["axes"][axis]["review_reasons"]]+ report.update({+ "status": "needs-review" if report["review_reasons"] else "pass",+ "method": "crop-overlap-minimum-error-quilt along x, then along y with a cyclic seam",+ "source_size": list(image.size),+ "source_crop": [x0, y0, x0 + period + overlap, y0 + period + overlap],+ "core_crop": [x0, y0, x0 + period, y0 + period],+ "overlap": overlap,})return tile, report+def inspect_tile_xy(image: Image.Image) -> dict[str, Any]:+ """Measure both wrap edges of a tile meant to repeat in both directions.++ ``axes`` holds the ``inspect_tile`` report of each axis; ``status`` is+ ``needs-review`` when either axis needs review, and every reason is+ prefixed with its axis.+ """+ axes = {axis: inspect_tile(image, axis) for axis in ("x", "y")}+ reasons = [f"{axis}: {reason}" for axis in ("x", "y") for reason in axes[axis]["review_reasons"]]+ return {+ "schema_version": 1, "axis": "xy", "size": list(image.size), "period": image.size[0],+ "status": "needs-review" if reasons else "pass",+ "requires_visual_review": True, "assessment": _ASSESSMENT,+ "review_reasons": reasons, "axes": axes,+ }++def _same_file(a: Path, b: Path) -> bool:return a == b or (a.exists() and b.exists() and a.samefile(b))@@ -301,8 +409,10 @@ def _publish(def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--source", required=True, type=Path, help="independent single-frame PNG")parser.add_argument("--out", required=True, type=Path, help="output PNG; cannot overwrite the source")- parser.add_argument("--period", required=True, type=int, help="tile length in pixels along --axis")- parser.add_argument("--axis", choices=("x", "y"), default="x")+ parser.add_argument("--period", required=True, type=int,+ help="tile length in pixels along --axis (with xy: the side of the square tile)")+ parser.add_argument("--axis", choices=("x", "y", "xy"), default="x",+ help="repeat direction; xy makes one tile seamless both ways and measures both joins")parser.add_argument("--overlap", type=int, default=32,help="1 <= overlap < period; source must contain period + overlap pixels")parser.add_argument("--report", type=Path, help="JSON report (default: <out-stem>.report.json)")diff --git a/tests/background/test_tile_xy.py b/tests/background/test_tile_xy.pynew file mode 100644index 0000000..9c9b576--- /dev/null+++ b/tests/background/test_tile_xy.py@@ -0,0 +1,133 @@+# SPDX-License-Identifier: Apache-2.0+"""`background-tile --axis xy`: one run, seamless on both axes, a report that measures both joins.++Synthetic oracles: a doubly periodic texture (an exact tile exists), textures that can only be+joined on one axis (the report must say which), and the seam search that keeps the first axis's+join when the second axis is quilted.+"""++import json++import numpy as np+import pytest+from PIL import Image++from sprite_gen.background import tile+from sprite_gen.background.tile import inspect_tile, make_tile+++def periodic(period=16, width=None, height=None):+ width, height = width or 3 * period + 7, height or 3 * period + 5+ y, x = np.indices((height, width))+ u, v = 2 * np.pi * x / period, 2 * np.pi * y / period+ pixels = np.stack((110 + 50 * np.sin(u) + 30 * np.cos(v),+ 120 + 40 * np.cos(u + v),+ 90 + 35 * np.sin(v) * np.cos(u),+ np.full_like(x, 255)), axis=-1)+ return Image.fromarray(pixels.round().astype(np.uint8))+++def ramp(axis, period=16, size=60):+ """Rows (or columns) brighten steadily: periodic along one axis, impossible to wrap along the other."""+ y, x = np.indices((size, size))+ along = y if axis == "y" else x+ pixels = np.stack((40 + 3 * along, 60 + 2 * along, 30 + along, np.full_like(x, 255)), axis=-1)+ return Image.fromarray(pixels.astype(np.uint8))+++def test_doubly_periodic_source_gives_an_exact_crop_and_both_joins_pass():+ source = periodic()+ before = source.tobytes()+ result, report = make_tile(source, 16, axis="xy", overlap=5)+ assert result.size == (16, 16) and result.mode == "RGBA"+ x0, y0, x1, y1 = report["core_crop"]+ assert (x1 - x0, y1 - y0) == (16, 16)+ assert result.tobytes() == source.crop((x0, y0, x1, y1)).tobytes()+ assert source.tobytes() == before+ assert report["axis"] == "xy"+ assert report["status"] == "pass" and report["review_reasons"] == []+ assert set(report["axes"]) == {"x", "y"}+ for axis in ("x", "y"):+ measured = report["axes"][axis]+ assert measured["status"] == "pass"+ assert measured["edge_color_difference"] == inspect_tile(result, axis)["edge_color_difference"]+ assert "quilt_seam" in measured+ json.dumps(report, allow_nan=False)++[email protected]("bad", ["x", "y"])+def test_a_join_that_stays_visible_on_one_axis_fails_the_report_and_names_that_axis(bad):+ good = "y" if bad == "x" else "x"+ _, report = make_tile(ramp(bad), 16, axis="xy", overlap=5)+ assert report["status"] == "needs-review"+ assert report["axes"][bad]["status"] == "needs-review"+ assert report["axes"][good]["status"] == "pass"+ assert report["review_reasons"]+ assert all(reason.startswith(f"{bad}: ") for reason in report["review_reasons"])++[email protected]("bad", ["x", "y"])+def test_inspection_of_both_axes_catches_a_tile_seamless_on_only_one(bad):+ # Periodic along one axis, a hard break along the other: one-axis inspection along the good axis passes.+ good = "y" if bad == "x" else "x"+ pixels = np.asarray(periodic(16, 16, 16)).copy()+ if bad == "x":+ pixels[:, 8:, :3] = 255 - pixels[:, 8:, :3]+ else:+ pixels[8:, :, :3] = 255 - pixels[8:, :, :3]+ image = Image.fromarray(pixels)+ assert inspect_tile(image, good)["status"] == "pass"+ report = tile.inspect_tile_xy(image)+ assert report["status"] == "needs-review"+ assert report["axes"][bad]["status"] == "needs-review"+ assert report["axes"][good]["status"] == "pass"+++def test_cyclic_seam_keeps_its_two_ends_within_one_step():+ # A zero-error path that drifts from column 0 to column 3: the open search follows it exactly,+ # the cyclic one must end within one step of where it starts (rows 0 and -1 are wrap neighbours).+ error = np.full((8, 6), 100.0)+ path = [0, 0, 1, 1, 2, 2, 3, 3]+ for row, col in enumerate(path):+ error[row, col] = 0+ open_seam, open_score = tile._minimum_seam(error)+ assert open_seam.tolist() == path and open_score == 0+ seam, score = tile._minimum_seam(error, cyclic=True)+ assert abs(int(seam[0]) - int(seam[-1])) <= 1+ assert np.all(np.abs(np.diff(seam)) <= 1)+ assert score > 0+++def test_second_pass_keeps_the_first_axis_join_exact_on_a_texture_with_a_drifting_match():+ # Rows repeat every 16 px; columns repeat every 16 px except that the rows' best match drifts+ # across x. The y quilt's seam may not differ by more than one step between the last and the+ # first column, so the x join (a wrap neighbour pair) stays a source adjacency or one seam step.+ rng = np.random.default_rng(7)+ base = periodic(16, 60, 60)+ pixels = np.asarray(base).astype(np.int16)+ pixels[..., :3] += rng.integers(-3, 4, pixels[..., :3].shape)+ result, report = make_tile(Image.fromarray(np.clip(pixels, 0, 255).astype(np.uint8)), 16, axis="xy", overlap=6)+ seam = report["axes"]["y"]["quilt_seam"]["positions"]+ assert len(seam) == 16+ assert abs(seam[0] - seam[-1]) <= 1+ assert report["axes"]["x"]["status"] == "pass"+++def test_xy_needs_the_period_plus_overlap_on_both_axes():+ with pytest.raises(ValueError, match="along y"):+ make_tile(Image.new("RGBA", (40, 20)), 16, axis="xy", overlap=5)+ with pytest.raises(ValueError, match="along x"):+ make_tile(Image.new("RGBA", (20, 40)), 16, axis="xy", overlap=5)+++def test_cli_accepts_axis_xy(tmp_path):+ source = tmp_path / "ground.png"+ periodic().save(source)+ out = tmp_path / "tile.png"+ assert tile.main(["--source", str(source), "--out", str(out), "--period", "16", "--overlap", "5",+ "--axis", "xy"]) == 0+ report = json.loads((tmp_path / "tile.report.json").read_text())+ assert report["axis"] == "xy" and report["status"] == "pass"+ assert report["source"] == str(source) and report["output"] == str(out)+ with Image.open(out) as image:+ assert image.size == (16, 16)