{"id":13496681,"url":"https://github.com/hackerb9/lsix","last_synced_at":"2025-05-14T10:13:07.464Z","repository":{"id":43720348,"uuid":"93463553","full_name":"hackerb9/lsix","owner":"hackerb9","description":"Like \"ls\", but for images. Shows thumbnails in terminal using sixel graphics.","archived":false,"fork":false,"pushed_at":"2024-06-20T15:12:30.000Z","size":678,"stargazers_count":4060,"open_issues_count":35,"forks_count":127,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-04-02T02:09:20.837Z","etag":null,"topics":["files","graphics","imagemagick","ls","montage","sixel-graphics","terminal","terminal-graphics","thumbnails","vt340","xterm"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hackerb9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-06T01:42:54.000Z","updated_at":"2025-03-30T06:36:11.000Z","dependencies_parsed_at":"2022-07-20T06:47:08.073Z","dependency_job_id":"13e85c37-2193-4735-9e8f-02030ed17919","html_url":"https://github.com/hackerb9/lsix","commit_stats":{"total_commits":111,"total_committers":6,"mean_commits":18.5,"dds":"0.19819819819819817","last_synced_commit":"3a431793a747df3f9340519555527da9b10d040a"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerb9%2Flsix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerb9%2Flsix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerb9%2Flsix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hackerb9%2Flsix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hackerb9","download_url":"https://codeload.github.com/hackerb9/lsix/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247968368,"owners_count":21025823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["files","graphics","imagemagick","ls","montage","sixel-graphics","terminal","terminal-graphics","thumbnails","vt340","xterm"],"created_at":"2024-07-31T19:01:56.627Z","updated_at":"2025-04-09T03:10:03.607Z","avatar_url":"https://github.com/hackerb9.png","language":"Shell","funding_links":[],"categories":["Shell","terminal","Command line","Tools"],"sub_categories":["Bash"],"readme":"\u003cimg align=\"right\" src=\"README.md.d/thumb.png\"\u003e\n\n# lsix\nLike \"ls\", but for images. Shows thumbnails in terminal using [sixel](https://en.wikipedia.org/wiki/Sixel)\ngraphics.\n\n\n## Usage\n\n    lsix [ FILES ... ]\n\n## Examples\n\n### Basic Usage\n\nJust typing `lsix` will show images in the current working directory.\nYou can also specify filenames and, of course, use shell wild cards\n(e.g., `lsix *jpg *png`).\n\nBecause lsix uses ImageMagick pretty much any image format will be\nsupported. However, some may be slow to render (like PDF), so lsix\ndoesn't show them unless you ask specifically. If you want to force a\nlisting of a certain type of image simply specify the filenames or\nuse a wildcard (`*.pdf` in the example below),.\n\n![Example 1 of lsix usage](/README.md.d/example1.png \"Most basic usage\")\n\n### Expanding GIFs \nIf you specify a GIF (or actually any file that has multiple images in\nit) on the command line, all the frames will get expanded and shown in\na montage. For example, `lsix nyancat.gif` shows all the frames. Note\nthat GIF stores some frames as only the pixels that differ from the\nprevious frame.\n![Example 2 of lsix usage](/README.md.d/example2.png \"GIFs get expanded\")\n\n### Terminal background color is detected\n\nYou may have noticed that PNGs and SVG files have correct alpha\nchannel for the terminal background. That is because lsix uses\nterminal escape sequences to try to figure out your foreground and\nbackground colors. (Foreground is used for the text fill color.)\n\nIn the first example below, after running `lsix` in a white on black\nxterm, I sent an escape sequence to swap foreground and background\ncolors. When I ran it again, `lsix` detected it and changed the\nbackground color to white. Of course, you can pick whatever default\ncolors you want (e.g., `xterm -bg blue`, in the second example below).\n\n![Example 3 of lsix usage](/README.md.d/example3.png \"Reverse video works\")\n![Example 4 of lsix usage](/README.md.d/example4.png \"Even 'xterm -bg blue' works\")\n\n## Features\n\n* Detects if your terminal can display SIXEL graphics inline using [control sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Sixel-Graphics).\n\n* Works great over ssh. Perfect for manipulating those images on the\n  web server when you can't quite remember what each one was. \n\n* Non-bitmap graphics often work fine (.svg, .eps, .pdf, .xcf).\n\n* Automatically detects if your terminal, like xterm, can increase the\n  number of color registers to improve the image quality and does so.\n\n* Automatically detects terminal's foreground and background colors.\n\n* In terminals that support dtterm WindowOps, the number of tiles per\n  row will adjust appropriately to the window width.\n\n* If there are many images in a directory (\u003e21), lsix will display them\n  one row at a time so you don't need to wait for the entire montage\n  to be created.\n\n* If your filenames are too long, lsix will wrap the text before\n  passing it into ImageMagick's `montage`. (Without lsix, `montage` just\n  jumbles long filenames on top of one another.)\n\n* You can easily change things like the width of each tile in the\n  montage, the font family, and point size by editing simple variables\n  at the top of the file. *(Tip: try `convert -list font` to see what\n  fonts you have on your machine.)*\n\n* Unicode filenames work fine, as long as your font has the glyphs.\n\n## Installation\n\nJust put the [`lsix`](/lsix) file in your path (e.g., /usr/local/bin) and run\nit. It's just a BASH shell script.\n\nThe only prerequisite software is ImageMagick. If you don't have it\nyet, your OS's package manager will make it easy to get. (E.g.,\n`apt-get install imagemagick`).\n\nMacOS users may prefer to install lsix using `brew install lsix` which\ninstalls ImageMagick, if necessary.\n\n## Your Terminal must support Sixel graphics\n\nI developed this using [xterm](https://invisible-island.net/xterm/) in\nvt340 emulation mode, but I believe this should work on\nany Sixel compatible terminal. You may test your terminal by viewing a\nsingle image, like so:\n\n    convert  foo.jpg  -geometry 800x480  sixel:- \n\n### XTerm\n\nNote that xterm does not have Sixel mode enabled by default, so you\nneed to either run it like so:\n\n    xterm -ti vt340\n\nOr, make vt340 the default terminal type for xterm. Add the following\nto your `.Xresources` file and run `xrdb -merge .Xresources`.\n\n    ! Allow sixel graphics. (Try: \"convert -colors 16 foo.jpg sixel:-\").\n    xterm*decTerminalID\t:\tvt340\n    \nFurther, some distributions, such as Fedora, appear to not compile `xterm`\nwith sixel support. In that case, try an alternate terminal, such as\n`foot` or `mlterm`.\n\n### SIXEL compatible terminals\n\n* XTerm (tested)\n* MLterm (tested)\n* foot (tested)\n* Wezterm (tested)\n* Contour (tested)\n* iTerm2 for Apple MacOS (tested)\n* Konsole (reported)\n* yakuake (reported)\n* WSLtty for Microsoft Windows (reported)\n* MinTTY for Cygwin (Microsoft Windows) (reported)\n* Yaft for Linux framebuffer (tested)\n* VTE (special compilation, reported)\n* sixel-tmux (fork of tmux, reported)\n* ttyd (reported)\n\n### SIXEL incompatible terminals\n\n* MacOS Terminal, kitty\n* All standard libvte based terminals\n  * gnome-terminal\n  * terminator\n  * lxterm\n* Alacritty (might work with [a patch](https://github.com/alacritty/alacritty/pull/4763))\n\n## Configuration\n\nBecause `lsix` is currently designed to be very simple, there are no\ncommand line flags, no configuration files, no knobs to twiddle, or\nfrobs to frobnosticate. However, since the script is so simple, if you\nwant to make a change, it's pretty easy to do just by editing the\nfile. Everything is nicely commented with the most common default\nvariables at the top.\n\n## Contact the author\n\nI welcome feedback. If you use lsix and like it or have suggestions\nfor how it can be improved, please go ahead and send your thoughts to\nme [@hackerb9](https://github.com/hackerb9/lsix/issues/new) via\nGitHub.\n\n\n## Bugs\n\n* XTerm's reverse video mode (`xterm -rv`) is different from\n  specifying the foreground and background explicitly. There is a way\n  to detect the latter, but not the former. That means the background\n  color will be incorrect for folks who use XTerm's reverseVideo\n  resource. (See issue #20).\n\n* XTerm's screen width is currently limited to 1000px due to a\n  misfeature which causes it to silently show nothing. This limitation\n  will be removed once xterm can handle images greater than 1000x1000.\n  [Last tested with XTerm(344)].\n\n* Filenames that begin with \"@\" are special to ImageMagick and it'll\n  freak out if you don't prepend a directory. (`lsix ./@foo.png`)\n  (This is a bug in ImageMagick, not lsix).\n\n* Specifying the empty string `\"\"` as a filename makes ImageMagick hang.\n  (This appears to be an ImageMagick bug / misfeature). \n\n* Long filenames are wrapped, but not intelligently. Would it\n  complicate this script too much to make it prefer to wrap on whites\n  space, dashes, underscores, and periods? Maybe.\n\n* Directories specified on the command line are processed as if the\n  user had cd'd to that directory. It wouldn't be hard to implement\n  recursion, but is there actually a need? I'm reluctant to complicate\n  such a simple script with command line flags.\n\n* If you run `lsix foo.avi`, you're asking for trouble.\n\n\n## Future Issues\n\n* The Sixel standard doesn't appear to have a way to query the size of\n  the graphics screen. Reading the VT340 documentation, it appears\n  your program has to already know the resolution of the device you're\n  rendering on.\n\n  XTerm, as of version 344, has added [a control\n  sequence](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Functions-using-CSI-_-ordered-by-the-final-character_s_)\n  that solves the problem — `CSI ? Pi ; Pa ; Pv S` — but some\n  terminals, for example `mlterm`, haven't yet implemented it.\n\n  There is an alternate way to read the window size using the dtterm\n  WindowOps extension but it is not quite the right solution as the\n  geometry of the Sixel graphics screen is not necessarily the same as\n  the window size. (For example, xterm limits the graphics geometry to\n  1000x1000, even though the window can actually be larger.) To help\n  with terminals such as mlterm, `lsix` will use the dtterm WindowOps\n  as a fallback.\n\n  If neither solution works, `lsix` will assume you are on a VT340\n  (800x480) and can fit only 6 tiles per row.\n\n* The Sixel standard also lacks a way to query the number of\n  color registers available. I used the extensions from `xterm` to do\n  so, but I do not know how widely implemented they are. If a terminal\n  does not respond, `lsix` presumes you're on an original vt340 and\n  uses only 16 color registers. (Sorry, 4-gray vt330 users! Time to\n  upgrade. ;-) )\n\n\n* The [Kermit project](https://kermitproject.org/) created a MS-DOS\n  terminal emulator that was popular in the late 1980s/early 1990s.\n  Its sixel implementation is not compatible with lsix because it\n  shows the graphics on a screen separate from the text. However, I\n  noticed one feature in its documentation: an escape sequence to\n  request the current graphics window size and number of colors:\n\n```\n ESC [ ? 256 n                  Request screen size report\n\n        Report is ESC [ ? 256; Ph; Pw; Pc n     for graphics systems\n\n        where   Ph is screen height in dots\n                Pw is screen width in dots\n                Pc is number of colors (0, 1 or 16, for none, b/w, ega/vga)\n\n        Report is ESC [ ? 24; 80; 0 n  for pure text mono systems.\n```\n\n  Did any other terminal emulators ever use the sequence? Would it be\n  worthwhile to add to `lsix`?\n\n* [libsixel](https://github.com/saitoha/libsixel) is an excellent\n  project for writing programs that can output optimized Sixel\n  graphics commands. Because I have a lot of respect for the project,\n  I feel I should explain why `lsix` does not use libsixel.\n\n  * (a) I wanted lsix to work everywhere easily. Bash and imagemagick\n    are ubiquitous, so a shell script is a natural solution.\n\n  * (b) I wanted `lsix` to be simple enough that it could be easily\n    customized and extended by other people. (Including myself.)\n\n  * (c) ImageMagick has better support for reading different formats\n    than stb_image (the library used by libsixel's `img2sixel`). (For\n    example: xpm, svg, 16-bit png, and even sixel files are not\n    recognized by img2sixel). Since ImageMagick can read all of those\n    and write sixel output directly, it made sense to use it for both.\n\n  * (d) While libsixel is optimized and would surely be faster than\n    ImageMagick, it's overkill. For a simple directory listing, this\n    is plenty fast enough.\n\n## Resources\n\n  * [XTerm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)\n  * [ImageMagick](https://imagemagick.org/)\n  * [VT340 Programmer's Reference](https://vt100.net/docs/vt3xx-gp/):\n    * [Chapter 14](https://vt100.net/docs/vt3xx-gp/chapter14.html). Sixel Graphics.\n    * [Chapter 16](https://vt100.net/docs/vt3xx-gp/chapter16.html#S16.3) Difference between Level 1 and Level 2 Sixel implementations.\n        \n        _Nota bene: this reference has the sense for DECSDM (sixel\n        display mode) reversed! The actual behaviour of the VT340 is\n        that when DECSDM is reset (the default), sixel scrolling is enabled.\n        This can be done by sending _`Esc[?80l`_, but lsix does not do\n        so as it would break many current terminal emulators.\n        See issue #41 for details._\n\n  * [DEC STD 070 Video Systems Reference Manual](https://archive.org/details/bitsavers_decstandar0VideoSystemsReferenceManualDec91_74264381).\n    A weighty tome which covers nearly everything in exacting detail. I referred mostly to sections 4 (escape sequences) and 9 (sixel programming).\n\n  * [VT340 Test](https://github.com/hackerb9/vt340test), a project to document the actual behaviour of the DEC VT340 hardware.\n\n  * [Digital ANSI-Compliant Printing Protocol: Level 2 Programming Reference Manual](http://www.vaxhaven.com/images/f/f7/EK-PPLV2-PM-B01.pdf), Chapter 5: Sixel Graphics. An excellent and reasonably clear discussion for anyone who wants to generate or parse sixel graphics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackerb9%2Flsix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhackerb9%2Flsix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackerb9%2Flsix/lists"}