Ubuntu Manpage: pqiv - powerful quick image viewer

NAME

       pqiv - powerful quick image viewer

SYNOPSIS

       pqiv [options] [filename(s)...]

DESCRIPTION

       pqiv  is a simple command line image viewer inspired by qiv. It is highly customizable and
       supports a variety of formats.

OPTIONS

-c, --transparent-background
Draw pqiv's window borderless and transparent. In window mode, a mouse click
activates and deactivates window decorations.

-d, --slideshow-interval=SECONDS
In slideshow mode (Activated by --slideshow or key s by default), cycle through
images at this rate. Floating point values are supported, e.g. use 0.5 to move
through the images at a rate of two images per second.

-f, --fullscreen
Start in fullscreen mode. Fullscreen can be toggled by pressing f at runtime by
default.

-F, --fade
Fade between images. See also --fade-duration.

-i, --hide-info-box
Initially hide the info box. Whether the box is visible can be toggled by pressing
i at runtime by default.

-l, --lazy-load
pqiv normally processes all command line arguments before displaying its main
window. With this option, the window is shown as soon as the first image has been
found and loaded.

-n, --sort
Instead of storing images in the order they are given on the command line and found
within directories, sort them. The default order is by name (natural order). See
--sort-key to change the order.

-P, --window-position=POSITION
Set the initial window position. POSITION may either be

x,y screen coordinates, or

off to not position the window at all.

-r, --additional-from-stdin
Read additional filenames/folders from the standard input. This option conflicts
with --commands-from-stdin.

-s, --slideshow
Start in slideshow mode. Slideshow mode can be toggled at runtime by pressing s by
default.

-t, --scale-images-up
Scale images up to fill the whole screen. This can be toggled at runtime by
pressing t by default. See also --disable-scaling.

-T, --window-title=TITLE
Set the title of the window. pqiv substitutes several variables into TITLE:

