Alaja.ImageRenderer (Alaja v1.0.0)

Image rendering for terminal emulators.

Supports multiple protocols:

Kitty Graphics Protocol
iTerm2 Inline Images
Sixel (via img2sixel)
ASCII fallback

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 a PNG binary from pixel data.

generate_png_rgba(pixels, width, height)

Generates a PNG binary from RGBA pixel data (with alpha channel for transparency).

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(
  [[{non_neg_integer(), non_neg_integer(), non_neg_integer()}]],
  pos_integer(),
  pos_integer()
) :: binary()

Generates a PNG binary from pixel data.

Parameters

pixels - List of rows, each row a list of {r, g, b} tuples
width - Image width in pixels
height - Image height in pixels

generate_png_rgba(pixels, width, height)

@spec generate_png_rgba(
  [
    [
      {non_neg_integer(), non_neg_integer(), non_neg_integer(),
       non_neg_integer()}
    ]
  ],
  pos_integer(),
  pos_integer()
) :: binary()

Generates a PNG binary from RGBA pixel data (with alpha channel for transparency).

Parameters

pixels - List of rows, each row a list of {r, g, b, a} tuples
width - Image width in pixels
height - Image height in pixels

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 (default: 40)
:height — target height in characters (default: auto from aspect ratio)
:ascii_style — character set preset (:blocks, :detailed, :simple, :braille)
:ascii_chars — custom character string (overrides :ascii_style)
:ascii_color — whether to colorize output (default: true)
:ascii_saturation — color saturation 0.0-1.0 (default: 1.0)

render_file(path, opts \\ [])

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

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)