jjstoo / qimg

Quick Image Display - Display images in terminal sessions

Qimg

Please see generated qimg.c docs for detailed usage info and function reference.

Quick Image Display - Display images in terminal sessions

Stuck in a terminal session and wish to quickly inspect some images? Qimg's got you covered!

Without any windowing systems or external dependencies Qimg can be used to display images on every modern(ish) Linux build.

How?

Linux has provided generic gramebuffer support since kernel 2.1.109. The Linux framebuffer (fbdev) is an abstraction layer providing access to hardware-independent graphics. Userspace access is also supported via /dev/fb* device files.

Qimg takes advantage of Linux framebuffer to simply draw out the images as raw pixels on the screen - no tricks, treats or windowing contexts included.

Why?

Mostly for fun but I've had a few occasions on some terminal-only systems where it would've been nice to view images and I found most of the existing solutions too complex and heavyweight for such a simple task.

Cool, how do I use Qimg?

qimg -h will teach you the basics. Usage is outlined by qimg [option]... input....

• -d <framebuffer dev> uses the given framebuffer device or similar mock-up device file.
• -b <framebuffer index> selects which frambuffer to use based on device index.
• -c will try to hide the terminal cursor and prevent it from refreshing on top of the image.
• -r will repaint the image continuously to prevent anything else from refreshing on top of the image.
• -delay <seconds> will set slideshow delay.
• -pos <position> is used set image position.
• -bg <color> is used to set background color.
• -scale <scale style> is used to set scale style. Useful for scaling images to fullscreen resolution.

Example usage:

qimg -c -delay 2 -pos c -scale fit input.jpg input2.jpg

This will show the two files as a slideshow on the default framebuffer, scaled to fit the screen and centered. -c will cause the cursor to be hidden which prevents the terminal of refreshing on top of the images.

Exits via SIGINT or SIGTERM will trigger cleanups and restore terminal cursor visibility.

Please note that Qimg will NOT work if an Xorg session or any other framebuffer-overriding services are active on the current TTY.

How to get Qimg

Building Qimg is easy as everything needed for the build is provided in this repository. However, I will be uploading some prebuilt binaries to releases and continuous build artifacts can be downloaded from repository actions.

A huge thank you to stb developers for their excellent image libraries.

qimg's Issues

Dynamic image loading

As of now, images are loaded in the beginning of the program all at once. This poses memory limitations and slows down program startup.

Images should be loaded in batches, which would minimize memory footprint and speed up program startup.