$BASEFILENAME The base file name of the current file (e.g. `image.png'),

$FILENAME The file name of the current file (e.g. `/home/user/image.png'),

$WIDTH The width of the current image in pixels,

$HEIGHT The height of the current image in pixels,

$ZOOM The current zoom level,

$IMAGE_NUMBER The index of the current image,

$IMAGE_COUNT The total number of images.

The default is `pqiv: $FILENAME ($WIDTHx$HEIGHT) $ZOOM%
[$IMAGE_NUMBER/$IMAGE_COUNT]'.

-z, --zoom-level=FLOAT
Set the initial zoom level as a floating point value, i.e., 1.0 is 100%. This only
applies to the first image, other images are scaled according to the scale mode
(see --scale-images-up and --disable-scaling) and window size.

-1, --command-1=COMMAND
Bind the external COMMAND to key 1. You can use 2..9 to bind further commands. The
ACTIONS feature (see below) allows one to bind further keys to other commands.
COMMAND is executed using the default shell processor. `$1' is substituted with
the current file name. Unless COMMAND begins with `|', if `$1' is not present, the
file name is appended to the command line.

If COMMAND begins with `>', its standard output is displayed in a popup window.

If COMMAND begins with `|', the current image is piped to its standard input, and
its standard output is loaded as an image. This can be used to e.g. process
images.

--action=ACTION
Execute a specific ACTION when starting pqiv. The syntax is
command(parameter); command(parameter);
See the ACTIONS section below for available commands.

--actions-from-stdin
Like --action, but read actions from the standard input. See the ACTIONS section
below for syntax and available commands. This option conflicts with
--additional-from-stdin.

--allow-empty-window
pqiv normally does not display the main window until one image has been found, and
quits when it cannot load any of the images anymore. With this option, both
situations result in an empty pqiv window being shown.

--background-pattern=PATTERN
pqiv draws a checkerboard as transparent images' background. Use this option to
alternatively use a white or black background. Valid values are checkerboard, white
and black.

--bind-key=KEY BINDING
Rebind a key to an action. The syntax is
key sequence { command(parameter); command(parameter); }
A key sequence may be one or more characters, or special characters supplied as
`<name>', where name is a GDK key specifier or a mouse button (`Mouse-1') or a
scrolling direction (`Mouse-Scroll-1'). If you e.g. use `a<Control>b', then a user
must hit `a' followed by control + `b' to trigger the command. It is possible to
bind `a' and `ab' as well. The action bound to `a' will then be slightly delayed to
allow a user to hit `b'. The semicolon separating commands is optional. See ACTIONS
below for available commands.

If you need to know the name of a key specifier, you can run xev and press the
desired key. The name of the keysym will be printed in parentheses, preceded by
`keysym' and a hexadecimal representation. An alternative is to run xmodmap -pk.
The command outputs the symbolic names in parentheses. Or use the list at
https://git.gnome.org/browse/gtk+/plain/gdk/gdkkeysyms.h.

pqiv groups key bindings into different contexts. Currently, montage mode is the
only context other than the default one: In montage mode, different key bindings
are used. To switch the context while binding key sequences, write
@MONTAGE { ... }
and insert the special key bindings within the curly braces.

---box-colors=FOREGROUND COLOR:BACKGROUND COLOR
Customize the colors used to draw the info box and montage mode borders. Colors can
be specified either as a comma separated list of RBG-values in the range from 0 to
255 or as a hexvalue, e.g., #aabbcc. The default value is #000000:#ffff00.

--browse
For each command line argument, additionally load all images from the image's
directory. pqiv will still start at the image that was given as the first
parameter.

--disable-backends=LIST OF BACKENDS
Use this option to selectively disable some of pqiv's backends. You can supply a
comma separated list of backends here. Non-available backends are silently ignored.
Disabling backends you don't want will speed up recursive loading significantly,
especially if you disable the archive backend. Available backends are archive,
archive_cbx, libav, gdkpixbuf, poppler, spectre, webp and wand.

--disable-scaling
Completely disable scaling. This can be toggled at runtime by pressing t by
default. See also --scale-images-up.

--end-of-files-action=ACTION
If all files have been viewed and the next image is to be viewed, either by the
user's request or because a slideshow is active, pqiv by default cycles and
restarts at the first image. This parameter can be used to modify this behaviour.
Valid choices for ACTION are:

quit Quit pqiv,

wait Wait until a new image becomes available. This only makes sense
if used with e.g. --watch-directories,

wrap (default) Restart at the first image. In shuffle mode, choose a new
random order,

wrap-no-reshuffle As wrap, but do not reshuffle in random mode.

--enforce-window-aspect-ratio
Tell the window manager to enforce the aspect ratio of the window. If this flag is
set, then a compliant window manager will not allow users to resize pqiv's window
to a different aspect ratio. This used to be the default behaviour, but window
managers tend to have bugs in the code handling forced aspect ratios. If the flag
is not set and the aspect ratios of the window and image do not match, then the
image will be still be drawn with the correct aspect ratio, with black borders
added at the sides.

--fade-duration=SECONDS
With --fade, make each fade this long. Floating point values are accepted, e.g. 0.5
makes each fade take half a second.

--low-memory
Try to keep memory usage to a minimum. pqiv by default e.g. preloads the next and
previous image to speed up navigation and caches scaled images to speed up redraws.
This flag disables such optimizations.

--max-depth=LEVELS
For parameters that are directories, pqiv searches recursively for images. Use this
parameter to limit the depth at which pqiv searches. A level of 0 disables
recursion completely, i.e. if you call pqiv with a directory as a parameter, it
will not search it at all.

--negate
Display negatives of images. You can toggle this feature at runtime by pressing n.

--shuffle
Display files in random order. This option conflicts with --sort. Files are
reshuffled after all images have been shown, but within one cycle, the order is
stable. The reshuffling can be disabled using --end-of-files-action. At runtime,
you can use Control + R by default to toggle shuffle mode; this retains the
shuffled order, i.e., you can disable shuffle mode, view a few images, then enable
it again and continue after the last image you viewed earlier in shuffle mode.

--show-bindings
Display the keyboard and mouse bindings and exit. This displays the key bindings in
the format accepted by --bind-key. See there, and the ACTIONS section for details
on available actions.

--sort-key=PROPERTY
Key to use for sorting. Supported values for PROPERTY are:

NAME To sort by filename in natural order, e.g. abc32d before abc112d, but b1
after both,

MTIME To sort by file modification date.

--thumbnail-size=WIDTHxHEIGHT
Adjust the size of thumbnails in montage mode. The default is 128x128.

--thumbnail-preload=COUNT
Preload COUNT thumbnails adjacent to the current image while displaying images or
having them selected in montage mode. This can be used to speed up montage mode,
but will lead to high CPU loads.

--thumbnail-persistence=DIRECTORY/STATUS
Persist thumbnails to disk. The simplest way to use this option is to supply a
value of yes. Thumbnails are then stored according to the Thumbnail Managing
Standard, in $XDG_CACHE_HOME/thumbnails/*. The standard allows storage of
thumbnails in sizes 128x128 and 256x256 exclusively, and does not specify how to
store thumbnails for files in archives or multi-page documents. Thumbnails
violating those constraints will be stored in a special x-pqiv subfolder. Supply
standard to store standard compliant thumbnails only. If this option is not used,
then thumbnails will not be loaded from the cache either - any thumbnails will be
regenerated each time montage mode is used. A value of read-only can be used to
load thumbnails, but never store them. read-only is the default.

If you supply local as the argument value, pqiv will store thumbnails in a
subfolder named .sh_thumbnails relative to the images as specified by the Thumbnail
Managing Standard. Your third option is to provide the name of a directory. pqiv
will then use that directory to store thumbnails to. The folder must be given as
an absolute path, relative paths do not work. Note that any folder not named
.sh_thumbnails will be considered in --watch-directories. Also, note that while
pqiv will store thumbnails to another folder, it will still attempt to load them
from the standard folders as well.

--recreate-window
Workaround for window managers that do not handle resize requests correctly:
Instead of resizing, recreate the window whenever the image is changed. This does
not redraw images upon changes in zoom alone.

--scale-mode-screen-fraction=FRACTION
Adjust how much screen space pqiv uses when auto-scaling images outside fullscreen
mode. Defaults to 0.8 (80%).

--wait-for-images-to-appear
If no images are found in the directories specified on the command line, instead of
exiting, wait for some to appear. This option only works in conjunction with
--lazy-load and --watch-directories.

--watch-directories
Watch all directories supplied as parameters to pqiv for new files and add them as
they appear. In --sort mode, files are sorted into the correct position, else, they
are appended to the end of the list. See also --watch-files, which handles how
changes to the image that is currently being viewed are handled.

--watch-files=VALUE
Watch files for changes on disk. Valid choices for VALUE are:

on (default) Watch files for changes, reload upon a change, and skip to the next
file if a file is removed,

changes-only Watch files for changes, reload upon a change, but do nothing if a
file is removed,

off Do not watch files for changes at all.

Note that a file that has been removed will still be removed from pqiv's image list
when it has been unloaded, i.e. if a user moves more than one image away from it.
(See also --low-memory.)

ACTIONS

Actions are the building blocks for controlling pqiv. The syntax for entering an action is
COMMAND(PARAMETER)
where COMMAND is one of the commands described in the following and PARAMETER is the
command's parameter. Strings are not quoted. Instead, the closing parenthesis must be
escaped by a backslash if it is used in a string. E.g., `command(echo \))' will output a
single `)'. The available commands are:

add_file(STRING)
Add a file or directory.

animation_step(INT)
Stop an animation, and advance by the given number of frames plus one.

animation_continue()
Continue a stopped animation.

animation_set_speed_relative(DOUBLE)
Scale the animation's display speed.

animation_set_speed_absolute(DOUBLE)
Set the animation's display speed scale level to an absolute value. 1.0 is the
animation's natural speed.

bind_key(STRING)
Override a key binding. Remember to quote closing parenthesis inside the new
definition by prepending a backslash. Useful in conjunction with send_keys(STRING)
to set up cyclic bindings.

command(STRING)
Execute the given shell command. The syntax of the argument is the same as for the
--command-1 option.

flip_horizontally()
Flip the current image horizontally.

flip_vertically()
Flip the current image vertically.

goto_directory_relative(INT)
Jump to the n'th next or previous directory.

goto_earlier_file()
Return to the image that was opened before the current one.

goto_file_byindex(INT)
Jump to a file given by its number.

goto_file_byname(STRING)
Jump to a file given by its displayed name.

goto_file_relative(INT)
Jump to the n'th next or previous file.

goto_logical_directory_relative(INT)
Jump to the n'th next or previous logical directory. Any multi-page documents, such
as PDFs or archive files, are regarded as logical directories. Directories within
archive files, recognizable by a slash in the archive member's file name, are
regarded as directories too. Basically, the rule is that two images are in the same
logical directory if no character following the common prefix of their file names
in either name is a slash or a hash symbol.

hardlink_current_image()
Hardlink the current image to ./.pqiv-select/, or copy it if hardlinking is not
possible.

jump_dialog()
Display the jump dialog.

montage_mode_enter()
Enter montage mode, a view for interactive selection of images.

montage_mode_follow(KEYS)
Set up "follow" mode: Bind a sequence composed of the keys in KEYS to each visible
thumbnail, such that typing that sequence moves the cursor to said position. At the
same time, turn on binding overlays, increase the keyboard timeout, and revert
everything after an image has been selected.

montage_mode_return_proceed()
Leave montage mode, and goto the currently selected image.

montage_mode_return_cancel()
Leave montage mode, and return to the last image viewed before entering montage
mode.

montage_mode_set_shift_x(INT)
Set the horizontal cursor position in montage mode to an absolute value, indexed
from 0.

montage_mode_set_shift_y(INT)
Set the vertical cursor position in montage mode to an absolute value, indexed from
0.

montage_mode_set_wrap_mode(INT)
Adjust how wrapping around edges works when shifting the cursor position in montage
mode: The default, 1, is to wrap around rows but not around the whole image list.
Set this to 0 to disable wrapping entirely. A value of 2 enables full wrapping.

montage_mode_shift_x(INT)
Shift the cursor in montage mode in horizontal direction. Shifts wrap around edges
to the adjacent vertical lines, but not around the end of the list back to its
beginning.

montage_mode_shift_y(INT)
Shift the cursor in montage mode in vertical direction.

montage_mode_show_binding_overlays(INT)
Disable (by using a parameter value of 0) or enable (by using any other value)
follow mode. In follow mode, pqiv will draw mnemonics on top of each thumbnail that
is reachable by typing a key (combination). Use this to realize keyboard navigation
similar to vimperator/pentadactyl/vimium/etc.

montage_mode_shift_y_pg(INT)
Shift the cursor in montage mode in vertical direction by n pages.

move_window(INT, INT)
Move pqiv's window to the specified coordinates. Negative values center the window
on the current monitor.

nop() Do nothing. Can be used to clear an existing binding.

numeric_command(INT)
Execute the n'th command defined via --command-1 etc.

output_file_list()
Output a list of all loaded files to the standard output.

quit() Quit pqiv.

reload()
Reload the current image from disk.

remove_file_byindex(INT)
Remove a file given by its number.

remove_file_byname(STRING)
Remove a file given by its displayed name.

reset_scale_level()
Reset the scale level to the default value.

rotate_left()
Rotate the current image left by 90°.

rotate_right()
Rotate the current image right by 90°.

send_keys(STRING)
Emulate pressing a sequence of keys. This action currently does not support special
keys that do not have an ASCII representation. Useful in conjunction with
bind_key(STRING) to set up cyclic key bindings.

set_cursor_visibility(INT)
Set the visibility of the cursor; 0 disables, other values enable visibility.

set_cursor_auto_hide(INT)
Automatically show the cursor when the pointer moves, and hide it after one second
of inactivity. Set to 0 to disable this feature or any other value to enable it.
Note that this enables pointer movement events, which might slow down pqiv if it is
used over slow network links.

set_fade_duration(DOUBLE)
Set the duration of fades between images. In contrast to the command line option,
this action also implicitly enables fading. Set the duration to zero to disable the
feature.

set_interpolation_quality(INT)
Set the interpolation quality for resized images. Options are: 0 to cycle between
the different modes, 1 for an automated choice based on the image size (small
images use nearest interpolation, large ones Cairo's `good' mode), 2 for `fast', 3
for `good' and 4 for `best'.

set_keyboard_timeout(DOUBLE)
Set the timeout for key sequence input. For example, if you bind something to a and
another action to ab, pqiv will give you by default half a second to enter the b
before assuming that you intended to type only a. Use this action to change this
value.

set_scale_level_absolute(DOUBLE)
Set the scale level to the parameter value. 1.0 is 100%. See also --zoom-level.

set_scale_level_relative(DOUBLE)
Adjust the scale level multiplicatively by the parameter value.

set_scale_mode_fit_px(INT, INT)
Always adjust the scale level such that each image fits the given dimensions.

set_scale_mode_screen_fraction(DOUBLE)
Adjust how much of the available screen space is used for scaling the window
outside fullscreen mode. Defaults to 0.8. This also affects the size of the montage
mode window.

set_shift_align_corner(STRING)
Align the image to the window/screen border. Possible parameter values are the
cardinal directions, e.g. NE will align the image to the north east, i.e. top
right, corner. You can prepend the parameter by an additional C to perform the
adjustment only if the image dimensions exceed the available space, and to center
the image elsewise.

set_shift_x(INT)
Set the shift in horizontal direction to a fixed value.

set_shift_y(INT)
Set the shift in vertical direction to a fixed value.

set_slideshow_interval_absolute(DOUBLE)
Set the slideshow interval to the parameter value, in seconds.

set_slideshow_interval_relative(DOUBLE)
Adjust the slideshow interval additively by the parameter value. See also
--slideshow-interval.

set_status_output(INT)
Set this to non-zero to make pqiv print status information for scripts to stdout,
once upon activation and then whenever the user moves between images. The format
is compatible with shell variable definitions. Variables currently implemented are
CURRENT_FILE_NAME and CURRENT_FILE_INDEX. An output sweep always ends with an empty
line.

set_thumbnail_preload(INT)
Change the amount of thumbnails to be preloaded. A value of zero disables the
feature.

set_thumbnail_size(INT,INT)
Change the size of thumbnails. The order of the arguments is width, then height.
Thumbnails are always scaled such that no side is larger than this limit. Note that
the persistent thumbnail cache only supports 128x128 and 256x256 thumbnails.

shift_x(INT)
Shift the current image in x direction.

shift_y(INT)
Shift the current image in y direction.

toggle_background_pattern(INT)
Toggle between the different background patterns: 0 to toggle, 1 for checkerboard
pattern, 2 for black, 3 for white.

toggle_fullscreen(INT)
Toggle fullscreen mode: 0 to toggle, 1 to go to fullscreen, 2 to return to window
mode.

toggle_info_box()
Toggle the visibility of the info box.

toggle_negate_mode(INT)
Toggle negate (color inversion) mode: 0 to toggle, 1 to enable, 2 to disable.

toggle_scale_mode(INT)
Change the scale mode: Use 1 to disable scaling, 2 for automated scaledown
(default), 3 to always scale images up, 4 to maintain the user-set zoom level, and
5 to maintain the window's size. 0 cycles through modes 1-3.

toggle_shuffle_mode(INT)
Toggle shuffle mode. Use 0 to cycle through the possible values, 1 to enable
shuffle, and any other value to disable it.

toggle_slideshow()
Toggle slideshow mode.

DEFAULT KEY BINDINGS

Backspace/Space Previous/Next file.

ctrl-a Link the current image to ./.pqiv-select/, or copy it if
hardlinking is not possible.

f Toggle fullscreen mode.

h/v Flip the image horizontally or vertically.

k/l Rotate the image right or left.

i Toggle visibility of the info box.

j Show a dialog with a list of all files for quick selection.

m Toggle montage mode, an interactive image selection mode. Use
cursor keys or your mouse to select an image and Return to return
to single image view. Use g to quickly navigate to a thumbnail.

q Quit pqiv

r Reload the current image.

s Toggle slideshow mode.

t Toggle the scale mode; cycle between scaling all images up,
scaling large images down and no scaling at all.

ctrl-t Maintain user-set scale level.

mod-t Maintain the window's size.

Plus/Minus Zoom.

Period, ctrl-Period Stop, single-step and continue animated images.

mod-Plus, mod-Minus Alter animation speed.

ctrl-r Go to the image viewed before the current one.

ctrl-Space, ctrl-Backspace
Go to the next/previous logical directory.

ctrl-Plus, ctrl-Minus Alter slideshow interval.

b Toggle background pattern for transparent images.

n Toggle negate ("negative") mode.

Mouse buttons (fullscreen)
Goto the next and previous files.

Mouse drag (fullscreen) Move the image.

Mouse drag with right button (fullscreen)
Zoom.

Arrow keys Move the image.

This list omitted some advanced default bindings. The descriptions of the actions above is
annotated with those bindings. You can also run `pqiv --show-bindings' to display a
complete list.

CONFIGURATION FILE

       Upon startup, pqiv parses the file ~/.config/pqivrc. It should be  a  INI-style  key/value
       file  with  an  options section. All long form parameters are valid keys. To set a boolean
       flag, set the value to 1. A set flag inverts the  meaning  of  the  associated  parameter.
       E.g., if you set `fullscreen=1', then pqiv will start in fullscreen mode unless you supply
       -f upon startup.

       As an example,
              [options]
              fullscreen=1
              sort=1
              command-1=|convert - -blur 20 -
       will make pqiv start in fullscreen by default, sort the file list and bind a  blur  filter
       to  key  1. The -f flag on the command line will make pqiv not start in fullscreen, and -n
       will make it not sort the list.

       You can place key bindings in  the  format  of  the  --bind-key  parameter  in  a  special
       [keybindings] section. E.g.,
              [keybindings]
              q { goto_file_relative(-1); }
              w { goto_file_relative(1); }

              x { send_keys(#1); }
              <numbersign>1 { set_scale_level_absolute(1.); bind_key(x { send_keys(#2\); }); }
              <numbersign>2 { set_scale_level_absolute(.5); bind_key(x { send_keys(#3\); }); }
              <numbersign>3 { set_scale_level_absolute(0.25); bind_key(x { send_keys(#1\); }); }
       will remap q and w to move between images, and set up x to cycle through 100%, 50% and 25%
       zoom levels.

       Similarly, you can also specify (multiple) actions  to  be  executed  each  time  pqiv  is
       started in a section called [actions].

       For  backwards  compatibility with old versions of pqiv, if the file does not start with a
       section definition, the first line will be parsed as command line parameters.

       You may place comments into the file by beginning a line with `;' or `#'.  Comments at the
       end of a line are not supported.

       Other  supported  paths  for  the  configuration  file  are ~/.pqivrc, /etc/xdg/pqivrc and
       /etc/pqivrc. pqiv will use whichever file it finds first.  You  can  use  the  environment
       variable PQIVRC_PATH to override the configuration file.

EXAMPLES

       pqiv  --bind-key="a  { goto_file_byindex(0) }" --bind-key='c { command(echo -n $1 | xclip)
       }' --sort foo bar.pdf
              Rebinds a to go back to the first image, c to store the path to the  current  image
              to  the  clipboard using xclip and loads all files from the foo folder and bar.pdf,
              sorted.

       pqiv --slideshow --watch-directories --end-of-files-action=wait --slideshow-interval=0.001
       test
              Load  all  files  from the test folder in a slideshow progressing very fast, and in
              the end wait until new files become available. This effectively displays new images
              as they appear in a directory and is useful e.g. if you output images from a script
              that you later intent to combine into a movie and wish to monitor progress.

       pqiv  --slideshow  --allow-empty-window  --watch-directories   --wait-for-images-to-appear
       --lazy-load test
              Set  up  a  slideshow that displays all images from the test folder such that it is
              possible to remove all images from  the  directory  and  place  new  ones  into  it
              afterwards without pqiv exiting.

       echo "output_file_list(); quit()" | pqiv --actions-from-stdin test
              Output a list of all files from the test folder that pqiv can handle and quit.

BUGS

       Please report any bugs on github, on https://github.com/phillipberndt/pqiv

AUTHOR

       Phillip Berndt (phillip dot berndt at googlemail dot com)