Provided by: xli_1.17.0+20061110-3ubuntu1_i386 bug

NAME

       xli - load images into an X11 window or onto the root window

SYNOPSIS

       xli [global_options] {[image_options] image ...}
       xli [global_options] [image_options] stdin < image

DESCRIPTION

       xli  displays  images  in  an  X11  window  or loads them onto the root
       window.  See the IMAGE TYPES section below for supported image types.

       If the filename stdin is given, xli will read the image  from  standard
       input.

       If  the  destination display cannot support the number of colors in the
       image, the image will be dithered (monochrome destination) or have  its
       colormap  reduced (color destination) as appropriate.  This can also be
       done forcibly with the -halftone, -dither, and -colors options.

       A variety of image manipulations  can  be  specified,  including  gamma
       correction,    brightening,   clipping,   dithering,   depth-reduction,
       rotation,  and  zooming.   Most  of  these  manipulations  have  simple
       implementations; speed was opted for above accuracy.

       If  you  are viewing a large image in a window, the initial window will
       be at most 90% of the size of the display  unless  the  window  manager
       does  not  correctly  handle window size requests or if you've used the
       -fullscreen or -fillscreen options.  You may move the image  around  in
       the  window  by  dragging with the first mouse button.  The cursor will
       indicate which directions you may drag, if any.

       When the keyboard focus is in the window you can:
       Type 'q' or '^C' to exit xli.
       Type space, 'n' or 'f' to move to the next image in the list.
       Type 'b' or 'p' to move to the previous image in the list.
       Type . to reload the image.
       Type l to rotate the image anti-clockwise.
       Type r to rotate the image clockwise.
       Type 0 to set the images assumed gamma to your display gamma
              (usually darkens images)
       Type 1 to set the images assumed gamma to 1.0
              (usually lightens images)
       Type 5-2 to lighten the image (5 in small steps, up to 2 in large steps)
       Type 6-9 to darken the image (6 in small steps, up to 9 in large steps)
       Type > resp. < to zoom in resp. out

       A wide variety of common image manipulations can be done by mixing  and
       matching  the  available  options.   See the section entitled HINTS FOR
       GOOD IMAGE DISPLAYS for some ideas.

RESOURCE CLASS

       xli uses the resource class name _XSETROOT_Id for window managers which
       need this resource set.

