XLI

NAME

SYNOPSIS

DESCRIPTION

If the filename stdin is given, xli 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 -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.

Typing a space, 'n' or 'f' moves to the next image in the list. Typing a 'b' or 'p' moves to the previous image in the list.

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.

Xsetbg is equivalent to xli -onroot -quiet and xview is equivalent to xli -view -verbose.  

RESOURCE CLASS

GLOBAL OPTIONS

-default

Set the root background to the default root weave. This is the same as xsetroot 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.

-dumpcore

Signals will not be trapped, and instead a coredump will occur.

-delay secs

Automatically advance to the next image after secs seconds.

-display display_name

X11 display name to send the image(s) to.

-dispgamma Display_gamma

Specify the gamma correction value appropriate for the display device. This overides the value read from the environment variable DISPLAY_GAMMA, or the default value of 2.2, which is approximately correct for many displays. A value of between 1.6 and 2.8 is reasonable. If individual images are too bright or dark, use the -gamma option.

There is an image provided with xli called 'chkgamma.jpg' that lets you set the display gamma reasonably accurately. This file contains two grayscale ramps. The ramps are chosen to look linear to the human eye, one using continuous tones, and the other using dithering. When the display gamma is correct, then the two ramps should look symmetrical, and the point at which they look equally bright should be almost exactly half way from the top to the bottom. (To find this point it helps if you move away a little from the screen, and de-focus your eyes a bit.)

If the equal brightness point is above center increase the gamma, and decrease it if it is below the center. The value will usually be around 2.2 Once you've got it right, you can set the DISPLAY_GAMMA environment variable in your .profile

-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 xli. This causes xli 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

When the end of the list of images is reached, go to image 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 images 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 the image path and image suffixes which will be used when looking for images. These are loaded from ~/.xloadimagerc and optionally from a system wide 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 allocated shared unless there are not enough colors available.

-quiet

Forces xli and xview to be quiet. This is the default for xsetbg, but the others like to whistle.

-supported

List the supported image types.

-verbose

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

-version

Print the version number and patchlevel of this version of xli.

-view

View image(s) in a window. This is the opposite of -onroot and the default for xview and xli.

-visual visual_name

Force the use of a specific visual type to display an image. Normally xli 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.

PERSISTENT IMAGE OPTIONS

-border color

This sets the background portion of the window or clipped image which is not covered by any images to be color.

-brighten percentage

Specify a percentage multiplier for a color images colormap. A value of more than 100 will brighten an image, one of less than 100 will darken it.

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

-cdither

-colordither

Dither the image with a Floyd-Steinberg dither if the number of colors is reduced. This will be slow, but will give a better looking result with a restricted color set. -cdither and -colordither are equivalent.

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

-gamma Image_gamma

Specify the gamma of the display the image was intended to be displayed on. Images seem to come in two flavors: 1) linear color images, produced by ray tracers, scanners etc. These sort of images generally look too dark when displayed directly to a CRT display. 2) Images that have been processed to look right on a typical CRT display without any sort of processing. These images have been 'gamma corrected'. By default, xli assumes that 8 bit images have been gamma corrected and need no other processing. 24 bit images are assumed to be linear. If a linear image is displayed as if it is gamma corrected it will look too dark, and a gamma value of 1.0 should be specified, so that xli can correct the image for the CRT display device. If a gamma corrected image is displayed as if it were a linear image, then it will look too light, and a gamma value of (approximately) 2.2 should be specified for that image. Some formats (RLE) allow the image gamma to be embedded as a comment in the file itself, and the -gamma option allows overriding of the file comment. In general, values smaller than 2.2 will lighten the image, and values greater than 2.2 will darken the image. In general this will work better than the -brighten option.

-gray

Convert an image to grayscale. This is very useful when displaying colorful images on servers with limited color capability. The optional spelling -grey may also be used.

-idelay secs

Set the delay to be used for this image to secs seconds (see -delay). If -delay 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.

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

-xpm color_context_key

