Skip to content

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

16.8 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Inspect generated sprite rows for closed-loop correction signals."""

from __future__ import annotations

import argparse
import json
import math
from pathlib import Path
from statistics import mean, pstdev
from typing import Any

from PIL import Image, ImageChops

from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.frames import extract
from sprite_gen.spec.layout import frames_dir_rel, raw_rel, state_frame_total
from sprite_gen.spec.runio import (acquire_run_dir_lock, atomic_write_text, load_request,
                              read_guard, relative_posix)
from sprite_gen.frames.segment import segment_strip
from sprite_gen.util.console import utf8_streams


HISTOGRAM_BINS = 64
D_HASH_BITS = 64
DEFAULT_HISTOGRAM_MIN = 0.0
DEFAULT_DHASH_MIN = 0.55
DEFAULT_MOTION_MIN = 0.01


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--run-dir", required=True, type=Path)
    parser.add_argument("--states", default="all")
    parser.add_argument("--report", default="sprite-inspect.report.json")
    parser.add_argument("--histogram-min", type=float, default=DEFAULT_HISTOGRAM_MIN)
    parser.add_argument("--dhash-min", type=float, default=DEFAULT_DHASH_MIN)
    parser.add_argument("--motion-min", type=float, default=DEFAULT_MOTION_MIN)
    parser.add_argument("--key-threshold", type=float, default=96.0)
    parser.add_argument("--fringe-key-threshold", type=float, default=180.0)
    parser.add_argument("--fringe-delta", type=float, default=18.0)
    parser.add_argument("--fringe-unmix-reach", type=int, default=None)
    parser.add_argument("--spill-max-fraction", type=float, default=None)
    parser.add_argument("--chroma-mode", choices=extract.CHROMA_MODES, default=None)
    parser.add_argument("--decontam", choices=extract.DECONTAM_MODES, default=None)
    parser.add_argument("--no-write", action="store_true")
    return parser


def _state_list(request: dict[str, Any], states: str) -> list[str]:
    if states == "all":
        return list(request["states"])
    selected = [state.strip() for state in states.split(",") if state.strip()]
    unknown = [state for state in selected if state not in request["states"]]
    if unknown:
        raise SystemExit(f"unknown state(s) in request: {', '.join(unknown)}")
    return selected


def _rgba(path: Path) -> Image.Image:
    with Image.open(path) as opened:
        return opened.convert("RGBA")


def _frame_sort_key(path: Path) -> int:
    stem = path.stem
    if stem.endswith(".plain"):
        stem = stem.removesuffix(".plain")
    try:
        return int(stem.split("-")[1])
    except (IndexError, ValueError):
        return 10**9


def _load_extracted_frames(run_dir: Path, state: str, request: dict[str, Any]) -> tuple[list[Image.Image], list[str]]:
    state_dir = run_dir / frames_dir_rel(request, state)
    if not state_dir.is_dir():
        return [], []
    paths = sorted(
        (path for path in state_dir.glob("frame-*.png") if not path.name.endswith(".plain.png")),
        key=_frame_sort_key,
    )
    return [_rgba(path) for path in paths], [relative_posix(path, run_dir) for path in paths]


def _strip_for_state(run_dir: Path, request: dict[str, Any], state: str, args: argparse.Namespace) -> Image.Image | None:
    raw_path = run_dir / raw_rel(request, state)
    if not raw_path.is_file():
        return None
    chroma_config = dict(request.get("chroma") or {})
    chroma_mode = args.chroma_mode if args.chroma_mode is not None else str(chroma_config.get("mode", extract.CHROMA_RGB))
    chroma_key = tuple(int(value) for value in request["chroma_key"]["rgb"])
    unmix_reach = (
        args.fringe_unmix_reach
        if args.fringe_unmix_reach is not None
        else int(chroma_config.get("unmix_reach", 4))
    )
    spill_max_fraction = (
        args.spill_max_fraction
        if args.spill_max_fraction is not None
        else float(chroma_config.get("spill_max_fraction", 0.005))
    )
    decontam = args.decontam if args.decontam is not None else str(chroma_config.get("decontam", extract.OFF))
    decontam_kwargs = {} if decontam == extract.OFF else {"decontam": decontam}
    with Image.open(raw_path) as opened:
        if chroma_mode == extract.CHROMA_YCBCR:
            notes: list[str] = []
            return extract.remove_chroma_background_ycbcr(opened, chroma_key, notes, **decontam_kwargs)
        return extract.remove_chroma_background(
            opened,
            chroma_key,
            args.key_threshold,
            args.fringe_key_threshold,
            args.fringe_delta,
            unmix_reach=unmix_reach,
            spill_max_fraction=spill_max_fraction,
            **decontam_kwargs,
        )


def _frames_from_raw(strip: Image.Image, expected: int, request: dict[str, Any]) -> tuple[list[Image.Image], int]:
    cell_width, cell_height, safe_margin_x, safe_margin_y = extract.cell_geometry(request["cell"])
    segments, natural = segment_strip(strip, expected)
    # A row is fitted the way extract fits it: one scale for every pose (extract.fit_row_to_cells).
    frames = extract.fit_row_to_cells(
        [strip.crop((left, 0, right, strip.height)) for left, right in segments],
        cell_width,
        cell_height,
        safe_margin_x,
        safe_margin_y,
        request.get("fit") or {},
    )
    return frames, natural


def _rgb_histogram(image: Image.Image) -> list[float]:
    bins = [0] * HISTOGRAM_BINS
    total = 0
    for red, green, blue, alpha in image.convert("RGBA").getdata():
        if alpha <= 16:
            continue
        index = (red // 64) * 16 + (green // 64) * 4 + (blue // 64)
        bins[index] += 1
        total += 1
    if total == 0:
        return [0.0] * HISTOGRAM_BINS
    return [value / total for value in bins]


def histogram_intersection(left: list[float], right: list[float]) -> float:
    return sum(min(a, b) for a, b in zip(left, right))


def _dhash(image: Image.Image) -> int:
    flattened = Image.new("RGBA", image.size, (255, 255, 255, 255))
    flattened.alpha_composite(image.convert("RGBA"))
    small = flattened.convert("L").resize((9, 8), Image.Resampling.BILINEAR)
    pixels = list(small.getdata())
    value = 0
    bit = 0
    for y in range(8):
        row = y * 9
        for x in range(8):
            if pixels[row + x] > pixels[row + x + 1]:
                value |= 1 << bit
            bit += 1
    return value


def dhash_similarity(left: int, right: int) -> float:
    return 1.0 - ((left ^ right).bit_count() / D_HASH_BITS)


def _alpha_centroid(image: Image.Image) -> tuple[float, float] | None:
    alpha = image.getchannel("A")
    total = 0
    weighted_x = 0
    weighted_y = 0
    for y in range(image.height):
        for x in range(image.width):
            value = alpha.getpixel((x, y))
            if value <= 10:
                continue
            total += value
            weighted_x += x * value
            weighted_y += y * value
    if total == 0:
        return None
    return weighted_x / total, weighted_y / total


def _motion_presence(frames: list[Image.Image]) -> float:
    if len(frames) < 2:
        return 0.0
    values: list[float] = []
    for left, right in zip(frames, frames[1:]):
        a = left.convert("RGBA").resize((64, 64), Image.Resampling.BILINEAR)
        b = right.convert("RGBA").resize((64, 64), Image.Resampling.BILINEAR)
        diff = ImageChops.difference(a, b)
        total = 0
        for pixel in diff.getdata():
            total += pixel[0] + pixel[1] + pixel[2] + pixel[3]
        values.append(total / (64 * 64 * 4 * 255))
    return mean(values) if values else 0.0


def _similarity_summary(frames: list[Image.Image]) -> dict[str, Any]:
    histograms = [_rgb_histogram(frame) for frame in frames]
    hashes = [_dhash(frame) for frame in frames]
    hist_pairs = [
        histogram_intersection(histograms[i], histograms[j])
        for i in range(len(histograms))
        for j in range(i + 1, len(histograms))
    ]
    dhash_pairs = [
        dhash_similarity(hashes[i], hashes[j])
        for i in range(len(hashes))
        for j in range(i + 1, len(hashes))
    ]
    centroids = [_alpha_centroid(frame) for frame in frames]
    xs = [point[0] for point in centroids if point is not None]
    ys = [point[1] for point in centroids if point is not None]
    return {
        "histogram_intersection": {
            "min": min(hist_pairs) if hist_pairs else 1.0,
            "mean": mean(hist_pairs) if hist_pairs else 1.0,
        },
        "dhash_similarity": {
            "min": min(dhash_pairs) if dhash_pairs else 1.0,
            "mean": mean(dhash_pairs) if dhash_pairs else 1.0,
        },
        "motion_presence": _motion_presence(frames),
        "centroid_sigma": {
            "x": pstdev(xs) if len(xs) > 1 else 0.0,
            "y": pstdev(ys) if len(ys) > 1 else 0.0,
        },
    }


def _manifest_state_notes(run_dir: Path, state: str) -> tuple[dict[str, Any] | None, list[str], list[str]]:
    """Per-state manifest row + failure notes for `state`, gathered from two sources:

    - `frames/frames-manifest.json` — the current COMPLETE generation (only ever published
      on a successful extract, so it carries the row for a good state, no failure errors).
    - `extract-failure.json` — the last failed extract's per-state diagnostics, written
      OUTSIDE canonical frames/ because a failed extract publishes no partial generation
      (whole-generation atomicity). This is the signal the automatic correction loop needs to
      know *which state failed and why* and drive error-driven regeneration; a successful
      extract removes it, so it never re-flags a now-good state.

    The row comes only from the published manifest (real frames); errors/warnings merge both."""
    manifest_row: dict[str, Any] | None = None
    state_errors: list[str] = []
    state_warnings: list[str] = []

    def _collect(manifest: dict, take_row: bool) -> None:
        nonlocal manifest_row
        if not manifest:
            return
        prefix = f"{state}:"
        for message in manifest.get("errors", []):
            text = str(message)
            if text.startswith(prefix) and text not in state_errors:
                state_errors.append(text)
        for message in manifest.get("warnings", []):
            text = str(message)
            if text.startswith(prefix) and text not in state_warnings:
                state_warnings.append(text)
        if take_row and manifest_row is None:
            for row in manifest.get("rows", []):
                if row.get("state") == state:
                    manifest_row = row
                    break

    # fail-loud on a corrupt/broken canonical record (No Silent Fallback), {} only if absent
    _collect(extract.load_frames_manifest(run_dir / "frames" / "frames-manifest.json"), take_row=True)
    _collect(extract.load_failure_evidence(run_dir / "extract-failure.json"), take_row=False)
    return manifest_row, state_errors, state_warnings


def inspect_run(run_dir: Path, states: str = "all", **kwargs: object) -> dict[str, Any]:
    """Inspect the run holding a shared read_guard, so the combined read of frames/,
    frames-manifest.json, and extract-failure.json sees ONE consistent snapshot — never a
    mid-publish mix of a newly-swapped frames generation with a stale failure record. The
    correction loop reads through here, so its diagnostics stay isolated from a concurrent
    extract commit (which advances both surfaces under the matching publish_guard)."""
    with read_guard(Path(run_dir).expanduser().resolve()):
        return _inspect_run_impl(run_dir, states=states, **kwargs)


def _inspect_run_impl(run_dir: Path, states: str = "all", **kwargs: object) -> dict[str, Any]:
    args = namespace_from_kwargs(_build_parser(), dict(run_dir=run_dir, states=states, no_write=True, **kwargs))
    run_dir = args.run_dir.expanduser().resolve()
    # Fail loud on a corrupt/inconsistent generation or orphan frames (frames with no manifest) —
    # otherwise the correction loop would read stale frames as ok:true (No Silent Fallback). A run
    # with no generation at all ({}) is fine: inspect falls back to raw-projection below.
    extract.load_consistent_frames_manifest(run_dir)
    request = load_request(run_dir)
    selected = _state_list(request, args.states)
    rows: list[dict[str, Any]] = []
    errors: list[str] = []
    warnings: list[str] = []

    for state in selected:
        expected = state_frame_total(request, state)
        frames, files = _load_extracted_frames(run_dir, state, request)
        source = "frames"
        natural_found: int | None = None
        if not frames:
            strip = _strip_for_state(run_dir, request, state, args)
            if strip is None:
                row = {
                    "state": state,
                    "source": "missing",
                    "expected_frames": expected,
                    "found_frames": 0,
                    "natural_pose_count": 0,
                    "ok": False,
                    "errors": [f"{state}: missing extracted frames and raw strip"],
                    "warnings": [],
                }
                rows.append(row)
                errors.extend(row["errors"])
                continue
            frames, natural_found = _frames_from_raw(strip, expected, request)
            source = "raw-projection"

        found = len(frames) if source == "frames" else int(natural_found or len(frames))
        row_errors: list[str] = []
        row_warnings: list[str] = []
        if found != expected:
            row_errors.append(f"{state}: expected {expected} frame(s), inspect found {found}")
        manifest_row, manifest_errors, manifest_warnings = _manifest_state_notes(run_dir, state)
        row_errors.extend(manifest_errors)
        row_warnings.extend(manifest_warnings)
        if manifest_row is not None:
            row_errors.extend(str(error) for error in manifest_row.get("errors", []))
            row_warnings.extend(str(warning) for warning in manifest_row.get("warnings", []))
        metrics = _similarity_summary(frames)
        if args.histogram_min > 0 and metrics["histogram_intersection"]["min"] < args.histogram_min:
            row_warnings.append(
                f"{state}: RGB histogram identity similarity is low "
                f"({metrics['histogram_intersection']['min']:.3f} < {args.histogram_min:.3f})"
            )
        if metrics["dhash_similarity"]["min"] < args.dhash_min:
            row_warnings.append(
                f"{state}: dHash silhouette similarity is low "
                f"({metrics['dhash_similarity']['min']:.3f} < {args.dhash_min:.3f})"
            )
        if metrics["motion_presence"] < args.motion_min:
            row_warnings.append(
                f"{state}: motion presence is too low "
                f"({metrics['motion_presence']:.4f} < {args.motion_min:.4f})"
            )
        row = {
            "state": state,
            "source": source,
            "expected_frames": expected,
            "found_frames": found,
            "natural_pose_count": natural_found if natural_found is not None else found,
            "frame_files": files,
            "metrics": metrics,
            "ok": not row_errors,
            "errors": row_errors,
            "warnings": row_warnings,
        }
        rows.append(row)
        errors.extend(row_errors)
        warnings.extend(row_warnings)

    return {
        "ok": not errors,
        "engine": "component-row",
        "kind": "sprite-gen-inspect-report",
        "run_dir": str(run_dir),
        "states": selected,
        "thresholds": {
            "histogram_min": args.histogram_min,
            "dhash_min": args.dhash_min,
            "motion_min": args.motion_min,
        },
        "rows": rows,
        "errors": errors,
        "warnings": warnings,
    }


def _run(args: argparse.Namespace) -> int:
    run_dir = args.run_dir.expanduser().resolve()
    report = inspect_run(
        run_dir,
        states=args.states,
        histogram_min=args.histogram_min,
        dhash_min=args.dhash_min,
        motion_min=args.motion_min,
        key_threshold=args.key_threshold,
        fringe_key_threshold=args.fringe_key_threshold,
        fringe_delta=args.fringe_delta,
        fringe_unmix_reach=args.fringe_unmix_reach,
        spill_max_fraction=args.spill_max_fraction,
        chroma_mode=args.chroma_mode,
        decontam=args.decontam,
    )
    if not args.no_write:
        acquire_run_dir_lock(run_dir, "inspect_sprite_run")
        atomic_write_text(run_dir / args.report, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
    print(json.dumps({k: v for k, v in report.items() if k != "rows"}, ensure_ascii=False, indent=2))
    return 0 if report["ok"] else 1


def run(**kwargs: object) -> int:
    return _run(namespace_from_kwargs(_build_parser(), kwargs))


def main() -> int:
    utf8_streams()
    return _run(_build_parser().parse_args())


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