Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# SPDX-License-Identifier: Apache-2.0
"""Compare final loop artifacts, with explicit limits on what can be ordered.
No quality values from an upstream loop report are used. That report supplies
source provenance only; follow-through may have changed every delivered pixel.
The v1 order is deliberately narrow: same source samples, timing and coordinates,
with unchanged coverage to prove preservation of the filmed silhouette motion.
"""
from __future__ import annotations
import argparse
import io
import json
import math
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from PIL import Image
from sprite_gen._deps import np
from sprite_gen.spec.runio import atomic_write_text, refuse_overlap
from sprite_gen.video import evidence, repair, rife, sway
from sprite_gen.video import loop as loop_mod
from sprite_gen.video.interpolation_quality import faults
METRIC_VERSION = "same-sample-defects-v1"
KIND = "sprite-gen-video-loop-comparison"
def _number(value: Any) -> bool:
return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
def _positive_int(value: Any, name: str) -> int:
if not isinstance(value, int) or isinstance(value, bool) or value < 1:
raise ValueError(f"{name} must be a positive integer")
return value
def _json(data: bytes, name: str) -> dict[str, Any]:
value = json.loads(data)
if not isinstance(value, dict):
raise ValueError(f"{name} must be a JSON object")
return value
@dataclass
class Loop:
frames: list[Image.Image]
meta: dict[str, Any]
source_report: dict[str, Any]
artifacts: dict[str, Any]
delay: float | None
@classmethod
def read(cls, strip: Path, meta: Path, report: Path) -> Loop:
# Read each artifact once. Hash and measure the same snapshot, including JSON whitespace.
data = {k: p.read_bytes() for k, p in (("strip", strip), ("meta", meta), ("report", report))}
m, r = _json(data["meta"], "meta"), _json(data["report"], "report")
n, w, h = (_positive_int(m.get(k), k) for k in ("frames", "w", "h"))
with Image.open(io.BytesIO(data["strip"])) as im:
if im.format != "PNG" or im.size != (n * w, h) or getattr(im, "n_frames", 1) != 1:
raise ValueError("strip must be a single PNG whose size agrees with meta frames/w/h")
sheet = im.convert("RGBA")
frames = [sheet.crop((k * w, 0, (k + 1) * w, h)) for k in range(n)]
if any(not f.getchannel("A").getbbox() for f in frames):
raise ValueError("strip contains a fully transparent frame")
delay = m.get("delay_ms")
if delay is not None and (not _number(delay) or delay <= 0):
raise ValueError("delay_ms must be finite and positive")
artifacts = {k: {"sha256": evidence.digest(b), "bytes": len(b)} for k, b in data.items()}
return cls(frames, m, r, artifacts, delay)
def timing_issue(self) -> str | None:
if self.delay is None:
return "timing-missing"
if "durations_ms" in self.meta:
return "nonuniform-timing-unsupported"
seconds = self.meta.get("cycle_seconds")
if not _number(seconds):
return "cycle-duration-missing"
# The writer rounds delay_ms to .01 ms and cycle_seconds to .0001 s.
if abs(seconds * 1000 - self.delay * len(self.frames)) > .005 * len(self.frames) + .05 + 1e-9:
return "timing-inconsistent"
return None
def provenance_issue(self) -> str | None:
cut = self.meta.get("source_cut")
src = self.source_report.get("source")
cycle = self.source_report.get("cycle")
if not all(isinstance(v, dict) for v in (cut, src, cycle)):
return "source-provenance-missing"
if self.source_report.get("kind") != loop_mod.REPORT_KIND or self.source_report.get("status") != loop_mod.REPORT_PASSED:
return "source-report-unverified"
sha = src.get("sha256")
if (src.get("kind") != evidence.SOURCE_KIND or not isinstance(sha, str) or len(sha) != 64
or any(c not in "0123456789abcdef" for c in sha)
or not isinstance(src.get("frames"), int) or isinstance(src["frames"], bool) or src["frames"] < 1
or not _number(src.get("fps")) or src["fps"] <= 0):
return "source-provenance-invalid"
start, length, samples = cut.get("start"), cut.get("length"), cut.get("samples")
if (not isinstance(start, int) or isinstance(start, bool) or start < 0
or not isinstance(length, int) or isinstance(length, bool) or length < 2
or start + length > src["frames"] or not isinstance(samples, list)
or len(samples) != len(self.frames) or any(not isinstance(k, int) or isinstance(k, bool) for k in samples)
or samples != sorted(set(samples)) or any(k < start or k >= start + length for k in samples)):
return "source-samples-unverified"
if (cut.get("source") != src or cycle.get("start") != start or cycle.get("length") != length
or self.source_report.get("fps") != src["fps"] or self.source_report.get("frames_total") != src["frames"]):
return "source-provenance-inconsistent"
if self.meta.get("cycle_frames") != length:
return "source-samples-unverified"
expected = [start + round(k * length / len(samples)) for k in range(len(samples))]
if samples != expected:
return "source-samples-unverified"
if not _number(self.meta.get("cycle_seconds")) or abs(self.meta["cycle_seconds"] - length / src["fps"]) > .00005 + 1e-9:
return "source-timing-inconsistent"
if "cycle_align" in self.meta:
return "aligned-source-phase-unverified"
if self.meta.get("loop") is not True:
return "loop-playback-unverified"
rect = self.meta.get("source_rect")
if rect is not None and (not isinstance(rect, list) or len(rect) != 4 or not all(_number(v) for v in rect)
or rect[2] <= rect[0] or rect[3] <= rect[1]):
return "source-geometry-invalid"
reported_strip = self.source_report.get("strip")
if not isinstance(reported_strip, dict) or any(self.meta.get(k) != reported_strip.get(k)
for k in ("w", "h", "frames", "scale", "source_rect", "foot_anchor")):
return "source-geometry-inconsistent"
return None
def describe(self) -> dict[str, Any]:
return {"artifacts": self.artifacts, "frames": len(self.frames), "cell": list(self.frames[0].size),
"timing": {"delay_ms": self.delay, "duration_ms": self.delay * len(self.frames) if self.delay else None},
"source_cut": self.meta.get("source_cut"), "producer": self.source_report.get("producer"),
"gait": self.source_report.get("gait"), "follow": loop_mod.sway_recorded(self.meta),
"pixels_sha256": evidence.digest(b"".join(f.tobytes() for f in self.frames))}
def _measure(loop: Loop) -> dict[str, Any]:
frames = loop.frames
rgba = [np.asarray(f, dtype=np.float64) / 255 for f in frames]
# Fixed native cell area; no private per-cut median in the denominator.
premul = [np.dstack((a[..., :3] * a[..., 3:], a[..., 3])) for a in rgba]
seam = float(np.abs(premul[-1] - premul[0]).mean())
quality = [rife.smear(f, frames[k - 1], frames[(k + 1) % len(frames)]) for k, f in enumerate(frames)]
body: dict[str, Any]
try:
y, x, height, worn = sway.body_motion(frames)
body = {"x_px": x.tolist(), "y_px": y.tolist(), "height_px": height, "worn_px": worn}
except ValueError as exc:
body = {"unknown": str(exc)}
try:
head = repair.head_track([a[..., 3] for a in rgba])
except ValueError as exc:
head = {"unknown": str(exc)}
return {"seam": {"premultiplied_rgba_mae": seam,
"per_second": seam * 1000 / loop.delay if loop.delay else None},
"interpolation": {"frames": quality, "faults": [faults(q) for q in quality]},
"body_motion": body, "top_band_motion": head}
def _axis(a: Any, b: Any, comparable: bool, reason: str, status: str = "unknown") -> dict[str, Any]:
return {"baseline": a, "candidate": b, "comparable": comparable, "reason": reason, "status": status}
def _order(a: list[float], b: list[float]) -> str:
# No tradeoffs/averaging: one worsening component is a regression.
delta = np.asarray(b) - np.asarray(a)
if (delta > 1e-9).any():
return "regressed"
return "improved" if (delta < -1e-9).any() else "non_regressing"
def compare(baseline: Loop, candidate: Loop) -> dict[str, Any]:
a, b = baseline, candidate
ma, mb = _measure(a), _measure(b)
reasons = []
for side, loop in (("baseline", a), ("candidate", b)):
for issue in (loop.timing_issue(), loop.provenance_issue()):
if issue:
reasons.append(f"{side}:{issue}")
same_samples = (not reasons and a.meta["source_cut"] == b.meta["source_cut"])
if not reasons and not same_samples:
reasons.append("different-source-samples-phase-unverified")
same_timing = a.delay == b.delay and len(a.frames) == len(b.frames)
if not same_timing:
reasons.append("different-timing")
# A fixed crop and scale put both arrays in the same coordinate system. Per-frame
# foot anchoring or an unrecorded/legacy crop cannot establish this.
geometry_keys = ("w", "h", "source_rect", "scale", "foot_anchor")
same_geometry = (all(k in a.meta and k in b.meta and a.meta[k] == b.meta[k] for k in geometry_keys)
and isinstance(a.meta.get("source_rect"), list) and len(a.meta["source_rect"]) == 4
and _number(a.meta.get("scale")) and a.meta["scale"] > 0)
if not same_geometry:
reasons.append("spatial-basis-unverified")
comparable = bool(same_samples and same_timing and same_geometry and not reasons)
same_coverage = (comparable and all(x.getchannel("A").tobytes() == y.getchannel("A").tobytes()
for x, y in zip(a.frames, b.frames)))
same_pixels = comparable and all(x.tobytes() == y.tobytes() for x, y in zip(a.frames, b.frames))
changed = [k for k, (x, y) in enumerate(zip(a.frames, b.frames)) if x.tobytes() != y.tobytes()] if comparable else []
# A smaller seam may just be a flattened drawing. Only frames with a pre-existing
# shared interpolation fault may change for an automatic improvement claim.
confined = comparable and all(ma["interpolation"]["faults"][k] for k in changed)
cleared = comparable and all(not mb["interpolation"]["faults"][k] for k in changed)
axes = {
"phase": _axis(a.meta.get("source_cut"), b.meta.get("source_cut"), bool(same_samples),
"same-source-samples" if same_samples else "source-phase-unverified",
"non_regressing" if same_samples else "unknown"),
"silhouette_motion": _axis("coverage-as-delivered", "coverage-as-delivered", comparable,
"identical-coverage-preserves-bob-and-pose" if same_coverage else "changed-coverage-pose-preservation-unverified",
"non_regressing" if same_coverage else "unknown"),
"body_motion": _axis(ma["body_motion"], mb["body_motion"], comparable and all("unknown" not in m["body_motion"] for m in (ma, mb)),
"observation-only-less-motion-is-not-better"),
"top_band_motion": _axis(ma["top_band_motion"], mb["top_band_motion"], comparable and all("unknown" not in m["top_band_motion"] for m in (ma, mb)),
"silhouette-top-not-an-identified-head"),
"scale": _axis(a.meta.get("scale"), b.meta.get("scale"), comparable,
"identical-coverage-preserves-size" if same_coverage else "rigid-scale-not-inferred-from-bbox",
"non_regressing" if same_coverage else "unknown"),
"drawing_preservation": _axis([], changed, comparable,
"unchanged-unfaulted-drawings" if confined else "changed-unfaulted-drawings-unverified",
"non_regressing" if confined else "unknown"),
}
seam_status = _order([ma["seam"]["premultiplied_rgba_mae"]], [mb["seam"]["premultiplied_rgba_mae"]]) if comparable else "unknown"
axes["seam"] = _axis(ma["seam"], mb["seam"], comparable, "native-common-canvas-no-relative-denominator", seam_status)
for metric in ("dark_excess", "outline_loss", "partial_excess"):
va, vb = ([max(0.0, q[metric]) for q in m["interpolation"]["frames"]] for m in (ma, mb))
axes[metric] = _axis(va, vb, comparable, "same-sample-excess-beyond-both-neighbours",
_order(va, vb) if comparable else "unknown")
statuses = [axes[k]["status"] for k in ("seam", "dark_excess", "outline_loss", "partial_excess")]
if not comparable:
verdict = "unknown"
elif "regressed" in statuses:
verdict = "regressed"
reasons.extend(f"{k}:regressed" for k, v in axes.items() if v["status"] == "regressed")
elif not same_coverage:
verdict = "unknown"
reasons.append("changed-coverage-pose-preservation-unverified")
elif same_pixels:
verdict = "non_regressing"
reasons.append("identical-pixels-and-timing")
elif not confined:
verdict = "unknown"
reasons.append("changed-unfaulted-drawings-unverified")
elif not cleared:
verdict = "unknown"
reasons.append("interpolation-fault-remains")
elif "improved" in statuses:
verdict = "improved"
reasons.append("measured-defect-reduced-with-motion-preserved")
else:
verdict = "non_regressing"
reasons.append("no-measured-defect-improvement")
return {"kind": KIND, "schema_version": 1, "metric_version": METRIC_VERSION,
"measurement_engine": evidence.engine_identity(), "verdict": verdict, "reasons": reasons,
"baseline": a.describe(), "candidate": b.describe(), "axes": axes,
"limits": ["same-sample defect comparison, not overall animation quality",
"own-foot identity and intended drawing changes are not certified",
"changed coverage requires pose review; no motion flattening or resampling"]}
def add_arguments(parser: argparse.ArgumentParser) -> None:
for side in ("baseline", "candidate"):
for artifact in ("strip", "meta", "report"):
parser.add_argument(f"--{side}-{artifact}", required=True, type=Path)
for artifact in ("gif", "webp"):
parser.add_argument(f"--{side}-{artifact}", type=Path)
from sprite_gen.video import restoration, source
for artifact in restoration.ARTIFACTS:
parser.add_argument(f"--origin-{artifact}", type=Path)
source.add_inputs(parser, required=False)
parser.add_argument("--repair-evidence", type=Path)
parser.add_argument("--report", required=True, type=Path)
def run(**kwargs: Any) -> int:
output = Path(kwargs["report"])
paths = {s: {k: Path(kwargs[f"{s}_{k}"]) for k in ("strip", "meta", "report")} for s in ("baseline", "candidate")}
try:
from sprite_gen.video import restoration, source
origin = {k: kwargs.get(f"origin_{k}") for k in restoration.ARTIFACTS}
restoration_mode = any(kwargs.get(k) is not None for k in (*source.INPUTS, "repair_evidence")) or any(origin.values())
protected: dict[str, Path] = {}
if restoration_mode:
inputs = source.input_paths(kwargs)
# The origin is never guessed from the current baseline, not even on a first request.
if (any(kwargs.get(f"{s}_{k}") is None for s in paths for k in ("gif", "webp"))
or None in origin.values() or not kwargs.get("repair_evidence")):
raise ValueError("source comparison requires the origin's five files, baseline/candidate GIF and WebP, and repair evidence")
for side in paths:
paths[side].update({k: Path(kwargs[f"{side}_{k}"]) for k in ("gif", "webp")})
paths["origin"] = {k: Path(p) for k, p in origin.items()}
evidence_path = Path(kwargs["repair_evidence"])
protected.update({"--" + k.replace("_", "-"): p for k, p in inputs.items()})
protected.update({f"{p.name} in --source-frames-dir": p for p in inputs["source_frames_dir"].glob("*.png")})
protected["--repair-evidence"] = evidence_path
elif any(kwargs.get(f"{s}_{k}") for s in paths for k in ("gif", "webp")):
raise ValueError("playback comparison requires source inputs and repair evidence")
# The report is written once every artifact is read: no input is that file (`runio.refuse_overlap`).
refuse_overlap({**{f"--{side}-{k}": p for side, row in paths.items() for k, p in row.items()}, **protected},
{"--report": output}, verb="video-loop-compare")
if restoration_mode:
a, ap = restoration.read_loop(paths["baseline"])
b, bp = restoration.read_loop(paths["candidate"])
payload = restoration.compare(restoration.read_loop(paths["origin"])[0], a, b, source.Source.read(**inputs),
baseline_playback=ap, candidate_playback=bp,
repair_evidence=_json(evidence_path.read_bytes(), "repair evidence"))
else:
payload = compare(Loop.read(**paths["baseline"]), Loop.read(**paths["candidate"]))
text = json.dumps(payload, indent=2, allow_nan=False) + "\n"
output.parent.mkdir(parents=True, exist_ok=True)
atomic_write_text(output, text)
except (OSError, ValueError, TypeError) as exc:
raise SystemExit(f"video-loop-compare: {exc}") from exc
print(text, end="")
return 0