render.py 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. """Decode a pet spritesheet and encode frames for a terminal.
  2. Shared by the base CLI (escape bytes to stdout) and the TUI (bytes shipped to
  3. Ink). Capability detection and the protocol encoders live in
  4. :mod:`agent.terminal_image`, which inline images use too. Missing Pillow or
  5. spritesheet degrades to an empty string rather than raising (PIL is imported
  6. lazily on purpose).
  7. """
  8. from __future__ import annotations
  9. import logging
  10. import sys
  11. import zlib
  12. from dataclasses import KW_ONLY, dataclass
  13. from functools import lru_cache
  14. from itertools import takewhile
  15. from pathlib import Path
  16. from agent.pet.constants import DEFAULT_SCALE, FRAME_H, FRAME_W, FRAMES_PER_STATE, PetState, state_row_index
  17. from agent.terminal_image import (
  18. CELL_H,
  19. CELL_W,
  20. Cell,
  21. cell_box,
  22. detect_terminal_graphics,
  23. downscale_cells,
  24. encode_iterm,
  25. encode_kitty,
  26. encode_kitty_virtual,
  27. encode_sixel,
  28. encode_unicode,
  29. kitty_placeholder_rows,
  30. )
  31. logger = logging.getLogger(__name__)
  32. # Public render-mode names accepted by ``display.pet.render_mode``.
  33. RENDER_MODES = ("auto", "kitty", "iterm", "sixel", "unicode", "off")
  34. def resolve_mode(configured: str | None, *, stream=None) -> str:
  35. """Effective render mode from ``display.pet.render_mode`` + env; ``off`` when not a TTY."""
  36. mode = (configured or "auto").strip().lower()
  37. mode = mode if mode in RENDER_MODES else "auto"
  38. stream = stream or sys.stdout
  39. try:
  40. if mode == "off" or not (hasattr(stream, "isatty") and stream.isatty()):
  41. return "off"
  42. except (ValueError, OSError):
  43. return "off"
  44. return detect_terminal_graphics() if mode == "auto" else mode
  45. # Max alpha at/below which a frame is blank padding: petdex sheets are left-packed,
  46. # so short states have transparent trailing cells; animating into one flashes blank.
  47. _BLANK_ALPHA = 8
  48. def _frame_is_blank(frame) -> bool:
  49. return frame.getchannel("A").getextrema()[1] <= _BLANK_ALPHA
  50. @lru_cache(maxsize=16)
  51. def _raw_frames(sheet_path: str, state_value: str, frame_w: int, frame_h: int, frames_per_state: int) -> tuple:
  52. """Cropped RGBA frames for one state row, stopping at the first blank column; ``()`` on any decode failure."""
  53. try:
  54. from PIL import Image
  55. sheet = Image.open(Path(sheet_path)).convert("RGBA")
  56. cols, rows = max(1, sheet.width // frame_w), max(1, sheet.height // frame_h)
  57. # Clamp to the sheet: some pets ship fewer rows than the taxonomy reserves.
  58. top = min(state_row_index(state_value, rows) * frame_h, max(0, sheet.height - frame_h))
  59. crops = (sheet.crop((i * frame_w, top, (i + 1) * frame_w, top + frame_h)) for i in range(min(frames_per_state, cols)))
  60. return tuple(takewhile(lambda f: not _frame_is_blank(f), crops))
  61. except Exception as exc:
  62. logger.debug("pet frame decode failed (%s, %s): %s", sheet_path, state_value, exc)
  63. return ()
  64. @lru_cache(maxsize=8)
  65. 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):
  66. """Scaled :func:`_raw_frames` (both cached, so animation-time requests are free)."""
  67. raw = _raw_frames(sheet_path, state_value, frame_w, frame_h, frames_per_state)
  68. if not raw or (scale_w, scale_h) == (frame_w, frame_h):
  69. return list(raw)
  70. from PIL import Image
  71. return [f.resize((scale_w, scale_h), Image.LANCZOS) for f in raw]
  72. def state_frame_counts(
  73. sheet_path: str | Path, *, frame_w: int = FRAME_W, frame_h: int = FRAME_H, frames_per_state: int = FRAMES_PER_STATE
  74. ) -> dict[str, int]:
  75. """Each driven :class:`PetState` → its real (padding-trimmed) frame count (shipped to the desktop canvas)."""
  76. return {s.value: len(_raw_frames(str(sheet_path), s.value, frame_w, frame_h, frames_per_state)) for s in PetState}
  77. def _fit_frames_to_cell_grid(frames):
  78. """Crop *frames* (non-empty) to their union opaque bbox, then resize so width/height are exact cell-box multiples.
  79. kitty paints transparent margins too, so an untrimmed pet looks small and adrift.
  80. """
  81. from PIL import Image
  82. boxes = [b for b in (f.getchannel("A").getbbox() for f in frames) if b]
  83. if boxes:
  84. 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))
  85. frames = [f.crop(union) for f in frames]
  86. w, h = frames[0].size
  87. target = (max(1, round(w / CELL_W)) * CELL_W, max(1, round(h / CELL_H)) * CELL_H)
  88. return frames if (w, h) == target else [f.resize(target, Image.LANCZOS) for f in frames]
  89. def kitty_image_id(slug: str) -> int:
  90. """Deterministic per-slug image id in ``[1, 0x7FFF]`` (non-zero; encoded in the placeholder fg color) so re-renders reuse the terminal-side image."""
  91. return (zlib.crc32(slug.encode("utf-8")) % 0x7FFE) + 1
  92. _ENCODERS = {"kitty": encode_kitty, "iterm": encode_iterm, "sixel": encode_sixel}
  93. @dataclass(eq=False)
  94. class PetRenderer:
  95. """Holds a pet's spritesheet and yields encoded frames per (state, index); decoded frames are cached."""
  96. spritesheet: str | Path
  97. _: KW_ONLY
  98. mode: str = "unicode"
  99. scale: float = DEFAULT_SCALE
  100. unicode_cols: int = 20
  101. frame_w: int = FRAME_W
  102. frame_h: int = FRAME_H
  103. frames_per_state: int = FRAMES_PER_STATE
  104. def __post_init__(self) -> None:
  105. self.spritesheet = str(self.spritesheet)
  106. self.mode = self.mode if self.mode in RENDER_MODES else "unicode"
  107. @property
  108. def available(self) -> bool:
  109. return self.mode != "off" and Path(self.spritesheet).is_file()
  110. def frame_count(self, state: PetState | str) -> int:
  111. return len(self._frames(state))
  112. def _frames(self, state: PetState | str):
  113. name = state.value if isinstance(state, PetState) else str(state)
  114. scaled = max(1, int(self.frame_w * self.scale)), max(1, int(self.frame_h * self.scale))
  115. return _frames_for(self.spritesheet, name, self.frame_w, self.frame_h, self.frames_per_state, *scaled)
  116. def cells(self, state: PetState | str, index: int, *, cols: int | None = None) -> list[list[Cell]]:
  117. """One frame as a half-block cell grid for Ink's native color props; ``[]`` when unavailable."""
  118. frames = self._frames(state)
  119. return downscale_cells(frames[index % len(frames)], target_cols=cols or self.unicode_cols) if frames else []
  120. def kitty_payload(self, state: PetState | str, *, image_id: int) -> dict | None:
  121. """kitty placeholder payload ``{cols, rows, placeholder, frames}`` (transmit escapes + static text grid); ``None`` if no frames."""
  122. if not (frames := self._frames(state)):
  123. return None
  124. frames = _fit_frames_to_cell_grid(frames)
  125. cols, rows = cell_box(frames[0])
  126. encoded = [encode_kitty_virtual(f, image_id=image_id, cols=cols, rows=rows) for f in frames]
  127. return {"cols": cols, "rows": rows, "placeholder": kitty_placeholder_rows(cols, rows), "frames": encoded}
  128. def frame(self, state: PetState | str, index: int) -> str:
  129. """Encoded escape string for one frame (``index`` taken modulo the frame count), or ``""``."""
  130. if self.mode == "off" or not (frames := self._frames(state)):
  131. return ""
  132. frame = frames[index % len(frames)]
  133. try:
  134. if self.mode in _ENCODERS:
  135. return _ENCODERS[self.mode](frame)
  136. return encode_unicode(frame, target_cols=self.unicode_cols)
  137. except Exception as exc:
  138. logger.debug("pet frame encode failed (mode=%s): %s", self.mode, exc)
  139. return ""
  140. def build_renderer(
  141. spritesheet: str | Path, *, configured_mode: str | None = None, scale: float = DEFAULT_SCALE, unicode_cols: int = 20, stream=None
  142. ) -> PetRenderer:
  143. """Resolve the mode from config+env, then construct a :class:`PetRenderer`."""
  144. return PetRenderer(spritesheet, mode=resolve_mode(configured_mode, stream=stream), scale=scale, unicode_cols=unicode_cols)