aboutsummaryrefslogtreecommitdiff
path: root/doc/imv.1.txt
blob: cc79e71be66ebda89dd874dfc45b4743fdffa483 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
/////
vim:set ts=4 sw=4 tw=82 noet:
/////
:quotes.~:

imv (1)
=======

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.

*-x*::
	Disable looping of input paths.

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 simpliy 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://github.com/eXeC64/imv>.

See Also
--------

**imv**(5) **imv-msg**(1) **imv-folder**(1)