comparing ae5b068884f37cd5f665f41b1f7e89acb5432cf1 and main on anil.recoil.org/ocaml-kgp

+49

.tangled/workflows/build.yml

···

       1
       1
       +
       when:

     

       2
       2
       +
         - event: ["push", "pull_request"]

     

       3
       3
       +
           branch: ["main"]

     

       4
       4
       +
       

     

       5
       5
       +
       engine: nixery

     

       6
       6
       +
       

     

       7
       7
       +
       dependencies:

     

       8
       8
       +
         nixpkgs:

     

       9
       9
       +
           - shell

     

       10
       10
       +
           - stdenv

     

       11
       11
       +
           - findutils

     

       12
       12
       +
           - binutils

     

       13
       13
       +
           - libunwind

     

       14
       14
       +
           - ncurses

     

       15
       15
       +
           - opam

     

       16
       16
       +
           - git

     

       17
       17
       +
           - gawk

     

       18
       18
       +
           - gnupatch

     

       19
       19
       +
           - gnum4

     

       20
       20
       +
           - gnumake

     

       21
       21
       +
           - gnutar

     

       22
       22
       +
           - gnused

     

       23
       23
       +
           - gnugrep

     

       24
       24
       +
           - diffutils

     

       25
       25
       +
           - gzip

     

       26
       26
       +
           - bzip2

     

       27
       27
       +
           - gcc

     

       28
       28
       +
           - ocaml

     

       29
       29
       +
       

     

       30
       30
       +
       steps:

     

       31
       31
       +
         - name: opam

     

       32
       32
       +
           command: |

     

       33
       33
       +
              opam init --disable-sandboxing -any

     

       34
       34
       +
         - name: switch

     

       35
       35
       +
           command: |

     

       36
       36
       +
              opam install . --confirm-level=unsafe-yes --deps-only

     

       37
       37
       +
         - name: build

     

       38
       38
       +
           command: |

     

       39
       39
       +
              opam exec -- dune build

     

       40
       40
       +
         - name: switch-test

     

       41
       41
       +
           command: |

     

       42
       42
       +
              opam install . --confirm-level=unsafe-yes --deps-only --with-test

     

       43
       43
       +
         - name: test

     

       44
       44
       +
           command: |

     

       45
       45
       +
              opam exec -- dune runtest --verbose

     

       46
       46
       +
         - name: doc

     

       47
       47
       +
           command: |

     

       48
       48
       +
              opam install -y odoc

     

       49
       49
       +
              opam exec -- dune build @doc

CHANGES.md

···

       1
       1
       +
       v1.0.0 (dev)

     

       2
       2
       +
       ------------

     

       3
       3
       +
       

     

       4
       4
       +
       - Initial public release (@avsm)

+18

LICENSE.md

···

       1
       1
       +
       (*

     

       2
       2
       +
        * ISC License

     

       3
       3
       +
        * 

     

       4
       4
       +
        * Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>

     

       5
       5
       +
        *

     

       6
       6
       +
        * Permission to use, copy, modify, and distribute this software for any

     

       7
       7
       +
        * purpose with or without fee is hereby granted, provided that the above

     

       8
       8
       +
        * copyright notice and this permission notice appear in all copies.

     

       9
       9
       +
        *

     

       10
       10
       +
        * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

     

       11
       11
       +
        * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

     

       12
       12
       +
        * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

     

       13
       13
       +
        * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

     

       14
       14
       +
        * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

     

       15
       15
       +
        * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

     

       16
       16
       +
        * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

     

       17
       17
       +
        *

     

       18
       18
       +
        *)

+66

README.md