GLOBAL OPTIONS

       The  following options affect the global operation of xli.  They may be
       specified anywhere on the command line.

       -default
              Set the root background to the default root weave.  This is  the
              same as xsetroot with no arguments.

       -debug Talk  to  the  X server in synchronous mode.  This is useful for
              debugging.  If an X error is seen while in  this  mode,  a  core
              will be dumped.

       -dumpcore
              Signals will not be trapped, and instead a coredump will occur.

       -display display_name
              X11 display name to send the image(s) to.

       -dispgamma Display_gamma
              Specify  the  gamma correction value appropriate for the display
              device.  This overrides the  value  read  from  the  environment
              variable  DISPLAY_GAMMA,  or  the default value of 2.2, which is
              approximately correct for many displays. A value of between  1.6
              and  2.8  is  reasonable. If individual images are too bright or
              dark, use the -gamma option.

       There is an image provided with xli called 'chkgamma.jpg' that lets you
       set  the  display  gamma reasonably accurately.  This file contains two
       grayscale ramps. The ramps are chosen to look linear to the human  eye,
       one  using  continuous  tones, and the other using dithering.  When the
       display gamma is correct, then the two ramps should  look  symmetrical,
       and  the  point  at  which  they  look  equally bright should be almost
       exactly half way from the top to the bottom. (To  find  this  point  it
       helps if you move away a little from the screen, and de-focus your eyes
       a bit.)

       If the equal brightness point is above center increase the  gamma,  and
       decrease it if it is below the center. The value will usually be around
       2.2 Once you've got it right, you can set the DISPLAY_GAMMA environment
       variable in your .profile

       -fillscreen
              Use  the whole screen for displaying an image. The image will be
              zoomed so that it just fits the size of the screen.  If  -onroot
              is  also  specified,  it  will  be zoomed to completely fill the
              screen.

       -fit   Force image to use the default visual  and  colormap.   This  is
              useful  if you do not want technicolor effects when the colormap
              focus is inside the image window, but it may reduce the  quality
              of  the  displayed  image.   This is on by default if -onroot or
              -windowid is specified.

       -forall
              Apply -fillscreen and -fullscreen options to all images and  not
              just the first.

       -fork  Fork  xli.   This  causes  xli  to  disassociate itself from the
              shell.  This option automatically turns on -quiet.

       -fullscreen
              Use the whole screen for displaying an image. The image will  be
              surrounded  by  a  border  if  it is smaller than the screen. If
              -onroot is also specified, the image will be zoomed so  that  it
              just fits the size of the screen.

       -geometry WxH[{+-X}{+-}Y]
              This  sets  the  size  of  the  window onto which the images are
              loaded to a different value than the size of  the  image.   When
              viewing  an  image in a window, this can be used to set the size
              and position  of  the  viewing  window.   If  the  size  is  not
              specified  in the geometry, (or is set to 0), then the size will
              be chosen to be small enough to able to fit the  window  in  the
              screen (as usual).

       -goto image_name
              When  the  end  of  the  list  of images is reached, go to image
              image_name.  This is useful for  generating  looped  slideshows.
              If  more than one image of the same name as the target exists on
              the argument list, the first in the argument list is used.

       -help [option ...]
              Give information on an option or list of options.  If no  option
              is given, a simple interactive help facility is invoked.

       -identify
              Identify the supplied images rather than display them.

       -install
              Forcibly install the images colormap when the window is focused.
              This violates ICCCM standards and only exists to allow operation
              with naive window managers.  Use this option only if your window
              manager does not install colormaps properly.

       -list  List the images which are along the image path.

       -onroot
              Load image(s) onto the root  window  instead  of  viewing  in  a
              window.   This  option automatically sets the -fit option.  This
              is  the  opposite  of  -view.   If  used  in  conjunction   with
              -fullscreen,  the image will be zoomed to just fit. If used with
              -fillscreen, the image will be zoomed  to  completely  fill  the
              screen. -border, -at, and -center also affect the results.

       -path  Displays  the  image  path and image suffixes which will be used
              when looking for images.  These are  loaded  from  ~/.xlirc  and
              optionally from a system wide file (normally /usr/lib/xlirc).

       -pixmap
              Force  the  use  of a pixmap as backing-store.  This is provided
              for servers where backing-store is broken (such as some versions
              of the AIXWindows server).  It may improve scrolling performance
              on servers which provide backing-store.

       -private
              Force the use  of  a  private  colormap.   Normally  colors  are
              allocated shared unless there are not enough colors available.

       -quiet Forces xli and xview to be quiet.

       -supported
              List the supported image types.

       -verbose
              Causes  xli to be talkative, telling you what kind of image it's
              playing with and any special processing that it has to do.  This
              is the default for xview and xli.

       -version
              Print the version number and patchlevel of this version of xli.

       -view  View  image(s) in a window.  This is the opposite of -onroot and
              the default for xview and xli.

       -visual visual_name
              Force the use of a specific visual type  to  display  an  image.
              Normally  xli  tries  to  pick  the  best  available image for a
              particular  image  type.   The  available  visual   types   are:
              DirectColor, TrueColor, PseudoColor, StaticColor, GrayScale, and
              StaticGray.  Nonconflicting names may be abbreviated and case is
              ignored.

       -windowid hex_window_id
              Sets  the  background  pixmap  of  a  particular window ID.  The
              argument must be in hexadecimal and must be preceded by "0x" (eg
              -windowid 0x40000b.  This is intended for setting the background
              pixmap of some servers which  use  untagged  virtual  roots  (eg
              HP-VUE), but can have other interesting applications.

PERSISTENT IMAGE OPTIONS

       The  following  options  may precede each image.  They take effect from
       the  next  image,  and  continue  until  overridden  or  canceled  with
       -newoptions.

       -border color
              This  sets the background portion of the window or clipped image
              which is not covered by any images to be color.

       -brighten percentage
              Specify a percentage multiplier for a color images colormap.   A
              value  of more than 100 will brighten an image, one of less than
              100 will darken it.

       -colors n
              Specify the maximum number of colors to use in the image.   This
              is a way to forcibly reduce the depth of an image.

       -cdither

       -colordither
              Dither  the image with a Floyd-Steinberg dither if the number of
              colors is reduced.  This will be slow, but will  give  a  better
              looking  result  with  a  restricted  color  set.  -cdither  and
              -colordither are equivalent.

       -delay secs
              Sets xli to automatically advance to the following  image,  secs
              seconds after the next image file is displayed.

       -dither
              Dither  a  color  image  to  monochrome  using a Floyd-Steinberg
              dithering algorithm.  This happens by default when viewing color
              images  on  a monochrome display.  This is slower than -halftone
              and affects the image accuracy but usually looks much better.

       -gamma Image_gamma
              Specify the gamma of the display the image was  intended  to  be
              displayed  on.   Images  seem  to come in two flavors: 1) linear
              color images, produced by ray tracers, scanners etc. These  sort
              of  images  generally look too dark when displayed directly to a
              CRT display. 2) Images that have been processed to look right on
              a  typical  CRT  display  without  any sort of processing. These
              images have been 'gamma corrected'. By default, xli assumes that
              8  bit  images  have  been  gamma  corrected  and  need no other
              processing. 24 bit images are assumed to be linear.  If a linear
              image  is displayed as if it is gamma corrected it will look too
              dark, and a gamma value of 1.0 should be specified, so that  xli
              can  correct  the  image  for the CRT display device. If a gamma
              corrected image is displayed as if it were a linear image,  then
              it will look too light, and a gamma value of (approximately) 2.2
              should be specified for that image.  Some  formats  (RLE)  allow
              the  image gamma to be embedded as a comment in the file itself,
              and the -gamma option allows overriding of the file comment.  In
              general,  values  smaller  than  2.2 will lighten the image, and
              values greater than 2.2 will darken the image.  In general  this
              will work better than the -brighten option.

       -gray  Convert  an  image  to  grayscale.   This  is  very  useful when
              displaying  colorful  images  on  servers  with  limited   color
              capability.  The optional spelling -grey may also be used.

       -idelay secs
              Set  the  delay  to  be used for this image to secs seconds (see
              -delay).  If -delay was specified, this overrides it.  If it was
              not  specified,  this  sets the automatic advance delay for this
              image while others will wait for the user to advance them.

       -smooth
              Smooth a color image.  This reduces blockiness after zooming  an
              image up.  If used on a monochrome image, nothing happens.  This
              option can take awhile to perform, especially on  large  images.
              You  may specify more than one -smooth option per image, causing
              multiple iterations of the smoothing algorithm.

       -title window_title
              Set the titlebar of the window used to display the image.   This
              will  override  any  title that is read from the image file. The
              title will also be used for the icon name.

       -xpm color_context_key
              Select the preferred xpm colour map. XPM files may contain  more
              than  one  color  mapping,  each mapping being appropriate for a
              particular visual.  Normally  xli  will  select  an  appropriate
              color mapping from that supported by the XPM file by checking on
              the default X visual class and depth.  This  option  allows  the
              user    to    override    this    choice.    Legal   values   of
              color_context_key are: m, g4, g and c.  m = mono, g4 =  4  level
              gray, g = gray, c = color ).

       -xzoom percentage
              Zoom  the  X  axis  of an image by percentage.  A number greater
              than 100 will expand the image, one smaller will compress it.  A
              zero value will be ignored.  This option, and the related -yzoom
              are useful for correcting the  aspect  ratio  of  images  to  be
              displayed.

       -yzoom percentage
              Zoom  the Y axis of an image by percentage.  See -xzoom for more
              information.

       -zoom percentage
              Zoom both the X and Y axes by percentage.  See -xzoom  for  more
              information.   Technically the percentage actually zoomed is the
              square of the number supplied since the zoom is  to  both  axes,
              but I opted for consistency instead of accuracy.

       -zoom auto
              Zoom large images to fit the screen; don't zoom small images.

       -newoptions
              Reset   options   that   propagate.    The   -bright,   -colors,
              -colordither,  -delay,  -dither,  -gamma,   -gray,   -normalize,
              -smooth, -xzoom, -yzoom, and -zoom options normally propagate to
              all following images.

