Skip to content

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

19.4 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Read-only adapters for external frames, loop strips and runtime atlases.

The returned sequence is an in-memory snapshot, never another editable asset store.
Durations are seconds; the anchor is in source pixels, defaulting to bottom centre.

Every source file is read from disk exactly once. Frames are decoded and
descriptors parsed from those bytes, and ``fingerprints()`` hashes the very same
bytes, so a file replaced on disk after loading can neither change the frames of
an existing sequence nor make its fingerprints agree with the new file.
"""
from __future__ import annotations

from dataclasses import dataclass, field
import hashlib
from io import BytesIO
import json
import math
from pathlib import Path

from PIL import Image

# An external asset descriptor's kind: ordered frame files with their durations (`effects.shadow` writes one), read
# by `load_asset`.
ASSET_KIND = "sprite-gen-asset"
# The video-set direction sheet's kind: `video-set-sheet` writes it (`set_sheet.KIND` is this name, as set_sheet
# imports this module) and `load_asset` reads a descriptor that says it as one.
SET_SHEET_KIND = "sprite-gen-video-set-sheet"


def finite(value, name: str, *, positive=False) -> float:
    if isinstance(value, bool):
        raise ValueError(f"{name} must be a finite number")
    try:
        result = float(value)
    except (ValueError, TypeError, OverflowError) as exc:
        raise ValueError(f"{name} must be a finite number") from exc
    if not math.isfinite(result) or (positive and result <= 0):
        raise ValueError(f"{name} must be {'positive and ' if positive else ''}finite")
    return result


def sequence_identity(sequence) -> dict:
    """The facts a measurement of ``sequence`` is bound to.

    A consumer that applies a report (for example a scene stride) must find the
    same source, atlas state, frame-rate override, frame count, canvas size,
    anchor and per-frame durations in the sequence it selected, in addition to
    matching ``fingerprints()``. Two states of one atlas share files and hashes
    but not this identity; so do one sequence loaded at two frame rates.
    """
    metadata = getattr(sequence, "metadata", None) or {}
    size = sequence.frames[0].size
    return {
        "source": metadata.get("source"),
        "state": metadata.get("state"),
        "fps_override": metadata.get("fps_override"),
        "frame_count": len(sequence.frames),
        "size": [int(size[0]), int(size[1])],
        "anchor_px": [float(v) for v in sequence.anchor],
        "durations_seconds": [float(v) for v in sequence.durations],
    }


def same_identity(reported, sequence) -> bool:
    """True when ``reported`` (a JSON round trip of ``sequence_identity``) names ``sequence``.

    The effective per-frame durations are compared, not how they were specified:
    a frame-rate override that reproduces the native timing measured the same
    motion. ``fps_override`` stays in the record for readers.
    """
    if not isinstance(reported, dict):
        return False
    expected = sequence_identity(sequence)
    if set(reported) != set(expected):
        return False
    for key in ("source", "state", "frame_count", "size"):
        if reported[key] != expected[key]:
            return False
    a, b = reported["anchor_px"], expected["anchor_px"]
    if not isinstance(a, list) or len(a) != len(b) or not all(_close(x, y) for x, y in zip(a, b)):
        return False
    # A report measured when a strip's cells were read off `delay_ms` rounded to hundredths (0.04167 s for 24 fps)
    # names the same cells read at their exact rate (`frame_seconds`).
    a, b = reported["durations_seconds"], expected["durations_seconds"]
    if not isinstance(a, list) or len(a) != len(b) or not all(_close(x, y) or _close(_snapped_seconds(x), y) for x, y in zip(a, b)):
        return False
    return True


def _close(a, b) -> bool:
    try:
        return math.isclose(float(a), float(b), rel_tol=1e-9, abs_tol=1e-12)
    except (TypeError, ValueError):
        return False


# A cell's time written in milliseconds rounded to hundredths (`video-loop`'s `delay_ms`, 41.67 for 24 fps) that lies
# within SNAP_MS of a whole number of cells a second is that rate's: the rounding drifts a scene a frame late.
SNAP_MS = 0.01


def frame_seconds(delay_ms) -> float:
    """One cell's time, seconds, of a sidecar's `delay_ms`: a value with a fraction of a millisecond within SNAP_MS of
    1000 over a whole number is that rate's exact time (41.67 is 1/24 s); a whole number of milliseconds, and any
    other value, is read as it is."""
    ms = finite(delay_ms, "delay_ms", positive=True)
    if ms != int(ms):
        rate = round(1000 / ms)
        if rate >= 1 and abs(ms - 1000 / rate) <= SNAP_MS:
            return 1 / rate
    return ms / 1000


def _snapped_seconds(value) -> float:
    try:
        return frame_seconds(round(float(value) * 1000, 2))
    except (TypeError, ValueError, OverflowError):
        return float("nan")


@dataclass(frozen=True)
class FrameSequence:
    """An in-memory frame sequence: ``frames, durations, anchor, source_files, metadata``.

    ``anchor`` defaults to the bottom centre of the frame canvas. A sequence
    built from files also carries, keyword-only, the SHA-256 of the bytes each
    source file contributed (``source_digests``, one per ``source_files`` entry);
    a manually constructed sequence that names source files without those
    digests is refused, so nothing unverifiable can pose as file-backed.
    """
    frames: tuple[Image.Image, ...]
    durations: tuple[float, ...]
    anchor: tuple[float, float] | None = None
    source_files: tuple[Path, ...] = ()
    metadata: dict = field(default_factory=dict)
    source_digests: tuple[str, ...] = field(default=(), kw_only=True)

    def __post_init__(self):
        if not self.frames or len(self.frames) != len(self.durations):
            raise ValueError("asset needs one positive duration per frame")
        if any(f.size != self.frames[0].size for f in self.frames):
            raise ValueError("asset frames must share a canvas size")
        for d in self.durations:
            finite(d, "frame duration", positive=True)
        if self.anchor is None:
            object.__setattr__(self, "anchor", (self.frames[0].width / 2, self.frames[0].height))
        if not isinstance(self.anchor, (tuple, list)) or len(self.anchor) != 2:
            raise ValueError("asset anchor needs [x, y]")
        object.__setattr__(self, "anchor", tuple(finite(v, "anchor") for v in self.anchor))
        if len(self.source_files) != len(self.source_digests):
            raise ValueError("each source file needs the SHA-256 of the bytes decoded from it")

    @property
    def size(self):
        return self.frames[0].size

    @property
    def duration(self):
        return sum(self.durations)

    def frame_at(self, t: float, loop=True):
        return self.frames[self.index_at(t, loop=loop)]

    def index_at(self, t: float, loop=True) -> int:
        """Which frame plays at `t` seconds: looped over the sequence, or held on the last frame after its end (and
        on the first before its start) where `loop` is false."""
        t = finite(t, "frame time")
        if loop:
            t %= self.duration
        elif t >= self.duration:
            return len(self.frames) - 1
        t = max(0, t)
        end = 0.0
        for k, duration in enumerate(self.durations):
            end += duration
            if t < end - 1e-10:
                return k
        return len(self.frames) - 1

    def fingerprints(self):
        """SHA-256 of the exact bytes this sequence was decoded from, keyed by resolved path.

        The digests were taken from the bytes read at load time, never from a
        later read of the files, so they describe these frames and nothing else.
        """
        return {str(path): digest for path, digest in zip(self.source_files, self.source_digests)}

    def identity(self) -> dict:
        return sequence_identity(self)


def _read_bytes(path: Path) -> bytes:
    """The single place a source file is read; every decode and hash uses its result."""
    return Path(path).read_bytes()


# One decoded source image (a frame, a loop strip or an atlas sheet) may hold at
# most this many pixels: 256 MB of RGBA, below Pillow's decompression-bomb
# warning, so a hostile header is refused before any pixel data is decoded.
MAX_SOURCE_PIXELS = 67_108_864


def _decode_image(data: bytes) -> Image.Image:
    with Image.open(BytesIO(data)) as image:
        if getattr(image, "n_frames", 1) != 1:
            raise ValueError("animated image input requires an explicit frame descriptor")
        width, height = image.size
        if width < 1 or height < 1 or width * height > MAX_SOURCE_PIXELS:
            raise ValueError(f"source image {width}x{height} exceeds the supported {MAX_SOURCE_PIXELS} pixels")
        return image.convert("RGBA")


class _Snapshot:
    """Bytes of every file touched by one load, each read once, with their digests."""

    def __init__(self):
        self.digests: dict[Path, str] = {}
        self._bytes: dict[Path, bytes] = {}
        self._images: dict[Path, Image.Image] = {}

    def read(self, path: Path) -> bytes:
        if path not in self._bytes:
            data = _read_bytes(path)
            self._bytes[path] = data
            self.digests[path] = hashlib.sha256(data).hexdigest()
        return self._bytes[path]

    def image(self, path: Path) -> Image.Image:
        if path not in self._images:
            self._images[path] = _decode_image(self.read(path))
        return self._images[path]

    def json(self, path: Path):
        return json.loads(self.read(path).decode("utf-8"))


def _choose(rows, state):
    if not isinstance(rows, dict) or not rows:
        raise ValueError("asset has no animation states")
    if state is None:
        if len(rows) != 1:
            raise ValueError("--state is required for a multi-state atlas")
        state = next(iter(rows))
    if state not in rows:
        raise ValueError(f"unknown asset state: {state}")
    return state


def _holds(value, n: int) -> list[dict]:
    """A strip's `holds`, the runs of cells it shows one picture in on purpose (`from` to `to`, both counted, with
    their `kind` and `reason`), checked against its `n` cells; absent, none."""
    if value is None:
        return []
    if not isinstance(value, list):
        raise ValueError("strip holds must be a list")
    out = []
    for entry in value:
        if not isinstance(entry, dict) or any(type(entry.get(k)) is not int for k in ("from", "to")):
            raise ValueError("each strip hold needs integer from and to")
        if not 0 <= entry["from"] < entry["to"] < n:
            raise ValueError(f"strip hold {entry['from']}-{entry['to']} is not a run of its {n} cells")
        out.append({"from": entry["from"], "to": entry["to"], "kind": entry.get("kind"), "reason": entry.get("reason")})
    return out


def _integer(value, name):
    number = finite(value, name, positive=True)
    if number != int(number):
        raise ValueError(f"{name} must be an integer")
    return int(number)


def load_asset(source: Path, *, state=None, fps=None, anchor=None) -> FrameSequence:
    source = Path(source).expanduser().resolve()
    return _load_asset(source, _Snapshot(), state=state, fps=fps, anchor=anchor)


PLAYBACK_FIELDS = ("loop", "hold_last", "end_frame", "events", "blend", "direction", "body_h", "frame_variant")


def _grid_frames(sheet, columns, rows, width, height, count, *, row=None):
    columns, rows, width, height, count = (
        _integer(v, name) for v, name in zip((columns, rows, width, height, count),
                                            ("columns", "rows", "width", "height", "frames")))
    if sheet.size != (columns * width, rows * height):
        raise ValueError("sheet size disagrees with its sidecar")
    if row is not None and (type(row) is not int or not 0 <= row < rows):
        raise ValueError("sheet row is outside the sheet")
    if count > (columns if row is not None else columns * rows):
        raise ValueError("sheet frame count exceeds its cells")
    return [sheet.crop(((i % columns) * width, (row if row is not None else i // columns) * height,
                        (i % columns + 1) * width, ((row if row is not None else i // columns) + 1) * height))
            for i in range(count)]


def _load_asset(source, snapshot, *, state=None, fps=None, anchor=None):
    meta = {"source": str(source)}
    declared_anchor = None
    if source.suffix.lower() != ".json":
        if state is not None:
            raise ValueError("--state is only valid for atlas input")
        frames = [snapshot.image(source)]
        durations = [1.0]
    else:
        data = snapshot.json(source)
        if not isinstance(data, dict):
            raise ValueError("asset descriptor must be an object")
        meta.update({key: data[key] for key in PLAYBACK_FIELDS if key in data})
        declared_anchor = data.get("anchor")
        if data.get("kind") == ASSET_KIND:
            if data.get("version") != 1 or state is not None:
                raise ValueError("external asset requires version 1 and no --state")
            entries = data.get("frames")
            if not isinstance(entries, list) or not entries:
                raise ValueError("asset frames must be a nonempty ordered list")
            frames, durations = [], []
            for entry in entries:
                if not isinstance(entry, dict) or not isinstance(entry.get("file"), str):
                    raise ValueError("each asset frame requires file and duration")
                frames.append(snapshot.image((source.parent / entry["file"]).resolve()))
                durations.append(finite(entry.get("duration"), "frame duration", positive=True))
        elif "frame_layout" in data:
            layout = data["frame_layout"]
            state = _choose(layout.get("rows"), state)
            sheet = snapshot.image((source.parent / data["sprite_sheet_alpha"]).resolve())
            frames = []
            for rect in layout["rows"][state]:
                x, y = finite(rect["x"], "rect x"), finite(rect["y"], "rect y")
                w, h = _integer(rect["w"], "rect width"), _integer(rect["h"], "rect height")
                if int(x) != x or int(y) != y or min(x, y) < 0 or x+w > sheet.width or y+h > sheet.height:
                    raise ValueError("atlas frame rectangle outside sheet")
                frames.append(sheet.crop((int(x), int(y), int(x)+w, int(y)+h)))
            anim = data["animation"]["rows"][state]
            meta.update({key: anim[key] for key in PLAYBACK_FIELDS if key in anim})
            declared_anchor = anim.get("anchor", declared_anchor)
            if "durations_ms" in anim:
                durations = [finite(v, "duration_ms", positive=True) / 1000 for v in anim["durations_ms"]]
            else:
                durations = [1 / finite(anim.get("fps"), "atlas fps", positive=True)] * len(frames)
            meta.update(state=state, loop=anim.get("loop", True))
        elif data.get("kind") == SET_SHEET_KIND:
            if data.get("schema") != 1:
                raise ValueError("direction sheet requires schema 1")
            rows = data["rows"]
            by_code = {row["code"]: row for row in rows}
            if len(by_code) != len(rows) or len({row["row"] for row in rows}) != len(rows):
                raise ValueError("direction sheet rows must be unique")
            state = _choose(by_code, state)
            selected = by_code[state]
            sheet = snapshot.image((source.parent / data["sheet"]).resolve())
            frames = _grid_frames(sheet, data["columns"], len(rows), data["cell_w"], data["cell_h"],
                                  selected["frames"], row=selected["row"])
            durations = [frame_seconds(selected["delay_ms"])] * len(frames)
            meta.update({key: selected[key] for key in PLAYBACK_FIELDS if key in selected})
            meta.update(state=state, direction=state)
            declared_anchor = selected.get("anchor", declared_anchor)
        elif isinstance(data.get("rows"), list) and "cell" in data:
            # Row-labelled direction sheets: explicit row order, never compass sorting.
            rows = data["rows"]
            if len(set(rows)) != len(rows):
                raise ValueError("direction sheet rows must be unique")
            state = _choose(dict.fromkeys(rows, True), state)
            sheet = snapshot.image(source.with_suffix(".png"))
            frames = _grid_frames(sheet, data["frames"], len(rows), *data["cell"], data["frames"], row=rows.index(state))
            durations = [1/finite(data["fps"], "fps", positive=True)] * len(frames)
            meta.update(state=state, direction=state)
        elif all(k in data for k in ("columns", "rows", "frame_width", "frame_height", "frames", "delay_ms")):
            if state is not None or data.get("order") != "row-major":
                raise ValueError("grid sheet requires row-major order and no --state")
            sheet = snapshot.image(source.with_suffix(".png"))
            frames = _grid_frames(sheet, data["columns"], data["rows"], data["frame_width"], data["frame_height"], data["frames"])
            durations = [frame_seconds(data["delay_ms"])] * len(frames)
        elif all(k in data for k in ("frames", "w", "h", "delay_ms")):
            if state is not None:
                raise ValueError("--state is only valid for atlas input")
            sheet = snapshot.image(source.with_suffix(".png"))
            n, w, h = (_integer(data[k], k) for k in ("frames", "w", "h"))
            if sheet.size != (n * w, h):
                raise ValueError("loop strip size disagrees with its sidecar")
            frames = [sheet.crop((i*w, 0, (i+1)*w, h)) for i in range(n)]
            # The cells' own rate where the strip says it (`fps`), else its `delay_ms` (`frame_seconds`).
            durations = ([1 / finite(data["fps"], "fps", positive=True)] if "fps" in data else [frame_seconds(data["delay_ms"])]) * n
            if "source_cut" in data:
                # A cut of a filmed clip (`video-loop`, `video-stop`): a scene gives it at its own times
                # (sprite_gen.scene.render), holding only the cells its strip lists as held on purpose (`holds`).
                meta["video_cut"] = True
                meta["holds"] = _holds(data.get("holds"), n)
            # `video-loop` writes `loop: false` for a one-shot cut (rest -> action -> rest);
            # an older sidecar without the key is a loop, as every strip was before.
            meta["loop"] = data.get("loop", True)
        else:
            raise ValueError("unsupported asset descriptor; use sprite-gen-asset, loop strip sidecar or atlas manifest")
    if not frames:
        raise ValueError("asset requires at least one frame")
    if fps is not None:
        durations = [1 / finite(fps, "fps", positive=True)] * len(frames)
        meta["fps_override"] = float(fps)
    point = anchor if anchor is not None else declared_anchor
    if point is None:
        point = (frames[0].width / 2, frames[0].height)
        meta["anchor_source"] = "bottom-center default"
    else:
        if not isinstance(point, (tuple, list)) or len(point) != 2:
            raise ValueError("anchor must be [x, y]")
        point = tuple(finite(v, "anchor") for v in point)
        meta["anchor_source"] = "explicit override" if anchor is not None else "asset metadata"
    return FrameSequence(tuple(frames), tuple(durations), tuple(point), tuple(snapshot.digests), meta,
                         source_digests=tuple(snapshot.digests.values()))