Package org.aesh.terminal.image

Class KittyImage

java.lang.Object
org.aesh.terminal.image.KittyImage
All Implemented Interfaces:
TerminalImage
public class KittyImage extends Object implements TerminalImage
Kitty graphics protocol implementation.

Protocol format: 

 ESC _ G [key=value,...] ; [payload] ESC \

The protocol uses APC (Application Program Command) escape sequences. Large images are split into multiple chunks of up to 4096 bytes.

Key control parameters:

  • a=t|T|p|d|f - action (transmit, put, delete, frame)
  • f=24|32|100 - format (RGB, RGBA, PNG)
  • t=d|f|t|s - transmission medium (direct, file, temp, shared memory)
  • s=N - source width in pixels
  • v=N - source height in pixels
  • c=N - display columns
  • r=N - display rows
  • m=0|1 - more data follows (for chunked transfer)
  • q=1|2 - suppress responses

Supported by: Kitty, Konsole (partial)

See Also:

  • Constructor Details

    • KittyImage

      public KittyImage(byte[] imageData)
      Create a Kitty image from image data.

      Supports PNG, JPEG, GIF, and other formats supported by Java ImageIO. Non-PNG images are automatically converted to PNG format since the Kitty graphics protocol only supports PNG for compressed images.

      Parameters:
      imageData - the image data (PNG, JPEG, GIF, etc.)

  • Method Details

    • fromFile

      public static KittyImage fromFile(Path path) throws IOException
      Create a Kitty image from a file.

      Supports PNG, JPEG, GIF, and other formats supported by Java ImageIO. Non-PNG images are automatically converted to PNG.

      Parameters:
      path - path to the image file
      Returns:
      the terminal image
      Throws:
      IOException - if the file cannot be read

    • fromBytes

      public static KittyImage fromBytes(byte[] data)
      Create a Kitty image from raw bytes.

      Supports PNG, JPEG, GIF, and other formats supported by Java ImageIO. Non-PNG images are automatically converted to PNG.

      Parameters:
      data - the image data
      Returns:
      the terminal image

    • widthCells

      public KittyImage widthCells(int cells)
      Set the display width in terminal cells (columns).
      Parameters:
      cells - number of columns
      Returns:
      this image for chaining

    • heightCells

      public KittyImage heightCells(int cells)
      Set the display height in terminal cells (rows).
      Parameters:
      cells - number of rows
      Returns:
      this image for chaining

    • sourceDimensions

      public KittyImage sourceDimensions(int width, int height)
      Set the source image dimensions. Required for raw RGB/RGBA data, optional for PNG.
      Parameters:
      width - source width in pixels
      height - source height in pixels
      Returns:
      this image for chaining

    • zIndex

      public KittyImage zIndex(int zIndex)
      Set the z-index for layering multiple images. Higher z-index images appear on top.
      Parameters:
      zIndex - the z-index value
      Returns:
      this image for chaining

    • suppressResponse

      public KittyImage suppressResponse(boolean suppress)
      Set whether to suppress terminal responses. Default is true to avoid cluttering input.
      Parameters:
      suppress - true to suppress responses
      Returns:
      this image for chaining

    • encode

      public String encode()
      Description copied from interface: TerminalImage
      Encode the image as an escape sequence string ready to be written to the terminal.
      Specified by:
      encode in interface TerminalImage
      Returns:
      the escape sequence that will display the image

    • getProtocol

      public ImageProtocol getProtocol()
      Description copied from interface: TerminalImage
      Get the protocol used by this image.
      Specified by:
      getProtocol in interface TerminalImage
      Returns:
      the image protocol

    • getWidthCells

      public int getWidthCells()
      Description copied from interface: TerminalImage
      Get the display width in terminal cells. Returns -1 if width is auto-detected or not specified.
      Specified by:
      getWidthCells in interface TerminalImage
      Returns:
      width in cells, or -1 for auto

    • getHeightCells

      public int getHeightCells()
      Description copied from interface: TerminalImage
      Get the display height in terminal cells. Returns -1 if height is auto-detected or not specified.
      Specified by:
      getHeightCells in interface TerminalImage
      Returns:
      height in cells, or -1 for auto