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

    • supportsPlacement

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

    • transmit

      public String transmit(int imageId)
      Description copied from interface: TerminalImage
      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 TerminalImage.place(int).
      Specified by:
      transmit in interface TerminalImage
      Parameters:
      imageId - a positive integer (1-4294967295) to identify the image
      Returns:
      the escape sequence for transmission

    • transmitAndDisplay

      public String transmitAndDisplay(int imageId)
      Description copied from interface: TerminalImage
      Transmit image data AND display it at the current cursor position, assigning an ID for later re-placement via TerminalImage.place(int).

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

      Specified by:
      transmitAndDisplay in interface TerminalImage
      Parameters:
      imageId - a positive integer (1-4294967295) to identify the image
      Returns:
      the escape sequence for transmission and display

    • place

      public String place(int imageId)
      Description copied from interface: TerminalImage
      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.
      Specified by:
      place in interface TerminalImage
      Parameters:
      imageId - the image ID from a previous TerminalImage.transmit(int) call
      Returns:
      the escape sequence for placement

    • place

      public String place(int imageId, int placementId)
      Description copied from interface: TerminalImage
      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.
      Specified by:
      place in interface TerminalImage
      Parameters:
      imageId - the image ID from a previous TerminalImage.transmit(int) call
      placementId - a positive integer (1-4294967295) identifying this placement
      Returns:
      the escape sequence for placement

    • delete

      public static String delete(int imageId)
      Delete a previously transmitted image from the terminal's memory. This removes the image data and all its placements.
      Parameters:
      imageId - the image ID to delete
      Returns:
      the escape sequence for deletion

    • deletePlacement

      public static String deletePlacement(int imageId)
      Delete all placements of an image without removing the image data from terminal memory. The image can be re-placed afterwards.

      Uses lowercase d=i which deletes placements only. Use delete(int) (uppercase d=I) to also free the image data.

      Parameters:
      imageId - the image ID whose placements to remove
      Returns:
      the escape sequence for placement deletion

    • getProtocol

      public org.aesh.terminal.detect.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