DISPLAY(1) DISPLAY(1)
NAME
display - display an image on any workstation running X
SYNOPSIS
display [ options ...] file [ [ options ...] file ...]
DESCRIPTION
Display is a machine architecture independent image pro-
cessing and display program. It can display an image on
any workstation display running an X server. Display
first determines the hardware capabilities of the worksta-
tion. 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 num-
ber of colors in the image is first reduced to match the
color resolution of the workstation before it is dis-
played.
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 cen-
tered 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 <width>x<height>{+-}<x offset>{+-}<y offset>
preferred size and location of the clipped image.
See X(1) for details about the geometry
ImageMagick 10 October 1992 1
DISPLAY(1) DISPLAY(1)
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 clipGe-
ometry (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 col-
ors 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 dis-
tances 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 Runlength-
Encoded.
ImageMagick 10 October 1992 2
DISPLAY(1) DISPLAY(1)
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 num-
ber 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 <width>x<height>
vertical and horizonal density of the image.
This option specifies an image density whose inter-
pretation changes with the type of image. The
default is 72 dots per inch in the horizonal and ver-
tical direction for Postscript. Text files default
to 80 characters in width and 60 lines in height.
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 work-
stations 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.
ImageMagick 10 October 1992 3
DISPLAY(1) DISPLAY(1)
-geometry <width>x<height>{+-}<x offset>{+-}<y offset>
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.
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 replica-
tion. 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, <x offset>
and <y offset> is relative to the root window. When
printing an image, <x offset> and <y offset> is rela-
tive to a Postscript page.
The equivalent X resource for this option is imageGe-
ometry (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 interlac-
ing 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
ImageMagick 10 October 1992 4
DISPLAY(1) DISPLAY(1)
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.
Monochrome images can benefit from error diffusion.
Use -dither with this option to diffuse the error.
-noise
reduce the noise in an image with a noise peak elimi-
nation filter.
The principal function of noise peak elimination fil-
ter is to smooth the objects within an image without
losing edge information and without creating unde-
sired 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
tranform image to span the full range of color val-
ues.
This is a contrast enhancement technique.
-quality value
JPEG quality setting.
Quality is 0 (worst) to 100 (best). The default is
75.
-reflect
create a "mirror image" by reflecting the image scan-
lines.
-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 loca-
tion (0,0).
-scale <width factor>x<height factor>
preferred size factors of the image.
This option behaves like -geometry except the width
and height values are relative instead of absolute.
The image size is multiplied by the width and height
factors to obtain the final image dimensions. If
ImageMagick 10 October 1992 5
DISPLAY(1) DISPLAY(1)
only one factor is specified, both the width and
height factors assume the value.
Factors may be fractional. To increase the size of
an image, use a scale factor greater than 1.0. To
decrease an image's size, use a scale factor less
than 1.0. Default is 1.0.
The equivalent X resource for this option is scaleGe-
ometry (class ScaleGeometry). See X RESOURCES for
details.
-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 represen-
tation of the source image with the fastest computa-
tional speed and the least amount of memory. How-
ever, the default depth is inappropriate for some
images. To assure the best representation, try val-
ues 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.
-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
ImageMagick 10 October 1992 6
DISPLAY(1) DISPLAY(1)
PseudoColor
TrueColor
DirectColor
default
visual id
The X server must support the visual you choose, oth-
erwise an error occurs. If a visual is not speci-
fied, 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.
By default, the image is stored in the MIFF image
format. If the number of unique colors in the image
exceed 65535, 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. If file has the
extension .Z, the file size is reduced using Lempel-
Ziv coding with compress. If file already exists,
you will be prompted as to whether it should be over-
written.
Use -compress to specify the type of image compres-
sion.
ImageMagick 10 October 1992 7
DISPLAY(1) DISPLAY(1)
The equivalent X resource for this option is write-
Filename (class WriteFilename). See X RESOURCES for
details.
In addition to those listed above, you can specify these
standard X resources as command line options: -back-
ground, -bordercolor, -borderwidth, -font, -foreground,
-iconGeometry, -iconic, -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 dis-
play 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.
file specifies the image filename. 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. Specify
file as - for standard input or output. If file has the
extension .Z, the file is decoded with uncompress.
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
Reflect
Rotate Right
Rotate Left
Half Size
Double Size
Restore
Annotate
Composite
Load
Write
Next
Previous
ImageMagick 10 October 1992 8
DISPLAY(1) DISPLAY(1)
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.
r Press to reflect the image scanlines.
/ Press to rotate the image 90 degrees clockwise.
\ Press to rotate the image 90 degrees counter-
clockwise.
< Press to half the image size.
> Press to double the image size.
o Press to restore the image to its original size.
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.
w Press to write the image to a file.
n Press to display the next image.
ImageMagick 10 October 1992 9
DISPLAY(1) DISPLAY(1)
p Press to display the previous image.
q Press to discard all images and exit program.
1-9 Press to change the level of magnification.
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 black.
borderColor (class BorderColor)
Specifies the preferred color to use for the image
window border. The default is white.
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 win-
dow 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 white.
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
ImageMagick 10 October 1992 10
DISPLAY(1) DISPLAY(1)
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.
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 ANNOTA-
TION for more details.
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.
IMAGE PANNING
When an image exceeds the width or height of the X server
screen, display maps a small panning window. The rectan-
gle within the panning window shows the area that is cur-
rently 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.
The panning window goes away if the image becomes smaller
than the dimensions of the X server screen.
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.
ImageMagick 10 October 1992 11
DISPLAY(1) DISPLAY(1)
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 under-
score cursor. Enter your text and once completed press
ImageMagick 10 October 1992 12
DISPLAY(1) DISPLAY(1)
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 win-
dow 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 Pseudo-
Class, 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 compos-
ite 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 win-
dow is selected by clicking the mouse in the desired win-
dow. See XtoPS(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
ImageMagick 10 October 1992 13
DISPLAY(1) DISPLAY(1)
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 win-
dow, 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 chan-
nels.
minus The result of image - image window, with under-
flow 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 under-
flow wrapping around (mod 256). The add and sub-
tract 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.
ImageMagick 10 October 1992 14
DISPLAY(1) DISPLAY(1)
The image compositor requires an alpha, or matte channel
in the image for some operations. This extra channel usu-
ally 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), oth-
erwise 255.
Note that alpha information for image window is not
retained for colormapped X server visuals (e.g. Static-
Color, StaticColor, GrayScale, PseudoColor). Correct com-
positing behavior may require a TrueColor or DirectColor
visual or a Standard Colormap.
Choosing a composite operator is optional. The default
operator is Ifover. 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 per-
manently 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. How-
ever, the color that appears in image window may be dif-
ferent. 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 Pseudo-
Class image is promoted to DirectClass (see MIFF(5)). To
force a PseudoClass image to remain PseudoClass, use -col-
ors.
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 1992 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
ImageMagick 10 October 1992 15
DISPLAY(1) DISPLAY(1)
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 spe-
cific, 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 war-
ranties 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 tortious action, arising out of or in connection
with the use or performance of this software.
ACKNOWLEDGEMENTS
The MIT X Consortium for making network transparent graph-
ics 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 ini-
tial implementation of Alan Paeth's image rotation algo-
rithm.
David Pensak, E. I. du Pont de Nemours & Company, for pro-
viding a computing environment that made this program pos-
sible.
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 Incorpo-
rated
ImageMagick 10 October 1992 16