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 c1 { set_shift_align_corner(NW); bind_key(c { send_keys(#c2\); }); } # ..etc.. c2 { set_shift_align_corner(NE); bind_key(c { send_keys(#c3\); }); } 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 c4 { set_shift_align_corner(SE); bind_key(c { send_keys(#c1\); }); } ```

Changelog

pqiv 2.13.1

• Revert to not adding --browse to desktop files (fixes #232)

pqiv 2.13

• Fix toggle_fullscreen(1/2) behavior when already fullscreen
• Add --font to adjust info box font, use Pango for rendering (See #221)
• Prefer x11 over Wayland GDK backend (it overall provides a better experience)
• Fix Client Side Decorations (CSD), e.g. in Wayland
• Fix race/crash upon exit (Fixes #227)