Provided by: fim_0.5~rc3-2build1_amd64 
NAME
fim - fbi (linux framebuffer imageviewer) improved
SYNOPSIS
fim [{options}] [--] {imagefile} [{imagefiles}]
... | fim [{options}] [--] [{imagefiles}] -
fim [{options}] [--] [{files}] - < {file_name_list_text_file}
fim --image-from-stdin [{options}] < {imagefile}
fim --script-from-stdin [{options}] < {scriptfile}
DESCRIPTION
fim is a `swiss army knife' for displaying image files. It is capable of displaying image
files using different graphical devices while offering a uniform look and feel; it
features an internal command language specialized to the image viewing purposes; it is
capable of interacting with standard input and output; the internal command language is
accessible via a command line capable of autocompletion and history; it features command
recording, supports initialization files, customizable key bindings, internal variables
and command aliases, vim-like autocommands, JPEG comments, EXIF tags display, EXIF
rotation/orientation, and much more.
As a default, fim displays the specified file(s) on the detected graphical device (e.g.
with SDL if X is detected, or the linux framebuffer device if not).
JPEG,PNG,GIF,BMP,TIFF,PPM,PGM,PBM,PCX formats are supported. For 'XCF' (Gimp's) images,
fim will try to use 'xcftopnm'. For '.FIG' vectorial images, fim will try to use
'fig2dev'. For '.DIA' vectorial images, fim will try to use 'dia'. For '.SVG' vectorial
images, fim will try to use 'inkscape'. For other formats fim will try to use
ImageMagick's 'convert' executable.
If {imagefile} is a directory, therein contained files of supported formats will be
loaded. If {imagefile} contains a trailing slash (/), it will be treated as a directory;
otherwise a check will be made using stat(2). To change this default, see description of
the _pushdir_re variable and the --no-stat-push and --recursive options.
If configured at build time, fim will be capable of using SDL or aalib output.
This man page only describes the fim command line options. See man fimrc(5) for a full
specification of the fim language, commands, variables, and an example configuration file.
USAGE
You may invoke fim from an interactive shell and control it with the keyboard, as you
would do with any image viewer with reasonable key bindings.
fim is keyboard oriented: there are no user menus or buttons available. If you need some
feature or setting which is not accessible from the default keyboard configuration, you
probably need a custom configuration or simply need to type a custom command. For these,
you can use the internal command and configuration language. The full specification for
these is accessible at runtime using the internal help system (typing :help).
OPTIONS
Accepted command line {options} :
-- The arguments before -- beginning with - will be treated as command line options.
All arguments after -- will be treated as filenames regardlessly.
-a, --autozoom
Enable autozoom. fim will automagically pick a reasonable zoom factor when loading
a new image (as in fbi).
-b, --binary[=24|1]
Display (any filetype) binary files contents as they were raw 24 or 1 bits per
pixel pixelmaps. Will arrange the image by rows long as specified by the
_preferred_rendering_width variable for the image width (unless a narrower image
suffices). Regard this as an easter bunny option.
--as-text
Display (any filetype) files contents as they were text. Will only show printable
characters. Regard this as an easter bunny option.
--cd-and-readdir
Step into the first loaded file directory and push other files.
-c {commands}, --execute-commands {commands}
The commands string will be executed before entering the interactive loop. Please
note that if your commands are more complicated than a simple 'next' or 'pornview'
command, they must be quoted and escaped in a manner suitable for your shell!
For example, -c '*2;2pan_up;display;while(1){align "bottom";sleep "1" ; align
"top"}' (with the single quotes) will tell fim to first double the displayed image
size, then pan two times up, then display the image ; and then do an endless loop
consisting of bottom and top aligning, alternated.
-C {commands}, --execute-commands-early {commands}
Just as the --execute-commands option, but commands will be executed before the
loading of any config file.
For example, -C '_scale_style=" "' will make fim start with no auto-scaling.
-d {framebuffer device}, --device {framebuffer device}
Framebuffer device to use. Default is the one your vc is mapped to (as in fbi).
--dump-reference-help[=man].
Will dump to stdout the language reference help.
-D, --dump-default-fimrc
The default configuration (the one hardcoded in the fim executable) is dumped on
standard output and fim exits.
-E {scriptfile}, --execute-script {scriptfile}
The scriptfile will be executed right after the default initialization file is
executed.
-f {fimrc}, --etc-fimrc {fimrc}
Specify an alternative system wide initialization file (default:
/usr/local/etc/fimrc), which will be executed prior to any other configuration
file.
-F {commands}, --final-commands {commands}
The commands string will be executed after exiting the interactive loop of the
program (right before terminating the program).
-h, --help[=s|d|l|m]
Print (short, descriptive, long, or complete man) program invocation
help, and terminate.
--load-image-descriptions-file {filename}
Load image descriptions from {filename}. In {filename} each line is the name of an
image file (its basename will be taken), then a Tab character (unless
--image-descriptions-file-separator specifies otherwise), then the description
text. Each description will be put in the _comment variable of the image at load
time. Will override the comment eventually loaded from the file (e.g. JPEG, PNG or
TIFF comment). Special comment lines like "#!fim:var=val" will lead i:var to be
assigned value val (unquoted) at image loading time. Special description lines
begin with markers: with "#!fim:=" the last description line to be used; with
"#!fim:+" what follows + will be appended to the last description line; with
"#!fim:^" what follows ^ will be prepended to the last description line; with
"#!fim:s/f/t" the last description line will be used, but occurrences of string f
will be substituted with string t (f and t can contain anything but not a /). If
val is empty that variable will be unset. These variables are stored also in an
internal index used by the limit command. This option sets _caption_over_image=2,
so that a caption will be displayed over the image.
--image-descriptions-file-separator {sepchar}
A character to be used as a separator between the filename and the description part
of lines specified just before a --load-image-descriptions-file.
-i, --image-from-stdin
Will read one single image from the standard input (the image data, not the
filename). May not work with all supported file formats. In the image list, this
image will be displayed as "<STDIN>".
-m {vmode}, --mode {vmode}
Name of the video mode to use video mode (must be listed in /etc/fb.modes).
Default is not to change the video mode. In the past, the XF86 config file
(/etc/X11/XF86Config) used to contain Modeline information, which could be fed to
the modeline2fb perl script (distributed with fbset). On many modern xorg based
systems, there is no direct way to obtain a fb.modes file from the xorg.conf file.
So instead one could obtain useful fb.modes info by using the (fbmodes (no man page
AFAIK)) tool, written by bisqwit. An unsupported mode should make fim exit with
failure. But it is possible the kernel could trick fim and set a supported mode
automatically, thus ignoring the user set mode.
-N, --no-rc-file
No personal initialization file will be read (default is ~/.fimrc) at startup.
--no-etc-rc-file
No system wide initialization file will be read (default is /usr/local/etc/fimrc)
at startup.
--no-internal-config
No internal default configuration at startup (uses internal variable
_no_default_configuration). Will only provide a minimal working configuration.
--no-commandline
With internal command line mode disabled.
--no-history-save
Do not save execution history at finalization (uses internal variable
_save_fim_history).
--no-history-load
Do not load execution history at startup.
--no-history
Do not load or save execution history at startup.
-p, --script-from-stdin
Will read commands from stdin prior to entering in interactive mode.
-o [fb|sdl|aa|imlib2|caca|dumb], --output-device [fb|sdl|aa|imlib2|caca|dumb]
Will use the specified device as fim video output device, overriding automatic
checks.The available devices depend on the original configuration/compilation
options, so you should get the list of available output devices issuing fim
--version. The aa option may be specified as aa={['w']} ; the 'w' character
allows windowed mode in case of aalib running under X (otherwise, the DISPLAY
environment variable will be unset for the current instance of fim). The sdl
option may be specified as sdl={['w']['m']['r']['W']['M']['R']width:height} ,
where width is and height are integer numbers specifying the desired resolution;
the 'w' character requests windowed mode; the 'm' character requests mouse pointer
display; the 'r' character requests support for window resize; the same letters
uppercase request explicit negation of the mentioned features.
--offset {bytes-offset[{:upper-offset}|{+offset-range}]}
Will use the specified offset (in bytes) for opening the specified files. If
:upper-offset is specified, further bytes until upper-offset will be probed. If
+offset-range is specified instead, that many additional bytes will be probed. Use
this option to search damaged file systems for image files.
-P, --text-reading
Enable textreading mode. This has the effect that fim will display images scaled
to the width of the screen, and aligned to the top. Useful if the images you are
watching text pages, all you have to do to get the next piece of text is to press
space (in the default key configuration, of course).
-s {value}, --scroll {value}
Set scroll steps for internal variable _steps (default is 20%).
--slideshow {number}
Interruptible slideshow mode; will wait for {number} of seconds (assigned to the
_want_sleep_seconds variable after each loading; implemented by executing
while(_fileindex<_filelistlen){sleep _want_sleep_seconds; next;} as a first
command.
-S, --sanity-check
A quick sanity check before starting the interactive fim execution, but after the
initialization.
-t, --no-framebuffer
Fim will not use the framebuffer but the aalib (ASCII art) driver instead (if you
are curious, see (info aalib)). If aalib was not enabled at tompile time, fim will
work without displaying images at all.
-T {terminal}, --vt {terminal}
The terminal will be used as virtual terminal device file (as in fbi). See (chvt
(1)), (openvt (1)) for more info about this. Use (con2fb (1)) to map a terminal to
a framebuffer device.
--sort Sort files list before browsing according to full filename.
--sort-basename
Sort files list before browsing according to file basename's.
-u, --random
Randomly shuffle the files list before browsing (seed depending on time()
function).
--random-no-seed
Randomly shuffle the files list before browsing (no seeding).
-v, --verbose
Be verbose: show status bar.
-V, --version
Display program version, compile flags, enabled features, linked libraries
information, supported filetypes/file loaders, and then terminate.
-w, --autowidth
Scale the image according to the screen width.
--no-auto-scale
Do not scale the images after loading (will set '_scale_style=" "';).
--autowindow
Will resize the window size (if supported) to the image size. Don't use this with
other image scaling options.
--no-stat-push
Sets _push_checks=0 before initialization, thus disabling file/dir existence checks
with stat(2) at push push time (and speeding up startup).
-H, --autoheight
Scale the image according to the screen height.
-W {scriptfile}, --write-scriptout {scriptfile}
All the characters that you type are recorded in the file {scriptout}, until you
exit Fim. This is useful if you want to create a script file to be used with
"fim -c" or ":exec" (analogous to Vim's -s and ":source!"). If the {scriptout}
file exists, it will be not touched (as in Vim's -w).
-, --read-from-stdin
Read file list from stdin: each line one file.
Note that these the three standard input reading functionalities (-i,-p and -)
conflict : if two or more of them occur in fim invocation, fim will exit with an
error and warn about the ambiguity.
See the section INVOCATION EXAMPLES below to read some useful (and unique) ways of
employing fim.
--read-from-stdin-elds <arg>
Specify an endline delimiter string for breaking lines read via
-/--read-from-stdin. Line text before the delimiter will be treated as names of
files to load; the text after will be ignored until a newline. This is useful e.g.
to description files as filename list files.
-A, --autotop
Align images to the top (UNFINISHED).
-q, --quiet
Quiet mode. Sets _display_status=0;_display_busy=0;.
-r {resolution}, --resolution {resolution}
Set resolution (UNFINISHED).
-R, --recursive
Push files/directories to the files list recursively.
PROGRAM RETURN STATUS
The program return status is 0 on correct operation; 252 on unsupported device
specification; 248 on bad input; 255 on a generic error; 42 on a signal-triggered program
exit; or a different value in case of an another error.
The return status may be controlled by the use of the quit command.
COMMON KEYS AND COMMANDS
The following keys and commands are hardcoded in the minimal configuration. These are working by default before any config loading, and before the hardcoded config loading (see variable _fim_default_config_file_contents).
n goto '+1f'
p goto '-1f'
+ magnify
- reduce
h pan 'left'
l pan 'right'
k pan 'up'
j pan 'down'
q quit
You can type a number before a command binding to iterate the assigned command:
3k 3pan 'up'
: enter command line mode
:{number} jump to {number}^th image in the list
:^ jump to first image in the list
:$ jump to last image in the list
:*{factor} scale the image by {factor}
:{scale}% scale the image to the desired {scale}
:+{scale}% scale the image up to the desired percentage {scale} (relatively to the original)
:-{scale}% scale the image down to the desired percentage {scale} (relatively to the original)
/{regexp} entering the pattern {regexp} (with /) makes fim jump to the next image whose filename matches {regexp}
/*.png$ entering this pattern (with /) makes fim jump to the next image whose filename ends with 'png'
/png a shortcut for /.*png.*
!{syscmd} executes the {syscmd} quoted string as a "/bin/sh" shell command
You can visualize all of the default bindings invoking fim --dump-default-fimrc | grep bind .
You can visualize all of the default aliases invoking fim --dump-default-fimrc | grep alias .
The Return vs. Space key thing can be used to create a file list while reviewing the
images and use the list for batch processing later on.
All of the key bindings are reconfigurable; see the default fimrc file for examples on
this, or read the complete manual: the FIM.TXT file distributed with fim.
AFFECTING ENVIRONMENT VARIABLES
FBFONT (just like in fbi) a Linux consolefont font file.
If using a gzipped font, the zcat program will be used to uncompress it (via execvp(3)).
If not specified, the following files will be probed and the first existing will be selected:
/usr/share/consolefonts/Uni3-TerminusBoldVGA14.psf.gz
/usr/lib/kbd/consolefonts/lat9-16.psf.gz
/usr/share/consolefonts/lat1-16.psf
/usr/share/consolefonts/lat1-16.psf.gz
/usr/share/consolefonts/lat1-16.psfu.gz
/usr/share/kbd/consolefonts/lat1-16.psf
/usr/share/kbd/consolefonts/lat1-16.psf.gz
/usr/share/kbd/consolefonts/lat1-16.psfu.gz
/usr/lib/kbd/consolefonts/lat1-16.psf
/usr/lib/kbd/consolefonts/lat1-16.psf.gz
/usr/lib/kbd/consolefonts/lat1-16.psfu.gz
/lib/kbd/consolefonts/lat1-16.psf
/lib/kbd/consolefonts/lat1-16.psf.gz
/lib/kbd/consolefonts/lat1-16.psfu.gz
/lib/kbd/consolefonts/Lat2-VGA14.psf.gz
/lib/kbd/consolefonts/Lat2-VGA16.psf.gz
/lib/kbd/consolefonts/Lat2-VGA8.psf.gz
/lib/kbd/consolefonts/Uni2-VGA16.psf.gz
/usr/share/consolefonts/default8x16.psf.gz
/usr/share/consolefonts/default8x9.psf.gz
/usr/share/consolefonts/Lat15-Fixed16.psf.gz
/usr/share/consolefonts/default.psf.gz
fim://
If the special fim:// string is specified, a hardcoded font will be used.
FBGAMMA (just like in fbi) gamma correction (applies to dithered 8 bit mode only). Default is 1.0.
FRAMEBUFFER (just like in fbi) user set framebuffer device file (applies only to the fb mode).
If unset, fim will probe for /dev/fb0.
TERM (only in fim) will influence the output device selection algorithm, especially if $TERM=="screen".
DISPLAY If this variable is set, then the sdl driver will be probed by default.
COMMON PROBLEMS
fim needs read-write access to the framebuffer devices (/dev/fbN or /dev/fb/N), i.e you
(our your admin) have to make sure fim can open the devices in rw mode. The IMHO most
elegant way is to use pam_console (see /etc/security/console.perms) to chown the devices
to the user logged in on the console. Another way is to create some group, chown the
special files to that group and put the users which are allowed to use the framebuffer
device into the group. You can also make the special files world writable, but be aware
of the security implications this has. On a private box it might be fine to handle it
this way through.
If using udev, you can edit : /etc/udev/permissions.d/50-udev.permissions and set these
lines like here :
# fb devices
fb:root:root:0600
fb[0-9]*:root:root:0600
fb/*:root:root:0600
fim also needs access to the linux console (i.e. /dev/ttyN) for sane console switch
handling. That is obviously no problem for console logins, but any kind of a pseudo tty
(xterm, ssh, screen, ...) will not work.
INVOCATION EXAMPLES
fim media/
# Will load files from the directory media.
fim -R media/ --sort
# Will open files found by recursive traversal of directory media, then sorting the list.
find /mnt/media/ -name *.jpg | fim -
# Will make fim read the file list from standard input.
find /mnt/media/ -name *.jpg | shuf | fim -
# will make fim read the file list from standard input, randomly shuffled.
cat script.fim | fim -p images/*
# Will make fim read the script file script.fim from standard input prior to displaying
files in the directory images
scanimage ... | tee scan.ppm | fim -i
# Will make fim read the image scanned from a flatbed scanner as soon as it is read
fim * > selection.txt
# Will output the file names marked interactively with the 'list "mark"' command in fim to
a file.
fim * | fim -
# will output the file names marked with 'm' in fim to a second instance of fim, in which
these could be marked again.
fim -c 'pread "vgrabbj -d /dev/video0 -o png";reload'
# will display an image grabbed from a webcam.
fim -o aa -c 'pread "vgrabbj -d /dev/video0 -o png";reload;system "fbgrab" "asciime.png"'
# if running in framebuffer mode, will save a png screenshot with an ASCII rendering of an
image grabbed from a webcam.
fim -c 'while(1){pread "vgrabbj -d /dev/video0 -o png";reload;sleep 1;};'
# will display a sequence of images grabbed from a webcam; circa 1 per second.
NOTES
This manual page is neither accurate nor complete. In particular, issues related to driver
selection shall be described more accurately. Also the accurate sequence of autocommands
execution, variables application is critical to understanding fim, and should be
documented. The filename "<STDIN>" is reserved for images read from standard input (view
this as a limitation), and thus handling files with such name may incur in limitations.
The SDL driver is quite inefficient, for a variety of reasons. In particular, its
interaction with the readline library can be problematic (e.g.: when running in sdl mode
without a terminal). This shall be fixed.
BUGS
fim has bugs. Please read the BUGS file shipped in the documentation directory to discover
the known ones.
FILES
/usr/local/share/doc/fim
The directory with Fim documentation files.
/usr/local/etc/fimrc
The system wide Fim initialization file (executed at startup, after
executing the hardcoded configuration).
~/.fimrc The personal Fim initialization file (executed at startup, after the system
wide initialization file).
~/.inputrc If Fim is built with GNU readline support, it will be susceptible to chages
in the user set ~/.inputrc configuration file contents. For details, see
(man readline(3)).
SEE ALSO
Other Fim man pages: fimgs(1), fimrc(1).
Or related programs: fbset(1), con2fb(1), convert(1), vim(1), fb.modes(8), fbset(8),
fbgrab(1), fbdev(4), setfont(8), xfs(1).
AUTHOR
Michele Martone <dezperado _CUT_ autistici _CUT_ org> is the author of fim, "fbi improved".
COPYRIGHT
Copyright (C) 2007-2016 Michele Martone <dezperado _CUT_ autistici _CUT_ org> (author of fim)
Copyright (C) 1999-2004 Gerd Hoffmann <kraxel _CUT_ bytesex.org> is the author of "fbi",
upon which fim was originally based.
This program is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program;
if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA.
(c) 2007-2016 Michele Martone fim(1)