# `Alaja.ImageRenderer`
[🔗](https://github.com/Lorenzo-SF/alaja/blob/2.1.0/lib/alaja/image_renderer.ex#L1)

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()

# `detect_protocol`

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

Detects the best protocol for the current terminal.

# `generate_png`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`)

---

*Consult [api-reference.md](api-reference.md) for complete listing*