Raxol.Terminal.Graphics.KittyProtocol (Raxol v2.0.1)

Kitty Graphics Protocol implementation for advanced terminal graphics.

Provides support for efficient image transmission, transparency, animations, and high-performance graphics rendering using the Kitty graphics protocol.

Features

Direct binary image transmission
Transparency and alpha channel support
Animation frame management
Chunked transmission for large images
Format detection and conversion
Error handling and fallback mechanisms

Supported Formats

PNG (with transparency)
JPEG
WebP
GIF (animation support)
Raw RGB/RGBA data

Protocol Specification

The Kitty graphics protocol uses OSC escape sequences with the format:

33_G<control_data>;<payload>33\

Where control_data contains comma-separated key=value pairs controlling the image transmission and display properties.

Summary

Types

action()

compression()

display_options()

format()

image_id()

kitty_image()

placement_id()

transmission_id()

transmission_medium()

transmission_options()

Functions

%Raxol.Terminal.Graphics.KittyProtocol{}

Creates a new Kitty graphics protocol handler.

create_animation(frames, options \\ %{})

Creates an animation from multiple image frames.

delete_image(image_id)

Deletes a transmitted image from terminal memory.

detect_support()

Detects if the current terminal supports Kitty graphics protocol.

display_image(image_id, options \\ %{})

Displays a previously transmitted image.

new()

query_capabilities()

Queries terminal capabilities for Kitty graphics protocol.

transmit_image(image_data, options \\ %{})

Transmits an image using the Kitty graphics protocol.

Types

action()

@type action() :: :transmit | :display | :delete | :query | :animate

compression()

@type compression() :: :none | :zlib

display_options()

@type display_options() :: %{
  optional(:x) => non_neg_integer(),
  optional(:y) => non_neg_integer(),
  optional(:width) => non_neg_integer(),
  optional(:height) => non_neg_integer(),
  optional(:x_offset) => non_neg_integer(),
  optional(:y_offset) => non_neg_integer(),
  optional(:columns) => non_neg_integer(),
  optional(:rows) => non_neg_integer(),
  optional(:z_index) => integer(),
  optional(:alpha) => float()
}

format()

@type format() :: :rgb | :rgba | :png | :jpeg | :webp | :gif

image_id()

@type image_id() :: non_neg_integer()

kitty_image()

@type kitty_image() :: %{
  id: image_id(),
  width: non_neg_integer(),
  height: non_neg_integer(),
  format: format(),
  data: binary(),
  metadata: map()
}

placement_id()

@type placement_id() :: non_neg_integer()

transmission_id()

@type transmission_id() :: non_neg_integer()

transmission_medium()

@type transmission_medium() :: :direct | :file | :temp_file | :shared_memory

transmission_options()

@type transmission_options() :: %{
  optional(:compression) => compression(),
  optional(:medium) => transmission_medium(),
  optional(:chunked) => boolean(),
  optional(:chunk_size) => non_neg_integer(),
  optional(:more_chunks) => boolean()
}

Functions

%Raxol.Terminal.Graphics.KittyProtocol{}

(struct)

Creates a new Kitty graphics protocol handler.

create_animation(frames, options \\ %{})

@spec create_animation([binary()], map()) :: {:ok, [binary()]} | {:error, term()}

Creates an animation from multiple image frames.

Parameters

frames - List of image data for animation frames
options - Animation options (frame_delay, loop, etc.)

Returns

{:ok, commands} - List of commands to create animation
{:error, reason} - Error with reason

delete_image(image_id)

@spec delete_image(image_id() | :all) :: {:ok, binary()} | {:error, term()}

Deletes a transmitted image from terminal memory.

Parameters

image_id - ID of image to delete, or :all to delete all images

Returns

{:ok, escape_sequence} - Success with delete command
{:error, reason} - Error with reason

detect_support()

@spec detect_support() :: {:ok, :supported | :unsupported} | {:error, :unknown}

Detects if the current terminal supports Kitty graphics protocol.

Uses environment variables and capability queries to determine support.

Returns

{:ok, :supported} - Terminal supports Kitty protocol
{:ok, :unsupported} - Terminal does not support Kitty protocol
{:error, :unknown} - Cannot determine terminal capabilities

display_image(image_id, options \\ %{})

@spec display_image(image_id(), display_options()) ::
  {:ok, binary()} | {:error, term()}

Displays a previously transmitted image.

Parameters

image_id - ID of previously transmitted image
options - Display positioning and sizing options

Returns

{:ok, escape_sequence} - Success with display command
{:error, reason} - Error with reason

new()

@spec new() :: %Raxol.Terminal.Graphics.KittyProtocol{
  images: term(),
  next_image_id: term()
}

query_capabilities()

@spec query_capabilities() :: {:ok, binary()} | {:error, term()}

Queries terminal capabilities for Kitty graphics protocol.

Returns

{:ok, escape_sequence} - Query command to send to terminal
{:error, reason} - Error with reason

transmit_image(image_data, options \\ %{})

@spec transmit_image(binary() | String.t(), map()) ::
  {:ok, binary()} | {:error, term()}

Transmits an image using the Kitty graphics protocol.

Parameters

image_data - Binary image data or file path
options - Transmission and display options

Returns

{:ok, escape_sequence} - Success with ANSI escape sequence
{:error, reason} - Error with reason

Examples

iex> KittyProtocol.transmit_image(png_data, %{format: :png, width: 100, height: 100})
{:ok, "\033_Ga=T,f=100,s=100,v=100,C=1,i=1;base64_data\033\\"}