xloadimage(1x)
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, depthreduction, 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 backingstore. This is provided
for servers where backingstore is broken (such as some
versions of the AIXWindows server). It may improve scrolling
performance on servers which provide backingstore.
-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 upperleft
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 FloydSteinberg
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 hashmark (#) is ignored; if you wish to
use a hashmark 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 doublequotes. For
example:
filter = "gzip -cd" .gz
Use backslash (\) characters to allow inclusion of doublequote 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 equalssign. 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 linebreak 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 noninterleaved 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
(LimpelZivWelsh compression, the default), jpeg (JPEG
compression), next (NeXT runlength 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 moreorless 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 SunViewunderX 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 upperleft
corner of the window and uses the zerovalue'ed pixel for any space
which is not covered by the image. This behavior is lessthangraceful
but so are window managers which are cruel enough to ignore such
details.
8 May 1991 XLOADIMAGE(1x)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
