Skip to content

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

6.4 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Score sprite inspection reports and produce correction hints."""

from __future__ import annotations

import argparse
import json
from pathlib import Path
from statistics import mean
from typing import Any

from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.spec.runio import atomic_write_text
from sprite_gen.util.console import utf8_streams


def _unique(items: list[str]) -> list[str]:
    seen: set[str] = set()
    result: list[str] = []
    for item in items:
        if item in seen:
            continue
        seen.add(item)
        result.append(item)
    return result


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--inspect-report", required=True, type=Path)
    parser.add_argument("--output", default="sprite-score.report.json")
    parser.add_argument("--no-write", action="store_true")
    return parser


def _hint_for_row(row: dict[str, Any], *, histogram_min: float, dhash_min: float) -> list[str]:
    state = row["state"]
    expected = int(row.get("expected_frames", 0))
    found = int(row.get("found_frames", 0))
    metrics = row.get("metrics") or {}
    hints: list[str] = []
    if found != expected:
        hints.append(
            f"{state}: The previous strip was read as {found} pose(s), but the request requires exactly "
            f"{expected}. Regenerate as exactly {expected} full-body poses in {expected} equal invisible "
            "horizontal slots. Keep clear gutters between poses; no limbs, props, shadows, or effects may cross a slot boundary."
        )
    hist_min = float((metrics.get("histogram_intersection") or {}).get("min", 1.0))
    if histogram_min > 0 and hist_min < histogram_min:
        hints.append(
            f"{state}: Frame-to-frame color identity drift was detected (RGB histogram similarity {hist_min:.3f}). "
            "Copy the accepted anchor palette, outfit colors, hair color, face markings, and outline weight in every pose."
        )
    row_dhash_min = float((metrics.get("dhash_similarity") or {}).get("min", 1.0))
    if row_dhash_min < dhash_min:
        hints.append(
            f"{state}: Silhouette drift was detected (dHash similarity {row_dhash_min:.3f}). "
            "Keep the same body proportions and camera angle; only change the limb motion needed for this action."
        )
    motion = float(metrics.get("motion_presence", 1.0))
    if motion < 0.01 and expected > 1:
        hints.append(
            f"{state}: Adjacent frames are too similar (motion presence {motion:.4f}). "
            "Make the action visibly progress across the row while preserving the same character identity and foot baseline."
        )
    for message in [*row.get("errors", []), *row.get("warnings", [])]:
        text = str(message)
        if "chroma-adjacent" in text:
            hints.append(
                f"{state}: Visible chroma residue remained after extraction. Use a flat clean chroma background and keep key-colored pixels away from the character."
            )
        elif "edge" in text:
            hints.append(
                f"{state}: Sprite content touched the frame edge. Leave the requested safe margin around every full-body pose."
            )
        elif "pitch" in text or "runlen" in text or "grid" in text:
            hints.append(
                f"{state}: Pixel-grid pitch instability was detected. Regenerate with a clearer true low-resolution pixel grid, or rerun extraction with the runlen crosscheck visible and review the before/after grid proof."
            )
    return hints


def score_inspection(report: dict[str, Any]) -> dict[str, Any]:
    rows: list[dict[str, Any]] = []
    hints: list[str] = []
    thresholds = report.get("thresholds") or {}
    histogram_min = float(thresholds.get("histogram_min", 0.0))
    dhash_min = float(thresholds.get("dhash_min", 0.55))
    for row in report.get("rows", []):
        expected = int(row.get("expected_frames", 0))
        found = int(row.get("found_frames", 0))
        errors = list(row.get("errors", []))
        warnings = list(row.get("warnings", []))
        metrics = row.get("metrics") or {}
        score = 100.0
        if found != expected:
            score -= 35 + 10 * abs(found - expected)
        score -= 13 * len(errors)
        score -= 3 * len(warnings)
        if float(metrics.get("motion_presence", 1.0)) < 0.01 and expected > 1:
            score -= 12
        if float((metrics.get("dhash_similarity") or {}).get("min", 1.0)) < dhash_min:
            score -= 10
        if histogram_min > 0 and float((metrics.get("histogram_intersection") or {}).get("min", 1.0)) < histogram_min:
            score -= 10
        score = max(0.0, min(100.0, score))
        row_hints = _unique(_hint_for_row(row, histogram_min=histogram_min, dhash_min=dhash_min))
        hints.extend(row_hints)
        rows.append(
            {
                "state": row.get("state"),
                "score": round(score, 2),
                "candidate_rank": found * 100 - len(errors) * 10 - len(warnings),
                "expected_frames": expected,
                "found_frames": found,
                "errors": errors,
                "warnings": warnings,
                "hints": row_hints,
            }
        )
    scores = [float(row["score"]) for row in rows]
    return {
        "ok": bool(rows) and all(row["score"] >= 90 and not row["errors"] for row in rows),
        "kind": "sprite-gen-score-report",
        "source_report": report.get("run_dir"),
        "overall_score": round(mean(scores), 2) if scores else 0.0,
        "candidate_rank": sum(int(row["candidate_rank"]) for row in rows),
        "rows": rows,
        "hints": _unique(hints),
    }


def _run(args: argparse.Namespace) -> int:
    report = json.loads(args.inspect_report.read_text(encoding="utf-8"))
    scored = score_inspection(report)
    if not args.no_write:
        output = Path(args.output)
        if not output.is_absolute():
            output = args.inspect_report.parent / output
        atomic_write_text(output, json.dumps(scored, ensure_ascii=False, indent=2) + "\n")
    print(json.dumps({k: v for k, v in scored.items() if k != "rows"}, ensure_ascii=False, indent=2))
    return 0 if scored["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())