Provided by: xloadimage_4.1-25build1_amd64 bug

NAME

       xloadimage, xsetbg, xview - load images into an X11 window or onto the root window

SYNOPSIS

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

DESCRIPTION

       Xloadimage  displays  images  in an X11 window, loads them onto the root window, or writes
       them into a file.  Many image types are recognized; use  the  -supported  option  to  list
       them.

       If the filename stdin is given, xloadimage will read the image from standard input if this
       capability is supported by the loader for that image type (most types do  support  reading
       from stdin).

       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 option.  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.  You may exit the window by typing 'q' or  '^C'  when  the  keyboard
       focus is on the window.

       If  more than one image file is specified on the command line, each image will be shown in
       order (except if -merge or -goto are being used).

       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.

       The  -dump  option  causes  an  image  to be written to a file rather than displayed after
       processing.  This allows you to read an image, perform a number of  processing  operations
       on  it,  and  save  the  resultant  image.   This  also allows translation from any of the
       recognized image types into any of the formats that support dumping.

       Xsetbg is equivalent to xloadimage -onroot -quiet and xview is  equivalent  to  xloadimage
       -view -verbose.

RESOURCE CLASS

       Xloadimage  uses  the  resource  class name Xloadimage for window managers which need this
       resource set.  This name changed in version 2.00 and 2.01; some previous versions used the
       name  XLoadImage  (which  was  difficult  to predict) or xloadimage (which conflicted with
       class naming conventions).

GLOBAL OPTIONS

       The following options affect the global operation of xloadimage.  They  may  be  specified
       anywhere  on  the  command  line.  Additionally the -global option can be used to force an
       image option to apply to all images.

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

       -configuration
               Displays  the image path, image suffixes, and supported filters which will be used
               when looking for and reading images.  These are loaded  from  ~/.xloadimagerc  and
               optionally from a systemwide file (normally /usr/lib/xloadimagerc).  This replaces
               the -path option.

       -default
               Use the default root weave as the image.  This option forces -onroot.  If -default
               is  used  alone,  it  is  the  same  as  xsetroot  with  no arguments.  If used in
               conjunction with -tile this option can be used to place images on the default root
               weave (see EXAMPLES below).

       -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.

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

       -dump image_type[,option[=value]] dump_file
               Rather than displaying the loaded and processed image, dump it into an image  file
               of  the  specified  type.   For  a list of image types that can be dumped, use the
               -supported option.  Some image types have options that affect the  format  of  the
               file  that's  created.   See  DUMP  OPTIONS  below.  An image can be dumped in any
               supported dump format regardless of the original image type, so  image  file  type
               translation is possible using this option.

       -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.

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

       -fullscreen
               Use the entire screen to display images.  If combined with -onroot, the image will
               be zoomed to fill the entire rootwindow.

       -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 reduce the size of the destination window.  When loading an image onto the
               root window, this option controls the size of the pixmap which will be loaded onto
               the root.  If the size is smaller than that of the  display,  the  image  will  be
               replicated.

       -goto image_name
               Forces  the  next image to be displayed to be the image named 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 image's 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.  XSetbg has
               this option set by default.

       -path   Displays miscellaneous information about the program configuration.   This  option
               is obsolete and has been replaced by -configuration.

       -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 xloadimage and xview to be quiet.  This is the default for xsetbg, but  the
               others like to whistle.

       -supported
               List the supported image types.

       -type type_name
               Forces  xloadimage  to try to load the image as a particular file type rather than
               trying to guess.  This often improves load performance noticeably.

       -verbose
               Causes xloadimage 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 xloadimage.

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

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

       -visual visual_name
               Force  the use of a specific visual type to display an image.  Normally xloadimage
               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.

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 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.

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

       -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.

       -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.

       -delay secs
              Automatically advance to the next image after secs seconds.  You may  want  to  use
              the -global switch with this command to create a slideshow with multiple images.

       -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.

       -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.

       -gamma display_gamma
              Specify  the gamma correction for the display.  The default value is 1.0, a typical
              display needs 2.0 to 2.5.

       -global
              Force the following option to apply to all images rather than one  specific  image.
              Local image options will temporarily override any option specified with -global.

       -gray  Convert an image to grayscale.  This is very useful when displaying colorful images
              on servers with limited color capability.  It can also be used to convert a  bitmap
              image into a grayscale image, although the resulting image will be smaller than the
              original.  The optional spelling -grey may also be used.

       -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.

       -idelay secs
              This  option  is  no  longer  supported  due  to the addition of -global.  The same
              functionality can be had with -delay.

       -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.  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.

       -newoptions
              Reset globally-specified options.

       -normalize
              Normalize a color image.

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

       -shrink
              Shrink an image down to fit on the  display.   This  is  particularly  useful  with
              servers  that  do  not  support  window  sizes  larger than the physical screen (eg
              DECWINDOWS servers).

       -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.

       -tile  Tile  this  image  (after  any  necessary merging or tiling) to create a fullscreen
              image.  This is usually used to create a large background image on which  to  merge
              other  images.   -geometry can be used to set the new image size to something other
              than -fullscreen.

       -title title
              Change the title of the image.  This sets the title bar title if  displaying  in  a
              window or the NIFF file image title if dumping the image.

       -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.

