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

View Source

iTerm2 inline images protocol implementation.

iTerm2 supports displaying images directly in the terminal using OSC escape sequences. This protocol allows embedding images inline with terminal text, making it perfect for rich terminal applications.

Features

  • Direct image embedding with OSC 1337 sequences
  • Multiple image formats (PNG, JPEG, GIF, BMP)
  • Base64 encoding for image data transmission
  • Image positioning and sizing controls
  • Preservation of aspect ratio
  • Image metadata and naming
  • Progress indicators for large images

Usage

# Display an image from file
ITerm2Protocol.display_image_file("/path/to/image.png")

# Display image with options
ITerm2Protocol.display_image_data(image_data, format: :png, 
                                  width: 200, height: 100)

# Check if terminal supports iTerm2 protocol
ITerm2Protocol.supported?()

OSC 1337 Format

The iTerm2 protocol uses OSC 1337 sequences with the format: \033]1337;File=[arguments]:base64_data\007

Where arguments can include:

  • name: filename
  • size: file size in bytes
  • width: display width
  • height: display height
  • preserveAspectRatio: 0 or 1
  • inline: 0 or 1 for inline display

Summary

Types

display_options()
image_format()

Functions

clear_images()

Clears all inline images from the terminal.

create_placeholder(identifier, options \\ %{})

Generates an iTerm2 image placeholder sequence.

create_progress_indicator(bytes_sent, total_bytes, options \\ %{})

Creates a progress indicator for large image transfers.

display_image_data(data, options \\ %{})

Displays image data using iTerm2 inline image protocol.

display_image_file(file_path, options \\ %{})

Displays an image file using iTerm2 inline image protocol.

get_max_image_size()

Gets the maximum recommended image size for the current terminal.

supported?()

Checks if the terminal supports iTerm2 inline images.

validate_image_data(data, options \\ %{})

Validates image data before transmission.

Types

display_options()

@type display_options() :: %{
  optional(:width) => pos_integer(),
  optional(:height) => pos_integer(),
  optional(:name) => String.t(),
  optional(:preserve_aspect_ratio) => boolean(),
  optional(:inline) => boolean(),
  optional(:format) => image_format()
}

image_format()

@type image_format() :: :png | :jpeg | :gif | :bmp | :tiff | :webp

Functions

clear_images()

@spec clear_images() :: binary()

Clears all inline images from the terminal.

Sends a sequence to clear any displayed inline images. Useful for cleaning up the display.

Returns

  • binary() - Sequence to clear images

create_placeholder(identifier, options \\ %{})

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

Generates an iTerm2 image placeholder sequence.

Creates a placeholder that can be later replaced with actual image data. Useful for progressive image loading or streaming scenarios.

Parameters

  • identifier - Unique identifier for the placeholder
  • options - Placeholder options

Returns

  • {:ok, sequence} - Placeholder sequence
  • {:error, reason} - Error if invalid parameters

create_progress_indicator(bytes_sent, total_bytes, options \\ %{})

@spec create_progress_indicator(non_neg_integer(), pos_integer(), map()) :: binary()

Creates a progress indicator for large image transfers.

Useful for showing upload progress when sending large images to the terminal.

Parameters

  • bytes_sent - Number of bytes already transmitted
  • total_bytes - Total size of the image
  • options - Progress display options

Returns

  • binary() - Progress display sequence

display_image_data(data, options \\ %{})

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

Displays image data using iTerm2 inline image protocol.

Parameters

  • image_data - Binary image data
  • options - Display options map

Returns

  • {:ok, sequence} - OSC sequence to display the image
  • {:error, reason} - Error if image cannot be processed

Examples

iex> ITerm2Protocol.display_image_data(png_data, format: :png, width: 300)
{:ok, "\e]1337;File=width=300;inline=1:base64data...\a"}

display_image_file(file_path, options \\ %{})

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

Displays an image file using iTerm2 inline image protocol.

Parameters

  • file_path - Path to the image file
  • options - Display options (width, height, etc.)

Returns

  • {:ok, sequence} - OSC sequence to display the image
  • {:error, reason} - Error if file cannot be read or processed

Examples

iex> ITerm2Protocol.display_image_file("/tmp/image.png")
{:ok, "\e]1337;File=name=aW1hZ2UucG5n;size=1024:base64data...\a"}

get_max_image_size()

@spec get_max_image_size() :: pos_integer()

Gets the maximum recommended image size for the current terminal.

Different terminals have different limits for inline images. This function returns a safe maximum size.

Returns

  • pos_integer() - Maximum image size in bytes

supported?()

@spec supported?() :: boolean()

Checks if the terminal supports iTerm2 inline images.

Returns

  • true if iTerm2 protocol is supported
  • false if not supported or unknown

validate_image_data(data, options \\ %{})

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

Validates image data before transmission.

Checks if the image data is valid and suitable for terminal display.

Parameters

  • data - Binary image data
  • options - Validation options

Returns

  • :ok - Image data is valid
  • {:error, reason} - Image data has issues