Home

Awesome

<img align="right" src="README.md.d/thumb.png">

lsix

Like "ls", but for images. Shows thumbnails in terminal using sixel graphics.

Usage

lsix [ FILES ... ]

Examples

Basic Usage

Just typing lsix will show images in the current working directory. You can also specify filenames and, of course, use shell wild cards (e.g., lsix *jpg *png).

Because lsix uses ImageMagick pretty much any image format will be supported. However, some may be slow to render (like PDF), so lsix doesn't show them unless you ask specifically. If you want to force a listing of a certain type of image simply specify the filenames or use a wildcard (*.pdf in the example below),.

Example 1 of lsix usage

Expanding GIFs

If you specify a GIF (or actually any file that has multiple images in it) on the command line, all the frames will get expanded and shown in a montage. For example, lsix nyancat.gif shows all the frames. Note that GIF stores some frames as only the pixels that differ from the previous frame. Example 2 of lsix usage

Terminal background color is detected

You may have noticed that PNGs and SVG files have correct alpha channel for the terminal background. That is because lsix uses terminal escape sequences to try to figure out your foreground and background colors. (Foreground is used for the text fill color.)

In the first example below, after running lsix in a white on black xterm, I sent an escape sequence to swap foreground and background colors. When I ran it again, lsix detected it and changed the background color to white. Of course, you can pick whatever default colors you want (e.g., xterm -bg blue, in the second example below).

Example 3 of lsix usage Example 4 of lsix usage

Features

Installation

Just put the lsix file in your path (e.g., /usr/local/bin) and run it. It's just a BASH shell script.

The only prerequisite software is ImageMagick. If you don't have it yet, your OS's package manager will make it easy to get. (E.g., apt-get install imagemagick).

MacOS users may prefer to install lsix using brew install lsix which installs ImageMagick, if necessary.

Your Terminal must support Sixel graphics

I developed this using xterm in vt340 emulation mode, but I believe this should work on any Sixel compatible terminal. You may test your terminal by viewing a single image, like so:

convert  foo.jpg  -geometry 800x480  sixel:- 

XTerm

Note that xterm does not have Sixel mode enabled by default, so you need to either run it like so:

xterm -ti vt340

Or, make vt340 the default terminal type for xterm. Add the following to your .Xresources file and run xrdb -merge .Xresources.

! Allow sixel graphics. (Try: "convert -colors 16 foo.jpg sixel:-").
xterm*decTerminalID	:	vt340

Further, some distributions, such as Fedora, appear to not compile xterm with sixel support. In that case, try an alternate terminal, such as foot or mlterm.

SIXEL compatible terminals

SIXEL incompatible terminals

Configuration

Because lsix is currently designed to be very simple, there are no command line flags, no configuration files, no knobs to twiddle, or frobs to frobnosticate. However, since the script is so simple, if you want to make a change, it's pretty easy to do just by editing the file. Everything is nicely commented with the most common default variables at the top.

Contact the author

I welcome feedback. If you use lsix and like it or have suggestions for how it can be improved, please go ahead and send your thoughts to me @hackerb9 via GitHub.

Bugs

Future Issues

 ESC [ ? 256 n                  Request screen size report

        Report is ESC [ ? 256; Ph; Pw; Pc n     for graphics systems

        where   Ph is screen height in dots
                Pw is screen width in dots
                Pc is number of colors (0, 1 or 16, for none, b/w, ega/vga)

        Report is ESC [ ? 24; 80; 0 n  for pure text mono systems.

Did any other terminal emulators ever use the sequence? Would it be worthwhile to add to lsix?

Resources