xli - load images into an X11 window or onto the root window
xli [global_options] {[image_options] image ...}
xli [global_options] [image_options] stdin < image
xli displays images in an X11 window or loads them onto the root window.
See the
IMAGE TYPES section below for supported image types.
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 or
-fillscreen options. 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.
When the keyboard focus is in the window you can:
Type 'q' or '^C' to exit xli.
Type space, 'n' or 'f' to move to the next image in the list.
Type 'b' or 'p' to move to the previous image in the list.
Type . to reload the image.
Type l to rotate the image anti-clockwise.
Type r to rotate the image clockwise.
Type 0 to set the images assumed gamma to your display gamma
(usually darkens images)
Type 1 to set the images assumed gamma to 1.0
(usually lightens images)
Type 5-2 to lighten the image (5 in small steps, up to 2 in large steps)
Type 6-9 to darken the image (6 in small steps, up to 9 in large steps)
Type > resp. < to zoom in resp. out
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.
xli uses the resource class name
_XSETROOT_Id for window
managers which need this resource set.
The following options affect the global operation of
xli. They may be
specified anywhere on the command line.
- -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.
- -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 overrides 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
- -fillscreen
- Use the whole screen for displaying an image. The image
will be zoomed so that it just fits the size of the screen. If -onroot is
also specified, it will be zoomed to completely fill the screen.
- -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.
- -forall
- Apply -fillscreen and -fullscreen options to all images and
not just the first.
- -fork
- Fork xli. This causes xli to disassociate itself from the
shell. This option automatically turns on -quiet.
- -fullscreen
- Use the whole screen for displaying an image. The image
will be surrounded by a border if it is smaller than the screen. If
-onroot is also specified, the image will be zoomed so that it just fits
the size of the screen.
- -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 set the size and position of the
viewing window. If the size is not specified in the geometry, (or is set
to 0), then the size will be chosen to be small enough to able to fit the
window in the screen (as usual).
- -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. If used in conjunction with -fullscreen, the
image will be zoomed to just fit. If used with -fillscreen, the image will
be zoomed to completely fill the screen. -border, -at, and -center also
affect the results.
- -path
- Displays the image path and image suffixes which will be
used when looking for images. These are loaded from ~/.xlirc and
optionally from a system wide file (normally /usr/lib/xlirc).
- -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.
- -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.
The following options may precede each image. They take effect from the next
image, and continue until overridden or canceled with
-newoptions.
- -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.
- -delay secs
- Sets xli to automatically advance to the following image,
secs seconds after the next image file is displayed.
- -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.
- -title window_title
- Set the titlebar of the window used to display the image.
This will override any title that is read from the image file. The title
will also be used for the icon name.
- -xpm color_context_key
- Select the preferred 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 appropriate 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 override 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.
- -zoom auto
- Zoom large images to fit the screen; don't zoom small
images.
- -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.
The following options may precede each image. These options are local to the
image they precede.
- -at X,Y
- Indicates coordinates to load the image at
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.
- -expand
- Forces the image (after all other optional processing) to
be expanded into a True Color (24 bit) image. This is useful on systems
which support 24 bit color, but where xli might choose to load a bitmap or
8 bit image into one of the other smaller depth visuals supported on your
system.
- -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.
To load the rasterfile "my.image" onto the background and replicate it
to fill the entire background:
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
Since images are likely to come from a variety of sources, they may be in a
variety of aspect ratios which may not be supported by your display. The
-xzoom and
-yzoom options can be used to change the aspect ratio
of an image before display. If you use these options, it is recommended that
you increase the size of one of the dimensions instead of shrinking the other,
since shrinking looses detail. For instance, many GIF and G3 FAX images have
an X:Y ratio of about 2:1. You can correct this for viewing on a 1:1 display
with either
-xzoom 50 or
-yzoom 200 (reduce X axis to 50% of its
size and expand Y axis to 200% of its size, respectively) but the latter
should be used so no detail is lost in the conversion.
When zooming color images up you can reduce blockiness with
-smooth. For
zooms of 300% or more, I recommend two smoothing passes (although this can
take awhile to do on slow machines). There will be a noticeable improvement in
the image.
You can perform image processing on a small portion of an image by loading the
image more than once and using the
-merge,
-at and
-clip
options. Load the image, then merge it with a clipped, processed version of
itself. To brighten a 100x100 rectangular portion of an image located at
(50,50), for instance, you could type:
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 (XLoadImageTrailingOptions) is a separate utility that provides a
file format independent way of marking image files with the appropriate
options to display correctly. It does this by appending to file a string
specified by the user, marked with some magic numbers so that this string can
be extracted by a program that knows where to look. Since almost all image
files have some sort of image size specifier, the programs that load or
manipulate these files do not look beyond the point at which they have read
the image, so trailing information can safely be appended to the file. If
appending this information causes trouble with other utilities, it can simply
be deleted.
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.
The file ~/.xlirc (and optionally a system-wide file) defines the path and
default extensions that
xli 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). Everything
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 following 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 ~/.xlirc 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.
xli currently supports the following image types:
CMU Window Manager raster files
Faces Project images
Fuzzy Bitmap (.fbm) images
GEM bit images
GIF images (Including GIF89a compatibility)
G3 FAX images
JFIF style jpeg images
McIDAS areafiles
MacPaint images
Windows, OS/2 RLE Image
Monochrome PC Paintbrush (.pcx) images
Photograph on CD Image
Portable Bitmap (.pbm, .pgm, .ppm) images
Sun monochrome rasterfiles
Sun color RGB rasterfiles
Targa (.tga) files
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". If HAVE_GUNZIP is defined in the Makefile.std make
file, then any image whose name ends in .gz or .Z will be filtered through
gunzip.
Any file that looks like a uuencoded file will be decoded automatically.
The original Author is:
Jim Frost
Saber Software
[email protected]
Version 1.16 of xli is derived from xloadimage 3.01 has been brought to you by:
Graeme Gill
[email protected]
Version 1.17 of xli is derived from xli 1.16 by
[email protected]
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.
xli - the image loader and viewer
xlito - the trailing options utility
/usr/lib/X11/Xli - default system-wide configuration file
~/.xlirc - user's personal configuration file
Copyright (c) 1989, 1990, 1991, 1992, 1993 Jim Frost, Graeme Gill and others.
Xli is copyrighted material with a very loose license allowing unlimited
modification and distribution if the copyright notices are left intact.
Various portions are copyrighted by various people, but all use a modification
of the MIT copyright notice. Please check the source for complete copyright
information. The intent is to keep the source free, not to stifle its
distribution, so please write to me if you have any questions.
Zooming dithered images, especially downwards, is UGLY.
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.
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 ~/.xlirc file.
Embedded trailing options override the command line
Image Options.
Command line options should really override trailing options.