The kitty/iTerm2/sixel/half-block encoders, terminal detection and the kitty Unicode-placeholder grid lived in agent/pet/render.py, though nothing in them is pet-specific. Move them to agent/terminal_image.py so inline images can use them too; the pet keeps its spritesheet decode and PetRenderer. The Ink half-block and placeholder painters get generic names for the same reason (petSprite.tsx -> cellImage.tsx: HalfBlockImage, KittyImage). No behaviour change; the detection tests move with the code.
185 lines
7.8 KiB
Python
185 lines
7.8 KiB
Python
"""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)
|