display(1)
display(1)
display - display an image on any workstation running X
SYNOPSIS
display [ options ...] file [ [ options ...] file ...]
DESCRIPTION
display is a machine architecture independent image
processing and display program. It can display an image on
any workstation display running an X server. display first
determines the hardware capabilities of the workstation. If
the number of unique colors in the image is less than or
equal to the number the workstation can support, the image
is displayed in an X window. Otherwise the number of colors
in the image is first reduced to match the color resolution
of the workstation before it is displayed.
This means that a continuous-tone 24 bits-per-pixel image
can display on a 8 bit pseudo-color device or monochrome
device. In most instances the reduced color image closely
resembles the original. Alternatively, a monochrome or
pseudo-color image can display on a continuous-tone 24
bits-per-pixel device.
EXAMPLES
To scale an image of a cockatoo to exactly 640 pixels in
width and 480 pixels in height and position the window at
location (200,200), use:
display -geometry 640x480+200+200! cockatoo.miff
To display an image of a cockatoo without a border centered
on a backdrop, use:
display +borderwidth -backdrop cockatoo.miff
To tile an image of a cockatoo onto the root window, use:
display -window root cockatoo.miff
OPTIONS
-backdrop
display the image centered on a backdrop.
This backdrop covers the entire workstation screen and
is useful for hiding other X window activity while
viewing the image. The color of the backdrop is
specified as the background color. Refer to X
RESOURCES for details.
-clip x{+-}{+-}
preferred size and location of the clipped image. See
X(1) for details about the geometry specification.
Use clipping to apply image processing options to, or
display, a particular area of an image.
The equivalent X resource for this option is
clipGeometry (class ClipGeometry). See X RESOURCES for
details.
-colormap type
the type of colormap: Shared or Private.
This option only applies when the default X server
visual is PseudoColor or GrayScale. Refer to -visual
for more details. By default, a shared colormap is
allocated. The image shares colors with other X
clients. Some image colors could be approximated,
therefore your image may look very different than
intended. Choose Private and the image colors appear
exactly as they are defined. However, other clients
may go "technicolor" when the image colormap is
installed.
-colors value
preferred number of colors in the image.
The actual number of colors in the image may be less
than your request, but never more. Note, this is a
color reduction option. Images with less unique colors
than specified with this option will remain unchanged.
Refer to quantize(9) for more details.
Note, options -dither, -colorspace, and -treedepth
affect the color reduction algorithm.
-colorspace value
the type of colorspace: GRAY, RGB, XYZ, YCbCr, YIQ, or
YUV.
Color reduction, by default, takes place in the RGB
color space. Empirical evidence suggests that
distances in color spaces such as YUV or YIQ correspond
to perceptual color differences more closely than do
distances in RGB space. These color spaces may give
better results when color reducing an image. Refer to
quantize(9) for more details.
The -colors or -monochrome option is required for this
option to take effect.
-compress type
the type of image compression: QEncoded or
RunlengthEncoded.
Use this option with -write to specify the the type of
image compression. See miff(5) for details.
Specify +compress to store the binary image in an
uncompressed format. The default is the compression
type of the specified image file.
-delay seconds
display the next image after pausing.
This option is useful when viewing several images in
sequence. Each image will display and wait the number
of seconds specified before the next image is
displayed. The default is to display the image and
wait until you choose to display the next image or
terminate the program.
-density x
vertical and horizontal density of the image.
This option specifies an image density for a Postscript
page. The default is 72 dots per inch in the
horizontal and vertical direction. Use this option to
alter the default density.
-display host:display[.screen]
specifies the X server to contact; see X(1).
-dither
apply Floyd/Steinberg error diffusion to the image.
The basic strategy of dithering is to trade intensity
resolution for spatial resolution by averaging the
intensities of several neighboring pixels. Images
which suffer from severe contouring when reducing
colors can be improved with this option.
The -colors or -monochrome option is required for this
option to take effect.
-enhance
apply a digital filter to enhance a noisy image.
-gamma value
level of gamma correction.
The same color image displayed on two different
workstations may look different due to differences in
the display monitor. Use gamma correction to adjust
for this color difference. Reasonable values extend
from 0.8 to 2.3.
You can apply separate gamma values to the red, green,
and blue channels of the image with a gamma value list
delineated with commas (i.e. 1.7,2.3,1.2).
-geometry {%}x{%}{+-}{+-
}{!}
preferred size and location of the image window. See
X(1) for details about the geometry specification. By
default, the window size is the image size and the
location is choosen by you when it is mapped.
By default, the width and height are maximum values.
That is, the image is expanded or contracted to fit the
width and height value while maintaining the aspect
ratio of the image. Append an exclamation point to the
geometry to force the image size to exactly the size
you specify. For example, if you specify 640x480! the
image width is set to 640 pixels and height to 480. If
only one factor is specified, both the width and height
assume the value.
To specify a percentage width or height instead, append
%. The image size is multiplied by the width and
height percentages to obtain the final image
dimensions. To increase the size of an image, use a
value greater than 100 (e.g. 125%). To decrease an
image's size, use a percentage less than 100.
If the specified image size is smaller than the actual
image size, the image is first reduced to an integral
of the specified image size with an antialias digital
filter. The image is then scaled to the exact
specified image size with pixel replication. If the
specified image size is greater than the actual image
size, the image is first enlarged to an integral of the
specified image size with bilinear interpolation. The
image is then scaled to the exact specified image size
with pixel replication.
When displaying an image on an X server, and
is relative to the root window.
The equivalent X resource for this option is
imageGeometry (class ImageGeometry). See X RESOURCES
for details.
-interlace type
the type of interlacing scheme: NONE, LINE, or PLANE.
This option is used to specify the type of interlacing
scheme for raw image formats such as RGB or YUV. NONE
means do not interlace (RGBRGBRGBRGBRGBRGB...), LINE
uses scanline interlacing
(RRR...GGG...BBB...RRR...GGG...BBB...), and PLANE uses
plane interlacing (RRRRRR...GGGGGG...BBBBBB...).
-inverse
apply color inversion to image.
The red, green, and blue intensities of an image are
negated.
-map type
display image using this Standard Colormap type.
Choose from these Standard Colormap types:
default
best
red
green
blue
gray
The X server must support the Standard Colormap you
choose, otherwise an error occurs. See xstdcmap(1) for
one way of creating Standard Colormaps.
-monochrome
transform the image to black and white.
-noise
reduce the noise in an image with a noise peak
elimination filter.
The principal function of noise peak elimination filter
is to smooth the objects within an image without losing
edge information and without creating undesired
structures. The central idea of the algorithm is to
replace a pixel with its next neighbor in value within
a 3 x 3 window, if this pixel has been found to be
noise. A pixel is defined as noise if and only if this
pixel is a maximum or minimum within the 3 x 3 window.
-normalize
transform image to span the full range of color values.
This is a contrast enhancement technique.
-page x{+-}{+-}
size and location of the Postscript page.
Use this option to specify the dimensions of the
Postscript page in picas or a TEXT page in pixels. The
default for a Postscript page is to center the image on
a letter page 612 by 792 dots per inch. The left and
right margins are 18 picas and the top and bottom 94
picas (i.e. 612x792+18+94). Other common sizes are:
540x720 Note
612x1008 Legal
842x1190 A3
595x842 A4
421x595 A5
297x421 A6
709x1002 B4
612x936 U.S. Foolscap
612x936 European Foolscap
396x612 Half Letter
792x1224 11x17
1224x792 Ledger
The page geometry is relative to the vertical and
horizontal density of the Postscript page. See
-density for details.
The default page dimensions for a TEXT image is
612x792+36+36.
-quality value
JPEG quality setting.
Quality is 0 (worst) to 100 (best). The default is 85.
-reflect
create a "mirror image" by reflecting the image
scanlines.
-rotate degrees
apply Paeth image rotation to the image.
Empty triangles left over from rotating the image are
filled with the color defined by the pixel at location
(0,0).
-scene value
image scene number.
-treedepth value
Normally, this integer value is zero or one. A zero or
one tells display to choose a optimal tree depth for
the color reduction algorithm.
An optimal depth generally allows the best
representation of the source image with the fastest
computational speed and the least amount of memory.
However, the default depth is inappropriate for some
images. To assure the best representation, try values
between 2 and 8 for this parameter. Refer to
quantize(9) for more details.
The -colors or -monochrome option is required for this
option to take effect.
-update seconds
detect when image file is modified and redisplay.
Suppose that while you are displaying an image the file
that is currently displayed is over-written. display
will automatically detect that the input file has been
changed and update the displayed image accordingly.
-verbose
print detailed information about the image.
This information is printed: image scene number; image
name; image size; the image class (DirectClass or
PseudoClass); the total number of unique colors; and
the number of seconds to read and transform the image.
Refer to miff(5) for a description of the image class.
If -colors is also specified, the total unique colors
in the image and color reduction error values are
printed. Refer to quantize(9) for a description of
these values.
-visual type
display image using this visual type.
Choose from these visual classes:
StaticGray
GrayScale
StaticColor
PseudoColor
TrueColor
DirectColor
default
visual id
The X server must support the visual you choose,
otherwise an error occurs. If a visual is not
specified, the visual class that can display the most
simultaneous colors on the default X server screen is
choosen.
-window id
set the background pixmap of this window to the image.
id can be a window id or name. Specify root to select
X's root window as the target window.
By default the image is tiled onto the background of
the target window. If -backdrop or -geometry are
specified, the image is surrounded by the background
color. Refer to X RESOURCES for details.
The image will not display on the root window if the
image has more unique colors than the target window
colormap allows. Use -colors to reduce the number of
colors.
-write filename
write image to a file.
If file already exists, you will be prompted as to
whether it should be overwritten.
If the image format is MIFF and the number of unique
colors in the image exceeds 4096, it is stored as
DirectClass; otherwise, it is stored as PseudoClass
format. Refer to miff(5) for more details.
By default, the image is written in the format that it
was read in as. To specify a particular image format,
prefix file with the image type and a colon (i.e.
ps:image) or specify the image type as the filename
suffix (i.e. image.ps). See convert(1) for a list of
valid image formats. Specify file as - for standard
output. If file has the extension .Z or .gz, the file
size is compressed using with compress or gzip
respectively. Precede the image file name | to pipe to
a system command. If file already exists, you will be
prompted as to whether it should be overwritten.
Use -compress to specify the type of image compression.
The equivalent X resource for this option is
writeFilename (class WriteFilename). See X RESOURCES
for details.
In addition to those listed above, you can specify these
standard X resources as command line options: -background,
-bordercolor, -borderwidth, -font, -foreground,
-iconGeometry, -iconic, -matte, -name, or -title. See X
RESOURCES for details.
Any option you specify on the command line remains in effect
until it is explicitly changed by specifying the option
again with a different effect. For example to display two
images, the first with 32 colors, and the second with only
16 colors, use:
display -colors 32 cockatoo.miff -colors 16 macaw.miff
Change - to + in any option above to reverse its effect.
For example, specify +compress to store the binary image in
an uncompressed format.
By default, the image format is determined by its magic
number. To specify a particular image format, precede the
filename with an image format name and a colon (i.e.
ps:image) or specify the image type as the filename suffix
(i.e. image.ps). See convert(1) for a list of valid image
formats.
When you specify X as your image type, the filename has
special meaning. It specifies an X window by id, name, or
root. If no filename is specified, the window is selected
by clicking the mouse in the desired window.
Specify file as - for standard input. If file has the
extension .Z or .gz, the file is uncompressed with
uncompress or gunzip respectively. Precede the image file
name | to pipe from a system command.
BUTTONS
The effects of each button press is described below. Three
buttons are required. If you have a two button mouse,
button 1 and 3 are returned. Press ALT and button 3 to
simulate button 2.
1 Press and drag to select a command from a pop-up menu.
Choose from these commands:
Image Info
Resize
Rotate
Reflect
Annotate
Composite
Print
Write
Restore
Load
Next
Former
Quit
2 Press and drag to define a region of the image to clip.
Release the button to crop the image, or return the
pointer to the location of the initial button press to
cancel the cropping operation.
3 Press and drag to define a region of the image to
magnify.
Note, this button behaves differently for a composite
MIFF image created with montage. Choose a particular
tile of the composite and press this button, the image
represented by the tile is then displayed. To return
to the composite MIFF image, choose Next from the
command menu (refer to Button 1). See montage(1) and
miff(5) for more details.
KEYBOARD ACCELERATORS
i Press to display information about the image. Press
any key or button to erase the information.
This information is printed: image scene number; image
name; image size; the visual class (see -visual); and
the total number of unique colors in the image.
< Press to half the image size.
= Press to resize the image to a width and height you
specify.
> Press to double the image size.
/ Press to rotate the image 90 degrees clockwise.
| Press to rotate the image the number of degrees you
specify.
Press to rotate the image 90 degrees counter-clockwise.
r Press to reflect the image scanlines.
a Press to annotate the image with text.
Refer to IMAGE ANNOTATION for more details.
c Press to composite the image with another.
Refer to IMAGE COMPOSITING for more details.
l Press to load an image from a file.
p Press to print the image to a Postscript printer.
w Press to write the image to a file.
o Press to restore the image to its original size.
n Press to display the next image.
f Press to display the former image.
q Press to discard all images and exit program.
1-9 Press to change the level of magnification.
Use the arrow keys to move the image one pixel up,
down, left, or right within the magnify window. Be
sure to first map the magnify window by pressing button
3.
Press and one of the arrow keys to trim off one
pixel from any side of the image. You can closely
define the area of the image you want to crop with
button 2. Use the trimming keys for a more precise
measurement.
X RESOURCES
display options can appear on the command line or in your X
resource file. Options on the command line supersede values
specified in your X resource file. See X(1) for more
information on X resources.
All display options have a corresponding X resource. In
addition, display uses the following X resources:
background (class Background)
Specifies the preferred color to use for the image
window background. The default is #ccc.
borderColor (class BorderColor)
Specifies the preferred color to use for the image
window border. The default is black.
borderWidth (class BorderWidth)
Specifies the width in pixels of the image window
border. The default is 2.
font (class Font)
Specifies the name of the preferred font to use when
displaying text within the image window. The default
is 9x15, fixed, or 6x13 determined by the image window
size.
font[1-9] (class Font[1-9])
Specifies the name of the preferred font to use when
annotating the image window with text. The default
fonts are fixed, variable, 5x8, 6x10, 7x13bold,
8x13bold, 9x15bold, 10x20, and 12x24. Refer to IMAGE
ANNOTATION for more details.
foreground (class Foreground)
Specifies the preferred color to use for text within
the image window. The default is black.
iconGeometry (class IconGeometry)
Specifies the preferred size and position of the
application when iconified. It is not necessarily
obeyed by all window managers.
iconic (class Iconic)
This resource indicates that you would prefer that the
application's windows initially not be visible as if
the windows had be immediately iconified by you.
Window managers may choose not to honor the
application's request.
magnify (class Magnify)
specifies an integral factor by which the image should
be enlarged. The default is 2.
This value only affects the magnification window which
is invoked with button number 3 after the image is
displayed. Refer to BUTTONS for more details.
matteColor (class MatteColor)
Specify the color of windows. It is used for the
backgrounds of windows, menus, and notices. A 3D
effect is achieved by using highlight and shadow
colors derived from this color. Default value: #eee.
name (class Name)
This resource specifies the name under which resources
for the application should be found. This resource is
useful in shell aliases to distinguish between
invocations of an application, without resorting to
creating links to alter the executable file name. The
default is the application name.
pen[1-9] (class Pen[1-9])
Specifies the color of the preferred font to use when
annotating the image window with text. The default
colors are black, blue, green, cyan, gray, red,
magenta, yellow, and white. Refer to IMAGE ANNOTATION
for more details.
printCommand (class PrintCommand)
This command is executed whenever Print is issued (see
BUTTONS. In general, it is the command to print
Postscript to your printer. Default value: lpr.
title (class Title)
This resource specifies the title to be used for the
image window. This information is sometimes used by a
window manager to provide a header identifying the
window. The default is the image file name.
usePixmap (class UsePixmap)
Images are maintained as a XImage by default. Set this
resource to True to utilize a server Pixmap instead.
This option is useful if your image exceeds the
dimensions of your server screen and you intend to pan
the image. Panning is much faster with Pixmaps than
with a XImage. Pixmaps are considered a precious
resource, use them with discretion.
IMAGE PANNING
When an image exceeds the width or height of the X server
screen, display maps a small panning window. The rectangle
within the panning window shows the area that is currently
displayed in the the image window. To "pan" about the
image, press and drag the mouse within the panning window.
The panning rectangle moves with the mouse and the image
window is updated to reflect the location of the rectangle
within the panning window. When you have selected the area
of the image you wish to view, just release the mouse
button.
Use the arrow keys to pan the image one pixel up, down,
left, or right within the image window.
The panning window goes away if the image becomes smaller
than the dimensions of the X server screen.
If you force the panning window to withdraw, the image is
restored to its original size.
IMAGE ANNOTATION
An image is annotated with text interactively. There is no
command line argument to annotate an image. To begin, press
button 1 and choose Annotate Image from the command menu
(see BUTTONS). Alternatively, press a in the image window
(see KEYBOARD ACCELERATORS). To exit immediately, press
ESC.
A small window appears showing the location of the cursor in
the image window. You are now in annotate mode. To exit
immediately, press ESC. In annotate mode a button press has
a different effect than described in BUTTONS. Press a
button to affect this behavior:
1 Press to select a location within the image window to
begin entering text.
2 Press and drag to select a font from a pop-up menu.
Choose from these fonts:
fixed
variable
5x8
6x10
7x13bold
8x13bold
9x15bold
10x20
12x24
Other fonts can be specified by setting the X resources
font1 through font9. Refer to X RESOURCES for more
details.
3 Press and drag to select a font color from a pop-up
menu. Choose from these font colors:
black
blue
cyan
green
gray
red
magenta
yellow
white
Other font colors can be specified by setting the X
resources pen1 through pen9. Refer to X RESOURCES for
more details.
Choosing a font and its color is optional. The default font
is fixed and the default color is black. However, you must
choose a location to begin entering text and press button 1.
An underscore character will appear at the location of the
cursor where you pressed button 1. The cursor changes to a
pencil to indicate you are in text mode. To exit
immediately, press ESC.
In text mode, any key presses will display the character at
the location of the underscore and advance the underscore
cursor. Enter your text and once completed press ESC to
finish your image annotation. To correct errors press BACK
SPACE. To delete an entire line of text, press DELETE. Any
text that exceeds the boundaries of the image window is
automatically continued onto the next line.
Before exiting text mode, immediately after pressing the ESC
key, the image is permanently updated with the text you
entered. There is no way to `undo' your changes so be
careful to check your text before you press ESC.
The actual color you request for the font is saved in the
image. However, the color that appears in your image window
may be different. For example, on a monochrome screen the
text will appear black or white even if you choose the color
red as the font color. However, the image saved to a file
with -write will be written with red lettering. To assure
the correct color text in the final image, any PseudoClass
image is promoted to DirectClass (see miff(5)). To force a
PseudoClass image to remain PseudoClass, use -colors.
IMAGE COMPOSITING
An image composite is created interactively. There is no
command line argument to composite an image. To begin,
press button 1 and choose Composite Image from the command
menu (see BUTTONS). Alternatively, press c in the image
window (see KEYBOARD ACCELERATORS).
First a popup window is displayed requesting you to enter an
image name. Press RETURN, enter 'X:', or type a file name.
Press RETURN if you choose not to create a composite image.
When you specify X: as your file name, the filename has
special meaning. It specifies an X window by id, name, or
root. If no filename is specified, the window is selected
by clicking the mouse in the desired window. See import(1)
for details.
A small window appears showing the location of the cursor in
the image window. You are now in composite mode. To exit
immediately, press ESC. In composite mode a button press
has a different effect than described in BUTTONS. Press a
button to affect this behavior:
1 Press to select a location within image window to
composite your image.
2 Press and drag to select a composite operation from a
pop-up menu. Choose from these composite operations:
over
in
out
atop
xor
plus
minus
add
subtract
difference
replace
The operations behaves as follows:
over The result will be the union of the two image
shapes, with image obscuring image window in the
region of overlap.
in The result is simply image cut by the shape of
image window. None of the image data of image
window will be in the result.
out The resulting image is image with the shape of
image window cut out.
atop The result is the same shape as image image window,
with image obscuring image window where the image
shapes overlap. Note this differs from over
because the portion of image outside image window's
shape does not appear in the result.
xor The result is the image data from both image and
image window that is outside the overlap region.
The overlap region will be blank.
plus The result is just the sum of the image data.
Output values are clipped to 255 (no overflow).
This operation is independent of the alpha
channels.
minus The result of image - image window, with underflow
clipped to zero. The alpha channel is ignored (set
to 255, full coverage).
add The result of image + image window, with overflow
wrapping around (mod 256).
subtract The result of image - image window, with underflow
wrapping around (mod 256). The add and subtract
operators can be used to perform reversible
transformations.
difference
The result of abs(image - image window). This is
useful for comparing two very similar images.
replace The resulting image is image window replaced with
image. Here the alpha information is ignored.
The image compositor requires an alpha, or matte channel in
the image for some operations. This extra channel usually
defines a mask which represents a sort of a cookie-cutter
for the image. This is the case when alpha is 255 (full
coverage) for pixels inside the shape, zero outside, and
between zero and 255 on the boundary. If image does not
have an alpha channel, it is initialized with 0 for any
pixel matching in color to pixel location (0,0), otherwise
255.
Note that alpha information for image window is not retained
for colormapped X server visuals (e.g. StaticColor,
StaticColor, GrayScale, PseudoColor). Correct compositing
behavior may require a TrueColor or DirectColor visual or a
Standard Colormap.
Choosing a composite operator is optional. The default
operator is over. However, you must choose a location to
composite your image and press button 1. Press and hold
button 1 before releasing and an outline of the image will
appear to help you identify your location.
Immediately after releasing button 1, image window is
permanently updated with your composited image. There is no
way to `undo' your changes. Be careful when choosing your
location.
The actual colors of the composite image is saved. However,
the color that appears in image window may be different.
For example, on a monochrome screen image window will appear
black or white even though your composited image may have
many colors. If the image is saved to a file it is written
with the correct colors. To assure the correct colors are
saved in the final image, any PseudoClass image is promoted
to DirectClass (see miff(5)). To force a PseudoClass image
to remain PseudoClass, use -colors.
ENVIRONMENT
display
To get the default host, display number, and screen.
SEE ALSO
import(1), mogrify(1), convert(1), quantize(9), miff(5),
X(1), xstdcmap(1), more(1), compress(1)
COPYRIGHT
Copyright 1994 E. I. du Pont de Nemours & Company
Permission to use, copy, modify, distribute, and sell this
software and its documentation for any purpose is hereby
granted without fee, provided that the above copyright
notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting
documentation, and that the name of E. I. du Pont de Nemours
& Company not be used in advertising or publicity pertaining
to distribution of the software without specific, written
prior permission. E. I. du Pont de Nemours & Company makes
no representations about the suitability of this software
for any purpose. It is provided "as is" without express or
implied warranty.
E. I. du Pont de Nemours & Company disclaims all warranties
with regard to this software, including all implied
warranties of merchantability and fitness, in no event shall
E. I. du Pont de Nemours & Company be liable for any
special, indirect or consequential damages or any damages
whatsoever resulting from loss of use, data or profits,
whether in an action of contract, negligence or other
tortuous action, arising out of or in connection with the
use or performance of this software.
ACKNOWLEDGEMENTS
The MIT X Consortium for making network transparent graphics
a reality.
Rod Bogart and John W. Peterson, University of Utah. Image
compositing is loosely based on rlecomp of the Utah Raster
Toolkit.
Michael Halle, Spatial Imaging Group at MIT, for the initial
implementation of Alan Paeth's image rotation algorithm.
David Pensak, E. I. du Pont de Nemours & Company, for
providing a computing environment that made this program
possible.
Paul Raveling, USC Information Sciences Institute, for the
original idea of using space subdivision for the color
reduction algorithm.
AUTHORS
John Cristy, E.I. du Pont de Nemours & Company Incorporated
ImageMagick Last change: 10 October 1992