LOCAL IMAGE OPTIONS

       The following options may precede each image.  These options are  local
       to the image they precede.

       -at X,Y
              Indicates  coordinates  to  load  the  image  at X,Y on the base
              image.  If this is an option to the first image, and the -onroot
              option  is  specified,  the  image  will  be loaded at the given
              location on the display background.

       -background color
              Use color  as  the  background  color  instead  of  the  default
              (usually  white  but  this depends on the image type) if you are
              transferring a monochrome image to a color display.

       -center
              Center the image on the base image loaded.  If this is an option
              to  the  first  image,  and the -onroot option is specified, the
              image will be centered on the display background.

       -clip X,Y,W,H
              Clip the image before loading it.  X and Y define the upper-left
              corner  of  the clip area, and W and H define the extents of the
              area.  A zero value for W  or  H  will  be  interpreted  as  the
              remainder  of the image.  Note that X and Y may be negative, and
              that W and H may be larger than the image. This causes a  border
              to  be placed around the image. The border color may be set with
              the -border option.

       -expand
              Forces the image (after all other  optional  processing)  to  be
              expanded  into  a  True  Color (24 bit) image. This is useful on
              systems which support 24 bit color, but where xli  might  choose
              to  load  a  bitmap or 8 bit image into one of the other smaller
              depth visuals supported on your system.

       -foreground color
              Use color as the foreground color instead of black  if  you  are
              transferring  a  monochrome  image to a color display.  This can
              also be used to invert the foreground and background colors of a
              monochrome image.

       -halftone
              Force  halftone  dithering of a color image when displaying on a
              monochrome  display.   This  option  is  ignored  on  monochrome
              images.   This  dithering algorithm blows an image up by sixteen
              times; if you don't like this, the -dither option will not  blow
              the  image  up  but will take longer to process and will be less
              accurate.

       -invert
              Inverts a monochrome image.  This is shorthand  for  -foreground
              white -background black.

       -merge Merge  this  image  onto  the base image after local processing.
              The base image is considered to be the first image specified  or
              the  last  image  that  was  not preceded by -merge.  If used in
              conjunction with -at and -clip, very complex images can be built
              up.   Note  that  the  final image will be the size of the first
              image,  and  that  subsequent  merged  images  overlay  previous
              images.  The  final image size can be altered by using the -clip
              option on the base image to make it  bigger  or  smaller.   This
              option  is  on  by  default  for  all  images  if the -onroot or
              -windowid options are specified.

       -name image_name
              Force the next argument to be treated as an image name.  This is
              useful if the name of the image is -dither, for instance.

       -normalize
              Normalize a color image.

       -rotate degrees
              Rotate  the  image  by  degrees clockwise.  The number must be a
              multiple of 90.

