| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184 |
- """Decode a pet spritesheet and encode frames for a terminal.
- Shared by the base CLI (escape bytes to stdout) and the TUI (bytes shipped to
- Ink). Capability detection and the protocol encoders live in
- :mod:`agent.terminal_image`, which inline images use too. Missing Pillow or
- spritesheet degrades to an empty string rather than raising (PIL is imported
- lazily on purpose).
- """
- from __future__ import annotations
- import logging
- import sys
- import zlib
- from dataclasses import KW_ONLY, dataclass
- from functools import lru_cache
- from itertools import takewhile
- from pathlib import Path
- from agent.pet.constants import DEFAULT_SCALE, FRAME_H, FRAME_W, FRAMES_PER_STATE, PetState, state_row_index
- from agent.terminal_image import (
- CELL_H,
- CELL_W,
- Cell,
- cell_box,
- detect_terminal_graphics,
- downscale_cells,
- encode_iterm,
- encode_kitty,
- encode_kitty_virtual,
- encode_sixel,
- encode_unicode,
- kitty_placeholder_rows,
- )
- logger = logging.getLogger(__name__)
- # Public render-mode names accepted by ``display.pet.render_mode``.
- RENDER_MODES = ("auto", "kitty", "iterm", "sixel", "unicode", "off")
- def resolve_mode(configured: str | None, *, stream=None) -> str:
- """Effective render mode from ``display.pet.render_mode`` + env; ``off`` when not a TTY."""
- mode = (configured or "auto").strip().lower()
- mode = mode if mode in RENDER_MODES else "auto"
- stream = stream or sys.stdout
- try:
- if mode == "off" or not (hasattr(stream, "isatty") and stream.isatty()):
- return "off"
- except (ValueError, OSError):
- return "off"
- return detect_terminal_graphics() if mode == "auto" else mode
- # Max alpha at/below which a frame is blank padding: petdex sheets are left-packed,
- # so short states have transparent trailing cells; animating into one flashes blank.
- _BLANK_ALPHA = 8
- def _frame_is_blank(frame) -> bool:
- return frame.getchannel("A").getextrema()[1] <= _BLANK_ALPHA
- @lru_cache(maxsize=16)
- def _raw_frames(sheet_path: str, state_value: str, frame_w: int, frame_h: int, frames_per_state: int) -> tuple:
- """Cropped RGBA frames for one state row, stopping at the first blank column; ``()`` on any decode failure."""
- try:
- from PIL import Image
- sheet = Image.open(Path(sheet_path)).convert("RGBA")
- cols, rows = max(1, sheet.width // frame_w), max(1, sheet.height // frame_h)
- # Clamp to the sheet: some pets ship fewer rows than the taxonomy reserves.
- top = min(state_row_index(state_value, rows) * frame_h, max(0, sheet.height - frame_h))
- crops = (sheet.crop((i * frame_w, top, (i + 1) * frame_w, top + frame_h)) for i in range(min(frames_per_state, cols)))
- return tuple(takewhile(lambda f: not _frame_is_blank(f), crops))
- except Exception as exc:
- logger.debug("pet frame decode failed (%s, %s): %s", sheet_path, state_value, exc)
- return ()
- @lru_cache(maxsize=8)
- def _frames_for(sheet_path: str, state_value: str, frame_w: int, frame_h: int, frames_per_state: int, scale_w: int, scale_h: int):
- """Scaled :func:`_raw_frames` (both cached, so animation-time requests are free)."""
- raw = _raw_frames(sheet_path, state_value, frame_w, frame_h, frames_per_state)
- if not raw or (scale_w, scale_h) == (frame_w, frame_h):
- return list(raw)
- from PIL import Image
- return [f.resize((scale_w, scale_h), Image.LANCZOS) for f in raw]
- def state_frame_counts(
- sheet_path: str | Path, *, frame_w: int = FRAME_W, frame_h: int = FRAME_H, frames_per_state: int = FRAMES_PER_STATE
- ) -> dict[str, int]:
- """Each driven :class:`PetState` → its real (padding-trimmed) frame count (shipped to the desktop canvas)."""
- return {s.value: len(_raw_frames(str(sheet_path), s.value, frame_w, frame_h, frames_per_state)) for s in PetState}
- def _fit_frames_to_cell_grid(frames):
- """Crop *frames* (non-empty) to their union opaque bbox, then resize so width/height are exact cell-box multiples.
- kitty paints transparent margins too, so an untrimmed pet looks small and adrift.
- """
- from PIL import Image
- boxes = [b for b in (f.getchannel("A").getbbox() for f in frames) if b]
- if boxes:
- union = (min(b[0] for b in boxes), min(b[1] for b in boxes), max(b[2] for b in boxes), max(b[3] for b in boxes))
- frames = [f.crop(union) for f in frames]
- w, h = frames[0].size
- target = (max(1, round(w / CELL_W)) * CELL_W, max(1, round(h / CELL_H)) * CELL_H)
- return frames if (w, h) == target else [f.resize(target, Image.LANCZOS) for f in frames]
- def kitty_image_id(slug: str) -> int:
- """Deterministic per-slug image id in ``[1, 0x7FFF]`` (non-zero; encoded in the placeholder fg color) so re-renders reuse the terminal-side image."""
- return (zlib.crc32(slug.encode("utf-8")) % 0x7FFE) + 1
- _ENCODERS = {"kitty": encode_kitty, "iterm": encode_iterm, "sixel": encode_sixel}
- @dataclass(eq=False)
- class PetRenderer:
- """Holds a pet's spritesheet and yields encoded frames per (state, index); decoded frames are cached."""
- spritesheet: str | Path
- _: KW_ONLY
- mode: str = "unicode"
- scale: float = DEFAULT_SCALE
- unicode_cols: int = 20
- frame_w: int = FRAME_W
- frame_h: int = FRAME_H
- frames_per_state: int = FRAMES_PER_STATE
- def __post_init__(self) -> None:
- self.spritesheet = str(self.spritesheet)
- self.mode = self.mode if self.mode in RENDER_MODES else "unicode"
- @property
- def available(self) -> bool:
- return self.mode != "off" and Path(self.spritesheet).is_file()
- def frame_count(self, state: PetState | str) -> int:
- return len(self._frames(state))
- def _frames(self, state: PetState | str):
- name = state.value if isinstance(state, PetState) else str(state)
- scaled = max(1, int(self.frame_w * self.scale)), max(1, int(self.frame_h * self.scale))
- return _frames_for(self.spritesheet, name, self.frame_w, self.frame_h, self.frames_per_state, *scaled)
- def cells(self, state: PetState | str, index: int, *, cols: int | None = None) -> list[list[Cell]]:
- """One frame as a half-block cell grid for Ink's native color props; ``[]`` when unavailable."""
- frames = self._frames(state)
- return downscale_cells(frames[index % len(frames)], target_cols=cols or self.unicode_cols) if frames else []
- def kitty_payload(self, state: PetState | str, *, image_id: int) -> dict | None:
- """kitty placeholder payload ``{cols, rows, placeholder, frames}`` (transmit escapes + static text grid); ``None`` if no frames."""
- if not (frames := self._frames(state)):
- return None
- frames = _fit_frames_to_cell_grid(frames)
- cols, rows = cell_box(frames[0])
- encoded = [encode_kitty_virtual(f, image_id=image_id, cols=cols, rows=rows) for f in frames]
- return {"cols": cols, "rows": rows, "placeholder": kitty_placeholder_rows(cols, rows), "frames": encoded}
- def frame(self, state: PetState | str, index: int) -> str:
- """Encoded escape string for one frame (``index`` taken modulo the frame count), or ``""``."""
- if self.mode == "off" or not (frames := self._frames(state)):
- return ""
- frame = frames[index % len(frames)]
- try:
- if self.mode in _ENCODERS:
- return _ENCODERS[self.mode](frame)
- return encode_unicode(frame, target_cols=self.unicode_cols)
- except Exception as exc:
- logger.debug("pet frame encode failed (mode=%s): %s", self.mode, exc)
- return ""
- def build_renderer(
- spritesheet: str | Path, *, configured_mode: str | None = None, scale: float = DEFAULT_SCALE, unicode_cols: int = 20, stream=None
- ) -> PetRenderer:
- """Resolve the mode from config+env, then construct a :class:`PetRenderer`."""
- return PetRenderer(spritesheet, mode=resolve_mode(configured_mode, stream=stream), scale=scale, unicode_cols=unicode_cols)
|