Skip to content

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

15.5 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Periodic background crops, joined with a hard minimum-error RGBA quilt.

The source must contain ``period + overlap`` pixels along the selected axis;
``1 <= overlap < period``. A bounded search chooses a crop. Its trailing
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.

Reports describe local pixel differences, not semantic continuity of a painting.
Inspect repeated tiles visually even when the numerical checks pass.
"""

from __future__ import annotations

import argparse
import io
import json
from numbers import Integral
from pathlib import Path
from typing import Any

from PIL import Image

from sprite_gen._deps import np
from sprite_gen.spec.runio import acquire_run_dir_lock, atomic_write_set, release_run_dir_lock, same_folder
from sprite_gen.util.console import utf8_streams


MAX_CANDIDATES = 32
_ASSESSMENT = (
    "Local pixel discontinuity checks only; review repeated tiles visually for "
    "cut silhouettes, repeated landmarks, and painting continuity."
)


def _pixels(image: Image.Image, axis: str) -> Any:
    if axis not in ("x", "y"):
        raise ValueError("axis must be x or y")
    if not isinstance(image, Image.Image):
        raise TypeError("image must be a PIL image")
    if min(image.size) < 1:
        raise ValueError("image dimensions must be positive")
    pixels = np.asarray(image.convert("RGBA"))
    return pixels if axis == "x" else pixels.transpose(1, 0, 2)


def _differences(a: Any, b: Any) -> tuple[Any, Any]:
    """Visible RGB on both black and white, plus independent alpha (0..255)."""
    a = a.astype(np.float32)
    b = b.astype(np.float32)
    alpha_delta = a[..., 3] - b[..., 3]
    black_delta = a[..., :3] * (a[..., 3:] / 255) - b[..., :3] * (b[..., 3:] / 255)
    white_delta = black_delta - alpha_delta[..., None]
    color = np.maximum(np.abs(black_delta), np.abs(white_delta)).mean(axis=-1)
    return color, np.abs(alpha_delta)


def _stats(values: Any) -> dict[str, float]:
    if not values.size:
        return {"mean": 0.0, "p95": 0.0, "max": 0.0}
    return {"mean": float(values.mean()), "p95": float(np.percentile(values, 95)),
            "max": float(values.max())}


def _alpha_stats(values: Any) -> dict[str, float]:
    return {**_stats(values),
            "mismatch_fraction": float(np.count_nonzero(values) / values.size) if values.size else 0.0}


def _limits(interior: dict[str, float]) -> dict[str, float]:
    return {key: max(floor, 2 * interior[key])
            for key, floor in (("mean", 3.0), ("p95", 8.0), ("max", 16.0))}


def _exceeds(measured: dict[str, float], limits: dict[str, float]) -> bool:
    return any(measured[key] > limit for key, limit in limits.items())


def _ratio(edge: float, interior: float) -> float | None:
    # JSON has no infinity. Null explicitly means a nonzero edge over a zero
    # baseline; the absolute metrics and thresholds still determine the verdict.
    return edge / interior if interior else (0.0 if edge == 0 else None)


def inspect_tile(image: Image.Image, axis: str = "x") -> dict[str, Any]:
    """Measure the actual wrap edge against ordinary interior neighbours.

    RGB is compared as displayed over both black and white, so invisible RGB
    cannot inflate a score and transparent silhouettes cannot disappear from it.
    All differences are in 8-bit channel units. ``pass`` is a local heuristic,
    never a guarantee of seamless artwork. An axis of length one lacks evidence.
    """
    pixels = _pixels(image, axis)
    edge_color, edge_alpha = _differences(pixels[:, -1], pixels[:, 0])
    inner_color, inner_alpha = _differences(pixels[:, :-1], pixels[:, 1:])
    color, alpha = _stats(edge_color), _alpha_stats(edge_alpha)
    interior_color, interior_alpha = _stats(inner_color), _alpha_stats(inner_alpha)
    color_limits, alpha_limits = _limits(interior_color), _limits(interior_alpha)
    reasons = []
    if pixels.shape[1] < 2:
        reasons.append("No interior neighbours along the tiling axis to establish a baseline.")
    if _exceeds(color, color_limits):
        reasons.append("Wrap edge color difference exceeds interior variation.")
    if _exceeds(alpha, alpha_limits):
        reasons.append("Wrap seam alpha mismatch exceeds interior variation.")
    return {
        "schema_version": 1, "axis": axis, "size": list(image.size),
        "period": int(pixels.shape[1]),
        "status": "needs-review" if reasons else "pass",
        "requires_visual_review": True, "assessment": _ASSESSMENT,
        "review_reasons": reasons,
        "color_metric": "mean per-channel absolute difference, worst of black/white composites (0..255)",
        "edge_color_difference": color,
        "interior_color_difference": interior_color,
        "edge_to_interior_color_ratio": _ratio(color["mean"], interior_color["mean"]),
        "seam_alpha_mismatch": alpha,
        "interior_alpha_difference": interior_alpha,
        "edge_to_interior_alpha_ratio": _ratio(alpha["mean"], interior_alpha["mean"]),
        "thresholds": {"color": color_limits, "alpha": alpha_limits},
    }


def _minimum_seam(error: Any) -> 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.
    """
    height, overlap = error.shape
    width = max(1, overlap - 1)
    costs = error[0, :width].astype(np.float64)
    steps = np.zeros((height, width), dtype=np.int8)
    for row in range(1, height):
        left = np.concatenate(([np.inf], costs[:-1]))
        right = np.concatenate((costs[1:], [np.inf]))
        steps[row, (left < costs) & (left <= right)] = -1
        steps[row, (right < costs) & (right < left)] = 1
        costs = np.minimum(costs, np.minimum(left, right)) + error[row, :width]
    seam = np.empty(height, dtype=np.int32)
    seam[-1] = int(np.argmin(costs))
    score = float(costs[seam[-1]] / height)
    for row in range(height - 1, 0, -1):
        seam[row - 1] = seam[row] + steps[row, seam[row]]
    return seam, score


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)
    height, length, _ = pixels.shape
    slack = length - period - overlap
    if slack < 0:
        raise ValueError(
            f"source has {length} pixels along {axis}; period + overlap requires {period + overlap}"
        )
    starts = np.unique(np.linspace(0, slack, min(MAX_CANDIDATES, slack + 1)).round().astype(int))
    best_score = float("inf")
    best_start = 0
    best_seam = None
    for start in starts:
        a = pixels[:, start:start + overlap].astype(np.float32)
        b = pixels[:, start + period:start + period + overlap].astype(np.float32)
        # Premultiplied RGB removes hidden RGB from the energy; alpha remains an
        # 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))
        if score < best_score:
            best_score, best_start, best_seam = score, int(start), seam
    assert best_seam is not None
    crop = pixels[:, best_start:best_start + period + overlap]
    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.
    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))
    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])
        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:])
        reference_color = np.concatenate((reference_color.ravel(), vertical_color.ravel()))
        reference_alpha = np.concatenate((reference_alpha.ravel(), vertical_alpha.ravel()))
    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)
    if _exceeds(quilt_color, quilt_color_limits):
        report["review_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,
        "search": {"evaluated_candidates": int(starts.size), "candidate_limit": MAX_CANDIDATES,
                   "available_crops": slack + 1, "strategy": "evenly-spaced including endpoints"},
        "quilt_seam": {
            "positions": best_seam.tolist(), "position_meaning": "last tail/B pixel per cross-axis row",
            "mean_squared_error": best_score,
            "color_difference": quilt_color, "alpha_mismatch": quilt_alpha,
            "source_interior_color_difference": reference_color_stats,
            "source_interior_alpha_difference": reference_alpha_stats,
            "thresholds": {"color": quilt_color_limits, "alpha": quilt_alpha_limits},
        },
    })
    return tile, report


