'\" t
.\"     Title: imv
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/18/2021
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "IMV" "1" "05/18/2021" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
imv \- Image viewer for X11 and Wayland
.SH "DESCRIPTION"
.sp
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\&.
.SH "SYNOPSIS"
.sp
\fIimv\fR [options] [paths\&...]
.SH "OPTIONS"
.PP
\fB\-h\fR
.RS 4
Show help message and quit\&.
.RE
.PP
\fB\-v\fR
.RS 4
Show version and quit\&.
.RE
.PP
\fB\-b\fR <background>
.RS 4
Set the background colour\&. Can either be a 6\-digit hexadecimal colour code or
\fIchecks\fR
to show a chequered background\&.
.RE
.PP
\fB\-c\fR <command>
.RS 4
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\&.
.RE
.PP
\fB\-d\fR
.RS 4
Start with overlay visible\&.
.RE
.PP
\fB\-f\fR
.RS 4
Start fullscreen\&.
.RE
.PP
\fB\-l\fR
.RS 4
List open files to stdout at exit\&.
.RE
.PP
\fB\-n\fR <path|index>
.RS 4
Start with the given path, or index selected\&.
.RE
.PP
\fB\-r\fR
.RS 4
Load directories recursively\&.
.RE
.PP
\fB\-s\fR <none|shrink|full|crop>
.RS 4
Set scaling mode to use\&.
\fInone\fR
will show each image at its actual size\&.
\fIshrink\fR
will scale down the image to fit inside the window\&.
\fIfull\fR
will both scale up and scale down the image to fit perfectly inside the window\&.
\fIcrop\fR
will scale and crop the image to fill the window\&. Defaults to
\fIfull\fR\&.
.RE
.PP
\fB\-t\fR <slideshow_duration>
.RS 4
Start in slideshow mode, with each image shown for the given number of seconds\&.
.RE
.PP
\fB\-u\fR <linear|nearest_neighbour>
.RS 4
Set upscaling method used by imv\&.
.RE
.PP
\fB\-x\fR
.RS 4
Disable looping of input paths\&.
.RE
.SH "COMMANDS"
.sp
Commands can be entered by pressing \fB:\fR\&. imv supports the following commands:
.PP
\fBquit\fR
.RS 4
Quit imv\&. Aliased to
\fIq\fR\&.
.RE
.PP
\fBpan\fR <x> <y>
.RS 4
Pan the view by the given amounts\&.
.RE
.PP
\fBnext\fR <offset>
.RS 4
Move forwards by a given number of images\&. Aliased to
\fIn\fR
.RE
.PP
\fBprev\fR <offset>
.RS 4
Move backwards by a given number of images\&. Aliased to
\fIp\fR
.RE
.PP
\fBgoto\fR <index>
.RS 4
Select an image by index\&.
\fI1\fR
is the first image,
\fI2\fR
the second, etc\&. The last image can be indexed as
\fI\-1\fR, the second last as
\fI\-2\fR\&. Aliased to
\fIg\fR\&.
.RE
.PP
\fBzoom\fR <amount|\fIactual\fR>
.RS 4
Zoom into the image by the given amount\&. Negative values zoom out\&.
\fIactual\fR
resets the zoom to 100%, showing the image at its actual size\&. Aliased to
\fIz\fR\&.
.RE
.PP
\fBrotate\fR <\*(Aqto\*(Aq|\fIby\fR> <angle>
.RS 4
Rotate image clockwise by/to the given amount in degrees\&.
.RE
.PP
\fBflip\fR <\*(Aqhorizontal\*(Aq|\fIvertical\fR>
.RS 4
Flip image horizontally/vertically (across vertical/horizontal axis)\&.
.RE
.PP
\fBopen\fR [\-r] <paths \&...>
.RS 4
Add the given paths to the list of open images\&. If the
\fI\-r\fR
option is specified, do so recursively\&. Shell expansions may be used\&. Aliased to
\fIo\fR\&.
.RE
.PP
\fBclose\fR [index|\fIall\fR]
.RS 4
Close the currently selected image, or the image at the given index, or all images\&.
.RE
.PP
\fBfullscreen\fR
.RS 4
Toggle fullscreen\&.
.RE
.PP
\fBoverlay\fR
.RS 4
Toggle the overlay\&.
.RE
.PP
\fBexec\fR <command>
.RS 4
Execute a shell command\&. imv provides various environment variables to the command executed\&. These are documented in the
\fIEnvironment Variables\fR
section\&.
.RE
.PP
\fBcenter\fR
.RS 4
Recenter the selected image\&.
.RE
.PP
\fBreset\fR
.RS 4
Reset the view, centering the image and using the current scaling mode to rescale it\&.
.RE
.PP
\fBnext_frame\fR
.RS 4
If an animated gif is currently being displayed, load the next frame\&.
.RE
.PP
\fBtoggle_playing\fR
.RS 4
Toggle playback of the current image if it is an animated gif\&.
.RE
.PP
\fBscaling\fR <none|shrink|full|crop|next>
.RS 4
Set the current scaling mode\&. Setting the mode to
\fInext\fR
advances it to the next mode in the list\&.
.RE
.PP
\fBupscaling\fR <linear|nearest_neighbour|next>
.RS 4
Set the current upscaling method\&. Setting the method to
\fInext\fR
advances it to the next method in the list\&.
.RE
.PP
\fBslideshow\fR <+amount|\-amount|duration>
.RS 4
Increase or decrease the slideshow duration by the given amount in seconds, or set its duration directly\&. Aliased to
\fIss\fR\&.
.RE
.PP
\fBbackground\fR <checks|hexadecimal\-code>
.RS 4
Set the background color\&.
\fIchecks\fR
for a chequerboard pattern, or specify a 6\-digit hexadecimal color code\&. Aliased to
\fIbg\fR\&.
.RE
.PP
\fBbind\fR <keys> <commands>
.RS 4
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
\fBimv\fR(5)\&.
.RE
.SH "DEFAULT BINDS"
.sp
imv comes with several binds configured by default
.PP
\fBq\fR
.RS 4
Quit
.RE
.PP
\fBLeft arrow,\fR
.RS 4
Previous image
.RE
.PP
\fBRight arrow\fR
.RS 4
Next Image
.RE
.PP
\fBgg\fR
.RS 4
Go to first image
.RE
.PP
\fBG\fR
.RS 4
Go to last image
.RE
.PP
\fBj\fR
.RS 4
Pan down
.RE
.PP
\fBk\fR
.RS 4
Pan up
.RE
.PP
\fBh\fR
.RS 4
Pan left
.RE
.PP
\fBl\fR
.RS 4
Pan right
.RE
.PP
\fBx\fR
.RS 4
Close current image
.RE
.PP
\fBf\fR
.RS 4
Toggle fullscreen
.RE
.PP
\fBd\fR
.RS 4
Toggle overlay
.RE
.PP
\fBp\fR
.RS 4
Print current image to stdout
.RE
.PP
\fBUp arrow\fR
.RS 4
Zoom in
.RE
.PP
\fBDown arrow\fR
.RS 4
Zoom out
.RE
.PP
\fBi\fR
.RS 4
Zoom in
.RE
.PP
\fBo\fR
.RS 4
Zoom out
.RE
.PP
\fB+\fR
.RS 4
Zoom in
.RE
.PP
\fB\-\fR
.RS 4
Zoom out
.RE
.PP
\fBCtrl+r\fR
.RS 4
Rotate clockwise by 90 degrees
.RE
.PP
\fBc\fR
.RS 4
Center image
.RE
.PP
\fBs\fR
.RS 4
Next scaling mode
.RE
.PP
\fBS\fR
.RS 4
Next upscaling mode
.RE
.PP
\fBa\fR
.RS 4
Zoom to actual size
.RE
.PP
\fBr\fR
.RS 4
Reset zoom and pan
.RE
.PP
\fB\&.\fR
.RS 4
Next frame (for animations)
.RE
.PP
\fBSpace\fR
.RS 4
Pause/play animations
.RE
.PP
\fBt\fR
.RS 4
Start slideshow/increase delay by 1 second
.RE
.PP
\fBT\fR
.RS 4
Stop slideshow/decrease delay by 1 second
.RE
.SH "CONFIGURATION"
.sp
The path to a config file can be given via the \fB$imv_config\fR environment variable\&. If not found, imv will search for it in the following locations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
$XDG_CONFIG_HOME/imv/config (recommended)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
$HOME/\&.config/imv/config
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
$HOME/\&.imv_config
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
$HOME/\&.imv/config
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
/usr/local/etc/imv_config
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
/etc/imv_config
.RE
.sp
A default config file is shipped with imv into /etc/imv_config
.sp
For documentation on the config file format, see \fBimv\fR(5)\&.
.SH "ENVIRONMENT VARIABLES"
.sp
When imv executes a shell command, it provides a number of environment variables, exposing imv\(cqs state\&. These environment variables are also available when customising the window\(cqs title, or the overlay text\&.
.PP
\fB$imv_pid\fR
.RS 4
The pid of this instance of imv\&. Useful for running imv\-msg in scripts\&.
.RE
.PP
\fB$imv_current_file\fR
.RS 4
Path of currently selected image\&.
.RE
.PP
\fB$imv_scaling_mode\fR
.RS 4
Name of the current scaling mode\&.
.RE
.PP
\fB$imv_loading\fR
.RS 4
1 if a new image is loading, 0 otherwise\&.
.RE
.PP
\fB$imv_current_index\fR
.RS 4
Index of current image, from 1\-N\&.
.RE
.PP
\fB$imv_file_count\fR
.RS 4
Total number of files\&.
.RE
.PP
\fB$imv_width\fR
.RS 4
Width of the current image\&.
.RE
.PP
\fB$imv_height\fR
.RS 4
Height of the current image\&.
.RE
.PP
\fB$imv_scale\fR
.RS 4
Scaling of current image in percent\&.
.RE
.PP
\fB$imv_slideshow_duration\fR
.RS 4
Number of seconds each image is shown for\&.
.RE
.PP
\fB$imv_slideshow_elapsed\fR
.RS 4
How long the current image has been shown for\&.
.RE
.SH "IPC"
.sp
imv can accept commands from another process over a unix socket\&. Each instance of imv will open a unix socket named \fI$XDG_RUNTIME_DIR/imv\-$PID\&.sock\fR\&. If $XDG_RUNTIME_DIR is undefined, the socket is placed into \fI/tmp/\fR instead\&.
.sp
The \fBimv\-msg\fR(1) utility is provided to simpliy this from shell scripts\&.
.SH "AUTHORS"
.sp
imv is written and maintained by Harry Jeffery <me@harry\&.pm> with contributions from other developers\&.
.sp
Full source code and other information can be found at https://github\&.com/eXeC64/imv\&.
.SH "SEE ALSO"
.sp
\fBimv\fR(5) \fBimv\-msg\fR(1)