NomadNet/nomadnet/ui/textui/images/widget.py

# An urwid widget that occupies the space an image should fill in a layout,
# without embedding any escape sequences in its canvas. The actual terminal
# graphics are transmitted by the ImageScreen class which tracks the widget's
# on-screen position after every draw.
# 
# This separation keeps the canvas trivially simple (urwid sees only blank
# rows) and lets the screen handle the hard parts; positioning, deletion when
# scrolled away, terminal resize and redraws - all of which are driven by
# urwid's own shard bookkeeping rather than by fragile escape-sequence
# manipulation inside canvas rows.
# 
# When the Kitty graphics protocol is unavailable (or the image cannot be
# loaded), the widget renders a simple text placeholder instead.

import os
import re
import urwid

from . import _termlib
from ._imagestore import image_store

DEFAULT_CELL_SIZE = (1, 2)  # Fallback, assume a 1:2 cell aspect ratio
MAX_Z_INDEX       = 2 ** 31 - 1
UI_MARGIN         = 8
_SIZE_SPEC_RE     = re.compile(r"(\d+(?:\.\d+)?)%")
_ALIGNS           = { "left": "<", "<": "<",
                      "center": "|", "|": "|",
                      "right": ">", ">": ">" }

def _check_align(value):
    if value not in _ALIGNS: raise ValueError("invalid alignment %r (expected 'left', 'center' or 'right')" % (value,))
    return _ALIGNS[value]


def _check_size_spec(value, name):
    # None = auto, int = absolute cells/rows, "NN%" = percent, "n" = native resolution
    if value is None: return None
    
    if isinstance(value, int):
        if value <= 0: raise ValueError("%s must be a positive integer, got %r" % (name, value))
        return value
    
    if isinstance(value, str):
        if value.lower() == "n": return "n"
        match = _SIZE_SPEC_RE.fullmatch(value)
        if not match or float(match.group(1)) <= 0:
            raise ValueError("invalid %s specification %r (expected a positive integer, a percent string like '50%%' or 'n' for native resolution)" % (name, value))
        return value
    
    raise TypeError("invalid type for %s (got %s)" % (name, type(value).__name__))