def _same_file(a: Path, b: Path) -> bool:
    """One path, or one file by identity (`runio.same_folder`): the PNG and its report may both be new paths."""
    return a == b or same_folder(a, b)


def _validate_paths(source: Path, out: Path, report: Path) -> None:
    if out.suffix.lower() != ".png" or report.suffix.lower() != ".json":
        raise ValueError("--out must be a PNG path and --report must be a JSON path")
    if not source.is_file():
        raise ValueError(f"source is not a file: {source}")
    for target in (out, report):
        if _same_file(source, target):
            raise ValueError(f"refusing to overwrite source: {target}")
        if target.exists() and not target.is_file():
            raise ValueError(f"output is not a regular file: {target}")
        for parent in target.parents:
            if parent.exists() and not parent.is_dir():
                raise ValueError(f"output parent is not a directory: {parent}")
    if _same_file(out, report):
        raise ValueError("PNG output and JSON report must be different files")
    if out in report.parents or report in out.parents:
        raise ValueError("an output file cannot be another output's parent directory")


def _publish(
    *, source: Path, out: Path, period: int, axis: str = "x", overlap: int = 32,
    report: Path | None = None,
) -> int:
    source = Path(source).expanduser().resolve()
    out = Path(out).expanduser().resolve()
    report_path = Path(report).expanduser().resolve() if report is not None else out.with_suffix(".report.json")
    _validate_paths(source, out, report_path)
    with Image.open(source) as image:
        if image.format != "PNG" or getattr(image, "n_frames", 1) != 1:
            raise ValueError("--source must be a single-frame PNG")
        tile, metrics = make_tile(image, period, axis=axis, overlap=overlap)
    metrics.update({"source": str(source), "output": str(out)})
    png = io.BytesIO()
    tile.save(png, format="PNG")
    payloads = {out: png.getvalue(), report_path: json.dumps(metrics, indent=2, allow_nan=False) + "\n"}
    # Validate and encode everything before any filesystem mutation. Lock each
    # destination directory (stable ordering), since reports may live elsewhere.
    # The locks are task-scoped: whatever this call acquired is released when it
    # returns or fails, including after a partial acquisition, so an API caller
    # never keeps a writer lock until the process exits.
    _validate_paths(source, out, report_path)
    locked = []
    try:
        for directory in sorted({out.parent, report_path.parent}):
            directory.mkdir(parents=True, exist_ok=True)
            acquire_run_dir_lock(directory, "background-tile")
            locked.append(directory)
        _validate_paths(source, out, report_path)
        atomic_write_set(payloads)
    finally:
        for directory in reversed(locked):
            release_run_dir_lock(directory)
    print(f"background-tile: {metrics['status']} — {out} (report: {report_path})")
    return 0


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("--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)")


def run(**kwargs: Any) -> int:
    try:
        return _publish(**kwargs)
    except (OSError, ValueError, TypeError) as exc:
        raise SystemExit(f"background-tile: {exc}") from exc


def main(argv: list[str] | None = None) -> int:
    utf8_streams()
    parser = argparse.ArgumentParser(description=__doc__)
    add_arguments(parser)
    return run(**vars(parser.parse_args(argv)))


if __name__ == "__main__":
    raise SystemExit(main())