···

       1
       1
       +
       # kgp - Kitty Graphics Protocol for OCaml

     

       2
       2
       +
       

     

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

     

       4
       4
       +
       

     

       5
       5
       +
       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.

     

       6
       6
       +
       

     

       7
       7
       +
       Other features include:

     

       8
       8
       +
       - Image transmission with automatic chunking and base64 encoding

     

       9
       9
       +
       - Multiple placements of the same image

     

       10
       10
       +
       - Animation support with frame deltas

     

       11
       11
       +
       - Unicode placeholder mode for proper scrolling

     

       12
       12
       +
       - tmux passthrough support (requires tmux 3.3+)

     

       13
       13
       +
       - Terminal capability detection

     

       14
       14
       +
       

     

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

     

       16
       16
       +
       

     

       17
       17
       +
       ## Installation

     

       18
       18
       +
       

     

       19
       19
       +
       ```

     

       20
       20
       +
       opam install kgp

     

       21
       21
       +
       ```

     

       22
       22
       +
       

     

       23
       23
       +
       ## Usage

     

       24
       24
       +
       

     

       25
       25
       +
       ### Library

     

       26
       26
       +
       

     

       27
       27
       +
       ```ocaml

     

       28
       28
       +
       (* Display a PNG image *)

     

       29
       29
       +
       let png_data = read_file "image.png" in

     

       30
       30
       +
       let cmd = Kgp.transmit_and_display ~format:`Png () in

     

       31
       31
       +
       let buf = Buffer.create 1024 in

     

       32
       32
       +
       Kgp.write buf cmd ~data:png_data;

     

       33
       33
       +
       print_string (Buffer.contents buf)

     

       34
       34
       +
       ```

     

       35
       35
       +
       

     

       36
       36
       +
       ```ocaml

     

       37
       37
       +
       (* Transmit once, display multiple times *)

     

       38
       38
       +
       let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in

     

       39
       39
       +
       Kgp.write buf cmd ~data:png_data;

     

       40
       40
       +
       

     

       41
       41
       +
       let cmd = Kgp.display ~image_id:1 () in

     

       42
       42
       +
       Kgp.write buf cmd ~data:""

     

       43
       43
       +
       ```

     

       44
       44
       +
       

     

       45
       45
       +
       ### CLI

     

       46
       46
       +
       

     

       47
       47
       +
       ```

     

       48
       48
       +
       # Display an image

     

       49
       49
       +
       kgpcat image.png

     

       50
       50
       +
       

     

       51
       51
       +
       # Display at specific size and position

     

       52
       52
       +
       kgpcat --place 40x20@10,5 image.png

     

       53
       53
       +
       

     

       54
       54
       +
       # Display from stdin

     

       55
       55
       +
       curl -s https://example.com/image.png | kgpcat

     

       56
       56
       +
       

     

       57
       57
       +
       # Detect terminal support

     

       58
       58
       +
       kgpcat --detect-support

     

       59
       59
       +
       

     

       60
       60
       +
       # Clear displayed images

     

       61
       61
       +
       kgpcat --clear

     

       62
       62
       +
       ```

     

       63
       63
       +
       

     

       64
       64
       +
       ## License

     

       65
       65
       +
       

     

       66
       66
       +
       ISC

TODO.md

···

       1
       1
       +
       - Support zlib via decompress or similar

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name kgpcat)

     

       3
       3
       +
        (public_name kgpcat)

     

       4
       4
       +
        (package kgp)

     

       5
       5
       +
        (libraries kgp kgp.cli cmdliner unix))

+352

bin/kgpcat.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* kgpcat - Display images in the terminal using Kitty Graphics Protocol *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       

     

       10
       10
       +
       module K = Kgp

     

       11
       11
       +
       

     

       12
       12
       +
       type align = Center | Left | Right

     

       13
       13
       +
       type fit = Width | Height | Both | None_

     

       14
       14
       +
       

     

       15
       15
       +
       type config = {

     

       16
       16
       +
         files : string list;

     

       17
       17
       +
         clear : bool;

     

       18
       18
       +
         clear_all : bool;

     

       19
       19
       +
         detect_support : bool;

     

       20
       20
       +
         align : align; [@warning "-69"]

     

       21
       21
       +
         place : (int * int * int * int) option;

     

       22
       22
       +
         scale_up : bool; [@warning "-69"]

     

       23
       23
       +
         fit : fit; [@warning "-69"]

     

       24
       24
       +
         z_index : int;

     

       25
       25
       +
         unicode_placeholder : bool;

     

       26
       26
       +
         no_trailing_newline : bool;

     

       27
       27
       +
         hold : bool;

     

       28
       28
       +
         graphics_mode : K.Terminal.graphics_mode;

     

       29
       29
       +
       }

     

       30
       30
       +
       

     

       31
       31
       +
       (* Default image size in cells when not using --place *)

     

       32
       32
       +
       let default_rows = 10

     

       33
       33
       +
       let default_cols = 20

     

       34
       34
       +
       

     

       35
       35
       +
       (* Read file contents *)

     

       36
       36
       +
       let read_file filename =

     

       37
       37
       +
         let ic = open_in_bin filename in

     

       38
       38
       +
         let n = in_channel_length ic in

     

       39
       39
       +
         let s = really_input_string ic n in

     

       40
       40
       +
         close_in ic;

     

       41
       41
       +
         s

     

       42
       42
       +
       

     

       43
       43
       +
       (* Read from stdin *)

     

       44
       44
       +
       let read_stdin () =

     

       45
       45
       +
         let buf = Buffer.create 4096 in

     

       46
       46
       +
         try

     

       47
       47
       +
           while true do

     

       48
       48
       +
             Buffer.add_channel buf stdin 4096

     

       49
       49
       +
           done;

     

       50
       50
       +
           assert false

     

       51
       51
       +
         with End_of_file -> Buffer.contents buf

     

       52
       52
       +
       

     

       53
       53
       +
       (* Detect if stdin has data *)

     

       54
       54
       +
       let stdin_has_data () =

     

       55
       55
       +
         let fd = Unix.descr_of_in_channel stdin in

     

       56
       56
       +
         not (Unix.isatty fd)

     

       57
       57
       +
       

     

       58
       58
       +
       (* Send command to terminal *)

     

       59
       59
       +
       let send ?(tmux = false) cmd ~data =

     

       60
       60
       +
         let s = if tmux then K.to_string_tmux cmd ~data else K.to_string cmd ~data in

     

       61
       61
       +
         print_string s;

     

       62
       62
       +
         flush stdout

     

       63
       63
       +
       

     

       64
       64
       +
       (* Check if file is a supported format (PNG only) *)

     

       65
       65
       +
       let is_supported_format filename =

     

       66
       66
       +
         let ext =

     

       67
       67
       +
           try

     

       68
       68
       +
             let dot = String.rindex filename '.' in

     

       69
       69
       +
             String.lowercase_ascii (String.sub filename (dot + 1) (String.length filename - dot - 1))

     

       70
       70
       +
           with Not_found -> ""

     

       71
       71
       +
         in

     

       72
       72
       +
         ext = "png" || filename = "stdin"

     

       73
       73
       +
       

     

       74
       74
       +
       (* Display a single image *)

     

       75
       75
       +
       let display_image config filename data =

     

       76
       76
       +
         let resolved_mode = K.Terminal.resolve_mode config.graphics_mode in

     

       77
       77
       +
         match resolved_mode with

     

       78
       78
       +
         | `Placeholder ->

     

       79
       79
       +
             (* No graphics support - show placeholder text *)

     

       80
       80
       +
             Printf.printf "[Image: %s (%d bytes)]\n" filename (String.length data)

     

       81
       81
       +
         | `Graphics | `Tmux ->

     

       82
       82
       +
             let use_tmux = resolved_mode = `Tmux in

     

       83
       83
       +
             (* Use unicode placeholders if requested or if in tmux mode *)

     

       84
       84
       +
             let use_unicode = config.unicode_placeholder || use_tmux in

     

       85
       85
       +
             let cols, rows =

     

       86
       86
       +
               match config.place with

     

       87
       87
       +
               | Some (w, h, _, _) -> (w, h)

     

       88
       88
       +
               | None -> (default_cols, default_rows)

     

       89
       89
       +
             in

     

       90
       90
       +
             if use_unicode then (

     

       91
       91
       +
               (* Unicode placeholder mode: transmit image, then output placeholder chars *)

     

       92
       92
       +
               let image_id = K.next_image_id () in

     

       93
       93
       +
               let placement =

     

       94
       94
       +
                 match config.place with

     

       95
       95
       +
                 | Some (w, h, x, y) ->

     

       96
       96
       +
                     K.Placement.make ~columns:w ~rows:h ~cell_x_offset:x ~cell_y_offset:y

     

       97
       97
       +
                       ~z_index:config.z_index ~unicode_placeholder:true ~cursor:`Static ()

     

       98
       98
       +
                 | None ->

     

       99
       99
       +
                     let z = if config.z_index <> 0 then Some config.z_index else None in

     

       100
       100
       +
                     K.Placement.make ~columns:cols ~rows ?z_index:z ~unicode_placeholder:true

     

       101
       101
       +
                       ~cursor:`Static ()

     

       102
       102
       +
               in

     

       103
       103
       +
               (* Transmit the image data with virtual placement *)

     

       104
       104
       +
               let cmd =

     

       105
       105
       +
                 K.transmit_and_display ~image_id ~format:`Png ~placement ~quiet:`Errors_only ()

     

       106
       106
       +
               in

     

       107
       107
       +
               send ~tmux:use_tmux cmd ~data;

     

       108
       108
       +
               (* Output unicode placeholder characters that reference the image *)

     

       109
       109
       +
               let buf = Buffer.create 256 in

     

       110
       110
       +
               K.Unicode_placeholder.write buf ~image_id ~rows ~cols ();

     

       111
       111
       +
               print_string (Buffer.contents buf);

     

       112
       112
       +
               if not config.no_trailing_newline then print_newline ()

     

       113
       113
       +
             ) else (

     

       114
       114
       +
               (* Direct graphics mode *)

     

       115
       115
       +
               let image_id = K.next_image_id () in

     

       116
       116
       +
               let placement =

     

       117
       117
       +
                 match config.place with

     

       118
       118
       +
                 | Some (w, h, x, y) ->

     

       119
       119
       +
                     Some

     

       120
       120
       +
                       (K.Placement.make ~columns:w ~rows:h ~cell_x_offset:x ~cell_y_offset:y

     

       121
       121
       +
                          ~z_index:config.z_index ~cursor:`Static ())

     

       122
       122
       +
                 | None ->

     

       123
       123
       +
                     let z = if config.z_index <> 0 then Some config.z_index else None in

     

       124
       124
       +
                     Some

     

       125
       125
       +
                       (K.Placement.make ?z_index:z

     

       126
       126
       +
                          ~cursor:(if config.no_trailing_newline then `Static else `Move) ())

     

       127
       127
       +
               in

     

       128
       128
       +
               let cmd =

     

       129
       129
       +
                 K.transmit_and_display ~image_id ~format:`Png ?placement ~quiet:`Errors_only ()

     

       130
       130
       +
               in

     

       131
       131
       +
               send ~tmux:use_tmux cmd ~data;

     

       132
       132
       +
               if not config.no_trailing_newline && config.place = None then print_newline ()

     

       133
       133
       +
             )

     

       134
       134
       +
       

     

       135
       135
       +
       (* Clear all images *)

     

       136
       136
       +
       let do_clear () =

     

       137
       137
       +
         send (K.delete `All_visible) ~data:""

     

       138
       138
       +
       

     

       139
       139
       +
       (* Clear all images including scrollback *)

     

       140
       140
       +
       let do_clear_all () =

     

       141
       141
       +
         (* Delete all images by ID range 1 to max, freeing data *)

     

       142
       142
       +
         send (K.delete ~free:true (`By_id_range (1, 4294967295))) ~data:""

     

       143
       143
       +
       

     

       144
       144
       +
       (* Detect terminal support *)

     

       145
       145
       +
       let do_detect_support () =

     

       146
       146
       +
         if K.Terminal.is_graphics_terminal () then (

     

       147
       147
       +
           let mode =

     

       148
       148
       +
             if K.Terminal.is_tmux () then "tmux"

     

       149
       149
       +
             else if K.Terminal.is_kitty () then "kitty"

     

       150
       150
       +
             else if K.Terminal.is_wezterm () then "wezterm"

     

       151
       151
       +
             else if K.Terminal.is_ghostty () then "ghostty"

     

       152
       152
       +
             else "stream"

     

       153
       153
       +
           in

     

       154
       154
       +
           Printf.eprintf "%s\n" mode;

     

       155
       155
       +
           0

     

       156
       156
       +
         ) else (

     

       157
       157
       +
           Printf.eprintf "not supported\n";

     

       158
       158
       +
           1

     

       159
       159
       +
         )

     

       160
       160
       +
       

     

       161
       161
       +
       (* Main run function *)

     

       162
       162
       +
       let run config =

     

       163
       163
       +
         (* Handle clear operations first *)

     

       164
       164
       +
         if config.clear_all then do_clear_all ()

     

       165
       165
       +
         else if config.clear then do_clear ();

     

       166
       166
       +
       

     

       167
       167
       +
         (* Handle detect support *)

     

       168
       168
       +
         if config.detect_support then exit (do_detect_support ());

     

       169
       169
       +
       

     

       170
       170
       +
         (* Process files *)

     

       171
       171
       +
         let files =

     

       172
       172
       +
           if config.files = [] && stdin_has_data () then [ "-" ] else config.files

     

       173
       173
       +
         in

     

       174
       174
       +
         if files = [] && not config.clear && not config.clear_all then (

     

       175
       175
       +
           Printf.eprintf "Usage: kgpcat [OPTIONS] IMAGE_FILE...\n";

     

       176
       176
       +
           Printf.eprintf "Try 'kgpcat --help' for more information.\n";

     

       177
       177
       +
           exit 1);

     

       178
       178
       +
       

     

       179
       179
       +
         List.iter

     

       180
       180
       +
           (fun file ->

     

       181
       181
       +
             let name = if file = "-" then "stdin" else file in

     

       182
       182
       +
             if not (is_supported_format name) then

     

       183
       183
       +
               Printf.eprintf "Error: %s is not a PNG file (only PNG format is supported)\n" file

     

       184
       184
       +
             else

     

       185
       185
       +
               try

     

       186
       186
       +
                 let data =

     

       187
       187
       +
                   if file = "-" then read_stdin () else read_file file

     

       188
       188
       +
                 in

     

       189
       189
       +
                 display_image config name data

     

       190
       190
       +
               with

     

       191
       191
       +
               | Sys_error msg ->

     

       192
       192
       +
                   Printf.eprintf "Error reading %s: %s\n" file msg

     

       193
       193
       +
               | exn ->

     

       194
       194
       +
                   Printf.eprintf "Error processing %s: %s\n" file (Printexc.to_string exn))

     

       195
       195
       +
           files;

     

       196
       196
       +
       

     

       197
       197
       +
         (* Ensure all output is flushed before exiting *)

     

       198
       198
       +
         flush stdout;

     

       199
       199
       +
       

     

       200
       200
       +
         if config.hold then (

     

       201
       201
       +
           Printf.eprintf "Press Enter to exit...";

     

       202
       202
       +
           flush stderr;

     

       203
       203
       +
           ignore (read_line ()))

     

       204
       204
       +
       

     

       205
       205
       +
       (* Cmdliner argument definitions *)

     

       206
       206
       +
       

     

       207
       207
       +
       let files_arg =

     

       208
       208
       +
         Arg.(value & pos_all file [] & info [] ~docv:"IMAGE" ~doc:"Image files to display.")

     

       209
       209
       +
       

     

       210
       210
       +
       let clear_arg =

     

       211
       211
       +
         let doc = "Remove all images currently displayed on the screen." in

     

       212
       212
       +
         Arg.(value & flag & info [ "clear" ] ~doc)

     

       213
       213
       +
       

     

       214
       214
       +
       let clear_all_arg =

     

       215
       215
       +
         let doc = "Remove all images from screen and scrollback." in

     

       216
       216
       +
         Arg.(value & flag & info [ "clear-all" ] ~doc)

     

       217
       217
       +
       

     

       218
       218
       +
       let detect_support_arg =

     

       219
       219
       +
         let doc =

     

       220
       220
       +
           "Detect support for image display in the terminal. Exits with code 0 if \

     

       221
       221
       +
            supported, 1 otherwise. Prints the supported transfer mode to stderr."

     

       222
       222
       +
         in

     

       223
       223
       +
         Arg.(value & flag & info [ "detect-support" ] ~doc)

     

       224
       224
       +
       

     

       225
       225
       +
       let align_arg =

     

       226
       226
       +
         let doc = "Horizontal alignment for the displayed image." in

     

       227
       227
       +
         let align_enum = Arg.enum [ ("center", Center); ("left", Left); ("right", Right) ] in

     

       228
       228
       +
         Arg.(value & opt align_enum Center & info [ "align" ] ~doc ~docv:"ALIGN")

     

       229
       229
       +
       

     

       230
       230
       +
       let place_arg =

     

       231
       231
       +
         let doc =

     

       232
       232
       +
           "Display image in specified rectangle. Format: WxH@X,Y where W and H are \

     

       233
       233
       +
            width and height in cells, and X,Y is the position. Example: 40x20@10,5"

     

       234
       234
       +
         in

     

       235
       235
       +
         let parse s =

     

       236
       236
       +
           try

     

       237
       237
       +
             let at_pos = String.index s '@' in

     

       238
       238
       +
             let size_part = String.sub s 0 at_pos in

     

       239
       239
       +
             let pos_part = String.sub s (at_pos + 1) (String.length s - at_pos - 1) in

     

       240
       240
       +
             let x_pos = String.index size_part 'x' in

     

       241
       241
       +
             let w = int_of_string (String.sub size_part 0 x_pos) in

     

       242
       242
       +
             let h = int_of_string (String.sub size_part (x_pos + 1) (String.length size_part - x_pos - 1)) in

     

       243
       243
       +
             let comma_pos = String.index pos_part ',' in

     

       244
       244
       +
             let x = int_of_string (String.sub pos_part 0 comma_pos) in

     

       245
       245
       +
             let y = int_of_string (String.sub pos_part (comma_pos + 1) (String.length pos_part - comma_pos - 1)) in

     

       246
       246
       +
             Ok (w, h, x, y)

     

       247
       247
       +
           with _ -> Error (`Msg "Invalid place format. Use WxH@X,Y (e.g., 40x20@10,5)")

     

       248
       248
       +
         in

     

       249
       249
       +
         let print ppf (w, h, x, y) = Format.fprintf ppf "%dx%d@%d,%d" w h x y in

     

       250
       250
       +
         let place_conv = Arg.conv (parse, print) in

     

       251
       251
       +
         Arg.(value & opt (some place_conv) None & info [ "place" ] ~doc ~docv:"WxH@X,Y")

     

       252
       252
       +
       

     

       253
       253
       +
       let scale_up_arg =

     

       254
       254
       +
         let doc =

     

       255
       255
       +
           "Scale up images smaller than the specified area to use as much of the \

     

       256
       256
       +
            area as possible."

     

       257
       257
       +
         in

     

       258
       258
       +
         Arg.(value & flag & info [ "scale-up" ] ~doc)

     

       259
       259
       +
       

     

       260
       260
       +
       let fit_arg =

     

       261
       261
       +
         let doc = "Control how the image is scaled relative to the screen." in

     

       262
       262
       +
         let fit_enum =

     

       263
       263
       +
           Arg.enum [ ("width", Width); ("height", Height); ("both", Both); ("none", None_) ]

     

       264
       264
       +
         in

     

       265
       265
       +
         Arg.(value & opt fit_enum Width & info [ "fit" ] ~doc ~docv:"FIT")

     

       266
       266
       +
       

     

       267
       267
       +
       let z_index_arg =

     

       268
       268
       +
         let doc =

     

       269
       269
       +
           "Z-index of the image. Negative values display text on top of the image."

     

       270
       270
       +
         in

     

       271
       271
       +
         Arg.(value & opt int 0 & info [ "z"; "z-index" ] ~doc ~docv:"Z")

     

       272
       272
       +
       

     

       273
       273
       +
       let unicode_placeholder_arg =

     

       274
       274
       +
         let doc =

     

       275
       275
       +
           "Use Unicode placeholder method to display images. This allows images to \

     

       276
       276
       +
            scroll properly with text in terminals and multiplexers. Automatically \

     

       277
       277
       +
            enabled when using tmux passthrough mode."

     

       278
       278
       +
         in

     

       279
       279
       +
         Arg.(value & flag & info [ "unicode-placeholder" ] ~doc)

     

       280
       280
       +
       

     

       281
       281
       +
       let no_trailing_newline_arg =

     

       282
       282
       +
         let doc = "Don't move cursor to next line after displaying an image." in

     

       283
       283
       +
         Arg.(value & flag & info [ "n"; "no-trailing-newline" ] ~doc)

     

       284
       284
       +
       

     

       285
       285
       +
       let hold_arg =

     

       286
       286
       +
         let doc = "Wait for a key press before exiting after displaying images." in

     

       287
       287
       +
         Arg.(value & flag & info [ "hold" ] ~doc)

     

       288
       288
       +
       

     

       289
       289
       +
       let config_term =

     

       290
       290
       +
         let combine files clear clear_all detect_support align place scale_up fit z_index

     

       291
       291
       +
             unicode_placeholder no_trailing_newline hold graphics_mode =

     

       292
       292
       +
           {

     

       293
       293
       +
             files;

     

       294
       294
       +
             clear;

     

       295
       295
       +
             clear_all;

     

       296
       296
       +
             detect_support;

     

       297
       297
       +
             align;

     

       298
       298
       +
             place;

     

       299
       299
       +
             scale_up;

     

       300
       300
       +
             fit;

     

       301
       301
       +
             z_index;

     

       302
       302
       +
             unicode_placeholder;

     

       303
       303
       +
             no_trailing_newline;

     

       304
       304
       +
             hold;

     

       305
       305
       +
             graphics_mode;

     

       306
       306
       +
           }

     

       307
       307
       +
         in

     

       308
       308
       +
         Term.(

     

       309
       309
       +
           const combine

     

       310
       310
       +
           $ files_arg

     

       311
       311
       +
           $ clear_arg

     

       312
       312
       +
           $ clear_all_arg

     

       313
       313
       +
           $ detect_support_arg

     

       314
       314
       +
           $ align_arg

     

       315
       315
       +
           $ place_arg

     

       316
       316
       +
           $ scale_up_arg

     

       317
       317
       +
           $ fit_arg

     

       318
       318
       +
           $ z_index_arg

     

       319
       319
       +
           $ unicode_placeholder_arg

     

       320
       320
       +
           $ no_trailing_newline_arg

     

       321
       321
       +
           $ hold_arg

     

       322
       322
       +
           $ Kgp_cli.graphics_term)

     

       323
       323
       +
       

     

       324
       324
       +
       let cmd =

     

       325
       325
       +
         let doc = "Display images in the terminal using Kitty Graphics Protocol" in

     

       326
       326
       +
         let man =

     

       327
       327
       +
           [

     

       328
       328
       +
             `S Manpage.s_description;

     

       329
       329
       +
             `P

     

       330
       330
       +
               "$(tname) displays images in terminals that support the Kitty Graphics \

     

       331
       331
       +
                Protocol (Kitty, WezTerm, Konsole, Ghostty, etc.).";

     

       332
       332
       +
             `P

     

       333
       333
       +
               "You can specify multiple image files. If no files are given and stdin \

     

       334
       334
       +
                is not a terminal, image data is read from stdin.";

     

       335
       335
       +
             `S Manpage.s_examples;

     

       336
       336
       +
             `P "Display an image:";

     

       337
       337
       +
             `Pre "  $(tname) photo.png";

     

       338
       338
       +
             `P "Display multiple images:";

     

       339
       339
       +
             `Pre "  $(tname) *.png";

     

       340
       340
       +
             `P "Display image from stdin:";

     

       341
       341
       +
             `Pre "  curl -s https://example.com/image.png | $(tname)";

     

       342
       342
       +
             `P "Display image at specific position:";

     

       343
       343
       +
             `Pre "  $(tname) --place 40x20@10,5 photo.png";

     

       344
       344
       +
             `P "Clear all displayed images:";

     

       345
       345
       +
             `Pre "  $(tname) --clear";

     

       346
       346
       +
             `S Kgp_cli.graphics_docs;

     

       347
       347
       +
           ]

     

       348
       348
       +
         in

     

       349
       349
       +
         let info = Cmd.info "kgpcat" ~version:"%%VERSION%%" ~doc ~man in

     

       350
       350
       +
         Cmd.v info Term.(const run $ config_term)

     

       351
       351
       +
       

     

       352
       352
       +
       let () = exit (Cmd.eval cmd)

