mirror of
https://github.com/kovidgoyal/kitty.git
synced 2026-05-13 08:26:56 +00:00
73 lines
2.7 KiB
ReStructuredText
73 lines
2.7 KiB
ReStructuredText
icat
|
|
========================================
|
|
|
|
.. only:: man
|
|
|
|
Overview
|
|
--------------
|
|
|
|
|
|
*Display images in the terminal*
|
|
|
|
The ``icat`` kitten can be used to display arbitrary images in the |kitty|
|
|
terminal. Using it is as simple as::
|
|
|
|
kitten icat image.jpeg
|
|
|
|
It supports all image types supported by `ImageMagick
|
|
<https://www.imagemagick.org>`__. It even works over SSH. For details, see the
|
|
:doc:`kitty graphics protocol </graphics-protocol>`.
|
|
|
|
You might want to create an alias in your shell's configuration files::
|
|
|
|
alias icat="kitten icat"
|
|
|
|
Then you can simply use ``icat image.png`` to view images.
|
|
|
|
.. note::
|
|
|
|
`ImageMagick <https://www.imagemagick.org>`__ must be installed for the
|
|
full range of image types. Without it only PNG/JPG/GIF/BMP/TIFF/WEBP are
|
|
supported.
|
|
|
|
.. note::
|
|
|
|
kitty's image display protocol may not work when used within a terminal
|
|
multiplexer such as :program:`screen` or :program:`tmux`, depending on
|
|
whether the multiplexer has added support for it or not.
|
|
|
|
|
|
.. program:: kitty +kitten icat
|
|
|
|
|
|
The ``icat`` kitten has various command line arguments to allow it to be used
|
|
from inside other programs to display images. In particular, :option:`--place`,
|
|
:option:`--detect-support` and :option:`--print-window-size`.
|
|
|
|
If you are trying to integrate icat into a complex program like a file manager
|
|
or editor, there are a few things to keep in mind. icat normally works by communicating
|
|
over the TTY device, it both writes to and reads from the TTY. So it is
|
|
imperative that while it is running the host program does not do any TTY I/O.
|
|
Any key presses or other input from the user on the TTY device will be
|
|
discarded. If you would instead like to use it just as a backend to generate
|
|
the escape codes for image display, you need to pass it options to tell it the
|
|
window dimensions, where to place the image in the window and the transfer mode
|
|
to use. If you do that, it will not try to communicate with the TTY device at
|
|
all. The requisite options are: :option:`--use-window-size`, :option:`--place`
|
|
and :option:`--transfer-mode`, :option:`--stdin=no`.
|
|
For example, to demonstrate usage without access to the TTY:
|
|
|
|
.. code:: sh
|
|
|
|
zsh -c 'setsid kitten icat --stdin=no --use-window-size $COLUMNS,$LINES,3000,2000 --transfer-mode=file myimage.png'
|
|
|
|
Here, ``setsid`` ensures icat has no access to the TTY device.
|
|
The values, 3000, 2000 are made up. They are the window width and height in
|
|
pixels, to obtain which access to the TTY is needed.
|
|
|
|
To be really robust you should consider writing proper support for the
|
|
:doc:`kitty graphics protocol </graphics-protocol>` in the program instead.
|
|
Nowadays there are many libraries that have support for it.
|
|
|
|
|
|
.. include:: /generated/cli-kitten-icat.rst
|