EXAMPLES

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

            xloadimage -onroot my.image

       To center an image on the default root background:

            xloadimage -default -tile my.image

       If using a monochrome display and a color image you will probably want to dither the image
       for a cleaner (and faster) display:

            xloadimage -default -tile -dither 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):

            xloadimage -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:

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

       To double the size of an image:

            xloadimage -zoom 200 my.image

       To halve the size of an image:

            xloadimage -zoom 50 my.image

       To brighten a dark image:

            xloadimage -brighten 150 my.image

       To darken a bright image:

            xloadimage -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:

            xloadimage 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.

PATHS AND EXTENSIONS

       The file  ~/.xloadimagerc  (and  optionally  a  system-wide  file)  defines  a  number  of
       configuration options that affect xloadimage.

       This  file  is  split into three section, the path section, the extension section, and the
       filter section.  The sections are identified by typing the section  name  followed  by  an
       equals sign, eg "path =".

       The  path  statement  is  used to provide a set of search paths to use when looking for an
       image of a specified name.  Separate each path in the list by whitespace (eg one  or  more
       spaces,  tabs,  or  newlines).   The  path  is searched in the order it is specified.  For
       example:

         path = ~/images /usr/local/images ~fred

       will first look for the image name you specified, then look for the name in ~/images  (the
       tilde  is  expanded to the value of $HOME), then in /usr/local/images, then in user fred's
       home directory.  This allows easy use of image repositories.

       The extension statement is used to provide a set of default extensions to use when looking
       for an image of a specified name.  Separate each extension in the list by whitespace.  The
       extensions are searched in the order in which they are specified.  For example:

         extension = .gif .jpg

       If you have a file named myimage.gif you could specify the  name  myimage  and  xloadimage
       would append the .gif extension automatically.

       The  filter statement is used to describe filter programs, such as "uncompress", which are
       to be applied to image files automatically.  You specify one filter program and any number
       of recognized extensions following the filter keyword.  For example:

         filter = uncompress .Z

       specifies  that  the  program uncompress should be used as a filter whenever an image file
       has a .Z extension.  By default filters are provided for compressed (.Z) files and GNU zip
       (.gz) files.  See the FILTERS section for more information on defining your own filters.

       Any text on a line following a hash‐mark (#) is ignored; if you wish to use a hash‐mark in
       a path, extension, or filter you can escape it using a backslash (\).

       If you wish to include white-space in a filter program name, path, or  extension  you  can
       enclose the entire text in double‐quotes.  For example:

         filter = "gzip -cd" .gz

       Use backslash (\) characters to allow inclusion of double‐quote marks or newlines.

       The following is a sample ~/.xloadimagerc file:

         # paths to look for images in
         path = /usr/local/images        # system image repository
               ~/images                 # personal images
               /usr/include/X11/bitmaps # standard X bitmaps

         # default extensions for images
         extension = .csun .msun .sun .face .xbm .bm

         # invoke GNU zip if a .z or .zip extension is found
         filter = "gzip -cd" .z .zip

IMAGE TYPES

       Xloadimage  currently  supports  many common and some uncommon image types, and can create
       images in several formats.  For a complete list use the -supported option.

DUMPING IMAGES

       Several image dumpers are included that can be used to create a new  image  after  loading
       and  processing.   The  NIFF (Native Image File Format) is the simplest and creates images
       that xloadimage can read the fastest; it is essentially  a  copy  of  the  internal  image
       format.

       Some image dumpers allow options that affect the image output.  These options are appended
       to the image type following a comma and are separated by commas.  If a value is desired it
       can be specified following an equals‐sign.  For example, to create a monochrome JPEG image
       file with a quality factor of 80, you would use the following command line:

         xloadimage image_name -dump jpeg,quality=80,grayscale new_image.jpg

       Option names can be abbreviated but if the abbreviation is too  short  to  be  unique  the
       option which will be used is indeterminate.

FILTERS

       Xloadimage  supports  automatic  filtering  by  recognizing  file  extensions.  By default
       "compress" and "gzip" files are recognized and their names passed to appropriate  commands
       to decompress them.

       The xloadimage distribution includes a special "smart" uudecoder, called uufilter that can
       be used to automatically uudecode files for processing.  Uufilter ignores extraneous lines
       in  the  file  so  it  is  particularly  useful  if  the  uuencoded  file  was  created by
       concatenating email or news postings that had headers or line‐break indicators included.

       To make use of uufilter you can add the following to your .xloadimagerc file:

         filter = "uufilter -s" .uu .uue
       The filter will be automatically invoked on any file with a .uu or .uue extension.

       For a list of filters  automatically  recognized  by  xloadimage  use  the  -configuration
       option.

SUPPORTED IMAGE OPTIONS

       The JPEG image dumper supports the following options:

       arithmetic
               Use arithmetic encoding.

       grayscale
               Force a monochrome (grayscale) image to be created given a color image.

       nointerleave
               Create a non‐interleaved file.

       optimize
               Enable entropy parameter optimization.

       quality Adjust  the quality of the image to be created.  The default quality factor is 75;
               lower values create poorer images.

       restart interval
               Set the restart interval in MCU rows, or MCUs if 'b' follows the interval value.

       smooth smoothing_factor
               Set the smoothing factor.  Value should be between 0 and 100, inclusive.

       If you are not familiar with the meaning of these options you can ask the Independent JPEG
       Group (IJG) via email at jpeg@cs.columbia.edu.

       The PBM image dumper supports the following options:

       normal  Dump a normal (ascii) PBM/PPM file.

       raw     Dump  a  RawBits  format  PBM/PPM  file.   This  is  the  default  and  results in
               significantly smaller image files than when using normal.

       There is no way to dump a PGM format file or a "compact" PBM format file (sorry).

       The TIFF image dumper supports the following options:

       compression
               Image data compression technique.  Can be  one  of:  none  (no  compression),  rle
               (CCITT RLE compression), g3fax (CCITT Group 3 FAX compression), g4fax (CCITT Group
               4 FAX compression), lzw (Limpel‐Ziv‐Welsh compression, the  default),  jpeg  (JPEG
               compression),  next  (NeXT run‐length compression), rlew (CCITT RLEW compression),
               mac  (Macintosh  PackBits  compression),  packbits  (same  as  mac),   thunderscan
               (ThunderScan compression).

       Xloadimage  will  save  using the MINISBLACK, MINISWHITE, COLORMAP, or RGB photometrics as
       appropriate for its internal image format.  There  is  no  way  to  specify  a  particular
       photometric or any other TIFF fields.

AUTHOR

       Jim Frost
       CenterLine Software
       jimf@centerline.com

       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

            xloadimage              - the image loader and viewer
            xsetbg                  - pseudonym which quietly sets the background
            xview                   - pseudonym which views in a window
            /etc/X11/Xloadimage     - default system-wide configuration file
            ~/.xloadimagerc         - user's personal configuration file

COPYRIGHT

       Copyright (c) 1989, 1993 Jim Frost and others.

       Xloadimage is  copyrighted  material  with  a  very  loose  copyright  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.  Xloadimage 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.
       See HINTS FOR GOOD IMAGE DISPLAYS for more information.

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

       Only GIF87a format is supported.

       One  of  the  pseudonyms  for  xloadimage,  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, xloadimage 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.

                                            8 May 1991                             XLOADIMAGE(1x)