Skip to content

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

17.3 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Byte receipts for extracted source files and a deliberately exact loop projection.

A receipt is not a declaration that a loop matches its source. ``project`` must
also reproduce every unmodified delivered cell before any source pixel is used.
Unsupported processing stays unknown; malformed or changed inputs are errors.
"""

from __future__ import annotations

import io
import json
import math
import platform
import subprocess
from dataclasses import dataclass
from pathlib import Path
from typing import Any

from PIL import Image, __version__ as pillow_version

from sprite_gen._deps import np
from sprite_gen.video import evidence
from sprite_gen.util.resample import resize_cell

KIND = "sprite-gen-video-source-manifest"
RECIPE = "scrub-specks-body-ramp-union-v1"


def timestamps(clip: Path, stream_index: int) -> list[float]:
    """Presentation timestamps from the actual picture stream, not index / fps."""
    from sprite_gen.video.frames import _require
    proc = subprocess.run([_require("ffprobe"), "-v", "error", "-select_streams", str(stream_index),
                           "-show_entries", "frame=best_effort_timestamp_time", "-of", "json", str(clip)],
                          capture_output=True, text=True, timeout=60)
    if proc.returncode:
        raise ValueError(f"cannot read source timestamps: {proc.stderr[:300]}")
    return [float(row["best_effort_timestamp_time"]) for row in json.loads(proc.stdout)["frames"]]


def artifact(data: bytes) -> dict[str, Any]:
    return {"sha256": evidence.digest(data), "bytes": len(data)}


INPUTS = ("source_manifest", "source_frames_dir", "source_clip", "source_canvas", "source_frames_report")


def add_inputs(parser: Any, *, required: bool = True) -> None:
    for name in INPUTS:
        parser.add_argument("--" + name.replace("_", "-"), type=Path, required=required)


def input_paths(kwargs: dict[str, Any]) -> dict[str, Path]:
    if any(kwargs.get(k) is None for k in INPUTS):
        raise ValueError("source comparison needs manifest, keyed directory, clip, canvas and frames report")
    return {k: Path(kwargs[k]) for k in INPUTS}


def manifest(*, clip: Path, canvas: Path, frames_report: Path,
             files: list[Path], timestamps: list[float]) -> dict[str, Any]:
    """Record existing extraction output; the caller obtains PTS from the clip."""
    report = json.loads(frames_report.read_bytes())
    if len(files) != len(timestamps) or not files:
        raise ValueError("source timestamp count differs from keyed frame count")
    fps = report["fps"]
    return {"kind": KIND, "schema_version": 1, "receipt_engine": evidence.engine_identity(),
            "receipt_environment": {"python": platform.python_version(), "platform": platform.platform(),
                                    "pillow": pillow_version, "numpy": np.__version__},
            "extraction_engine": report.get("producer"),
            "inputs": {k: artifact(p.read_bytes()) for k, p in
                       (("clip", clip), ("canvas", canvas), ("frames_report", frames_report))},
            "recipe": {k: report.get(k) for k in ("key", "spill", "decontam", "edge_policy", "stream_index")},
            "fps": fps, "source": evidence.source_identity(files, fps),
            "frames": [{"file": p.name, "pts_seconds": t, **artifact(p.read_bytes())}
                       for p, t in zip(files, timestamps)]}


@dataclass
class Source:
    frames: list[Image.Image]
    record: dict[str, Any]
    artifacts: dict[str, Any]

    @classmethod
    def read(cls, *, source_manifest: Path, source_frames_dir: Path, source_clip: Path,
             source_canvas: Path, source_frames_report: Path) -> Source:
        paths = {"manifest": source_manifest, "clip": source_clip, "canvas": source_canvas,
                 "frames_report": source_frames_report}
        data = {k: p.read_bytes() for k, p in paths.items()}
        m = json.loads(data["manifest"])
        report = json.loads(data["frames_report"])
        if not isinstance(m, dict) or m.get("kind") != KIND or m.get("schema_version") != 1:
            raise ValueError("unsupported source manifest")
        if any(m.get("inputs", {}).get(k) != artifact(data[k]) for k in ("clip", "canvas", "frames_report")):
            raise ValueError("source input bytes do not match manifest")
        fps = m.get("fps")
        if (isinstance(fps, bool) or not isinstance(fps, (int, float)) or not math.isfinite(fps)
                or fps <= 0 or fps != report.get("fps")):
            raise ValueError("invalid source fps")
        rows = m.get("frames")
        files = sorted(source_frames_dir.glob("*.png"))
        if (not isinstance(rows, list) or not files or len(files) != len(rows)
                or any(not isinstance(r, dict) for r in rows)
                or [p.name for p in files] != [r.get("file") for r in rows]):
            raise ValueError("source ordered file list differs from manifest")
        images, hashes = [], []
        previous = -math.inf
        for p, r in zip(files, rows):
            blob = p.read_bytes()
            if any(r.get(k) != v for k, v in artifact(blob).items()):
                raise ValueError(f"source frame bytes differ: {p.name}")
            t = r.get("pts_seconds")
            if isinstance(t, bool) or not isinstance(t, (int, float)) or not math.isfinite(t) or t <= previous:
                raise ValueError("source timestamps must be finite and strictly increasing")
            previous = t
            with Image.open(io.BytesIO(blob)) as im:
                if im.format != "PNG":
                    raise ValueError("source must contain PNG frames")
                images.append(im.convert("RGBA"))
            hashes.append(bytes.fromhex(evidence.digest(blob)))
        identity = {"kind": evidence.SOURCE_KIND, "sha256": evidence.digest(b"".join(hashes)),
                    "frames": len(images), "fps": fps}
        if m.get("source") != identity or report.get("frames") != len(images):
            raise ValueError("source sequence identity differs from actual files")
        if any(im.size != images[0].size for im in images):
            raise ValueError("source frame sizes differ")
        if images[0].size != (report.get("width"), report.get("height")):
            raise ValueError("source dimensions differ from extraction report")
        actual_pts = timestamps(source_clip, report["stream_index"])
        if actual_pts != [r["pts_seconds"] for r in rows]:
            raise ValueError("source timestamps differ from actual clip")
        if m.get("recipe") != {k: report.get(k) for k in ("key", "spill", "decontam", "edge_policy", "stream_index")}:
            raise ValueError("source recipe differs from extraction report")
        return cls(images, m, {k: artifact(b) for k, b in data.items()})


@dataclass
class Projection:
    frames: list[Image.Image]
    record: dict[str, Any]
    cropped: list[Image.Image]  # what each cell was resampled from: the held, cleaned, ramped source frame cut to the crop


def _cut_moves(hold: dict[str, Any], n: int) -> tuple[list[dict[str, Any]], tuple[int, int, int, int]]:
    """The move each frame of a held fixed cut was held by (`size_hold.cut_frames`, `gait_fallback.frame_hold`) and the
    room every frame was widened by (`padding_ltrb`): one move per frame of the cut, in order."""
    moves, pad = hold.get("cut_frames"), hold.get("padding_ltrb")

    def number(v: Any) -> bool:
        return type(v) in (int, float) and math.isfinite(v)

    if (not isinstance(moves, list) or len(moves) != n or not isinstance(pad, list) or len(pad) != 4
            or any(type(v) is not int or v < 0 for v in pad)
            or any(not isinstance(move, dict) or set(move) != {"scale", "foot_point_px", "lift_px"}
                   or not number(move["scale"]) or move["scale"] <= 0
                   or not isinstance(move["foot_point_px"], list) or len(move["foot_point_px"]) != 2
                   or not all(number(v) for v in move["foot_point_px"])
                   or not (move["lift_px"] is None or number(move["lift_px"])) for move in moves)):
        raise ValueError("invalid size_hold.cut_frames")
    return moves, tuple(pad)  # type: ignore[return-value]


def project(baseline: Any, source: Source) -> tuple[Projection | None, str | None]:
    """Prove one shared crop against all cells outside the recorded repair hints. A fixed cut held at its size
    (`size_hold`) is read on its source frames held again, each by the move its report records for it."""
    from sprite_gen.video import gait_fallback, loop
    from sprite_gen.video.frames import drop_specks

    m, report = baseline.meta, baseline.source_report
    if report.get("kind") != loop.REPORT_KIND or report.get("status") != loop.REPORT_PASSED:
        return None, "source-report-unverified"
    if loop.sway_recorded(m):
        return None, "follow-source-warp-unverified"
    n = len(baseline.frames)
    cycle = report.get("cycle", {})
    start, length = cycle.get("start"), cycle.get("length")
    if (type(start) is not int or type(length) is not int or start < 0 or length != n
            or n < 3 or start + n > len(source.frames) or m.get("subsampled") is not False
            or m.get("cycle_frames") != n or m.get("loop") is not True):
        return None, "source-schedule-unsupported"
    if m.get("sample_indices", list(range(n))) != list(range(n)):
        return None, "source-samples-mismatch"
    for drawings in (m.get("cycle_drawings"), report.get("cycle_drawings")):
        if drawings is not None and (drawings.get("start") != start or drawings.get("length") != n):
            return None, "source-drawings-mismatch"
    reported = report.get("strip")
    if not isinstance(reported, dict) or any(m.get(k) != reported.get(k) for k in
            ("frames", "w", "h", "delay_ms", "cycle_seconds", "scale", "source_rect", "foot_anchor", "wrap_dx_px")):
        return None, "source-geometry-inconsistent"
    fps = source.record["fps"]
    if (report.get("fps") != fps or report.get("frames_total") != len(source.frames)
            or baseline.timing_issue() or abs(m["cycle_seconds"] - n / fps) > .00005 + 1e-9):
        return None, "source-timing-unverified"
    pts = [row["pts_seconds"] for row in source.record["frames"]]
    if any(abs((b - a) - 1 / fps) > 1e-5 for a, b in zip(pts, pts[1:])):
        return None, "nonuniform-source-timing-unsupported"
    if report.get("source") is not None and report["source"] != source.record["source"]:
        return None, "source-sequence-mismatch"
    if "source_cut" in m and m["source_cut"] != {
            "source": source.record["source"], "start": start, "length": n,
            "samples": list(range(start, start + n))}:
        return None, "source-samples-mismatch"
    anchor = m.get("foot_anchor")
    if anchor not in ("none", "body") or report.get("anchor") != anchor:
        return None, "source-anchor-unsupported"
    hold = report.get("size_hold", {})
    # A held cut is read again only where its report records each frame's move, and the cut's frames before repair to
    # prove every one of them on (`source_projection`, the moves of the cells the repair replaced included).
    held = bool(hold.get("applied"))
    # A cut whose held cells were made again (`held_fill`), or whose cells are times of their own (`out_fps`, an air
    # retimed: `air_retime`), shows frames the source does not hold.
    if (any(k in m for k in ("cycle_align", "motion_anchor", "wrap_blend", "out_fps")) or (m.get("held_fill") or {}).get("made")
            or (m.get("air_retime") or {}).get("applied")
            or held and ("cut_frames" not in hold or report.get("source_projection") is None)):
        return None, "source-processing-unsupported"
    moves, pad = _cut_moves(hold, n) if held else (None, None)
    hints = (report.get("jump_repair") or {}).get("replaced", [])
    if (not isinstance(hints, list) or any(type(k) is not int or not 0 <= k < n for k in hints)
            or len(set(hints)) != len(hints) or len(hints) > n // 2):
        return None, "repair-locations-unverified"
    keep = [k for k in range(n) if k not in hints]
    frames = []
    for j, frame in enumerate(source.frames[start:start + n]):
        frame = gait_fallback.hold_frame(frame, moves[j], pad) if moves else frame.copy()
        loop._scrub(frame)
        frames.append(drop_specks(frame, alpha_over=16, diagonal=False, apart=0)[0])
    dx = loop.body_wrap_offset(frames) if anchor == "body" else 0
    if anchor == "body" and m.get("wrap_dx_px") != dx:
        return None, "source-anchor-mismatch"
    frames = loop.ramp_frames(frames, dx)
    native = report.get("source_projection")
    if native is not None and (native.get("recipe") != RECIPE or native.get("wrap_dx_px") != dx
            or native.get("before_repair_pixels_sha256") != [evidence.digest(f.tobytes()) for f in frames]):
        return None, "source-processing-receipt-mismatch"
    boxes = [frames[k].getchannel("A").point(lambda v: 255 if v >= 8 else 0).getbbox() for k in keep]
    if any(b is None for b in boxes):
        return None, "empty-source-subject"
    w, h = m["w"], m["h"]
    rect = m.get("source_rect")
    if rect is not None:
        if (not isinstance(rect, list) or len(rect) != 4 or any(type(v) is not int for v in rect)
                or rect[2] <= rect[0] or rect[3] <= rect[1]):
            raise ValueError("invalid source_rect")
        candidates = [rect]
    else:
        # A legacy strip omits the crop. Bounds come only from its recorded scale
        # recipe, frame canvas and the union of the known unmodified subjects.
        target, standing, cap, top = (m.get(k) for k in
                                     ("body_height_target", "body_src_h", "cell_height_cap", "top_margin_px"))
        if any(type(v) is not int or v <= 0 for v in (target, standing, cap)) or type(top) is not int or top < 0:
            return None, "legacy-projection-recipe-missing"
        left_max, right_min = min(b[0] for b in boxes) - 8, max(b[2] for b in boxes) + 8
        candidates = []
        for bottom in range(max(b[3] for b in boxes), frames[0].height + 1):
            if bottom <= top:
                continue
            scale = min(cap / (bottom - top), target / standing)
            if round(scale, 4) != m.get("scale") or round((bottom - top) * scale) != h:
                continue
            for width in range(max(1, math.floor((w - .5) / scale)), math.ceil((w + .5) / scale) + 1):
                if round(width * scale) != w:
                    continue
                for left in range(max(-8, right_min - width), left_max + 1):
                    if left + width <= frames[0].width + 8:
                        candidates.append([left, top, left + width, bottom])
                        if len(candidates) > 4096:
                            return None, "legacy-projection-search-budget"
    hits = []
    for crop in candidates:
        if all(resize_cell(frames[k].crop(crop), (w, h)).tobytes() == baseline.frames[k].tobytes() for k in keep):
            hits.append(crop)
            if len(hits) > 1:
                return None, "legacy-projection-ambiguous"
    if not hits:
        return None, "legacy-source-correspondence-unverified"
    crop = hits[0]
    cropped = [frame.crop(crop) for frame in frames]
    projected = [resize_cell(frame, (w, h)) for frame in cropped]
    receipt = {"recipe": RECIPE, "crop": crop, "cell": [w, h], "wrap_dx_px": dx,
               "source": source.record["source"], "inputs": source.artifacts,
               "measurement_engine": evidence.engine_identity(),
               "scale_xy": [w / (crop[2] - crop[0]), h / (crop[3] - crop[1])],
               "samples": list(range(start, start + n)), "pts_seconds": pts[start:start + n],
               "unmodified_cells": keep, "repair_hints": hints, "exact_projections": 1,
               "reference_pixels_sha256": [evidence.digest(f.tobytes()) for f in projected]}
    if moves:
        receipt["size_hold"] = {"padding_ltrb": list(pad), "cut_frames": moves}
    return Projection(projected, receipt, cropped), None


def add_arguments(parser: Any) -> None:
    for name in ("clip", "canvas", "frames_report", "frames_dir", "out"):
        parser.add_argument("--" + name.replace("_", "-"), type=Path, required=True)


def run(**kwargs: Any) -> int:
    """Receipt existing keyed output without repeating extraction; not a source attestation."""
    from sprite_gen.spec.runio import atomic_write_text, refuse_overlap
    clip, canvas, report, directory, out = (Path(kwargs[k]) for k in
                                           ("clip", "canvas", "frames_report", "frames_dir", "out"))
    files = sorted(directory.glob("*.png"))
    try:
        # The manifest is written once every input is read: no input is that file (`runio.refuse_overlap`).
        refuse_overlap({"--clip": clip, "--canvas": canvas, "--frames-report": report, "--frames-dir": directory,
                        **{f"{f.name} in --frames-dir": f for f in files}}, {"--out": out}, verb="video-source-manifest")
        record = manifest(clip=clip, canvas=canvas, frames_report=report, files=files,
                          timestamps=timestamps(clip, json.loads(report.read_bytes())["stream_index"]))
        out.parent.mkdir(parents=True, exist_ok=True)
        atomic_write_text(out, json.dumps(record, indent=2, allow_nan=False) + "\n")
    except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as exc:
        raise SystemExit(f"video-source-manifest: {exc}") from exc
    print(json.dumps({"manifest": str(out), "source": record["source"]}))
    return 0