PQIV README

About pqiv

pqiv is a powerful GTK 3 based command-line image viewer with a minimal UI. It is highly customizable, can be fully controlled from scripts, and has support for various file formats including PDF, Postscript, video files and archives. It is optimized to be quick and responsive.

It comes with support for animations, slideshows, transparency, VIM-like key bindings, automated loading of new images as they appear, external image filters, marks, image preloading, and much more.

pqiv started as a Python rewrite of qiv avoiding imlib, but evolved into a much more powerful tool. Today, pqiv stands for powerful quick image viewer.

Features

Recursive loading from directories
Can watch files and directories for changes
Sorts images in natural order
Has a status bar showing information on the current image
Comes with transparency support
Can move/zoom/rotate/flip images
Can pipe images through external filters
Loads the next image in the background for quick response times
Caches zoomed images for smoother movement
Supports fade image transition animations
Supports various image and video formats through a rich set of backends
Comes with an interactive montage mode (a.k.a. "image grid")
Customizable key-bindings with support for VIM-like key sequences, action cycling and binding multiple actions to a single key
Mark/unmark images and pipe the list of marked images to an external script

Installation

Usual stuff. ./configure && make && make install. The configure script is optional if you only want gdk-pixbuf support and will auto-determine which backends to build if invoked without parameters.

You can also use precompiled and packaged versions of pqiv. Note that the distribution packages are usually somewhat out of date:

Nightly builds for Debian, Ubuntu, SUSE and Fedora thanks to the OpenSUSE build service
Alpine package
Arch package
Debian package
FreeBSD port
Gentoo ebuild
macOS brew
NixOS package
OpenBSD port
OpenSUSE package
Void linux

If you'd like to compile pqiv manually, you'll need

gtk+ 3.0 or gtk+ 2.6
gdk-pixbuf 2.2 (included in gtk+)
glib 2.32 (with gvfs for opening URLs)
cairo 1.6
Pango 1.10
gio 2.0
gdk 2.8

and optionally also

ffmpeg / libav (for video support)
libarchive (for images in archives and cbX comic book files)
libspectre (any version, for ps/eps support)
libwebp (for WebP support)
MagickWand (any version, for additional image formats like psd)
poppler (any version, for pdf support)

The backends are per default linked statically into the code, so all backend related build-time dependencies are also run-time dependencies. If you need a shared version of the backends, for example for separate packaging of the binaries or to make the run-time dependencies optional, use the --backends-build=shared configure option.

For macOS, have a look at the pqiv.app target of the Makefile, too.

pqiv can be linked statically, though GTK only supports static linking in GTK 2.x; in early versions of GTK 3.x it was fairly simple to still link statically.

Windows builds are supported and work in GTK 2.x, it is recommended to use MXE for cross-compiling.

Thanks

This program uses Martin Pool's natsort algorithm https://www.github.com/sourcefrog/natsort/.

Contributors

Contributors to pqiv 2.x are:

J. Paul Reed
Chen Jonh L
Anton Älgmyr
Christian Garbs
Kanon Kubose
Wessel Dankers
@buzzingwires

Contributors to pqiv ≤ 1.0 were:

Alexander Sulfrian
Alexandros Diamantidis
Brandon
David Lindquist
Hanspeter Gysin
John Keeping
Nir Tzachar
Rene Saarsoo
Tinoucas
Yaakov

Known bugs

The window is centered in between two monitors in old multi-head setups: This happens if you have the RandR extension enabled, but configured incorrectly. GTK is programmed to first try RandR and use Xinerama only as a fallback if that fails. (See gdkscreen-x11.c.) So if your video drivers for some reason detect your multiple monitors as one big screen you can not simply use fakexinerama to fix things. This might also apply to nvidia drivers older than version 304. I believe that I can not fix this without breaking functionality for other users or maintaining a blacklist, so you should deactivate RandR completely until your driver is able to provide correct information, or use a fake xrand (like mine, for example)
Loading postscript files failes with Error #12288; Unknown output format: This issue happens if your poppler and spectre libraries are linked against different versions of libcms. libcms and libcms2 will both be used, but interfere with each other. Compile using --backends-build=shared to circumvent this issue.

Examples

Basic usage of pqiv is very straightforward, call

pqiv <files or directories>

and then use space, backspace, f (for fullscreen), q (to quit), and m for the montage overview to navigate through your images. To see all key bindings, see the DEFAULT KEY BINDINGS section of the man-page, or run pqiv --show-bindings.

For some advanced uses of pqiv, take a look at these resouces:

Play music while looking at specific images