class ImageWidget(urwid.Widget):
    # A widget that displays an image via the Kitty graphics protocol.
    # The widget is a plain FLOW/BOX widget; its canvas is blank. The
    # ImageScreen class performs the actual drawing over the Kitty
    # TGP side-channel.

    placeholder_glyph = ""

    _sizing = frozenset((urwid.FLOW, urwid.BOX))
    ignore_focus = True

    # Z-index allocation. Each widget instance gets a unique z-index so that
    # the screen can delete exactly one image when it scrolls away or moves.
    _ti_next_z = 1
    _ti_free_z = set()

    def __init__(self, path, name=None, width=None, height=None, align="center"):
        if path and not isinstance(path, (str, os.PathLike)): raise TypeError("path must be a string or path-like object")
        self.path = path
        self._notice = None
        self._ti_path = None
        self._ti_data = None
        self._ti_width = _check_size_spec(width, "width")
        self._ti_height = _check_size_spec(height, "height")
        self._ti_align = _check_align(align)
        self._ti_name = name if name is not None else ""
        self._ti_z = self._ti_alloc_z()
        self.image_id = self._ti_z
        
        # Display size (cols, rows) from the most recent render.
        # Used by the screen to place the image.
        self._ti_cols = None
        self._ti_rows = None
        self._ti_closed = False
        self._ti_key = None
        super().__init__()
        if self.path: self.load()

    def load(self, path=None, remote_source=False):
        if path: self.path = path
        if self.path:
            from ._imagedata import ImageData
            self._ti_path = os.path.abspath(os.fspath(self.path))
            self._ti_data = ImageData(self._ti_path, remote_source=remote_source)

            if self._ti_data.ok:
                # Register with the image store (de-duplicates identical data
                # and allocates the terminal-side image id on first use).
                self._ti_key = self._ti_data.key
                image_store.register(self._ti_key, self._ti_data.data)
                self._invalidate()
            else:
                error_msg = self._ti_data.error or "Unknown error"
                self.notice(f"Error: {error_msg}")

    def notice(self, msg=""):
        if not msg: self._notice = None
        else:       self._notice = str(msg)
        self._invalidate()

    def __del__(self):
        try: type(self)._ti_free_z.add(self._ti_z)
        except Exception: pass
        try: self.close()
        except Exception: pass

    def close(self):
        # Releases the widget's reference to its image data.
        # The data is evicted from the terminal by the screen as soon as no
        # live widget references it any more. Safe to call multiple times and
        # from __del__.
        try:
            if not self._ti_closed:
                self._ti_closed = True
                if self._ti_key is not None: image_store.unregister(self._ti_key)
        except Exception: pass

    @classmethod
    def _ti_alloc_z(cls):
        if cls._ti_free_z: return cls._ti_free_z.pop()
        z = cls._ti_next_z
        if z >= MAX_Z_INDEX: raise RuntimeError("Too many image widgets")
        cls._ti_next_z += 1
        return z

    ##########
    # Sizing #
    ##########

    width = property(
        lambda self: self._ti_width,
        doc="""Display width specification: None (full width), a positive
        int (columns), a percent string ("NN%") of the available layout
        width, or "n" for native resolution.""",
    )

    @width.setter
    def width(self, value):
        self._ti_width = _check_size_spec(value, "width")
        self._invalidate()

    height = property(
        lambda self: self._ti_height,
        doc="""Display height specification: None (derived, aspect
        preserving), a positive int (rows), a percent string ("NN%") of
        the visible page height, or "n" for native resolution.""",
    )

    @height.setter
    def height(self, value):
        self._ti_height = _check_size_spec(value, "height")
        self._invalidate()

    align = property(
        lambda self: self._ti_align,
        doc="""Horizontal alignment of the image within its allocated
        space: ``"<"`` (left), ``"|"`` (center) or ``">"`` (right).""",
    )

    @align.setter
    def align(self, value):
        self._ti_align = _check_align(value)
        self._invalidate()

    def _short(self): return "img#%x" % (id(self) & 0xFFFFF)

    def _display_size(self, maxcol, maxrow=None):
        if not self._ti_data.ok: return (min(maxcol, 1), 1)
        iw, ih = self._ti_data.size
        cell_w, cell_h = _termlib.get_cell_size() or DEFAULT_CELL_SIZE
        w_spec, h_spec = self._ti_width, self._ti_height

        def _pct(value): return float(value[:-1]) / 100.0

        def _raw_width():
            if w_spec is None: return float(maxcol)
            if isinstance(w_spec, int): return float(w_spec)
            if w_spec == "n": return iw / cell_w
            return maxcol * _pct(w_spec)

        def _raw_height():
            if h_spec is None: return None
            if isinstance(h_spec, int): return float(h_spec)
            if h_spec == "n": return ih / cell_h
            columns, lines = _termlib.get_terminal_size()
            page = max(1, lines - UI_MARGIN)
            return page * _pct(h_spec)

        def _height_for_width(cols): return cols * cell_w * ih / (cell_h * iw)
        def _width_for_height(rows): return rows * cell_h * iw / (cell_w * ih)

        if w_spec is not None and h_spec is not None:
            # Stretch mode: Target rectangle, uniformly scaled down only if
            # it would overflow the available space.
            target_w = max(1.0, _raw_width())
            target_h = max(1.0, _raw_height())
            scale = min(1.0, maxcol / target_w)
            if maxrow is not None: scale = min(scale, maxrow / target_h)
            cols = max(1, round(target_w * scale))
            rows = max(1, round(target_h * scale))
        elif w_spec is not None:
            # Width given: Height derived, aspect preserving.
            cols = max(1, min(maxcol, round(_raw_width())))
            rows = max(1, round(_height_for_width(cols)))
            if maxrow is not None and rows > maxrow:
                rows = maxrow
                cols = max(1, min(maxcol, round(_width_for_height(rows))))
        elif h_spec is not None:
            # Height given: Width derived, aspect preserving.
            rows = max(1, round(_raw_height()))
            cols = max(1, min(maxcol, round(_width_for_height(rows))))
            if maxrow is not None and rows > maxrow:
                rows = maxrow
                cols = max(1, min(maxcol, round(_width_for_height(rows))))
        else:
            # Default: Full width, height derived.
            cols = maxcol
            rows = max(1, round(_height_for_width(cols)))
            if maxrow is not None and rows > maxrow:
                rows = maxrow
                cols = max(1, min(maxcol, round(_width_for_height(rows))))
        
        return (cols, rows)

    def rows(self, size, focus=False):
        maxcol = size[0]
        if not (self._ti_data and self._ti_data.ok and _termlib.is_kitty_supported()):
            return len(self._placeholder_lines())
        n = self._display_size(maxcol)[1]
        return n

    def render(self, size, focus=False):
        if len(size) == 2:
            maxcol, maxrow = size
            is_box = True
        else:
            maxcol, maxrow = size[0], None
            is_box = False

        if not (self._ti_data and self._ti_data.ok and _termlib.is_kitty_supported()):
            return self._placeholder_canvas(maxcol, maxrow, focus)

        cols, rows = self._display_size(maxcol, maxrow)
        self._ti_cols, self._ti_rows = cols, rows
        # urwid requires canvases to fill the allocated space exactly
        # (width == maxcol for FLOW, (maxcol, maxrow) for BOX). The image
        # itself is placed by the screen at its resolved size inside the
        # canvas, left-aligned; the rest of the canvas stays blank.
        if is_box: return ImageCanvas(maxcol, maxrow)
        else:      return ImageCanvas(maxcol, rows)

    #########################
    # Placeholder rendering #
    #########################

    def _placeholder_lines(self):
        return [f"{self.placeholder_glyph}{self._notice or self._ti_name}"]

    def _placeholder_canvas(self, maxcol, maxrow, focus):
        align = {"<": "left", "|": "center", ">": "right"}.get(self._ti_align, "center")
        text = urwid.Text("\n".join(self._placeholder_lines()), align=align)
        if maxrow is not None: return urwid.Filler(text).render((maxcol, maxrow), focus)
        else:                  return text.render((maxcol,), focus)


class ImageCanvas(urwid.SolidCanvas):
    # A blank canvas marking the space occupied by an image.
    # Urwid sets _widget_info on this canvas to the owning
    # ImageWidget. ImageScreen finds image canvases through
    # that reference during its shard scan.
    def __init__(self, cols, rows): super().__init__(" ", cols, rows)