MONTAGE(1) X Version 11(1 July 1991) 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
appearing just above the individual tile.
The composite image is constructed in the following manner. 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 command 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
maintainted.
Next the composite image is initialized with the color specified by the
-bordercolor command line argument or X resource. The width and height
of the composite image is determined by the maximum tile size, the number
of tiles per row, the border width and height, 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. This value can be
specified with -tiles_per_row. The border width and height 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 -foreground
command line argument or X resource. Note, that if the background and
foreground colors are the same, labels will not appear.
Finally, each image is set onto the composite image with its name
centered just above it. The individual images are centered within the
width of the tiled area. The order of the images is the same as they
appear on the command line unless the images have a scene keyword. If a
scene number is specified in each image, then the images are tiled onto
the composite in the order of their scene number. The final argument on
the command line is the name assigned to the composite image. The image
is written in the MIFF format and may by viewed or printed with
display(1). See MIFF FILE FORMAT for details on the MIFF format.
EXAMPLES
To create a montage of a cockatoo, a parrot, and a hummingbird and write
it to a file called birds, use:
10/89 Page 1
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
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 10 pixels wide, 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
-clip <width>x<height>+<x offset>+<y offset>
preferred size and location of the clipped image. See X(1) for
details about the geometry specification.
Use clipping to tile only a particular area of an image.
The equivalent X resource for this option is clipGeometry (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 colors than specified with this option will
remain unchanged. Refer to COLOR REDUCTION ALGORITHM for more
details.
Note, options -dither and -treedepth affect the color reduction
algorithm.
-compress type
the type of image compression: QEncoded or RunlengthEncoded.
This option specifies the type of image compression for the
composite image. See MIFF FILE FORMAT for details.
Specify +compress to store the binary image in an uncompressed
format. The default is the compression type of the specified image
file.
-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.
Page 2 10/89
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(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, -gray, 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 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.
-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
specified as border width and border height.
The equivalent X resource for this option is imageGeometry (class
ImageGeometry). See X RESOURCES for details.
-gray
transform the image to gray scale colors.
-monochrome
transform the image to black and white.
Monochrome images can benefit from error diffusion. Use -dither
with this option to diffuse the error.
-reflect
create a "mirror image" by reflecting the image scanlines.
-rotate degrees
apply Paeth image rotation to the image.
-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.
10/89 Page 3
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
-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 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 COLOR REDUCTION ALGORITHM for
more details.
The -colors, -gray, or -monochrome option is required for this
option to take effect.
In addition to those listed above, you can specify these standard X
resources as command line options: -background, -bordercolor,
-borderwidth, -font, or -foreground. 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 second 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 +montage to apply image transformations without viewing them on
the X server. Or, specify +dither to not apply error diffusion to an
image.
Specify file as - for standard input or output. If file has the
extension .Z, the file is decoded with uncompress.
X RESOURCES
Montage options can appear on the command line or in your X resource
file. Options on the command line supercede 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, the
montage program uses the following X resources:
background (class Background)
Specifies the preferred color to use for the composite image
background. The default is black.
borderColor (class BorderColor)
Specifies the preferred color to use for the composite image border.
The default is white.
Page 4 10/89
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
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 composite image size.
foreground (class Foreground)
Specifies the preferred color to use for text within the composite
image. The default is white.
COLOR REDUCTION ALGORITHM
This section describes how Montage performs color reduction in an image.
To fully understand this section, you should have a knowledge of basic
imaging techniques and the tree data structure and terminology.
For purposes of color allocation, an image is a set of n pixels, where
each pixel is a point in RGB space. RGB space is a 3-dimensional vector
space, and each pixel, pi, is defined by an ordered triple of red,
green, and blue coordinates, (ri, gi, bi).
Each primary color component (red, green, or blue) represents an
intensity which varies linearly from 0 to a maximum value, cmax, which
corresponds to full saturation of that color. Color allocation is
defined over a domain consisting of the cube in RGB space with opposite
vertices at (0,0,0) and (cmax,cmax,cmax). Montage requires cmax = 255.
The algorithm maps this domain onto a tree in which each node represents
a cube within that domain. In the following discussion, these cubes are
defined by the coordinate of two opposite vertices: The vertex nearest
the origin in RGB space and the vertex farthest from the origin.
The tree's root node represents the the entire domain, (0,0,0) through
(cmax,cmax,cmax). Each lower level in the tree is generated by
subdividing one node's cube into eight smaller cubes of equal size. This
corresponds to bisecting the parent cube with planes passing through the
midpoints of each edge.
The basic algorithm operates in three phases: Classification, Reduction,
and Assignment. Classification builds a color description tree for the
image. Reduction collapses the tree until the number it represents, at
most, is the number of colors desired in the output image. Assignment
defines the output image's color map and sets each pixel's color by
reclassification in the reduced tree.
Classification begins by initializing a color description tree of
sufficient depth to represent each possible input color in a leaf.
However, it is impractical to generate a fully-formed color description
tree in the classification phase for realistic values of cmax. If color
components in the input image are quantized to k-bit precision, so that
10/89 Page 5
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
cmax = 2k-1, the tree would need k levels below the root node to allow
representing each possible input color in a leaf. This becomes
prohibitive because the tree's total number of nodes is
≳ k
i=1 8k
A complete tree would require 19,173,961 nodes for k = 8, cmax = 255.
Therefore, to avoid building a fully populated tree, Montage: (1)
Initializes data structures for nodes only as they are needed; (2)
Chooses a maximum depth for the tree as a function of the desired number
of colors in the output image (currently log4(colormap size)+2). A tree
of this 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.
Therefore, the caller can request a specific tree depth.
For each pixel in the input image, classification scans downward from the
root of the color description tree. At each level of the tree, it
identifies the single node which represents a cube in RGB space
containing the pixel's color. It updates the following data for each
such node:
n1: Number of pixels whose color is contained in the RGB cube which this
node represents;
n2: Number of pixels whose color is not represented in a node at lower
depth in the tree; initially, n2 = 0 for all nodes except leaves
of the tree.
Sr, Sg, Sb:
Sums of the red, green, and blue component values for all pixels not
classified at a lower depth. The combination of these sums and n2
will ultimately characterize the mean color of a set of pixels
represented by this node.
Reduction repeatedly prunes the tree until the number of nodes with n2 >
0 is less than or equal to the maximum number of colors allowed in the
output image. On any given iteration over the tree, it selects those
nodes whose n1 count is minimal for pruning and merges their color
statistics upward. It uses a pruning threshold, np, to govern node
selection as follows:
np = 0
while number of nodes with (n2 > 0) > required maximum number of colors
prune all nodes such that n1 <= np
Set np to minimum n1 in remaining nodes
When a node to be pruned has offspring, the pruning procedure invokes
itself recursively in order to prune the tree from the leaves upward.
The values of n2 Sr, Sg, and Sb in a node being pruned are always added
to the corresponding data in that node's parent. This retains the pruned
node's color characteristics for later averaging.
Page 6 10/89
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
For each node, n2 pixels exist for which that node represents the
smallest volume in RGB space containing those pixel's colors. When n2 >
0 the node will uniquely define a color in the output image. At the
beginning of reduction, n2 = 0 for all nodes except the leaves of the
tree which represent colors present in the input image.
The other pixel count, n1, indicates the total number of colors within
the cubic volume which the node represents. This includes n1 - n2 pixels
whose colors should be defined by nodes at a lower level in the tree.
Assignment generates the output image from the pruned tree. The output
image consists of two parts: (1) A color map, which is an array of
color descriptions (RGB triples) for each color present in the output
image; (2) A pixel array, which represents each pixel as an index into
the color map array.
First, the assignment phase makes one pass over the pruned color
description tree to establish the image's color map. For each node with
n2 > 0, it divides Sr, Sg, and Sb by n2. This produces the mean color of
all pixels that classify no lower than this node. Each of these colors
becomes an entry in the color map.
Finally, the assignment phase reclassifies each pixel in the pruned tree
to identify the deepest node containing the pixel's color. The pixel's
value in the pixel array becomes the index of this node's mean color in
the color map.
MEASURING COLOR REDUCTION ERROR
Depending on the image, the color reduction error may be obvious or
invisible. Images with high spatial frequencies (such as hair or grass)
will show error much less than pictures with large smoothly shaded areas
(such as faces). This is because the high-frequency contour edges
introduced by the color reduction process are masked by the high
frequencies in the image.
To measure the difference between the original and color reduced images
(the total color reduction error), Montage sums over all pixels in an
image the distance squared in RGB space between each original pixel value
and its color reduced value. Montage prints several error measurements
including the mean error per pixel, the normalized mean error, and the
normalized maximum error.
The normalized error measurement can be used to compare images. In
general, the closer the mean error is to zero the more the quantized
image resembles the source image. Ideally, the error should be
perceptually-based, since the human eye is the final judge of
quantization quality.
These errors are measured and printed when -verbose and -colors are
specified on the command line:
10/89 Page 7
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
mean error per pixel:
is the mean error for any single pixel in the image.
normalized mean square error:
is the normalized mean square quantization error for any single
pixel in the image.
This distance measure is normalized to a range between 0 and 1. It
is independent of the range of red, green, and blue values in the
image.
normalized maximum square error:
is the largest normalized square quantization error for any single
pixel in the image.
This distance measure is normalized to a range between 0 and 1. It
is independent of the range of red, green, and blue values in the
image.
MIFF FILE FORMAT
The Machine Independent File Format is described in this section.
A MIFF image file consist of two sections. The first section is composed
of keywords describing the image in text form. The next section is the
binary image data. The two sections are separated by a : character
immediately followed by a newline. Generally, the first section has a
form-feed and newline proceeding the : character. You can then list the
image keywords with more, without printing the binary image that follows
the : separator.
Each keyword must be separated by at least one space but can be separated
with control characters such a form-feed or newline.
A list of valid keywords follows:
class=DirectClass | PseudoClass
identifies the type of binary image stored within the file.
This keyword is optional. If it is not specified, a DirectClass
image format is assumed. An explanation of DirectClass and
PseudoClass image data follows this list.
colors=value
specifies the number of colors in the image, and for pseudo-color
images the size of the colormap.
This keyword is optional. However, if a colormap size is not
specified, a linear colormap is assumed for pseudo-color images.
columns=value
is a required keyword and specifies the number of columns, or width
in pixels, of the image.
Page 8 10/89
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
compression=QEncoded | RunlengthEncoded
identifies how the image stored within the file is compressed.
This keyword is optional. If it is not specified, the image is
assumed to be uncompressed. A detailed explanation of runlength-
encoded and Q-coder image compression follows this list.
id=ImageMagick
is a required keyword and identifies this file as a MIFF image.
packets=value
specifies the number of compressed color packets in the image data
section.
This keyword is optional, but recommended, for runlength-encoded
image compression. It is required for Q-encoded image compression.
A detailed explanation of image compression follows this list.
rows=value
is a required keyword and specifies the number of rows, or height in
pixels, of the image.
scene=value
is an optional keyword and is a reference number for sequencing of
images.
This keyword is typically useful for animating a sequence of images.
Comments can be included in the keyword section. Comments must begin
with a { character and end with a } character.
An example keyword section follows:
{
Rendered via Dore by Sandy Hause.
}
id=ImageMagick
class=PseudoClass colors=256
compression=RunlengthEncoded packets=27601
columns=1280 rows=1024
scene=1
^L
:
The binary image data that follows the keyword text is stored in one of
two binary classes as specified by the class keyword: DirectClass or
PseudoClass.
Use the DirectClass class to store continuous-tone images. DirectClass
requires that the image pixels immediately follow the keyword text and be
stored as binary red, green, and blue intensity values. The total number
of pixels expected is equal to the number of pixel columns times the
10/89 Page 9
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
number of pixel rows as specified by the columns and rows keywords.
If the compression keyword is not specified, a red, green, and blue byte
in that order is expected for each pixel of the image.
If compression is QEncoded, each red, green, and blue byte intensity
value is encoded using the Q-coder compression algorithm. Use the
packets keyword to specify the total number of Q-encoded packets that
comprise the image. Refer to "Sofware implementations of the Q-Coder",
by Mitchell, J. L. and Pennebaker, W.B. (IBM Journal Res. Development,
Volume 32, Number 6, November 1988, pages 753 - 774) for implementation
specific details.
If compression is RunlengthEncoded, each red, green, and blue byte
intensity value is followed by a count byte. This value specifies the
number of horizonally contiguous pixels in the image of that color. The
count (0-255) is one less than the actual number of contiguous pixels;
thus a single packet can represent from 1 up to 256 identical pixels.
The total number of pixels specified by the individual count bytes must
add up to the number of pixel columns times the number of pixel rows as
specified by the columns and rows keywords. Use packets to specify the
total number of runlength-encoded packets that comprise the image.
Use the PseudoClass class to store pseudo-color images. PseudoClass
requires that the image colormap and pseudo-color pixels immediately
follow the keyword text. The colormap is stored as contiguous red,
green, and blue intensity values. The number of intensity values
expected is determined by the colors keyword. Note, an image colormap is
restricted to at most 65535 entries. The binary pseudo-color image is
stored as indexes into the colormap. If the colormap size exceeds 256
entries, then each colormap index is two bytes each with the most-
significant-byte first. The total number of pixels expected is equal to
the number of pixel columns times the number of pixel rows as specified
by the columns and rows keywords.
If the compression keyword is not specified, a colormap index is expected
for each pixel of the image.
If compression is QEncoded, each colormap index is encoded using the Q-
coder compression algorithm. Use the packets keyword to specify the
total number of Q-encoded packets comprise the image. Refer to "Sofware
implementations of the Q-Coder", by Mitchell, J. L. and Pennebaker, W.B.
(IBM Journal Res. Development, Volume 32, Number 6, November 1988, pages
753 - 774) for implementation specific details.
If compression is RunlengthEncoded, each colormap index is followed by a
count byte. This value specifies the number of horizonally contiguous
pixels in the image of that color. The count (0-255) is one less than
the actual number of contiguous pixels; thus a single packet can
represent from 1 up to 256 identical pixels. The total number of pixels
specified by the individual count bytes must add up to the number of
pixels expected in the image as specified by the columns and rows
Page 10 10/89
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
keywords. Use packets to specify the total number of runlength-encoded
packets that comprise the image.
FEATURES
Montage memory requirements is proportionate to the area of the image.
Montage does not complain when it encounters a keyword in an image file
it does not understand.
ENVIRONMENT
DISPLAY
To get the default host, display number, and screen.
SEE ALSO
X(1), display(1), more(1), compress(1)
COPYRIGHT
Copyright 1991 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 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 graphics a reality.
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. With
Paul's permission, the COLOR REDUCTION ALGORITHM section is a adaptation
from a document he wrote.
10/89 Page 11
MONTAGE(1) X Version 11(1 July 1991) MONTAGE(1)
AUTHORS
John Cristy, E.I. du Pont de Nemours & Company Incorporated
Page 12 10/89