1XLOADIMAGE(1x)                                                  XLOADIMAGE(1x)
2
3
4

NAME

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

SYNOPSIS

10       xloadimage [global_options] {[image_options] image ...}
11       xloadimage [global_options] [image_options] stdin < image
12

DESCRIPTION

14       Xloadimage displays images in an X11 window, loads them onto  the  root
15       window,  or  writes them into a file.  Many image types are recognized;
16       use the -supported option to list them.
17
18       If the filename stdin is given, xloadimage will  read  the  image  from
19       standard  input  if this capability is supported by the loader for that
20       image type (most types do support reading from stdin).
21
22       If the destination display cannot support the number of colors  in  the
23       image,  the image will be dithered (monochrome destination) or have its
24       colormap reduced (color destination) as appropriate.  This can also  be
25       done forcibly with the -halftone, -dither, and -colors options.
26
27       A variety of image manipulations can be specified, including gamma cor‐
28       rection, brightening, clipping, dithering,  depth-reduction,  rotation,
29       and  zooming.  Most of these manipulations have simple implementations;
30       speed was opted for above accuracy.
31
32       If you are viewing a large image in a window, the initial  window  will
33       be  at  most  90%  of the size of the display unless the window manager
34       does not correctly handle window size requests or if  you've  used  the
35       -fullscreen  option.   You  may  move the image around in the window by
36       dragging with the first mouse button.  The cursor will  indicate  which
37       directions you may drag, if any.  You may exit the window by typing 'q'
38       or '^C' when the keyboard focus is on the window.
39
40       If more than one image file is specified  on  the  command  line,  each
41       image  will  be  shown  in  order  (except if -merge or -goto are being
42       used).
43
44       A wide variety of common image manipulations can be done by mixing  and
45       matching  the  available  options.   See the section entitled HINTS FOR
46       GOOD IMAGE DISPLAYS for some ideas.
47
48       The -dump option causes an image to be written to a  file  rather  than
49       displayed  after processing.  This allows you to read an image, perform
50       a number of processing operations on it, and save the resultant  image.
51       This  also  allows  translation  from any of the recognized image types
52       into any of the formats that support dumping.
53
54       Xsetbg is equivalent to xloadimage -onroot -quiet and xview is  equiva‐
55       lent to xloadimage -view -verbose.
56

RESOURCE CLASS

58       Xloadimage  uses the resource class name Xloadimage for window managers
59       which need this resource set.  This name changed in  version  2.00  and
60       2.01; some previous versions used the name XLoadImage (which was diffi‐
61       cult to predict) or xloadimage (which conflicted with class naming con‐
62       ventions).
63

GLOBAL OPTIONS

