NAME¶
imv - Image viewer for X11 and Wayland
DESCRIPTION¶
imv is an image viewer for X11 and Wayland, aimed at users of
tiling window managers. It supports a wide variety of image file formats,
including animated gif files. imv will automatically reload the current
image, if it is changed on disk.
SYNOPSIS¶
imv [options] [paths...]
OPTIONS¶
-h
Show help message and quit.
-v
Show version and quit.
-b <background>
Set the background colour. Can either be a 6-digit
hexadecimal colour code or checks to show a chequered background.
-c <command>
Specify a command to be run on launch, after the
configuration has been loaded. Can be used to configure custom keys with the
bind command. This option can be used multiple times. Commands are run in the
order that they have been passed to imv.
-d
Start with overlay visible.
-f
Start fullscreen.
-l
List open files to stdout at exit.
-n <path|index>
Start with the given path, or index selected.
-r
Load directories recursively.
-s <none|shrink|full|crop>
Set scaling mode to use. none will show each image
at its actual size. shrink will scale down the image to fit inside the
window. full will both scale up and scale down the image to fit
perfectly inside the window. crop will scale and crop the image to fill
the window. Defaults to full.
-t <slideshow_duration>
Start in slideshow mode, with each image shown for the
given number of seconds.
-u <linear|nearest_neighbour>
Set upscaling method used by imv.
-w <windowtitle>
Set window title when starting imv.
-x
Disable looping of input paths.
-W <width>
Initial width of window.
-H <height>
Initial height of window.
COMMANDS¶
Commands can be entered by pressing :. imv supports the
following commands:
quit
Quit imv. Aliased to q.
pan <x> <y>
Pan the view by the given amounts.
next <offset>
Move forwards by a given number of images. Aliased to
n
prev <offset>
Move backwards by a given number of images. Aliased to
p
goto <index>
Select an image by index. 1 is the first image,
2 the second, etc. The last image can be indexed as -1, the
second last as -2. Aliased to g.
zoom <amount|actual>
Zoom into the image by the given amount. Negative values
zoom out. actual resets the zoom to 100%, showing the image at its
actual size. Aliased to z.
rotate <'to'|by> <angle>
Rotate image clockwise by/to the given amount in
degrees.
flip <'horizontal'|vertical>
Flip image horizontally/vertically (across
vertical/horizontal axis).
open [-r] <paths ...>
Add the given paths to the list of open images. If the
-r option is specified, do so recursively. Shell expansions may be
used. Aliased to o.
close [index|all]
Close the currently selected image, or the image at the
given index, or all images.
fullscreen
Toggle fullscreen.
overlay
Toggle the overlay.
exec <command>
Execute a shell command. imv provides various environment
variables to the command executed. These are documented in the Environment
Variables section.
center
Recenter the selected image.
reset
Reset the view, centering the image and using the current
scaling mode to rescale it.
next_frame
If an animated gif is currently being displayed, load the
next frame.
toggle_playing
Toggle playback of the current image if it is an animated
gif.
scaling <none|shrink|full|crop|next>
Set the current scaling mode. Setting the mode to
next advances it to the next mode in the list.
upscaling <linear|nearest_neighbour|next>
Set the current upscaling method. Setting the method to
next advances it to the next method in the list.
slideshow <+amount|-amount|duration>
Increase or decrease the slideshow duration by the given
amount in seconds, or set its duration directly. Aliased to ss.
background <checks|hexadecimal-code>
Set the background color. checks for a
chequerboard pattern, or specify a 6-digit hexadecimal color code. Aliased to
bg.
bind <keys> <commands>
Binds an action to a set of key inputs. Uses the same
syntax as the config file, but without an equals sign between the keys and the
commands. For more information on syntax, see
imv(5).
DEFAULT BINDS¶
imv comes with several binds configured by default
q
Quit
Left arrow,
Previous image
Right arrow
Next Image
gg
Go to first image
G
Go to last image
j
Pan down
k
Pan up
h
Pan left
l
Pan right
x
Close current image
f
Toggle fullscreen
d
Toggle overlay
p
Print current image to stdout
Up arrow
Zoom in
Down arrow
Zoom out
i
Zoom in
o
Zoom out
+
Zoom in
-
Zoom out
Ctrl+r
Rotate clockwise by 90 degrees
c
Center image
s
Next scaling mode
S
Next upscaling mode
a
Zoom to actual size
r
Reset zoom and pan
.
Next frame (for animations)
Space
Pause/play animations
t
Start slideshow/increase delay by 1 second
T
Stop slideshow/decrease delay by 1 second
CONFIGURATION¶
The path to a config file can be given via the $imv_config
environment variable. If not found, imv will search for it in the following
locations:
•$XDG_CONFIG_HOME/imv/config (recommended)
•$HOME/.config/imv/config
•$HOME/.imv_config
•$HOME/.imv/config
•/usr/local/etc/imv_config
•/etc/imv_config
A default config file is shipped with imv into /etc/imv_config
For documentation on the config file format, see
imv(5).
ENVIRONMENT VARIABLES¶
When imv executes a shell command, it provides a number of
environment variables, exposing imv’s state. These environment
variables are also available when customising the window’s title, or
the overlay text.
$imv_pid
The pid of this instance of imv. Useful for running
imv-msg in scripts.
$imv_current_file
Path of currently selected image.
$imv_scaling_mode
Name of the current scaling mode.
$imv_loading
1 if a new image is loading, 0 otherwise.
$imv_current_index
Index of current image, from 1-N.
$imv_file_count
Total number of files.
$imv_width
Width of the current image.
$imv_height
Height of the current image.
$imv_scale
Scaling of current image in percent.
$imv_slideshow_duration
Number of seconds each image is shown for.
$imv_slideshow_elapsed
How long the current image has been shown for.
IPC¶
imv can accept commands from another process over a unix socket.
Each instance of imv will open a unix socket named
$XDG_RUNTIME_DIR/imv-$PID.sock. If $XDG_RUNTIME_DIR is undefined, the
socket is placed into /tmp/ instead.
The imv-msg(1) utility is provided to simplify this from
shell scripts.
AUTHORS¶
imv is written and maintained by Harry Jeffery <me@harry.pm>
with contributions from other developers.
Full source code and other information can be found at
https://sr.ht/~exec64/imv.