8 May 1991 XLOADIMAGE(1) NAME xloadimage, xsetbg, xview - load images into an X11 window or onto the root window SYNOPSIS _x_l_o_a_d_i_m_a_g_e [global_options] {[image_options] image ...} _x_l_o_a_d_i_m_a_g_e [global_options] [image_options] stdin < image DESCRIPTION _X_l_o_a_d_i_m_a_g_e displays images in an X11 window or loads them onto the root window. See the _I_M_A_G_E _T_Y_P_E_S section below for supported image types. If the filename _s_t_d_i_n is given, xloadimage will read the image from standard input. 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 -_h_a_l_f_t_o_n_e, -_d_i_t_h_e_r, and -_c_o_l_o_r_s 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 -_f_u_l_l_s_c_r_e_e_n 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. It's possible to have a "slideshow" of many images by specifying the -_s_l_i_d_e_s_h_o_w option. A wide variety of common image manipulations can be done by mixing and matching the available options. See the section entitled _H_I_N_T_S _F_O_R _G_O_O_D _I_M_A_G_E _D_I_S_P_L_A_Y_S for some ideas. _X_s_e_t_b_g is equivalent to _x_l_o_a_d_i_m_a_g_e -_o_n_r_o_o_t -_q_u_i_e_t and _x_v_i_e_w is equivalent to _x_l_o_a_d_i_m_a_g_e -_v_i_e_w -_v_e_r_b_o_s_e. RESOURCE CLASS _X_l_o_a_d_i_m_a_g_e uses the resource class name _X_l_o_a_d_i_m_a_g_e for window managers which need this resource set. This name changed in version 2.00 and 2.01; some previous versions used the name _X_L_o_a_d_I_m_a_g_e (which was diffi- cult to predict) or _x_l_o_a_d_i_m_a_g_e (which conflicted with class naming con- ventions). 1 XLOADIMAGE(1) 8 May 1991 GLOBAL OPTIONS The following options affect the global operation of _x_l_o_a_d_i_m_a_g_e. They may be specified anywhere on the command line. -border _c_o_l_o_r This sets the background portion of the window which is not covered by any images to be _c_o_l_o_r. -default Set the root background to the default root weave. This is the same as _x_s_e_t_r_o_o_t with no arguments. -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. -delay _s_e_c_s Automatically advance to the next image after _s_e_c_s seconds. -display _d_i_s_p_l_a_y__n_a_m_e X11 display name to send the image(s) to. -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 _W_x_H[{+-_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 _i_m_a_g_e__n_a_m_e. 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. 2 8 May 1991 XLOADIMAGE(1) -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 win- dow. This option automatically sets the -fit option. This is the opposite of -_v_i_e_w. _X_S_e_t_b_g has this option set by default. -path Displays the image path and image suffixes which will be used when looking for images. These are loaded from ~/.xloadimagerc and optionally from a systemwide file (normally /usr/lib/xloadimagerc). -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 allo- cated shared unless there are not enough colors available. -quiet Forces _x_l_o_a_d_i_m_a_g_e and _x_v_i_e_w to be quiet. This is the default for _x_s_e_t_b_g, but the others like to whistle. -supported List the supported image types. -verbose Causes _x_l_o_a_d_i_m_a_g_e 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 _x_v_i_e_w and _x_l_o_a_d_i_m_a_g_e. -version Print the version number and patchlevel of this version of _x_l_o_a_d_i_m_a_g_e. -view View image(s) in a window. This is the opposite of -_o_n_r_o_o_t and the default for _x_v_i_e_w and _x_l_o_a_d_i_m_a_g_e. -visual _v_i_s_u_a_l__n_a_m_e Force the use of a specific visual type to display an image. Normally _x_l_o_a_d_i_m_a_g_e 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. 3 XLOADIMAGE(1) 8 May 1991 -windowid _h_e_x__w_i_n_d_o_w__i_d Sets the background pixmap of a particular window ID. The argu- ment must be in hexadecimal and must be preceeded by "0x" (_e_g -windowid 0x40000b. This is intended for setting the background pixmap of some servers which use untagged virtual roots (_e_g HP- VUE), but can have other interesting applications. IMAGE OPTIONS The following options may preceed each image. These options are local to the image they preceed. -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 -_o_n_r_o_o_t option is specified, the image will be loaded at the given location on the display background. -background _c_o_l_o_r Use _c_o_l_o_r 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 _p_e_r_c_e_n_t_a_g_e 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 -_o_n_r_o_o_t 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. -dither Dither a color image to monochrome using a Floyd-Steinberg dither- ing algorithm. This happens by default when viewing color images on a monochrome display. This is slower than -_h_a_l_f_t_o_n_e and affects the image accuracy but usually looks much better. -foreground _c_o_l_o_r Use _c_o_l_o_r 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 mono- chrome image. 4 8 May 1991 XLOADIMAGE(1) -gamma _d_i_s_p_l_a_y__g_a_m_m_a Specify the gamma correction for the display. The default value is 1.0, a typical display needs 2.0 to 2.5. -gray Convert an image to grayscale. This is very useful when displaying colorful images on servers with limited color capability. The optional spelling -_g_r_e_y 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 -_d_i_t_h_e_r option will not blow the image up but will take longer to process and will be less accurate. -idelay _s_e_c_s Set the delay to be used for this image to _s_e_c_s seconds (see -_d_e_l_a_y). If -_d_e_l_a_y was specified, this overrides it. If it was not specified, this sets the automatic advance delay for this image while others will wait for the user to advance them. -invert Inverts a monochrome image. This is shorthand for -_f_o_r_e_g_r_o_u_n_d _w_h_i_t_e -_b_a_c_k_g_r_o_u_n_d _b_l_a_c_k. -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 preceeded by -_m_e_r_g_e. If used in conjunc- tion with -_a_t and -_c_l_i_p, very complex images can be built up. This option is on by default for all images if the -_o_n_r_o_o_t or -_w_i_n_d_o_w_i_d options are specified. -name _i_m_a_g_e__n_a_m_e Force the next argument to be treated as an image name. This is useful if the name of the image is -_d_i_t_h_e_r, for instance. -newoptions Reset options that propagate. The -_b_r_i_g_h_t, -_c_o_l_o_r_s, -_d_e_l_a_y, -_d_i_t_h_e_r, -_g_a_m_m_a, -_n_o_r_m_a_l_i_z_e, -_s_m_o_o_t_h, -_x_z_o_o_m, -_y_z_o_o_m, and -_z_o_o_m options normally propagate to all following images. -normalize Normalize a color image. -rotate _d_e_g_r_e_e_s Rotate the image by _d_e_g_r_e_e_s clockwise. The number must be a multi- ple of 90. -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 5 XLOADIMAGE(1) 8 May 1991 may specify more than one -_s_m_o_o_t_h option per image, causing multi- ple iterations of the smoothing algorithm. -xzoom _p_e_r_c_e_n_t_a_g_e Zoom the X axis of an image by _p_e_r_c_e_n_t_a_g_e. 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 -_y_z_o_o_m are useful for correcting the aspect ratio of images to be displayed. -yzoom _p_e_r_c_e_n_t_a_g_e Zoom the Y axis of an image by _p_e_r_c_e_n_t_a_g_e. See -_x_z_o_o_m for more information. -zoom _p_e_r_c_e_n_t_a_g_e Zoom both the X and Y axes by _p_e_r_c_e_n_t_a_g_e. See -_x_z_o_o_m 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 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 6 8 May 1991 XLOADIMAGE(1) 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 -_x_z_o_o_m and -_y_z_o_o_m 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 -_x_z_o_o_m _5_0 or -_y_z_o_o_m _2_0_0 (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 -_s_m_o_o_t_h. 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 noticable improvement in the image. You can perform image processing on a small portion of an image by load- ing the image more than once and using the -_m_e_r_g_e, -_a_t and -_c_l_i_p options. Load the image, then merge it with a clipped, processed ver- sion 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 -_g_r_a_y option to convert to grayscale. PATHS AND EXTENSIONS The file ~/.xloadimagerc (and optionally a system-wide file) defines the path and default extensions that _x_l_o_a_d_i_m_a_g_e will use when looking for images. This file can have two statements: "path=" and "extension=" (the equals signs must follow the word with no spaces between). Every- thing following the "path=" keyword will be prepended to the supplied image name if the supplied name does not specify an existing file. The paths will be searched in the order they are specified. Everything fol- lowing the "extension=" keyword will be appended to the supplied image name if the supplied name does not specify an existing file. As with paths, these extensions will be searched in the order they are given. Comments are any portion of a line following a hash-mark (#). The following is a sample ~/.xloadimagerc file: # paths to look for images in path= /usr/local/images /home/usr1/guest/madd/images /usr/include/X11/bitmaps # default extensions for images; .Z is automatic; scanned in order extension= .csun .msun .sun .face .xbm .bm 7 XLOADIMAGE(1) 8 May 1991 Versions of _x_l_o_a_d_i_m_a_g_e prior to version 01, patchlevel 03 would load the system-wide file (if any), followed by the user's file. This behavior made it difficult for the user to configure her environment if she didn't want the default. Newer versions will ignore the system-wide file if a personal configuration file exists. IMAGE TYPES _X_l_o_a_d_i_m_a_g_e currently supports the following image types: CMU Window Manager raster files Faces Project images Fuzzy Bitmap (FBM) images GEM bit images GIF images G3 FAX images McIDAS areafiles MacPaint images PC Paintbrush (PCX) images Portable Bitmap (PBM, PGM, PPM) images Sun monochrome rasterfiles Sun color RGB rasterfiles Utah Raster Toolkit (RLE) files X pixmap files X10 bitmap files X11 bitmap files X Window Dump (except TrueColor and DirectColor) Normal, compact, and raw PBM images are supported. Both standard and run-length encoded Sun rasterfiles are supported. Any image whose name ends in .Z is assumed to be a compressed image and will be filtered through "uncompress". AUTHOR Jim Frost Saber Software jimf@saber.com For a more-or-less complete list of other contributors (there are a _l_o_t 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 /usr/lib/X11/Xloadimage - default system-wide configuration file ~/.xloadimagerc - user's personal configuration file COPYRIGHT Copyright (c) 1989, 1990 Jim Frost and others. _X_l_o_a_d_i_m_a_g_e is copywritten material with a very loose copyright allowing unlimited modification and distribution if the copyright notices are left intact. Various portions are copywritten by various people, but 8 8 May 1991 XLOADIMAGE(1) 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. _X_l_o_a_d_i_m_a_g_e 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 _H_I_N_T_S _F_O_R _G_O_O_D _I_M_A_G_E _D_I_S_P_L_A_Y_S for more information. The GIF format allows more than one image to be stored in a single GIF file, but _x_l_o_a_d_i_m_a_g_e will only display the first. Only GIF87a format is supported. One of the pseudonyms for _x_l_o_a_d_i_m_a_g_e, _x_v_i_e_w, 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, _x_l_o_a_d_i_m_a_g_e merely places the image in the upper-left corner of the win- dow 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. The order in which operations are performed on an image is independent of the order in which they were specified on the command line. Wherever possible I tried to order operations in such a way as to look the best possible (zooming before dithering, for instance) or to increase speed (zooming downward before compressing, for instance). 9