Select the prefered xpm colour map. XPM files may contain more than one color mapping, each mapping being appropriate for a particular visual. Normally xli will select an apropriate color mapping from that supported by the XPM file by checking on the default X visual class and depth. This option allows the user to overide this choice. Legal values of color_context_key are: m, g4, g and c. m = mono, g4 = 4 level gray, g = gray, c = color ).

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

-newoptions

Reset options that propagate. The -bright, -colors, -colordither, -delay, -dither, -gamma, -gray, -normalize, -smooth, -xzoom, -yzoom, and -zoom options normally propagate to all following images.

LOCAL IMAGE OPTIONS

-at X,Y

Indicates coordinates to load the image at X,Y 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.

-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. Note that X and Y may be negative, and that W and H may be larger than the image. This causes a border to be placed around the image. The border color may be set with the -border option.

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

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

-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. Note that the final image will be the size of the first image, and that subsequent merged images overlay previous images. The final image size can be altered by using the -clip option on the base image to make it bigger or smaller. 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.

-normalize

Normalize a color image.

-rotate degrees

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

EXAMPLES

      xli -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):

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

      xli -center -clip 10,10,100,0 my.image

To double the size of an image:

      xli -zoom 200 my.image

To halve the size of an image:

      xli -zoom 50 my.image

To brighten a dark image:

      xli -brighten 150 my.image

To darken a bright image:

      xli -brighten 50 my.image  

HINTS FOR GOOD IMAGE DISPLAYS

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:

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

XLITO

xli will recognize these trailing options at the end of the image files, and will treat the embedded string as if it were a sequence of command line IMAGE OPTIONS. Any GLOBAL OPTIONS will be ignored, and the IMAGE OPTIONS are never propagated to other images.

Trailing options can be examined with:

      xlito image_file ...

Changed or added with:

      xlito -c "string of options" image_file

And deleted with:

      xlito -d image_file ...

For example, if you have a gif file fred.gif which is too dark and is the wrong aspect ratio, then it may need to be viewed with:

      xli -yzoom 130 -gamma 1.0 fred.gif

to get it to look OK. These options can then be appended to the file by:

      xlito -c "-yzoom 130 -gamma 1.0" fred.gif

and from then on xli will get the appropriate options from the image file itself. See the xlito manual entry for more details about this utility.

PATHS AND EXTENSIONS

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

Versions of xli 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

xli 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
  JFIF style jpeg Image
  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 (XPM) files (Version 1, 2C and 3)
  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".

Any file that looks like a uuencoded file will be decoded automatically.  

AUTHORS

Jim Frost
Saber Software
jimf@saber.com

Version 1.11 of xli is derived from xloadimage 3.01 has been brought to you by:

Graeme Gill
Labtam Australia
graeme@labtam.oz.au

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

xli                         - the image loader and viewer
xsetbg                  - pseudonym which quietly sets the background
xview                   - pseudonym which views in a window
xlito                   - the trailing options utility
/usr/lib/X11/Xloadimage - default system-wide configuration file
~/.xloadimagerc         - user's personal configuration file

COPYRIGHT

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

Images can come in a variety of aspect ratios. Xli 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. The solution to this is to use xlito to append the appropriate options to the image file. See HINTS FOR GOOD IMAGE DISPLAYS and XLITO for more information.

The GIF format allows more than one image to be stored in a single GIF file, but xli will only display the first.

Only GIF87a format is supported.

One of the pseudonyms for xli, 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, xli 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.

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

Display Gamma should setable in the ~/.xloadimagerc file.

Embedded trailing options overide the command line Image Options. Command line options should really overide trailing options.

Index

NAME

SYNOPSIS

DESCRIPTION

RESOURCE CLASS

GLOBAL OPTIONS

PERSISTENT IMAGE OPTIONS

LOCAL IMAGE OPTIONS

EXAMPLES

HINTS FOR GOOD IMAGE DISPLAYS

XLITO

PATHS AND EXTENSIONS

IMAGE TYPES

AUTHORS

FILES

COPYRIGHT

BUGS