Bind keys to cycle through panels of a 2x2 comic

Store this in your .pqivrc:

# Bind c to act as if "#c1" was typed
c { send_keys(#c1); }
# If "#c1" is typed, shift the current image to it's north west corner, and
# rebind "c" to act as if "#c2" was typed
<numbersign>c1 { set_shift_align_corner(NW); bind_key(c { send_keys(#c2\); }); }
# ..etc..
<numbersign>c2 { set_shift_align_corner(NE); bind_key(c { send_keys(#c3\); }); }
<numbersign>c3 { set_shift_align_corner(SW); bind_key(c { send_keys(#c4\); }); }
# The last binding closes the cycle by rebinding "c" to act as if "#c1" was typed
<numbersign>c4 { set_shift_align_corner(SE); bind_key(c { send_keys(#c1\); }); }

Changelog

pqiv 2.13 (dev)

Fix toggle_fullscreen(1/2) behavior when already fullscreen
Add --font to adjust info box font, use Pango for rendering (See #221)

pqiv 2.12

Fix external image filters (Fixes #182)
Fix support for best interpolation quality (Fixes #139)
Fix wrap-around in shuffled image view (Fixes #176)
Fix max-depth behavior if the argument is a file (Fixes #170)
Allow keybinding of special keys with shift modifier
Add --auto-montage-mode (Fixes #181)
Replace GTimeVal with GDateTime for glib 2.62 support
Add an sxiv-like marks system

Click to expand changelog for old pqiv versions

pqiv 2.11

Added negate (color inversion) mode (bound to n, --negate)
Rebound a (hardlink image) to c-a by default (See #124)
Improved key bindings documentation (See #127)
Add --actions-from-stdin and let it block until actions are completed (See #118/#119)
Fix zooming on tiling WMs (See #129)
Support ffmpeg 4.0 API
Fix cross-compiling with X11 (Debian #913589)
Fix resizing in WMs without moveresize support (See #130)
Work around GTK bug resulting in crash due to invalid free()
Improve autotools compatibility of the configure script (See #135)

pqiv 2.10.4

Fix output of montage_mode_shift_y_rows() in key bindings
Update the info text when the background pattern is cycled
Prevent potential crashes in poppler backend for rapid image movements
Fix processing of dangling symlinks in the file buffer
Removed possible deadlock in ImageMagick wand backend
Fix --command-9 shortcut
Makefile: Move -shared compiler flag to the end of the command line

pqiv 2.10

Enable cursor auto-hide by default
Enable mouse navigation in montage mode
Added toggle_background_pattern() (bound to b) and --background-pattern.
Added support for alternate pqivrc paths, changed recommended location to ./.config/pqivrc.
Sped up --low-memory mode (using native- instead of image-surfaces)
Fixed graphical issues with fading mode and quick image transition
Fixed support for platforms with sizeof(time_t) != sizeof(int)
Fixed a race condition in the file buffer map

pqiv 2.9

Added a montage/image grid mode (bound to m by default)
Added a WebP backend (by @john0312)
Added the means to skip over "logical" directories, such as archive files (bound to ctrl+space and ctrl+backspace by default)
Improved responsivity by caching pre-scaled copies of images
Removed tearing/flickering in WMs without extended frame sync support
Fixed support for huge images (>32,767px) in the GdkPixbuf backend
Added option --info-box-colors to customize the colors used in the info box
It is now possible to view --help even if no display is available
Added --version
Added an auto scale mode that maintains window size
Bound Control+t to switch to "maintain scale level" by default
Bound Alt+t to switch to "maintain window size" by default
Added action move_window() to explicitly move pqiv's main window around

pqiv 2.8.5

Fixed an issue where the checkerboard pattern sometimes was visible at image borders
Fixed image rotation in low-memory mode
Fix a memory leak (leaking a few bytes each time an image is drawn)
Correctly handle string arguments from the configuration file
Fix building with old glib versions that do not expose their x11 dependency in pkgconfig
Fix support for duplicate files in sorted mode
Fix MagickWand exit handler code

pqiv 2.8

Added option --allow-empty-window: Show pqiv even if no images can be loaded
Explicitly allow to load all files from a directory multiple times
Allow to use --libdir option in configure to override .so-files location
Fix shared-backend-pqiv in environments that compile with --enable-new-dtags
Enable the libav backend by default
Add option --disable-backends to disable backends at runtime

pqiv 2.7.4

Fix GTK 2 compilation
Fix backends list in configure script
Fix race condition upon reloading animations
Fix Ctrl-R default binding (move goto_earlier_file() to Ctrl-P)

pqiv 2.7

Fixed window decoration toggling with --transparent-background
Work around bug #67, poppler bug #96884
Added new action set_interpolation_quality to change interpolation/filter mode
pqiv now by default uses nearest interpolation for small images
Added actions and key bindings to control animation playback speed
Added a general archive backend for reading images from archives
Added a new action goto_earlier_file() to return to the image that was shown before the current one
Added a new action set_cursor_auto_hide() to automatically hide the pointer when it is not moved for some time
Support an actions section in the configuration file for default actions
Create and install a desktop file for pqiv during install
Disable GTK's transparent scaling on HiDpi monitors
New option --wait-for-images-to-appear to wait for images to appear if none are found

pqiv 2.6

Added --enforce-window-aspect-ratio
Do not enforce the aspect ratio of the window to match the image's by default

pqiv 2.5.1

Prevent a crash in --lazy-load mode if many images fail to load

pqiv 2.5

Added a configure option to build the backends as shared libraries
Added a configure option to remove unneeded/unwanted features
Added --watch-files to make the file-changed-on-disk action configurable
Added support for cbz/cbr/cbt/cb7 comic books
Key bindings are now configurable
Deprecated --keyboard-alias and --reverse-cursor-keys in favor of --bind-key.
Added --actions-from-stdin to make pqiv scriptable
Added --recreate-window to create a new window instead of resizing the old one, as a workaround for buggy window managers
Fixed crash on reloading of images created by pipe-command output

pqiv 2.4.1

Fix --end-of-files-action=quit if only one file is present
Fixed libav backend's pkg-config dependency list (by @onodera-punpun)
Enable image format support in the libav backend

pqiv 2.4

Added --sort-key=mtime to sort by modification time instead of file name
Delay the "Image is still loading" message for half a second to avoid flickering status messages
Remove the "Image is still loading" message if --hide-info-box is set
Added libav backend for video support
Added --end-of-files-action=action to allow users to control what happens once all images have been viewed
Fix various minor memory allocation issues / possible race conditions

pqiv 2.3.5

Fix parameters in pqivrc that are handled by a callback
Fix reference counting if an image fails to load
Properly reload multi-page files if they change on disk while being viewed
Properly handle if a user closes pqiv while the image loader is still active

pqiv 2.3

Refactored an abstraction layer around the image backend
Added optional support for PDF-files through poppler
Added optional support for PS-files through libspectre
Added optional support for more image formats through ImageMagick's MagickWand
Support for gtk+ 3.14
configure/Makefile updated to support (Free-)BSD
Added ctrl + space/backspace hotkey for jumping to the next/previous directory
Improved pqiv's reaction if a file is removed
gtk 3.16 deprecates gdk_cursor_new, replaced by a different function
Shuffle mode is now toggleable at run-time (using Ctrl-R)

pqiv 2.2

Accept URLs as command line arguments
Revived -r for reading additional files from stdin (by J.P. Reed)
Display the help message if invoked without parameters (by J.P. Reed)
Accept floating point slideshow intervals on the command line
Update the info box with the current numbers if (new) images are (un)loaded
Added --max-depth=n to limit how deep directories are searched
Added --browse to load, in addition to images from the command line, also all other images from the containing directories
Bugfix: Fixed handling of non-image command line arguments

pqiv 2.1

Support for watching directories for new files
Downstream Makefile fix: Included LDFLAGS (from Gentoo package, by Tim Harder), updated for clean builds on OpenBSD (by jca[at]wxcvbn[dot]org, reported by github user @clod89)
Also included CPPFLAGS, for completeness
Renamed '.qiv-select' directory to '.pqiv-select'
Added a certain level of autoconf compatibility to the configure script, for automated building
gtk 3.10 stock icon deprecation issue fixed
Reimplemented fading between images
Display the last image while the current image has not been loaded
Gave users the option to abort the loading of huge images
Respect --shuffle and --sort with --watch-directories, i.e. insert keeping order, not always at the end
New option --lazy-load to display the main window while still traversing paths, searching for images
New option --low-memory to disable memory hungry features
Detect nested symlinks without preventing users from loading the same image multiple times
Improved cross-compilation support with mingw64

pqiv 2.0

Complete rewrite from scratch
Based on GTK 3 and Cairo

pqiv ≤ 1.0

See the old GTK 2 release for information on that (in the gtk2 branch on github)

pqiv ≤ 0.3

See the old python release for information on that (in the python branch on github)

phillipberndt/pqiv

phillipberndt

Reviews

Repository Details