NAME¶
xloadimage, xsetbg, xview - load images into an X11 window or onto the root
window
SYNOPSIS¶
xloadimage [global_options] {[image_options] image ...}
xloadimage [global_options] [image_options] stdin < image
DESCRIPTION¶
Xloadimage displays images in an X11 window, loads them onto the root
window, or writes them into a file. Many image types are recognized; use the
-supported option to list them.
If the filename
stdin is given, xloadimage will read the image from
standard input if this capability is supported by the loader for that image
type (most types do support reading from stdin).
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.
If more than one image file is specified on the command line, each image will be
shown in order (except if
-merge or
-goto are being used).
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.
The
-dump option causes an image to be written to a file rather than
displayed after processing. This allows you to read an image, perform a number
of processing operations on it, and save the resultant image. This also allows
translation from any of the recognized image types into any of the formats
that support dumping.
Xsetbg is equivalent to
xloadimage -onroot -quiet and
xview
is equivalent to
xloadimage -view -verbose.
RESOURCE CLASS¶
Xloadimage uses the resource class name
Xloadimage for window
managers which need this resource set. This name changed in version 2.00 and
2.01; some previous versions used the name
XLoadImage (which was
difficult to predict) or
xloadimage (which conflicted with class naming
conventions).
GLOBAL OPTIONS¶
The following options affect the global operation of
xloadimage. They may
be specified anywhere on the command line. Additionally the
-global
option can be used to force an image option to apply to all images.
- -border color
- This sets the background portion of the window which is not covered by any
images to be color.
- -configuration
- Displays the image path, image suffixes, and supported filters which will
be used when looking for and reading images. These are loaded from
~/.xloadimagerc and optionally from a systemwide file (normally
/usr/lib/xloadimagerc). This replaces the -path option.
- -default
- Use the default root weave as the image. This option forces
-onroot. If -default is used alone, it is the same as
xsetroot with no arguments. If used in conjunction with
-tile this option can be used to place images on the default root
weave (see EXAMPLES below).
- -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.
- -display display_name
- X11 display name to send the image(s) to.
- -dump image_type[,option[=value]] dump_file
- Rather than displaying the loaded and processed image, dump it into an
image file of the specified type. For a list of image types that can be
dumped, use the -supported option. Some image types have options
that affect the format of the file that's created. See DUMP OPTIONS
below. An image can be dumped in any supported dump format regardless of
the original image type, so image file type translation is possible using
this option.
- -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 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
- Forces the next image to be displayed to be the image named
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 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 window. This
option automatically sets the -fit option. This is the opposite of
-view. XSetbg has this option set by default.
- -path
- Displays miscellaneous information about the program configuration. This
option is obsolete and has been replaced by -configuration.
- -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 xloadimage and xview to be quiet. This is the default
for xsetbg, but the others like to whistle.
- -supported
- List the supported image types.
- -type type_name
- Forces xloadimage to try to load the image as a particular file
type rather than trying to guess. This often improves load performance
noticeably.
- -verbose
- Causes xloadimage 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 xloadimage.
- -version
- Print the version number and patchlevel of this version of
xloadimage.
- -view
- View image(s) in a window. This is the opposite of -onroot and the
default for xview and xloadimage.
- -visual visual_name
- Force the use of a specific visual type to display an image. Normally
xloadimage 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.
IMAGE OPTIONS¶
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 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.
- -brighten percentage
- 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 -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.
- -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.
- -delay secs
- Automatically advance to the next image after secs seconds. You may
want to use the -global switch with this command to create a
slideshow with multiple images.
- -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.
- -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.
- -gamma display_gamma
- Specify the gamma correction for the display. The default value is 1.0, a
typical display needs 2.0 to 2.5.
- -global
- Force the following option to apply to all images rather than one specific
image. Local image options will temporarily override any option specified
with -global.
- -gray
- Convert an image to grayscale. This is very useful when displaying
colorful images on servers with limited color capability. It can also be
used to convert a bitmap image into a grayscale image, although the
resulting image will be smaller than the original. The optional spelling
-grey 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
-dither option will not blow the image up but will take longer to
process and will be less accurate.
- -idelay secs
- This option is no longer supported due to the addition of -global.
The same functionality can be had with -delay.
- -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. 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.
- -newoptions
- Reset globally-specified options.
- -normalize
- Normalize a color image.
- -rotate degrees
- Rotate the image by degrees clockwise. The number must be a
multiple of 90.
- -shrink
- Shrink an image down to fit on the display. This is particularly useful
with servers that do not support window sizes larger than the physical
screen (eg DECWINDOWS servers).
- -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.
- -tile
- Tile this image (after any necessary merging or tiling) to create a
fullscreen image. This is usually used to create a large background image
on which to merge other images. -geometry can be used to set the
new image size to something other than -fullscreen.
- -title title
- Change the title of the image. This sets the title bar title if displaying
in a window or the NIFF file image title if dumping the image.
- -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.
EXAMPLES¶
To load the rasterfile "my.image" onto the background and replicate it
to fill the entire background:
xloadimage -onroot my.image
To center an image on the default root background:
xloadimage -default -tile my.image
If using a monochrome display and a color image you will probably want to dither
the image for a cleaner (and faster) display:
xloadimage -default -tile -dither 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
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
-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:
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
-gray option to convert to grayscale.
PATHS AND EXTENSIONS¶
The file ~/.xloadimagerc (and optionally a system-wide file) defines a number of
configuration options that affect xloadimage.
This file is split into three section, the
path section, the
extension section, and the
filter section. The sections are
identified by typing the section name followed by an equals sign, eg
"path =".
The
path statement is used to provide a set of search paths to use when
looking for an image of a specified name. Separate each path in the list by
whitespace (eg one or more spaces, tabs, or newlines). The path is searched in
the order it is specified. For example:
path = ~/images /usr/local/images ~fred
will first look for the image name you specified, then look for the name in
~/images (the tilde is expanded to the value of $HOME), then in
/usr/local/images, then in user fred's home directory. This allows easy use of
image repositories.
The
extension statement is used to provide a set of default extensions to
use when looking for an image of a specified name. Separate each extension in
the list by whitespace. The extensions are searched in the order in which they
are specified. For example:
extension = .gif .jpg
If you have a file named
myimage.gif you could specify the name
myimage and xloadimage would append the
.gif extension
automatically.
The
filter statement is used to describe filter programs, such as
"uncompress", which are to be applied to image files automatically.
You specify one filter program and any number of recognized extensions
following the
filter keyword. For example:
filter = uncompress .Z
specifies that the program
uncompress should be used as a filter whenever
an image file has a .Z extension. By default filters are provided for
compressed (.Z) files and GNU zip (.gz) files. See the
FILTERS section
for more information on defining your own filters.
Any text on a line following a hash‐mark (#) is ignored; if you wish to
use a hash‐mark in a path, extension, or filter you can escape it using
a backslash (\).
If you wish to include white-space in a filter program name, path, or extension
you can enclose the entire text in double‐quotes. For example:
filter = "gzip -cd" .gz
Use backslash (\) characters to allow inclusion of double‐quote marks or
newlines.
The following is a sample ~/.xloadimagerc file:
# paths to look for images in
path = /usr/local/images # system image repository
~/images # personal images
/usr/include/X11/bitmaps # standard X bitmaps
# default extensions for images
extension = .csun .msun .sun .face .xbm .bm
# invoke GNU zip if a .z or .zip extension is found
filter = "gzip -cd" .z .zip
IMAGE TYPES¶
Xloadimage currently supports many common and some uncommon image types,
and can create images in several formats. For a complete list use the
-supported option.
DUMPING IMAGES¶
Several image dumpers are included that can be used to create a new image after
loading and processing. The NIFF (Native Image File Format) is the simplest
and creates images that
xloadimage can read the fastest; it is
essentially a copy of the internal image format.
Some image dumpers allow options that affect the image output. These options are
appended to the image type following a comma and are separated by commas. If a
value is desired it can be specified following an equals‐sign. For
example, to create a monochrome JPEG image file with a quality factor of 80,
you would use the following command line:
xloadimage image_name -dump jpeg,quality=80,grayscale new_image.jpg
Option names can be abbreviated but if the abbreviation is too short to be
unique the option which will be used is indeterminate.
FILTERS¶
Xloadimage supports automatic filtering by recognizing file extensions. By
default "compress" and "gzip" files are recognized and
their names passed to appropriate commands to decompress them.
The xloadimage distribution includes a special "smart" uudecoder,
called
uufilter that can be used to automatically uudecode files for
processing.
Uufilter ignores extraneous lines in the file so it is
particularly useful if the uuencoded file was created by concatenating email
or news postings that had headers or line‐break indicators included.
To make use of
uufilter you can add the following to your
.xloadimagerc file:
filter = "uufilter -s" .uu .uue
The filter will be automatically invoked on any file with a .uu or .uue
extension.
For a list of filters automatically recognized by xloadimage use the
-configuration option.
SUPPORTED IMAGE OPTIONS¶
The JPEG image dumper supports the following options:
- arithmetic
- Use arithmetic encoding.
- grayscale
- Force a monochrome (grayscale) image to be created given a color
image.
- nointerleave
- Create a non‐interleaved file.
- optimize
- Enable entropy parameter optimization.
- quality
- Adjust the quality of the image to be created. The default quality factor
is 75; lower values create poorer images.
- restart interval
- Set the restart interval in MCU rows, or MCUs if 'b' follows the interval
value.
- smooth smoothing_factor
- Set the smoothing factor. Value should be between 0 and 100,
inclusive.
If you are not familiar with the meaning of these options you can ask the
Independent JPEG Group (IJG) via email at jpeg@cs.columbia.edu.
The PBM image dumper supports the following options:
- normal
- Dump a normal (ascii) PBM/PPM file.
- raw
- Dump a RawBits format PBM/PPM file. This is the default and results in
significantly smaller image files than when using normal.
There is no way to dump a PGM format file or a "compact" PBM format
file (sorry).
The TIFF image dumper supports the following options:
- compression
- Image data compression technique. Can be one of: none (no
compression), rle (CCITT RLE compression), g3fax (CCITT
Group 3 FAX compression), g4fax (CCITT Group 4 FAX compression),
lzw (Limpel‐Ziv‐Welsh compression, the default),
jpeg (JPEG compression), next (NeXT run‐length
compression), rlew (CCITT RLEW compression), mac (Macintosh
PackBits compression), packbits (same as mac),
thunderscan (ThunderScan compression).
Xloadimage will save using the MINISBLACK, MINISWHITE, COLORMAP, or RGB
photometrics as appropriate for its internal image format. There is no way to
specify a particular photometric or any other TIFF fields.
AUTHOR¶
Jim Frost
CenterLine Software
jimf@centerline.com
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¶
xloadimage - the image loader and viewer
xsetbg - pseudonym which quietly sets the background
xview - pseudonym which views in a window
/etc/X11/Xloadimage - default system-wide configuration file
~/.xloadimagerc - user's personal configuration file
COPYRIGHT¶
Copyright (c) 1989, 1993 Jim Frost and others.
Xloadimage is copyrighted material with a very loose copyright 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.
BUGS¶
Zooming dithered images, especially downwards, is UGLY.
Images can come in a variety of aspect ratios.
Xloadimage 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
HINTS FOR GOOD IMAGE
DISPLAYS for more information.
The GIF format allows more than one image to be stored in a single GIF file, but
xloadimage will only display the first.
Only GIF87a format is supported.
One of the pseudonyms for
xloadimage,
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,
xloadimage 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.