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(background): background-tile --axis xy, seamless both ways in one run

Soohong Kim01da534a859b
diff --git a/docs/asset-tools.md b/docs/asset-tools.md
index 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 o
sprite-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 input
diff --git a/sprite_gen/background/tile.py b/sprite_gen/background/tile.py
index 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=0
must 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-column
overlap 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.shape
width = 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.shape
slack = length - period - overlap
if slack < 0:
@@ -184,7 +202,7 @@ def make_tile(
# independent equally weighted channel. Selection still copies raw RGBA.
a[..., :3] *= a[..., 3:] / 255
b[..., :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), seam
assert 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.py
new file mode 100644
index 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)