+1 -1

example/example.ml

···

       3
       3
        
          SPDX-License-Identifier: ISC

     

       4
       4
        
         ---------------------------------------------------------------------------*)

     

       5
       5
        
       

     

       6
       6
       -
       (* Kitty Graphics Protocol Demo - Matching kgp/examples/demo *)

     

       6
       6
       +
       (* Kitty Graphics Protocol Demo  *)

     

       7
       7
        
       

     

       8
       8
        
       module K = Kgp

     

       9
       9

+4 -4

example/tiny_anim.ml

···

       31
       31
        
         (* Clear any existing images *)

     

       32
       32
        
         send (K.delete ~free:true ~quiet:`Errors_only `All_visible) ~data:"";

     

       33
       33
        
       

     

       34
       34
       -
         (* Step 1: Transmit base frame (red) - matching Go's sequence *)

     

       34
       34
       +
         (* Step 1: Transmit base frame (red) *)

     

       35
       35
        
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       36
       36
        
         send

     

       37
       37
        
           (K.transmit ~image_id ~format:`Rgba32 ~width ~height ~quiet:`Errors_only ())

     

       38
       38
        
           ~data:red_frame;

     

       39
       39
        
       

     

       40
       40
       -
         (* Step 2: Add frame (orange) with 100ms gap - like Go *)

     

       40
       40
       +
         (* Step 2: Add frame (orange) with 100ms gap *)

     

       41
       41
        
         let orange_frame =

     

       42
       42
        
           solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255

     

       43
       43
        
         in

     
···

       65
       65
        
              ~quiet:`Errors_only ())

     

       66
       66
        
           ~data:green_frame;

     

       67
       67
        
       

     

       68
       68
       -
         (* Step 5: Create placement - exactly like Go *)

     

       68
       68
       +
         (* Step 5: Create placement *)

     

       69
       69
        
         send

     

       70
       70
        
           (K.display ~image_id

     

       71
       71
        
              ~placement:

     
···

       74
       74
        
              ~quiet:`Errors_only ())

     

       75
       75
        
           ~data:"";

     

       76
       76
        
       

     

       77
       77
       -
         (* Step 6: Start animation - exactly like Go (NO root frame gap) *)

     

       77
       77
       +
         (* Step 6: Start animation *)

     

       78
       78
        
         send (K.animate ~image_id (K.Animation.set_state ~loops:1 `Run)) ~data:"";

     

       79
       79
        
       

     

       80
       80
        
         print_endline "";

Compare changes