Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1# kgp - Kitty Graphics Protocol for OCaml
2
3An OCaml library for displaying images in terminals using the [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
4
5This 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.
6
7Other features include:
8- Image transmission with automatic chunking and base64 encoding
9- Multiple placements of the same image
10- Animation support with frame deltas
11- Unicode placeholder mode for proper scrolling
12- tmux passthrough support (requires tmux 3.3+)
13- Terminal capability detection
14
15The library provides a Cmdliner term via the `kgp.cli` package to make integration into other CLI tools easier.
16
17## Installation
18
19```
20opam install kgp
21```
22
23## Usage
24
25### Library
26
27```ocaml
28(* Display a PNG image *)
29let png_data = read_file "image.png" in
30let cmd = Kgp.transmit_and_display ~format:`Png () in
31let buf = Buffer.create 1024 in
32Kgp.write buf cmd ~data:png_data;
33print_string (Buffer.contents buf)
34```
35
36```ocaml
37(* Transmit once, display multiple times *)
38let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in
39Kgp.write buf cmd ~data:png_data;
40
41let cmd = Kgp.display ~image_id:1 () in
42Kgp.write buf cmd ~data:""
43```
44
45### CLI
46
47```
48# Display an image
49kgpcat image.png
50
51# Display at specific size and position
52kgpcat --place 40x20@10,5 image.png
53
54# Display from stdin
55curl -s https://example.com/image.png | kgpcat
56
57# Detect terminal support
58kgpcat --detect-support
59
60# Clear displayed images
61kgpcat --clear
62```
63
64## License
65
66ISC