Seeqie: A Terminal-Based Image Viewer Using Sixel Graphics
What is Seeqie?
Seeqie is a lightweight terminal-based image gallery browser inspired by geeqie but built exclusively with sixel graphics. It allows you to browse and view images directly within your terminal environment, eliminating the need to switch between applications.
The project began when I switched back to using mutt as my mail user agent (MUA) and wanted a way to view image attachments without leaving the terminal. What started as a simple utility script quickly evolved into a full-featured image browser with navigation controls and viewing modes.
Unlike many of my other projects, Seeqie is one of the few that I consider essentially complete - it does exactly what I need it to do. While there might be occasional bugs or incompatibilities to address, the core functionality is stable and reliable. My preferred terminal emulator, mlterm, works particularly well with it, though I'd be interested to see how it performs in other sixel-compatible terminals.
If you'd like to try it yourself or dive into the code, the entire script is available on GitHub.
Key Features
- Terminal-native: Works entirely within your terminal using sixel graphics
- Intuitive navigation: Controls use familiar key mappings (wasd, arrow keys, or vim-style hjkl)
- Dual view modes: Toggle between single-image and tile/thumbnail views
- Performance optimized: Efficient thumbnail generation with lazy loading
Performance Optimizations
I've spent significant time on improving the script's performance, focusing primarily on startup time and responsiveness. The initial approach involved parallelizing the sixel thumbnail generation by spawning multiple processes on startup, but this revealed several challenges.
Challenges and Solutions
The first major issue was system responsiveness. With multiple img2sixel processes consuming all available CPU resources, the desktop environment became unresponsive. I resolved this by implementing nice to lower the priority of these processes, maintaining system responsiveness while still utilizing all CPU cores.
Another significant problem was that the original implementation generated thumbnails for all images at startup rather than just the visible ones. This caused substantial delays when browsing directories with hundreds of images (a common scenario for photographers and digital artists).
Technical Deep Dive
To identify the bottleneck, I examined the img2sixel source code with debug symbols and profiled the thumbnail generation process using valgrind/callgrind. The analysis revealed that scaling operations, not the sixel conversion itself, were causing the performance issues. The nearest_neighbor interpolation algorithm was faster because it used an optimized fast path, bypassing the more complex scaling operations.
This led to two potential solutions:
- Skip the built-in scaling functionality
- Optimize the scaling process
I chose the pragmatic approach (as laziness is indeed a virtue in programming!) by offloading the scaling operations to an external program. Since GraphicsMagick was already a dependency, it was the natural choice for handling image scaling.
Results and Improvements
This optimization resulted in approximately 10x faster performance, allowing me to switch from parallel ahead-of-time thumbnail generation to a sequential lazy-loading approach. This change dramatically improved startup times, especially for large directories, as thumbnails are now generated on demand when needed.
A pleasant side effect is the natural loading animation that occurs as thumbnails appear sequentially, providing better visual feedback compared to the previous implementation where users experienced a delay followed by all thumbnails appearing simultaneously.
Current Status and Future Development
Seeqie has become my go-to image viewer for terminal work. I find myself using it frequently due to its convenience and integration with my terminal-based workflow. While I'm pleased with its current functionality, there are still some compatibility issues with different screen sizes and several pending bugs that need addressing.
The project demonstrates how terminal applications can provide rich visual experiences without sacrificing the efficiency and keyboard-focused nature of command-line tools. For developers and users who spend significant time in the terminal, tools like Seeqie offer a way to reduce context switching and maintain workflow momentum.
If you're interested in terminal-based image viewing or working with sixel graphics in your own projects, feel free to check out the code and experiment with it yourself.
Adios,
べン