Raxol.Terminal.ANSI.SixelGraphics (Raxol v2.0.1)

View Source

Complete Sixel graphics support for terminal rendering.

This module provides comprehensive Sixel (DEC Sixel Graphics) support:

  • Full Sixel image encoding and decoding
  • Advanced color palette management with quantization
  • Image format conversion (PNG, JPEG, GIF -> Sixel)
  • Color optimization and dithering algorithms
  • Animation frame support
  • Terminal compatibility detection
  • Performance optimizations for large images

Sixel Format

Sixel is a bitmap graphics format developed by Digital Equipment Corporation for their terminals. Each character represents 6 vertical pixels, allowing efficient transmission of images over serial connections.

Features

  • PNG/JPEG/GIF to Sixel conversion
  • Color palette optimization (up to 256 colors)
  • Floyd-Steinberg dithering
  • Transparency support
  • Animation support for GIF files
  • Compression and size optimization

Summary

Types

color_format()
dithering_algorithm()
image_format()
rgb_color()
rgba_color()
sixel_options()
sixel_state()
t()

Functions

apply_dithering(image, algorithm \\ :floyd_steinberg)

Applies dithering to reduce color banding when quantizing colors.

decode(data)

Decodes an ANSI escape sequence into a Sixel image.

encode(image)

Encodes a Sixel image to ANSI escape sequence.

from_image_data(image_data, format, options \\ %{})

Converts an image from common formats (PNG, JPEG, GIF) to Sixel format.

get_data(image)

Gets the current image data.

get_palette(image)

Gets the current color palette.

get_position(image)

Gets the current position.

get_scale(image)

Gets the current scale factors.

new()

Creates a new Sixel image with default values.

new(width, height)

Creates a new Sixel image with specified dimensions.

optimize_palette(image, max_colors \\ 256, algorithm \\ :median_cut)

Optimizes the color palette using quantization algorithms.

process_sequence(state, data)

Processes a sequence of Sixel data.

set_data(image, data)

Sets the image data for a Sixel image.

set_palette(image, palette)

Sets the color palette for a Sixel image.

set_position(image, x, y)

Sets the position for a Sixel image.

set_scale(image, x_scale, y_scale)

Sets the scale factor for a Sixel image.

supported?()

Checks if the terminal supports Sixel graphics.

Types

color_format()

@type color_format() :: :rgb | :rgba | :hsl | :indexed

dithering_algorithm()

@type dithering_algorithm() :: :none | :floyd_steinberg | :ordered | :random

image_format()

@type image_format() :: :png | :jpeg | :gif | :bmp | :raw_rgb | :raw_rgba

rgb_color()

@type rgb_color() :: {non_neg_integer(), non_neg_integer(), non_neg_integer()}

rgba_color()

@type rgba_color() ::
  {non_neg_integer(), non_neg_integer(), non_neg_integer(), non_neg_integer()}

sixel_options()

@type sixel_options() :: %{
  optional(:max_colors) => non_neg_integer(),
  optional(:dithering) => dithering_algorithm(),
  optional(:transparent_color) => rgb_color() | nil,
  optional(:optimize_palette) => boolean(),
  optional(:target_width) => non_neg_integer() | nil,
  optional(:target_height) => non_neg_integer() | nil,
  optional(:preserve_aspect_ratio) => boolean()
}

sixel_state()

@type sixel_state() :: %{
  width: non_neg_integer(),
  height: non_neg_integer(),
  data: binary(),
  palette: map(),
  current_color: non_neg_integer(),
  pixel_buffer: map()
}

t()

@type t() :: %Raxol.Terminal.ANSI.SixelGraphics{
  animation_frames: [t()] | nil,
  attributes: map(),
  compression_enabled: boolean(),
  current_color: non_neg_integer(),
  data: binary(),
  dithering_algorithm: dithering_algorithm(),
  height: non_neg_integer(),
  original_format: image_format() | nil,
  palette: map(),
  pixel_buffer: map(),
  position: {non_neg_integer(), non_neg_integer()},
  scale: {non_neg_integer(), non_neg_integer()},
  sixel_cursor_pos: {non_neg_integer(), non_neg_integer()},
  transparent_color: rgb_color() | nil,
  width: non_neg_integer()
}

Functions

apply_dithering(image, algorithm \\ :floyd_steinberg)

@spec apply_dithering(map(), dithering_algorithm()) :: map()

