Alaja.ImageRenderer (Alaja v2.4.0)

Image rendering for terminal emulators.

Supports multiple protocols:

Kitty Graphics Protocol
iTerm2 Inline Images
Sixel (via img2sixel)
ASCII fallback (via img2txt)
ASCII art (coloured or monochrome, pure Elixir for PNG)

Usage

# Render an image file
Alaja.ImageRenderer.render_file("image.png")

# Render pixel data directly
pixels = for y <- 0..99, do: for x <- 0..99, do: {x * 2, y * 2, 128}
Alaja.ImageRenderer.render(pixels, width: 100, height: 100)

# Detect protocol
protocol = Alaja.ImageRenderer.detect_protocol()

Summary

Functions

detect_protocol()

Detects the best protocol for the current terminal.

generate_png(pixels, width, height)

Generates an RGB PNG binary from pixel data.

generate_png_rgba(pixels, width, height)

Generates an RGBA PNG binary from pixel data (with alpha).

load_image_pixels(path, opts \\ [])

Loads image pixels for rendering.

render(pixels, opts \\ [])

Renders pixel data to the terminal.

render_ascii_art(path, opts \\ [])

Renders an image as colored or monochrome ASCII art.

render_file(path, opts \\ [])

Renders an image file to the terminal.

Functions

detect_protocol()

@spec detect_protocol() :: :kitty | :iterm2 | :sixel | :ascii

Detects the best protocol for the current terminal.

generate_png(pixels, width, height)

@spec generate_png([[{0..255, 0..255, 0..255}]], pos_integer(), pos_integer()) ::
  binary()

Generates an RGB PNG binary from pixel data.

generate_png_rgba(pixels, width, height)

@spec generate_png_rgba(
  [[{0..255, 0..255, 0..255, 0..255}]],
  pos_integer(),
  pos_integer()
) :: binary()

Generates an RGBA PNG binary from pixel data (with alpha).

load_image_pixels(path, opts \\ [])

@spec load_image_pixels(
  String.t(),
  keyword()
) :: {:ok, [[{0..255, 0..255, 0..255}]]} | {:error, String.t()}

Loads image pixels for rendering.

Returns pixel data as a list of rows, each row a list of {r, g, b} tuples. Supports PNG natively; other formats require ImageMagick's convert.

render(pixels, opts \\ [])

@spec render(
  [[{non_neg_integer(), non_neg_integer(), non_neg_integer()}]],
  keyword()
) :: :ok | :unsupported

Renders pixel data to the terminal.

Parameters

pixels — List of rows, each row is a list of {r, g, b} tuples

render_ascii_art(path, opts \\ [])

@spec render_ascii_art(
  String.t(),
  keyword()
) :: :ok | :unsupported

Renders an image as colored or monochrome ASCII art.

Only PNG is supported natively (pure Elixir). For other formats, ImageMagick (convert) is required as a fallback.

Options

:width — target width in characters
:height — target height in characters
:ascii_style — character set preset
:ascii_chars — custom character string
:ascii_color — whether to colorize output (default: true)
:ascii_saturation — color saturation 0.0-1.0

render_file(path, opts \\ [])

@spec render_file(
  String.t(),
  keyword()
) :: :ok | :unsupported | {:error, term()}

Renders an image file to the terminal.

Options

:width — Target width in cells
:height — Target height in cells
:protocol — Force a specific protocol (:kitty, :iterm2, :sixel, :ascii)