XLOADIMAGE(1x)                                                    XLOADIMAGE(1x)

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

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

       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.

       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

       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.

               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

               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.

               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 the supplied images rather than display them.

               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

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

               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.

               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.

               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.

               Print the version number and patchlevel of this version of

       -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

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

              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.

              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.

              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.

              Reset globally-specified options.

              Normalize a color image.

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

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

       -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

       -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

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

       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

       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

       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.

       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

       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

       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.

       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.

       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

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

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

       The JPEG image dumper supports the following options:

               Use arithmetic encoding.

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

               Create a non-interleaved file.

               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,

       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

       There is no way to dump a PGM format file or a "compact" PBM format file

       The TIFF image dumper supports the following options:

               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.

       Jim Frost
       CenterLine Software

       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.

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

       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)