fim

fim(1)                      General Commands Manual                     fim(1)



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)