1XLOADIMAGE(1x) XLOADIMAGE(1x)
2
6 xloadimage, xsetbg, xview - load images into an X11 window or onto the
7 root window
8
10 xloadimage [global_options] {[image_options] image ...}
11 xloadimage [global_options] [image_options] stdin < image
12
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 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 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 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 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 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 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 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 Xsetbg is equivalent to xloadimage -onroot -quiet and xview is equiva‐
55 lent to xloadimage -view -verbose.
56
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
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 -border color
71 This sets the background portion of the window which is not
72 covered by any images to be color.
73 -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 -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 -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 -display display_name
93 X11 display name to send the image(s) to.
94 -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 -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 -fork Fork xloadimage. This causes xloadimage to disassociate itself
112 from the shell. This option automatically turns on -quiet.
113 -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 -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 -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 -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 -identify
139 Identify the supplied images rather than display them.
140 -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 -list List the images which are along the image path.
149 -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 -path Displays miscellaneous information about the program configura‐
155 tion. This option is obsolete and has been replaced by -con‐
156 figuration.
157 -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 -private
164 Force the use of a private colormap. Normally colors are allo‐
165 cated shared unless there are not enough colors available.
166 -quiet Forces xloadimage and xview to be quiet. This is the default
168 for xsetbg, but the others like to whistle.
169 -supported
171 List the supported image types.
172 -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 -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 -version
184 Print the version number and patchlevel of this version of
185 xloadimage.
186 -view View image(s) in a window. This is the opposite of -onroot and
188 the default for xview and xloadimage.
189 -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 -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
206 The following options may precede each image. These options are local
207 to the image they precede.
208 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -invert
286 Inverts a monochrome image. This is shorthand for -foreground
287 white -background black.
288 -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 -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 -newoptions
301 Reset globally-specified options.
302 -normalize
304 Normalize a color image.
305 -rotate degrees
307 Rotate the image by degrees clockwise. The number must be a
308 multiple of 90.
309 -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 -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 -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 -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 -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 -yzoom percentage
341 Zoom the Y axis of an image by percentage. See -xzoom for more
342 information.
343 -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
351 To load the rasterfile "my.image" onto the background and replicate it
352 to fill the entire background:
353 xloadimage -onroot my.image
355 To center an image on the default root background:
357 xloadimage -default -tile my.image
359 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 xloadimage -default -tile -dither my.image
364 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 xloadimage -foreground red my.image -at 10,10 another.image
370 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 xloadimage -center -clip 10,10,100,0 my.image
375 To double the size of an image:
377 xloadimage -zoom 200 my.image
379 To halve the size of an image:
381 xloadimage -zoom 50 my.image
383 To brighten a dark image:
385 xloadimage -brighten 150 my.image
387 To darken a bright image:
389 xloadimage -brighten 50 my.image
391
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 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 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 xloadimage my.image -merge -at 50,50 -clip 50,50,100,100 -brighten
417 150 my.image
418 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
423 The file ~/.xloadimagerc (and optionally a system-wide file) defines a
424 number of configuration options that affect xloadimage.
425 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 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 path = ~/images /usr/local/images ~fred
436 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 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 extension = .gif .jpg
448 If you have a file named myimage.gif you could specify the name myimage
450 and xloadimage would append the .gif extension automatically.
451 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 filter = uncompress .Z
458 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 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 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 filter = "gzip -cd" .gz
473 Use backslash (\) characters to allow inclusion of double-quote marks
475 or newlines.
476 The following is a sample ~/.xloadimagerc file:
478 # 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 # default extensions for images
485 extension = .csun .msun .sun .face .xbm .bm
486 # invoke GNU zip if a .z or .zip extension is found
488 filter = "gzip -cd" .z .zip
489
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
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 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 xloadimage image_name -dump jpeg,quality=80,grayscale new_image.jpg
509 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
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 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 To make use of uufilter you can add the following to your .xloadimagerc
526 file:
527 filter = "uufilter -s" .uu .uue
529 The filter will be automatically invoked on any file with a .uu or .uue
530 extension.
531 For a list of filters automatically recognized by xloadimage use the
533 -configuration option.
534
536 The JPEG image dumper supports the following options:
537 arithmetic
539 Use arithmetic encoding.
540 grayscale
542 Force a monochrome (grayscale) image to be created given a
543 color image.
544 nointerleave
546 Create a non-interleaved file.
547 optimize
549 Enable entropy parameter optimization.
550 quality Adjust the quality of the image to be created. The default
552 quality factor is 75; lower values create poorer images.
553 restart interval
555 Set the restart interval in MCU rows, or MCUs if 'b' follows
556 the interval value.
557 smooth smoothing_factor
559 Set the smoothing factor. Value should be between 0 and 100,
560 inclusive.
561 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 The PBM image dumper supports the following options:
566 normal Dump a normal (ascii) PBM/PPM file.
568 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 There is no way to dump a PGM format file or a "compact" PBM format
574 file (sorry).
575 The TIFF image dumper supports the following options:
577 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 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
592 Jim Frost
593 CenterLine Software
594 jimf@centerline.com
595 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
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 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
618 Zooming dithered images, especially downwards, is UGLY.
619 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 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 Only GIF87a format is supported.
630 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 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 8 May 1991 XLOADIMAGE(1x)