From CleanPosts

Jump to: navigation, search

XLI(1) General Commands Manual XLI(1)


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


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


      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 destina‐
      tion) 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, bright‐
      ening, 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


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


      The following options affect the global operation of xli.  They may be  specified  any‐
      where on the command line.
             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.
             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 symmetri‐
      cal,  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
             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.
             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.
             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 sim‐
             ple interactive help facility is invoked.
             Identify the supplied images rather than display them.
             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.
             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).
             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.
             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.
             List the supported image types.
             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
             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.


      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.
             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 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
      -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 dis‐
             played 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 auto‐
             matic advance delay for this image while  others  will  wait  for  the  user  to
             advance them.
             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.
             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.


      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
             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.
             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 fore‐
             ground and background colors of a monochrome image.
             Force halftone dithering of a color image when displaying on a  monochrome  dis‐
             play.   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
             Inverts a monochrome image.  This is shorthand for -foreground white -background
      -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  pre‐
             ceded 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 -win‐
             dowid 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 a color image.
      -rotate degrees
             Rotate the image by degrees clockwise.  The number must be a multiple of 90.


      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


      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 por‐
      tion 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 (XLoadImageTrailingOptions) is a separate utility that  provides  a  file  format
      independent  way  of  marking  image files with the appropriate options to display cor‐
      rectly.  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  pro‐
      grams  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
      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.


      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 state‐
      ments: "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=" key‐
      word 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
        # 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.


      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.


      The original Author is:
      Jim Frost
      Saber Software
      Version 1.16 of xli is derived from xloadimage 3.01 has been brought to you by:
      Graeme Gill
      Version 1.17 of xli is derived from xli 1.16 by
      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.


           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 (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 copy‐
      righted 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


      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  Sun‐
      View-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 Max‐
      Size 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)
Personal tools
Strangers In Paradise