EXAMPLES

       To load the rasterfile "my.image" onto the background and replicate  it
       to fill the entire background:

            xli -onroot my.image

       To load a monochrome image "my.image" onto the background, using red as
       the foreground color, replicate the image, and overlay  "another.image"
       onto it at coordinate (10,10):

            xli -foreground red my.image -at 10,10 another.image

       To  center  the  rectangular region from 10 to 110 along the X axis and
       from 10 to the height of the image along the Y axis:

            xli -center -clip 10,10,100,0 my.image

       To double the size of an image:

            xli -zoom 200 my.image

       To halve the size of an image:

            xli -zoom 50 my.image

       To brighten a dark image:

            xli -brighten 150 my.image

       To darken a bright image:

            xli -brighten 50 my.image

HINTS FOR GOOD IMAGE DISPLAYS

       Since images are likely to come from a variety of sources, they may  be
       in  a  variety  of  aspect  ratios  which  may not be supported by your
       display.  The -xzoom and -yzoom options  can  be  used  to  change  the
       aspect  ratio of an image before display.  If you use these options, it
       is recommended that you increase the size  of  one  of  the  dimensions
       instead  of  shrinking  the  other, since shrinking looses detail.  For
       instance, many GIF and G3 FAX images have an X:Y ratio  of  about  2:1.
       You can correct this for viewing on a 1:1 display with either -xzoom 50
       or -yzoom 200 (reduce X axis to 50% of its size and expand  Y  axis  to
       200%  of  its  size,  respectively) but the latter should be used so no
       detail is lost in the conversion.

       When zooming color images up you can reduce  blockiness  with  -smooth.
       For  zooms  of 300% or more, I recommend two smoothing passes (although
       this can take awhile  to  do  on  slow  machines).   There  will  be  a
       noticeable improvement in the image.

       You  can  perform  image  processing  on a small portion of an image by
       loading the image more than once and using the -merge,  -at  and  -clip
       options.   Load  the  image,  then  merge  it with a clipped, processed
       version of itself.  To brighten a 100x100  rectangular  portion  of  an
       image located at (50,50), for instance, you could type:

            xli  my.image  -merge  -at 50,50 -clip 50,50,100,100 -brighten 150
       my.image

       If you're using a display with a small  colormap  to  display  colorful
       images, try using the -gray option to convert to grayscale.

