# kgp - Kitty Graphics Protocol for OCaml

An OCaml library for displaying images in terminals using the [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).

This library can display PNG images in supported terminals (e.g. Kitty, WezTerm, Konsole, Ghostty) with varying levels of support depending on the terminal. Most core features work but some advanced things like animations might be only partially supported outside of Kitty.

Other features include:
- Image transmission with automatic chunking and base64 encoding
- Multiple placements of the same image
- Animation support with frame deltas
- Unicode placeholder mode for proper scrolling
- tmux passthrough support (requires tmux 3.3+)
- Terminal capability detection

The library provides a Cmdliner term via the `kgp.cli` package to make integration into other CLI tools easier.

## Installation

```
opam install kgp
```

## Usage

### Library

```ocaml
(* Display a PNG image *)
let png_data = read_file "image.png" in
let cmd = Kgp.transmit_and_display ~format:`Png () in
let buf = Buffer.create 1024 in
Kgp.write buf cmd ~data:png_data;
print_string (Buffer.contents buf)
```

```ocaml
(* Transmit once, display multiple times *)
let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in
Kgp.write buf cmd ~data:png_data;

let cmd = Kgp.display ~image_id:1 () in
Kgp.write buf cmd ~data:""
```

### CLI

```
# Display an image
kgpcat image.png

# Display at specific size and position
kgpcat --place 40x20@10,5 image.png

# Display from stdin
curl -s https://example.com/image.png | kgpcat

# Detect terminal support
kgpcat --detect-support

# Clear displayed images
kgpcat --clear
```

## License

ISC