Applies dithering to reduce color banding when quantizing colors.

Parameters

  • image - The Sixel image
  • algorithm - Dithering algorithm (:floyd_steinberg, :ordered, :none)

Returns

  • t() - Image with dithering applied

decode(data)

@spec decode(binary()) :: Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Decodes an ANSI escape sequence into a Sixel image.

Parameters

  • data - The ANSI escape sequence to decode

Returns

A new Raxol.Terminal.ANSI.SixelGraphics.t/0 struct with the decoded image data.

encode(image)

@spec encode(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()) :: binary()

Encodes a Sixel image to ANSI escape sequence.

Parameters

  • image - The image to encode

Returns

A binary containing the ANSI escape sequence for the Sixel image.

from_image_data(image_data, format, options \\ %{})

@spec from_image_data(binary(), image_format(), sixel_options()) ::
  {:ok, map()} | {:error, term()}

Converts an image from common formats (PNG, JPEG, GIF) to Sixel format.

Parameters

  • image_data - Binary image data
  • format - Image format (:png, :jpeg, :gif)
  • options - Sixel conversion options

Returns

  • {:ok, sixel_image} - Converted Sixel image
  • {:error, reason} - Conversion error

get_data(image)

@spec get_data(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()) :: binary()

Gets the current image data.

Parameters

  • image - The current image

Returns

The binary image data.

get_palette(image)

@spec get_palette(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()) :: map()

Gets the current color palette.

Parameters

  • image - The current image

Returns

A map containing the current color palette.

get_position(image)

@spec get_position(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()) ::
  {non_neg_integer(), non_neg_integer()}

Gets the current position.

Parameters

  • image - The current image

Returns

A tuple {x, y} with the current position.

get_scale(image)

@spec get_scale(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()) ::
  {non_neg_integer(), non_neg_integer()}

Gets the current scale factors.

Parameters

  • image - The current image

Returns

A tuple {x_scale, y_scale} with the current scale factors.

new()

@spec new() :: Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Creates a new Sixel image with default values.

Returns

A new Raxol.Terminal.ANSI.SixelGraphics.t/0 struct with default values.

new(width, height)

@spec new(pos_integer(), pos_integer()) ::
  Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Creates a new Sixel image with specified dimensions.

Parameters

  • width - The image width in pixels
  • height - The image height in pixels

Returns

A new Raxol.Terminal.ANSI.SixelGraphics.t/0 struct with the specified dimensions.

optimize_palette(image, max_colors \\ 256, algorithm \\ :median_cut)

@spec optimize_palette(map(), non_neg_integer(), atom()) :: map()

Optimizes the color palette using quantization algorithms.

Parameters

  • image - The Sixel image
  • max_colors - Maximum number of colors (default: 256)
  • algorithm - Quantization algorithm (:median_cut, :octree)

Returns

  • t() - Image with optimized palette

process_sequence(state, data)

@spec process_sequence(
  Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t(),
  binary()
) :: Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Processes a sequence of Sixel data.

Parameters

  • state - The current Sixel state
  • data - The Sixel data to process

Returns

A tuple containing the updated state and a response.

set_data(image, data)

@spec set_data(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t(), binary()) ::
  Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Sets the image data for a Sixel image.

Parameters

  • image - The current image
  • data - The binary image data

Returns

The updated image with new data.

set_palette(image, palette)

@spec set_palette(Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t(), map()) ::
  Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Sets the color palette for a Sixel image.

Parameters

  • image - The current image
  • palette - A map of color indices to RGB values

Returns

The updated image with new palette.

set_position(image, x, y)

@spec set_position(
  Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t(),
  non_neg_integer(),
  non_neg_integer()
) :: Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Sets the position for a Sixel image.

Parameters

  • image - The current image
  • x - The horizontal position
  • y - The vertical position

Returns

The updated image with new position.

set_scale(image, x_scale, y_scale)

@spec set_scale(
  Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t(),
  non_neg_integer(),
  non_neg_integer()
) :: Raxol.Terminal.ANSI.SixelGraphics.Behaviour.t()

Sets the scale factor for a Sixel image.

Parameters

  • image - The current image
  • x_scale - The horizontal scale factor
  • y_scale - The vertical scale factor

Returns

The updated image with new scale factors.

supported?()

@spec supported?() :: boolean()

Checks if the terminal supports Sixel graphics.

Returns

true if Sixel graphics are supported, false otherwise.