65       The  following options affect the global operation of xloadimage.  They
66       may be specified  anywhere  on  the  command  line.   Additionally  the
67       -global  option  can  be  used to force an image option to apply to all
68       images.
69
70       -border color
71               This sets the background portion of the  window  which  is  not
72               covered by any images to be color.
73
74       -configuration
75               Displays  the image path, image suffixes, and supported filters
76               which will be used when looking for and reading images.   These
77               are  loaded  from  ~/.xloadimagerc  and  optionally from a sys‐
78               temwide file (normally /usr/lib/xloadimagerc).   This  replaces
79               the -path option.
80
81       -default
82               Use  the  default  root weave as the image.  This option forces
83               -onroot.  If -default is used alone, it is the same as xsetroot
84               with  no  arguments.   If  used  in conjunction with -tile this
85               option can be used to place images on the  default  root  weave
86               (see EXAMPLES below).
87
88       -debug  Talk  to  the X server in synchronous mode.  This is useful for
89               debugging.  If an X error is seen while in this  mode,  a  core
90               will be dumped.
91
92       -display display_name
93               X11 display name to send the image(s) to.
94
95       -dump image_type[,option[=value]] dump_file
96               Rather  than displaying the loaded and processed image, dump it
97               into an image file of the specified type.  For a list of  image
98               types  that  can  be  dumped,  use the -supported option.  Some
99               image types have options that affect the  format  of  the  file
100               that's  created.   See  DUMP  OPTIONS  below.   An image can be
101               dumped in any supported dump format regardless of the  original
102               image  type,  so  image file type translation is possible using
103               this option.
104
105       -fit    Force image to use the default visual and  colormap.   This  is
106               useful if you do not want technicolor effects when the colormap
107               focus is inside the image window, but it may reduce the quality
108               of  the  displayed  image.  This is on by default if -onroot or
109               -windowid is specified.
110
111       -fork   Fork xloadimage.  This causes xloadimage to disassociate itself
112               from the shell.  This option automatically turns on -quiet.
113
114       -fullscreen
115               Use  the  entire  screen  to  display images.  If combined with
116               -onroot, the image will be zoomed to fill the  entire  rootwin‐
117               dow.
118
119       -geometry WxH[{+-X}{+-}Y]
120               This  sets  the  size  of  the window onto which the images are
121               loaded to a different value than the size of the  image.   When
122               viewing  an  image  in a window, this can be used to reduce the
123               size of the destination window.  When loading an image onto the
124               root  window, this option controls the size of the pixmap which
125               will be loaded onto the root.  If the size is smaller than that
126               of the display, the image will be replicated.
127
128       -goto image_name
129               Forces  the  next  image  to be displayed to be the image named
130               image_name.  This is useful for generating  looped  slideshows.
131               If more than one image of the same name as the target exists on
132               the argument list, the first in the argument list is used.
133
134       -help [option ...]
135               Give information on an option or list of options.  If no option
136               is given, a simple interactive help facility is invoked.
137
138       -identify
139               Identify the supplied images rather than display them.
140
141       -install
142               Forcibly  install  the  image's  colormap  when  the  window is
143               focused.  This violates ICCCM  standards  and  only  exists  to
144               allow  operation  with  naive window managers.  Use this option
145               only if your window manager does not  install  colormaps  prop‐
146               erly.
147
148       -list   List the images which are along the image path.
149
150       -onroot Load image(s) onto the root window instead of viewing in a win‐
151               dow.  This option automatically sets the -fit option.  This  is
152               the opposite of -view.  XSetbg has this option set by default.
153
154       -path   Displays miscellaneous information about the program configura‐
155               tion.  This option is obsolete and has been replaced  by  -con‐
156               figuration.
157
158       -pixmap Force  the  use of a pixmap as backing-store.  This is provided
159               for servers where backing-store is broken (such  as  some  ver‐
160               sions of the AIXWindows server).  It may improve scrolling per‐
161               formance on servers which provide backing-store.
162
163       -private
164               Force the use of a private colormap.  Normally colors are allo‐
165               cated shared unless there are not enough colors available.
166
167       -quiet  Forces  xloadimage  and xview to be quiet.  This is the default
168               for xsetbg, but the others like to whistle.
169
170       -supported
171               List the supported image types.
172
173       -type type_name
174               Forces xloadimage to try to load the image as a particular file
175               type  rather  than  trying  to guess.  This often improves load
176               performance noticeably.
177
178       -verbose
179               Causes xloadimage to be talkative, telling  you  what  kind  of
180               image  it's playing with and any special processing that it has
181               to do.  This is the default for xview and xloadimage.
182
183       -version
184               Print the version number and  patchlevel  of  this  version  of
185               xloadimage.
186
187       -view   View image(s) in a window.  This is the opposite of -onroot and
188               the default for xview and xloadimage.
189
190       -visual visual_name
191               Force the use of a specific visual type to  display  an  image.
192               Normally  xloadimage tries to pick the best available image for
193               a particular image  type.   The  available  visual  types  are:
194               DirectColor,  TrueColor,  PseudoColor,  StaticColor, GrayScale,
195               and StaticGray.  Nonconflicting names may  be  abbreviated  and
196               case is ignored.
197
198       -windowid hex_window_id
199               Sets  the  background  pixmap  of  a particular window ID.  The
200               argument must be in hexadecimal and must be  preceded  by  "0x"
201               (eg -windowid 0x40000b.  This is intended for setting the back‐
202               ground pixmap of some servers which use untagged virtual  roots
203               (eg HP-VUE), but can have other interesting applications.
204

IMAGE OPTIONS

206       The  following options may precede each image.  These options are local
207       to the image they precede.
208
209       -at X,Y
210              Indicates coordinates to load the image at on  the  base  image.
211              If  this is an option to the first image, and the -onroot option
212              is specified, the image will be loaded at the given location  on
213              the display background.
214
215       -background color
216              Use  color  as the background color instead of the default (usu‐
217              ally white but this depends on the image type) if you are trans‐
218              ferring a monochrome image to a color display.
219
220       -brighten percentage
221              Specify a percentage multiplier for a color image's colormap.  A
222              value of more than 100 will brighten an image, one of less  than
223              100 will darken it.
224
225       -center
226              Center the image on the base image loaded.  If this is an option
227              to the first image, and the -onroot  option  is  specified,  the
228              image will be centered on the display background.
229
230       -clip X,Y,W,H
231              Clip the image before loading it.  X and Y define the upper-left
232              corner of the clip area, and W and H define the extents  of  the
233              area.   A  zero  value  for  W  or  H will be interpreted as the
234              remainder of the image.
235
236       -colors n
237              Specify the maximum number of colors to use in the image.   This
238              is a way to forcibly reduce the depth of an image.
239
240       -delay secs
241              Automatically advance to the next image after secs seconds.  You
242              may want to use the -global switch with this command to create a
243              slideshow with multiple images.
244
245       -dither
246              Dither  a  color  image  to  monochrome  using a Floyd-Steinberg
247              dithering algorithm.  This happens by default when viewing color
248              images  on  a monochrome display.  This is slower than -halftone
249              and affects the image accuracy but usually looks much better.
250
251       -foreground color
252              Use color as the foreground color instead of black  if  you  are
253              transferring  a  monochrome  image to a color display.  This can
254              also be used to invert the foreground and background colors of a
255              monochrome image.
256
257       -gamma display_gamma
258              Specify the gamma correction for the display.  The default value
259              is 1.0, a typical display needs 2.0 to 2.5.
260
261       -global
262              Force the following option to apply to all  images  rather  than
263              one  specific image.  Local image options will temporarily over‐
264              ride any option specified with -global.
265
266       -gray  Convert an image to grayscale.  This is very  useful  when  dis‐
267              playing  colorful  images on servers with limited color capabil‐
268              ity.  It can also be used to  convert  a  bitmap  image  into  a
269              grayscale  image,  although  the resulting image will be smaller
270              than the original.  The optional  spelling  -grey  may  also  be
271              used.
272
273       -halftone
274              Force  halftone  dithering of a color image when displaying on a
275              monochrome  display.   This  option  is  ignored  on  monochrome
276              images.   This  dithering algorithm blows an image up by sixteen
277              times; if you don't like this, the -dither option will not  blow
278              the  image  up  but will take longer to process and will be less
279              accurate.
280
281       -idelay secs
282              This option is no  longer  supported  due  to  the  addition  of
283              -global.  The same functionality can be had with -delay.
284
285       -invert
286              Inverts  a  monochrome image.  This is shorthand for -foreground
287              white -background black.
288
289       -merge Merge this image onto the base  image  after  local  processing.
290              The  base image is considered to be the first image specified or
291              the last image that was not preceded by -merge.  If used in con‐
292              junction  with  -at  and -clip, very complex images can be built
293              up.  This option is on by default for all images if the  -onroot
294              or -windowid options are specified.
295
296       -name image_name
297              Force the next argument to be treated as an image name.  This is
298              useful if the name of the image is -dither, for instance.
299
300       -newoptions
301              Reset globally-specified options.
302
303       -normalize
304              Normalize a color image.
305
306       -rotate degrees
307              Rotate the image by degrees clockwise.  The  number  must  be  a
308              multiple of 90.
309
310       -shrink
311              Shrink  an  image  down to fit on the display.  This is particu‐
312              larly useful with servers  that  do  not  support  window  sizes
313              larger than the physical screen (eg DECWINDOWS servers).
314
315       -smooth
316              Smooth  a color image.  This reduces blockiness after zooming an
317              image up.  If used on a monochrome image, nothing happens.  This
318              option  can  take awhile to perform, especially on large images.
319              You may specify more than one -smooth option per image,  causing
320              multiple iterations of the smoothing algorithm.
321
322       -tile  Tile  this image (after any necessary merging or tiling) to cre‐
323              ate a fullscreen image.  This is usually used to create a  large
324              background  image on which to merge other images.  -geometry can
325              be used to set the  new  image  size  to  something  other  than
326              -fullscreen.
327
328       -title title
329              Change the title of the image.  This sets the title bar title if
330              displaying in a window or the NIFF file image title  if  dumping
331              the image.
332
333       -xzoom percentage
334              Zoom  the  X  axis  of an image by percentage.  A number greater
335              than 100 will expand the image, one smaller will compress it.  A
336              zero value will be ignored.  This option, and the related -yzoom
337              are useful for correcting the aspect ratio of images to be  dis‐
338              played.
339
340       -yzoom percentage
341              Zoom  the Y axis of an image by percentage.  See -xzoom for more
342              information.
343
344       -zoom percentage
345              Zoom both the X and Y axes by percentage.  See -xzoom  for  more
346              information.   Technically the percentage actually zoomed is the
347              square of the number supplied since the zoom is  to  both  axes,
348              but I opted for consistency instead of accuracy.
349

EXAMPLES

351       To  load the rasterfile "my.image" onto the background and replicate it
352       to fill the entire background:
353
354            xloadimage -onroot my.image
355
356       To center an image on the default root background:
357
358            xloadimage -default -tile my.image
359
360       If using a monochrome display and a color image you will probably  want
361       to dither the image for a cleaner (and faster) display:
362
363            xloadimage -default -tile -dither my.image
364
365       To load a monochrome image "my.image" onto the background, using red as
366       the foreground color, replicate the image, and overlay  "another.image"
367       onto it at coordinate (10,10):
368
369            xloadimage -foreground red my.image -at 10,10 another.image
370
371       To  center  the  rectangular region from 10 to 110 along the X axis and
372       from 10 to the height of the image along the Y axis:
373
374            xloadimage -center -clip 10,10,100,0 my.image
375
376       To double the size of an image:
377
378            xloadimage -zoom 200 my.image
379
380       To halve the size of an image:
381
382            xloadimage -zoom 50 my.image
383
384       To brighten a dark image:
385
386            xloadimage -brighten 150 my.image
387
388       To darken a bright image:
389
390            xloadimage -brighten 50 my.image
391

HINTS FOR GOOD IMAGE DISPLAYS

393       Since images are likely to come from a variety of sources, they may  be
394       in  a  variety of aspect ratios which may not be supported by your dis‐
395       play.  The -xzoom and -yzoom options can be used to change  the  aspect
396       ratio of an image before display.  If you use these options, it is rec‐
397       ommended that you increase the size of one of the dimensions instead of
398       shrinking the other, since shrinking looses detail.  For instance, many
399       GIF and G3 FAX images have an X:Y ratio of about 2:1.  You can  correct
400       this  for  viewing on a 1:1 display with either -xzoom 50 or -yzoom 200
401       (reduce X axis to 50% of its size and expand Y  axis  to  200%  of  its
402       size,  respectively) but the latter should be used so no detail is lost
403       in the conversion.
404
405       When zooming color images up you can reduce  blockiness  with  -smooth.
406       For  zooms  of 300% or more, I recommend two smoothing passes (although
407       this can take awhile to do on slow machines).  There will be a  notice‐
408       able improvement in the image.
409
410       You  can  perform  image  processing  on a small portion of an image by
411       loading the image more than once and using the -merge,  -at  and  -clip
412       options.   Load the image, then merge it with a clipped, processed ver‐
413       sion of itself.  To brighten a 100x100 rectangular portion of an  image
414       located at (50,50), for instance, you could type:
415
416            xloadimage my.image -merge -at 50,50 -clip 50,50,100,100 -brighten
417       150 my.image
418
419       If you're using a display with a small  colormap  to  display  colorful
420       images, try using the -gray option to convert to grayscale.
421

PATHS AND EXTENSIONS

423       The  file ~/.xloadimagerc (and optionally a system-wide file) defines a
424       number of configuration options that affect xloadimage.
425
426       This file is split into three section, the path section, the  extension
427       section, and the filter section.  The sections are identified by typing
428       the section name followed by an equals sign, eg "path =".
429
430       The path statement is used to provide a set of search paths to use when
431       looking  for  an  image of a specified name.  Separate each path in the
432       list by whitespace (eg one or more spaces,  tabs,  or  newlines).   The
433       path is searched in the order it is specified.  For example:
434
435         path = ~/images /usr/local/images ~fred
436
437       will  first  look  for  the image name you specified, then look for the
438       name in ~/images (the tilde is expanded to the value of $HOME), then in
439       /usr/local/images,  then  in  user  fred's home directory.  This allows
440       easy use of image repositories.
441
442       The extension statement is used to provide a set of default  extensions
443       to  use  when  looking for an image of a specified name.  Separate each
444       extension in the list by whitespace.  The extensions  are  searched  in
445       the order in which they are specified.  For example:
446
447         extension = .gif .jpg
448
449       If you have a file named myimage.gif you could specify the name myimage
450       and xloadimage would append the .gif extension automatically.
451
452       The filter statement is used  to  describe  filter  programs,  such  as
453       "uncompress",  which  are  to  be applied to image files automatically.
454       You specify one filter program and any number of recognized  extensions
455       following the filter keyword.  For example:
456
457         filter = uncompress .Z
458
459       specifies  that the program uncompress should be used as a filter when‐
460       ever an image file has a .Z extension.  By default filters are provided
461       for  compressed  (.Z)  files  and GNU zip (.gz) files.  See the FILTERS
462       section for more information on defining your own filters.
463
464       Any text on a line following a hash-mark (#) is ignored; if you wish to
465       use a hash-mark in a path, extension, or filter you can escape it using
466       a backslash (\).
467
468       If you wish to include white-space in a filter program name,  path,  or
469       extension  you can enclose the entire text in double-quotes.  For exam‐
470       ple:
471
472         filter = "gzip -cd" .gz
473
474       Use backslash (\) characters to allow inclusion of  double-quote  marks
475       or newlines.
476
477       The following is a sample ~/.xloadimagerc file:
478
479         # paths to look for images in
480         path = /usr/local/images        # system image repository
481               ~/images                 # personal images
482               /usr/include/X11/bitmaps # standard X bitmaps
483
484         # default extensions for images
485         extension = .csun .msun .sun .face .xbm .bm
486
487         # invoke GNU zip if a .z or .zip extension is found
488         filter = "gzip -cd" .z .zip
489
490

IMAGE TYPES

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

DUMPING IMAGES

497       Several  image  dumpers  are  included that can be used to create a new
498       image after loading and processing.  The NIFF (Native Image  File  For‐
499       mat)  is  the  simplest and creates images that xloadimage can read the
500       fastest; it is essentially a copy of the internal image format.
501
502       Some image dumpers allow options that affect the image  output.   These
503       options  are appended to the image type following a comma and are sepa‐
504       rated by commas.  If a value is desired it can be  specified  following
505       an  equals-sign.   For  example, to create a monochrome JPEG image file
506       with a quality factor of 80, you would use the following command line:
507
508         xloadimage image_name -dump jpeg,quality=80,grayscale new_image.jpg
509
510       Option names can be abbreviated but if the abbreviation is too short to
511       be unique the option which will be used is indeterminate.
512

FILTERS

514       Xloadimage supports automatic filtering by recognizing file extensions.
515       By default "compress" and "gzip" files are recognized and  their  names
516       passed to appropriate commands to decompress them.
517
518       The  xloadimage  distribution  includes  a  special  "smart" uudecoder,
519       called uufilter that can be used to automatically  uudecode  files  for
520       processing.   Uufilter  ignores  extraneous  lines in the file so it is
521       particularly useful if the uuencoded file was created by  concatenating
522       email  or  news  postings  that  had  headers  or line-break indicators
523       included.
524
525       To make use of uufilter you can add the following to your .xloadimagerc
526       file:
527
528         filter = "uufilter -s" .uu .uue
529       The filter will be automatically invoked on any file with a .uu or .uue
530       extension.
531
532       For a list of filters automatically recognized by  xloadimage  use  the
533       -configuration option.
534

SUPPORTED IMAGE OPTIONS

536       The JPEG image dumper supports the following options:
537
538       arithmetic
539               Use arithmetic encoding.
540
541       grayscale
542               Force  a  monochrome  (grayscale)  image  to be created given a
543               color image.
544
545       nointerleave
546               Create a non-interleaved file.
547
548       optimize
549               Enable entropy parameter optimization.
550
551       quality Adjust the quality of the image to  be  created.   The  default
552               quality factor is 75; lower values create poorer images.
553
554       restart interval
555               Set  the  restart  interval in MCU rows, or MCUs if 'b' follows
556               the interval value.
557
558       smooth smoothing_factor
559               Set the smoothing factor.  Value should be between 0  and  100,
560               inclusive.
561
562       If  you  are not familiar with the meaning of these options you can ask
563       the Independent JPEG Group (IJG) via email at jpeg@cs.columbia.edu.
564
565       The PBM image dumper supports the following options:
566
567       normal  Dump a normal (ascii) PBM/PPM file.
568
569       raw     Dump a RawBits format PBM/PPM file.  This is  the  default  and
570               results  in  significantly  smaller image files than when using
571               normal.
572
573       There is no way to dump a PGM format file or  a  "compact"  PBM  format
574       file (sorry).
575
576       The TIFF image dumper supports the following options:
577
578       compression
579               Image data compression technique.  Can be one of: none (no com‐
580               pression), rle (CCITT RLE compression), g3fax  (CCITT  Group  3
581               FAX  compression),  g4fax  (CCITT Group 4 FAX compression), lzw
582               (Limpel-Ziv-Welsh compression, the default),  jpeg  (JPEG  com‐
583               pression), next (NeXT run-length compression), rlew (CCITT RLEW
584               compression), mac (Macintosh  PackBits  compression),  packbits
585               (same as mac), thunderscan (ThunderScan compression).
586
587       Xloadimage will save using the MINISBLACK, MINISWHITE, COLORMAP, or RGB
588       photometrics as appropriate for its internal image format.  There is no
589       way to specify a particular photometric or any other TIFF fields.
590

AUTHOR

592       Jim Frost
593       CenterLine Software
594       jimf@centerline.com
595
596       For a more-or-less complete list of other contributors (there are a lot
597       of them), please see the README file enclosed with the distribution.
598

FILES

600            xloadimage              - the image loader and viewer
601            xsetbg                  - pseudonym which quietly sets the background
602            xview                   - pseudonym which views in a window
603            /etc/X11/Xloadimage     - default system-wide configuration file
604            ~/.xloadimagerc         - user's personal configuration file
605
607       Copyright (c) 1989, 1993 Jim Frost and others.
608
609       Xloadimage is copyrighted material with a very loose copyright allowing
610       unlimited  modification  and  distribution if the copyright notices are
611       left intact.  Various portions are copyrighted by various  people,  but
612       all  use  a modification of the MIT copyright notice.  Please check the
613       source for complete copyright information.  The intent is to  keep  the
614       source  free,  not to stifle its distribution, so please write to me if
615       you have any questions.
616

BUGS

618       Zooming dithered images, especially downwards, is UGLY.
619
620       Images can come in a  variety  of  aspect  ratios.   Xloadimage  cannot
621       detect what aspect ratio the particular image being loaded has, nor the
622       aspect ratio of the  destination  display,  so  images  with  differing
623       aspect  ratios from the destination display will appear distorted.  See
624       HINTS FOR GOOD IMAGE DISPLAYS for more information.
625
626       The GIF format allows more than one image to be stored in a single  GIF
627       file, but xloadimage will only display the first.
628
629       Only GIF87a format is supported.
630
631       One  of  the  pseudonyms for xloadimage, xview, is the same name as Sun
632       uses for their SunView-under-X package.   This  will  be  confusing  if
633       you're one of those poor souls who has to use Sun's XView.
634
635       Some  window managers do not correctly handle window size requests.  In
636       particular, many versions of the twm window  manager  use  the  MaxSize
637       hint  instead  of  the PSize hint, causing images which are larger than
638       the screen to display in a window larger  than  the  screen,  something
639       which  is  normally avoided.  Some versions of twm also ignore the Max‐
640       Size argument's real function, to limit the maximum size of the window,
641       and allow the window to be resized larger than the image.  If this hap‐
642       pens, xloadimage merely places the image in the  upper-left  corner  of
643       the  window and uses the zero-value'ed pixel for any space which is not
644       covered by the image.  This behavior is less-than-graceful but  so  are
645       window managers which are cruel enough to ignore such details.
646
647
648
649                                  8 May 1991                    XLOADIMAGE(1x)
Impressum