Interface TerminalImage

All Known Implementing Classes:
ITermImage, KittyImage, SixelImage
public interface TerminalImage
Represents an image that can be displayed in a terminal. Different implementations handle different terminal image protocols.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    encode()
    Encode the image as an escape sequence string ready to be written to the terminal.
    int
    getHeightCells()
    Get the display height in terminal cells.
    org.aesh.terminal.detect.ImageProtocol
    getProtocol()
    Get the protocol used by this image.
    int
    getWidthCells()
    Get the display width in terminal cells.
    default String
    place(int imageId)
    Place a previously transmitted image at the current cursor position.
    default String
    place(int imageId, int placementId)
    Place a previously transmitted image with a specific placement ID.
    default boolean
    supportsPlacement()
    Whether this image supports the transmit-once / place-many pattern.
    default String
    transmit(int imageId)
    Transmit image data to the terminal with an ID but do not display it.
    default String
    transmitAndDisplay(int imageId)
    Transmit image data AND display it at the current cursor position, assigning an ID for later re-placement via place(int).

  • Method Details

    • encode

      String encode()
      Encode the image as an escape sequence string ready to be written to the terminal.
      Returns:
      the escape sequence that will display the image

    • getProtocol

      org.aesh.terminal.detect.ImageProtocol getProtocol()
      Get the protocol used by this image.
      Returns:
      the image protocol

    • getWidthCells

      int getWidthCells()
      Get the display width in terminal cells. Returns -1 if width is auto-detected or not specified.
      Returns:
      width in cells, or -1 for auto

    • getHeightCells

      int getHeightCells()
      Get the display height in terminal cells. Returns -1 if height is auto-detected or not specified.
      Returns:
      height in cells, or -1 for auto

    • supportsPlacement

      default boolean supportsPlacement()
      Whether this image supports the transmit-once / place-many pattern. When true, callers can use transmit(int) to send the image data once, then place(int) to display it at different positions without re-sending the data.
      Returns:
      true if placement is supported (currently only Kitty protocol)

    • transmit

      default String transmit(int imageId)
      Transmit image data to the terminal with an ID but do not display it. The image is stored in the terminal's memory and can be displayed later using place(int).
      Parameters:
      imageId - a positive integer (1-4294967295) to identify the image
      Returns:
      the escape sequence for transmission
      Throws:
      UnsupportedOperationException - if the protocol does not support placement

    • transmitAndDisplay

      default String transmitAndDisplay(int imageId)
      Transmit image data AND display it at the current cursor position, assigning an ID for later re-placement via place(int).

      This is the common use case for images that are shown once and may need to be repositioned later.

      Parameters:
      imageId - a positive integer (1-4294967295) to identify the image
      Returns:
      the escape sequence for transmission and display

    • place

      default String place(int imageId)
      Place a previously transmitted image at the current cursor position. This is a lightweight operation (~30 bytes) that references the image by ID without re-sending any image data.
      Parameters:
      imageId - the image ID from a previous transmit(int) call
      Returns:
      the escape sequence for placement
      Throws:
      UnsupportedOperationException - if the protocol does not support placement

    • place

      default String place(int imageId, int placementId)
      Place a previously transmitted image with a specific placement ID. Sending the same image ID and placement ID replaces the previous placement without flicker — useful for animation.
      Parameters:
      imageId - the image ID from a previous transmit(int) call
      placementId - a positive integer (1-4294967295) identifying this placement
      Returns:
      the escape sequence for placement
      Throws:
      UnsupportedOperationException - if the protocol does not support placement