pqiv(1)

NAME
pqiv - 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 to bind further keys to other commands. COMMAND is executed using the default shell processor. `$1' is substituted with the current file name.

    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.

--bind-key=KEYBINDING
    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.

--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-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.

--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.

--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.

--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.

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 command.

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_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.

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

jump_dialog()
    Display the jump dialog.

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_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_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.

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

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

toggle_fullscreen()
    Toggle fullscreen mode.

toggle_info_box()
    Toggle the visibility of the info box.

toggle_scale_mode(INT)
    Change the scale mode: Use 1 to disable scaling, 2 for automated scaledown (default), 3 to always scale images up, and 4 to maintain the user-set zoom level. 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

Space
    Next file.

Backspace
    Previous file.

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.

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.

Plus/minus
    Zoom.

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. Run `pqiv --show-bindings' to display a complete list.

CONFIGURATION FILE
Upon startup, pqiv parses the file ~/.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.

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.

EXAMPLES

pqiv --bind-key="a { goto_file_byindex(0) }" --sort foo bar.pdf
    Rebinds a to go back to the first image, 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.

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)