ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
NAME
animate - display a sequence of images on any workstation running X
SYNOPSIS
animate [ options ...] file [ [ options ...] file ...]
DESCRIPTION
Animate displays a sequence of images in the MIFF format on any
workstation display running an X server. Animate first determines the
hardware capabilities of the workstation. If the number of unique colors
in an 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/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/pixels device.
To prevent colormap flashing, the use of a Standard Colormap or static
visual is recommended. Refer to the -map and -visual in OPTIONS.
EXAMPLES
To animate a cockatoo image sequence while using the Standard Colormap
"best", use:
xstdcmap -best
animate -map best cockatoo.*
width and 480 pixels in height and position the window at location
(200,200), use:
animate -geometry 640x480+200+200 cockatoo.*
To animate an image of a cockatoo without a border centered on a
backdrop, use:
animate -backdrop -borderwidth 0 cockatoo.*
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 sequence.
The color of the backdrop is specified as the background color.
Refer to X RESOURCES for details.
10/89 Page 1
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
-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 apply image processing options, or display, 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.
-delay milliseconds
display the next image after pausing.
This option is useful for regulating the display of the sequence of
images. milliseconds milliseconds must expire before the display of
the next image. The default is to display each image without delay.
-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, -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.
Page 2 10/89
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(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 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, the x and y offset in the
geometry specification is relative to the root window.
The equivalent X resource for this option is imageGeometry (class
ImageGeometry). See X RESOURCES for details.
-gray
transform the image to gray scale colors.
-map type
animate images 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 xcmap(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.
-reflect
create a "mirror image" by reflecting the image scanlines.
-rotate degrees
apply Paeth image rotation to the image.
10/89 Page 3
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
-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 only one factor is specified, both the width and
height factors assume the value.
Factors may be fractional. For example, a factor of 1.5 will
increase the image size by one and one-half.
The equivalent X resource for this option is scaleGeometry (class
ScaleGeometry). See X RESOURCES for details.
-treedepth value
Normally, this integer value is zero or one. A zero or one tells
Animate 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.
-visual type
animate images 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 screen is
choosen.
In addition to those listed above, you can specify these standard X
resources as command line options: -background, -bordercolor,
-borderwidth, -font, -foreground, -iconGeometry, -iconic, -name, or
Page 4 10/89
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
-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 animate two images, the first with 32 colors and
the second with only 16 colors, use:
animate -colors 32 cockatoo.1 -colors 16 cockatoo.2
Change - to + in any option above to reverse its effect. For example,
specify +animate 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.
BUTTONS
1 Press and drag to select a command from a pop-up menu. Choose from
these commands:
Play
Step
Repeat
Auto Reverse
Forward
Reverse
Image Info
Quit
KEYS
0-9 Press to change the level of delay. Refer to -delay for more
information.
p Press to animate the sequence of images.
s Press to display the next image in the sequence.
. Press to continually display the sequence of images.
a Press to automatically reverse the sequence of images.
f Press to animate in the forward direction.
r Press to animate in the reverse direction.
i Press to display information about the image. Press any key or
button to erase the information.
This information is printed: image name; image size; and the total
number of unique colors in the image.
10/89 Page 5
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
q Press to discard all images and exit program.
X RESOURCES
Animate 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 animate options have a corresponding X resource. In addition, the
animate program 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 5x8
determined by the image window size.
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 application's request.
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.
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
some sort of header identifying the window. The default is the
Page 6 10/89
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
image file name.
COLOR REDUCTION ALGORITHM
This section describes how Animate 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). Animate 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
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, Animate: (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
10/89 Page 7
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
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.
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.
Page 8 10/89
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
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), Animate sums over all pixels in an
image the distance squared in RGB space between each original pixel value
and its color reduced value. Animate 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:
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.
10/89 Page 9
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
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.
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.
Page 10 10/89
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
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
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,
10/89 Page 11
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
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
keywords. Use packets to specify the total number of runlength-encoded
packets that comprise the image.
FEATURES
Although Animate will display an image on a server with an immutable
colormap, the image quality may suffer as compared to a server with a
read/write colormap.
Page 12 10/89
ANIMATE(1) X Version 11(1 July 1991) ANIMATE(1)
Animate memory requirements is proportionate to the area of the image.
Animate 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), xcmap(1), import(1), XtoPS(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.
AUTHORS
John Cristy, E.I. du Pont de Nemours & Company Incorporated
10/89 Page 13