Provided by: xloadimage_4.1-25_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)