XLITO

       xlito (XLoadImageTrailingOptions) is a separate utility that provides a
       file format independent way of marking image files with the appropriate
       options  to  display  correctly.   It  does this by appending to file a
       string specified by the user, marked with some magic  numbers  so  that
       this  string  can  be  extracted by a program that knows where to look.
       Since almost all image files have some sort of  image  size  specifier,
       the programs that load or manipulate these files do not look beyond the
       point at which they have read the image, so  trailing  information  can
       safely  be  appended  to the file. If appending this information causes
       trouble with other utilities, it can simply be deleted.

       xli will recognize these trailing options  at  the  end  of  the  image
       files,  and  will treat the embedded string as if it were a sequence of
       command line IMAGE OPTIONS. Any GLOBAL OPTIONS will be ignored, and the
       IMAGE OPTIONS are never propagated to other images.

       Trailing options can be examined with:

            xlito image_file ...

       Changed or added with:

            xlito -c "string of options" image_file

       And deleted with:

            xlito -d image_file ...

       For  example,  if you have a gif file fred.gif which is too dark and is
       the wrong aspect ratio, then it may need to be viewed with:

            xli -yzoom 130 -gamma 1.0 fred.gif

       to get it to look OK. These options can then be appended  to  the  file
       by:

            xlito -c "-yzoom 130 -gamma 1.0" fred.gif

       and  from  then  on xli will get the appropriate options from the image
       file itself.  See the  xlito manual entry for more details  about  this
       utility.

