MONTAGE(1) MONTAGE(1)
NAME
montage - creates a composite image by combining several
separate images
SYNOPSIS
montage [ options ...] file [ [ options ...] file ...]
file
DESCRIPTION
Montage creates a composite image by combining several
separate images. The images are tiled on the composite
image with the name of the image optionally appearing just
below the individual tile.
The composite image is constructed in the following man-
ner. First, each image specified on the command line,
except for the last, is scaled to fit the maximum tile
size. The maximum tile size by default is 256x256. It
can be modified with the -geometry command line argument
or X resource. See OPTIONS for more information on com-
mand line arguments. See X(1) for more information on X
resources. Note that the maximum tile size need not be a
square. The original aspect ratio of each image is main-
tainted unless +aspectratio is specified.
Next the composite image is initialized with the color
specified by the -background command line argument or X
resource. The width and height of the composite image is
determined by the title specified, the maximum tile size,
the number of tiles per row, the tile border width and
height, the image border width, and the label height. The
number of tiles per row specifies how many images are to
appear in each row of the composite image. The default is
to have an equal number of images in each row and column
of the composite. A specific value is specified with
-tilesperrow. The tile border width and height, and the
image border width defaults to the value of the X resource
-borderwidth. It can be changed with the -borderwidth or
-geometry command line argument or X resource. The label
height is determined by the font you specify with the
-font command line argument or X resource. If you do not
specify a font, a font is choosen that allows the name of
the image to fit the maximum width of a tiled area. The
label colors is determined by the -background and -fore-
ground command line argument or X resource. Note, that if
the background and foreground colors are the same, labels
will not appear.
Initially, the composite image title is placed at the top
if one is specified (refer to -foreground X resource).
Next, each image is set onto the composite image, sur-
rounded by its border color, with its name centered just
below it. The individual images are left-justified within
the width of the tiled area. The order of the images is
ImageMagick 10 October 1992 1
MONTAGE(1) MONTAGE(1)
the same as they appear on the command line unless the
images have a scene keyword. If a scene number is speci-
fied in each image, then the images are tiled onto the
composite in the order of their scene number. Finally,
the last argument on the command line is the name assigned
to the composite image. By default, the image is written
in the MIFF format and can be viewed or printed with dis-
play(1).
You can specify a particular image format by prefixing
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 for-
mats. 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 overwritten.
EXAMPLES
To create a montage of a cockatoo, a parrot, and a hum-
mingbird and write it to a file called birds, use:
montage cockatoo.miff parrot.miff hummingbird.miff
birds.miff
To tile several bird images so that they are at most 256
pixels in width and 192 pixels in height, surrounded by a
red border, and separated by 10 pixels of background
color, use:
montage -geometry 256x192+10+10 -bordercolor red
birds.* montage.miff
To create an unlabeled parrot image, 640 by 480 pixels,
and surrounded by a border of black, use:
montage +display -geometry 640x480 -bordercolor black
parrot.miff bird.miff
OPTIONS
-aspectratio
The original aspect ratio of each image is adhered to
unless +aspectratio is specfified.
That is, as each image is tiled onto the composite
image it is scaled to fit the maximum width and
height of the tiled area while respecting the aspect
ratio of the original image. +aspectratio means the
image is scaled to exactly the dimensions of the
tiled image as specified by -geometry.
-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 2
MONTAGE(1) MONTAGE(1)
specification.
Use clipping to tile only a particular area of an
image.
The equivalent X resource for this option is clipGe-
ometry (class ClipGeometry). See X RESOURCES for
details.
-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.
-compose operator
the type of image composition.
By default, each of the composite image pixels are
replaced by the cooresponding image tile pixel. You
can choose an alternate composite operation:
over
in
out
atop
xor
plus
minus
add
subtract
difference
replace
ImageMagick 10 October 1992 3
MONTAGE(1) MONTAGE(1)
The operations behaves as follows:
over The result will be the union of the two image
shapes, with image obscuring composite image in
the region of overlap.
in The result is simply image cut by the shape of
image window. None of the image data of compos-
ite image will be in the result.
out The resulting image is image with the shape of
composite image cut out.
atop The result is the same shape as image composite
image, with image obscuring composite image where
the image shapes overlap. Note this differs from
over because the portion of image outside compos-
ite image's shape does not appear in the result.
xor The result is the image data from both image and
composite image 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 - composite image, with
underflow clipped to zero. The alpha channel is
ignored (set to 255, full coverage).
add The result of image + composite image, with over-
flow wrapping around (mod 256).
subtract The result of image - composite image, with
underflow wrapping around (mod 256). The add and
subtract operators can be used to perform
reversible transformations.
difference
The result of abs(image - composite image). This
is useful for comparing two very similar images.
replace The resulting image is composite image 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 repre-
sents a sort of a cookie-cutter for the image.
This is the case when alpha is 255 (full cover-
age) for pixels inside the shape, zero outside,
ImageMagick 10 October 1992 4
MONTAGE(1) MONTAGE(1)
and between zero and 255 on the boundary. If
image does not have an alpha channel, it is ini-
tialized with 0 for any pixel matching in color
to pixel location (0,0), otherwise 255 (to work
properly borderwidth must be 0).
-compress type
the type of image compression: QEncoded or Runlength-
Encoded.
This option specifies the type of image compression
for the composite image. 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.
-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).
Specify +display if an X server is not available.
The label font is obtained from the X server. If
none is available, the composite image will not have
labels.
-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.
-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
ImageMagick 10 October 1992 5
MONTAGE(1) MONTAGE(1)
0.8 to 2.3.
-geometry <width>x<height>+<border width>+<border height>
preferred tile and border size of each tile of the
composite image. See X(1) for details about the
geometry specification. By default, the tile size is
256x256 and there is no border.
The tile size you specify is a maximum size. Each
image is scaled to fit the maximum size while still
retaining its original aspect ratio. Each image is
surrounded by a border whose size in pixels is speci-
fied as <border width> and <border height> and whose
color is the background color.
The equivalent X resource for this option is imageGe-
ometry (class ImageGeometry). See X RESOURCES for
details.
-gravity direction
direction image gravitates to within a tile. See
X(1) for details about the gravity specification.
A tile of the composite image is a fixed width and
height. However, the image within the tile may not
fill it completely (see -aspectratio). The direc-
tion you specify indicates where to position the
image within the tile. For example Center gravity
forces the image to be centered within the tile. By
default, the image gravity is Center.
-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...).
-monochrome
transform the image to black and white.
Monochrome images can benefit from error diffusion.
Use -dither with this option to diffuse the error.
-quality value
JPEG quality setting.
Quality is 0 (worst) to 100 (best). The default is
75.
ImageMagick 10 October 1992 6
MONTAGE(1) MONTAGE(1)
-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).
-tilesperrow value
specifies how many images are to appear in each row
of the composite image. The default is to have an
equal number of images in each row and column of the
composite.
-treedepth value
Normally, this integer value is zero or one. A zero
or one tells Montage 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 write the
image.
In addition to those listed above, you can specify these
standard X resources as command line options: -back-
ground, -bordercolor, -borderwidth, -font, -foreground,
-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
montage two images, the first with 32 colors and the sec-
ond with only 16 colors, use:
montage -colors 32 cockatoo.1 -colors 16 cockatoo.2
cockatoo.miff
Change - to + in any option above to reverse its effect.
For example, specify +dither to not apply error diffusion
ImageMagick 10 October 1992 7
MONTAGE(1) MONTAGE(1)
to an image.
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 as the
filename suffix (i.e. image.ps). See convert(1) for a
list of valid image formats. Specify file as - for stan-
dard input or output. If file has the extension .Z, the
file is decoded with uncompress.
Note, a composite MIFF image displayed to an X server with
display behaves differently than other images. You can
think of the composite as a visual image directory.
Choose a particular tile of the composite and press a but-
ton to display it. See display(1) and MIFF(5) for
details.
X RESOURCES
Montage 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 montage options have a corresponding X resource. In
addition, montage uses the following X resources:
background (class Background)
Specifies the preferred color to use for the compos-
ite image background. The default is black.
borderColor (class BorderColor)
Specifies the preferred color to use for the compos-
ite image border. The default is white.
borderWidth (class BorderWidth)
Specifies the width in pixels of the composite image
border. The default is 2.
font (class Font)
Specifies the name of the preferred font to use when
displaying text within the composite image. The
default is 9x15, fixed, or 5x8 determined by the com-
posite image size.
foreground (class Foreground)
Specifies the preferred color to use for text within
the composite image. The default is white.
title (class Title)
This resource specifies the title to be placed at the
top of the composite image. The default is not to
place a title at the top of the composite image.
ImageMagick 10 October 1992 8
MONTAGE(1) MONTAGE(1)
ENVIRONMENT
DISPLAY
To get the default host, display number, and screen.
SEE ALSO
display(1), mogrify(1), convert(1), X(1), Quantize(9),
MIFF(5), 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
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.
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 9