PATHS AND EXTENSIONS

       The  file ~/.xlirc (and optionally a system-wide file) defines the path
       and default extensions that xli will use when looking for images.  This
       file  can  have  two  statements:  "path=" and "extension=" (the equals
       signs must  follow  the  word  with  no  spaces  between).   Everything
       following  the  "path=" keyword will be prepended to the supplied image
       name if the supplied name does not specify an existing file.  The paths
       will be searched in the order they are specified.  Everything following
       the "extension=" keyword will be appended to the supplied image name if
       the  supplied  name  does not specify an existing file.  As with paths,
       these extensions  will  be  searched  in  the  order  they  are  given.
       Comments are any portion of a line following a hash-mark (#).

       The following is a sample ~/.xlirc file:

         # paths to look for images in
         path= /usr/local/images
               /home/usr1/guest/madd/images
               /usr/include/X11/bitmaps

         # default extensions for images; .Z is automatic; scanned in order
         extension= .csun .msun .sun .face .xbm .bm

       Versions  of  xli  prior  to  version  01, patchlevel 03 would load the
       system-wide file (if any), followed by the user's file.  This  behavior
       made  it  difficult  for  the  user to configure her environment if she
       didn't want the default.  Newer versions will  ignore  the  system-wide
       file if a personal configuration file exists.

IMAGE TYPES

       xli currently supports the following image types:

         CMU Window Manager raster files
         Faces Project images
         Fuzzy Bitmap (.fbm) images
         GEM bit images
         GIF images (Including GIF89a compatibility)
         G3 FAX images
         JFIF style jpeg images
         McIDAS areafiles
         MacPaint images
         Windows, OS/2 RLE Image
         Monochrome PC Paintbrush (.pcx) images
         Photograph on CD Image
         Portable Bitmap (.pbm, .pgm, .ppm) images
         Sun monochrome rasterfiles
         Sun color RGB rasterfiles
         Targa (.tga) files
         Utah Raster Toolkit (.rle) files
         X pixmap (.xpm) files (Version 1, 2C and 3)
         X10 bitmap files
         X11 bitmap files
         X Window Dump (except TrueColor and DirectColor)

       Normal,  compact,  and raw PBM images are supported.  Both standard and
       run-length encoded Sun rasterfiles are supported.  Any image whose name
       ends  in  .Z  is  assumed to be a compressed image and will be filtered
       through "uncompress". If HAVE_GUNZIP is  defined  in  the  Makefile.std
       make file, then any image whose name ends in .gz or .Z will be filtered
       through gunzip.

       Any  file  that  looks  like  a  uuencoded   file   will   be   decoded
       automatically.

AUTHORS

       The original Author is:
       Jim Frost
       Saber Software
       jimf@saber.com

       Version 1.16 of xli is derived from xloadimage 3.01 has been brought to
       you by:
       Graeme Gill
       graeme@labtam.oz.au

       Version 1.17 of xli is derived from xli 1.16 by
       smar@reptiles.org

       For a more-or-less complete list of other contributors (there are a lot
       of them), please see the README file enclosed with the distribution.

FILES

            xli                      - the image loader and viewer
            xlito                   - the trailing options utility
            /usr/lib/X11/Xli        - default system-wide configuration file
            ~/.xlirc                - user's personal configuration file

COPYRIGHT

       Copyright  (c)  1989, 1990, 1991, 1992, 1993 Jim Frost, Graeme Gill and
       others.

       Xli  is  copyrighted  material  with  a  very  loose  license  allowing
       unlimited  modification  and  distribution if the copyright notices are
       left intact.  Various portions are copyrighted by various  people,  but
       all  use  a modification of the MIT copyright notice.  Please check the
       source for complete copyright information.  The intent is to  keep  the
       source  free,  not to stifle its distribution, so please write to me if
       you have any questions.

BUGS

       Zooming dithered images, especially downwards, is UGLY.

       Images can come in a variety of aspect ratios.  Xli cannot detect  what
       aspect  ratio  the  particular  image  being loaded has, nor the aspect
       ratio of the destination  display,  so  images  with  differing  aspect
       ratios  from  the  destination  display  will  appear  distorted.   The
       solution to this is to use xlito to append the appropriate  options  to
       the  image  file.  See HINTS FOR GOOD IMAGE DISPLAYS and XLITO for more
       information.

       The GIF format allows more than one image to be stored in a single  GIF
       file, but xli will only display the first.

       One  of the pseudonyms for xli, xview, is the same name as Sun uses for
       their SunView-under-X package.  This will be confusing if you're one of
       those poor souls who has to use Sun's XView.

       Some  window managers do not correctly handle window size requests.  In
       particular, many versions of the twm window  manager  use  the  MaxSize
       hint  instead  of  the PSize hint, causing images which are larger than
       the screen to display in a window larger  than  the  screen,  something
       which  is  normally  avoided.   Some  versions  of  twm also ignore the
       MaxSize argument's real function, to limit  the  maximum  size  of  the
       window,  and  allow the window to be resized larger than the image.  If
       this happens, xli merely places the image in the upper-left  corner  of
       the  window and uses the zero-value'ed pixel for any space which is not
       covered by the image.  This behavior is less-than-graceful but  so  are
       window managers which are cruel enough to ignore such details.

       The  order in which operations are performed on an image is independent
       of the order  in  which  they  were  specified  on  the  command  line.
       Wherever  possible I tried to order operations in such a way as to look
       the best possible  (zooming  before  dithering,  for  instance)  or  to
       increase speed (zooming downward before compressing, for instance).

       Display Gamma should setable in the ~/.xlirc file.

       Embedded  trailing  options  override  the  command line Image Options.
       Command line options should really override trailing options.

                                  28 Oct 2002                           XLI(1)