.ds Vv 1.2.14
.TH VistaIOImage 3 "12 April 1994" "VistaIO Version \*(Vv"
.SH NAME
VistaIOImage \- image representation
.SH SYNOPSIS
.nf
.B #include <vistaio.h>
.PP
.B VistaIOImage \fIimage\fP;
.fi
.SH DESCRIPTION
.SS Introduction
Vista represents an image as one or more two-dimensional arrays of pixel
values. Each two-dimensional array, called a \fIband\fP, has the same size,
which is expressed as a number of rows and a number of columns. Multiple
bands may, for example, be used to represent multiple color components,
multiple frames of a motion sequence, the real and imaginary components of
a complex image, or some combination of these. Besides pixel data, an image
may also has an arbitrary list of attributes associated with it.
.PP
An image in memory is referred to by the C pointer type \fBVistaIOImage\fP. In 
data files it's identified by the type name \fBimage\fP, and in memory, by 
the \fBVistaIORepnKind\fP code \fBVistaIOImageRepn\fP. Since it is a standard object 
type with built-in support in the Vista library, images can be read from 
data files, written to data files, and manipulated as part of attribute 
lists by routines such as \fBVistaIOReadFile\fP(3), \fBVistaIOWriteFile\fP(3), and 
\fBVistaIOGetAttr\fP(3). 
.SS "Creating and Destroying Images"
The following routines create and destroy images.
.HP 10n
.na
.nh
.B VistaIOImage VistaIOCreateImage (int \fInbands\fP, int\ \fInrows\fP, 
.B int\ \fIncolumns\fP, VistaIOPixelRepn \fIpixel_repn\fP)
.ad
.hy
.IP "" 0.5i
\fBVistaIOCreateImage\fP allocates memory for a new image with the specified
numbers of bands, rows, and columns. Its pixel values are not initialized,
and it is given an empty attribute list. The \fIpixel_repn\fP argument is
described below, under ``Pixel Representation''. (See
\fBVistaIOCreateImage\fP(3) for details.)
.PP
.B void VistaIODestroyImage (VistaIOImage \fIimage\fP)
.IP
\fBVistaIODestroyImage\fP releases the memory occupied by \fIimage\fP, including
that occupied by its pixel data and attribute list.
.SS "Image Size"
An image's numbers of bands, row, and columns are sometimes abbreviated as 
\fBnbands\fP, \fBnrows\fP, and \fBncolumns\fP. The following macros access 
those numbers.
.PP
.B int VistaIOImageNBands (VistaIOImage \fIimage\fP)
.PP
.B int VistaIOImageNRows (VistaIOImage \fIimage\fP)
.PP
.B int VistaIOImageNColumns (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOImageNBands\fP, \fBVistaIOImageNRows\fP, \fBVistaIOImageNColumns\fP return
the number of bands, rows, and columns that \fIimage\fP has. 
.PP
.B int VistaIOImageNPixels (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOImageNPixels\fP returns the number of pixel values \fIimage\fP has 
altogether (i.e., the product \fBnbands\fP * \fBnrows\fP * \fBncolumns\fP). 
.SS "Pixel Representation"
An image's pixel values may have any of the following types: \fBVistaIOBit\fP, 
\fBVistaIOUByte\fP, \fBVistaIOSByte\fP, \fBVistaIOShort\fP, \fBVistaIOLong\fP, \fBVistaIOFloat\fP, or 
\fBVistaIODouble\fP. VistaIOariables meant to hold pixel values or 
pointers to pixel values should be defined using these same types (rather 
than built-in C types such as \fBshort\fP and \fBlong\fP) to ensure 
software portability. 
.PP
The following macros return information about an image's pixel 
representation: 
.PP
.B VistaIORepnKind VistaIOPixelRepn (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOPixelRepn\fP returns a code indicating \fIimage\fP's pixel 
representation. If \fIimage\fP has \fBVistaIOBit\fP pixels, for example, 
it returns \fBVistaIOBitRepn\fP. 
.PP
.B size_t VistaIOPixelSize (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOPixelSize\fP returns the size, in bytes, used for storing a single 
pixel of \fIimage\fP (i.e, a pixel within a single band, row, and column). 
This value depends on machine architecture. 
.PP
.B int VistaIOPixelPrecision (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOPixelPrecision\fP returns the minimum size, in bits, needed for 
representing a single pixel of \fIimage\fP. This value does not depend on 
machine architecture, but only on the kind of pixel value representation 
used by \fIimage\fP. If \fIimage\fP has \fBVistaIOBit\fP pixels, for example, 
this macro returns 1. 
.PP
.B VistaIOStringConst VistaIOPixelRepnName (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOPixelRepnName\fP returns a string describing the type of pixel value
representation used by \fIimage\fP. For example, if \fIimage\fP has
\fBVistaIOBit\fP pixels, the string ``bit'' is returned.
.PP
.B VistaIODouble VistaIOPixelMaxValue (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOPixelMaxValue\fP returns the maximum value that a pixel of \fIimage\fP
may have. For example, if \fIimage\fP has \fBVistaIOSByte\fP pixels, it returns
127.0.
.PP
.B VistaIODouble VistaIOPixelMinValue (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOPixelMinValue\fP returns the minimum value that a pixel of \fIimage\fP
may have. For example, if \fIimage\fP has \fBVistaIOSByte\fP pixels, it returns
\-128.0.
.PP
.B size_t VistaIOImageSize (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOImageSize\fP returns the size, in bytes, of \fIimage\fP's block of 
pixel data, which contains the values of all pixels in all bands. This 
value depends on machine architecture. 
.SS "Pixel VistaIOalues"
A particular pixel value is indexed by a band number, a row number, and a
column number. Bands, rows, and columns are numbered consecutively from
zero. Rows number down and columns number to the right so that row 0,
column 0 is at the upper-left corner of the image.
.HP 10n
.na
.nh
.B \fItype\fP VistaIOPixel (VistaIOImage \fIimage\fP, int \fIband\fP,
.B int\ \fIrow\fP, int\ \fIcolumn\fP, \fItype\fP)
.ad
.hy
.IP "" 0.5i
\fBVistaIOPixel\fP accesses the pixel at a specified band, row and column in an 
image whose pixels are of a specified type. The pixel type, \fItype\fP, 
must be one of \fBVistaIOBit\fP, \fBVistaIOUByte\fP, \fBVistaIOSByte\fP, \fBVistaIOShort\fP, 
\fBVistaIOLong\fP, \fBVistaIOFloat\fP, or \fBVistaIODouble\fP. The macro may be used either 
as an rvalue (to fetch the pixel's value) or as an lvalue (to modify it 
or obtain its address). The ``EXAMPLES'' section, below, demonstrates its 
use as an rvalue.
.HP 10n
.na
.nh
.B VistaIOPointer VistaIOPixelPtr (VistaIOImage \fIimage\fP, int \fIband\fP, 
.B int\ \fIrow\fP, int\ \fIcolumn\fP)
.ad
.hy
.PP
.RS
\fBVistaIOPixelPtr\fP returns the address of a pixel specified by its
band, row, and column coordinates. The pixel at that address can be fetched
or modified by first coercing the pointer to the appropriate type for the
pixel. For example:
.RS
.PP
.nf
.ft B
pixel = VistaIOPixelPtr (image, band, row, column);
if (VistaIOPixelRepn (image) == VistaIOBitRepn)
.RS
* (VistaIOBit *) pixel = new_value;
.RE
else \fR...
.fi
.RE
.RE
.PP
.nf
.B \fItype\fP ** VistaIOPixelArray (VistaIOImage \fIimage\fP, \fItype\fP)
.fi
.RS
.PP
\fBVistaIOPixelArray\fP returns a pointer that can be used to access any image
pixel by indexing it first with the pixel's band number, then its row
number, and then its column number. For example:
.RS
.PP
.nf
.B VistaIOUByte **pixels = VistaIOPixelArray (image, VistaIOUByte);
.B pixels[band][row][column] = new_value;
.fi
.RE
.RE
.PP
.B VistaIOPointer VistaIOImageData (VistaIOImage \fIimage\fP)
.IP
\fBVistaIOImageData\fP returns a pointer to \fIimage\fP's block of pixel data. 
The block has the size \fBVistaIOImageSize\ (\fIimage\fB)\fR bytes.
.SS "Other Image Attributes"
In addition to its pixel values an image may have any number of other
attributes; they are represented as an attribute list.
.PP
.B VistaIOAttrList VistaIOImageAttrList (VistaIOImage \fIimage\fP)
.RS
.PP
\fBVistaIOImageAttrList\fP is a macro for accessing the attribute list associated
with an image. The macro may be used as an rvalue to reach attributes
within the list:
.RS
.PP
.nf
.B VistaIOGetAttr (VistaIOImageAttrList (image), VistaIONameAttr, \fR...\fP)
.fi
.RE
.PP
or as an lvalue to manipulate the entire list:
.RS
.PP
.nf
.B VistaIODestroyAttrList (VistaIOImageAttrList (image));
.B VistaIOImageAttrList (image) = VistaIOCopyAttrList (other_list);
.RE
.RE
.fi
.SS "Band Interpretation"
The bands of a multi-band image might represent the successive frames of a 
motion sequence, the left and right halves of a stereo pair, or the red, 
green, and blue channels of a color image. They might even represent a 
combination of such dimensions \(em for example, a stereo pair of color 
images. Because a great many different uses of the bands are possible, each 
image includes information describing how its bands are to be interpreted. 
This information assigns each band an interpretation in terms of four 
dimensions:
.RS 2n
.IP \fIframe\fP 10n
covers the various frames of a motion sequence
.IP \fIviewpoint\fP
covers, for example, the left and right channels of a stereo pair
.IP \fIcolor\fP
covers, for example, the red, green, and blue channels of a color image
.IP \fIcomponent\fP
covers, for example, the real and imaginary components of a complex image
.RE
.PP
Although these four dimensions do not account for all conceivable ways one 
might wish to use the bands of a multi-band image, they do cover most 
cases. The scheme can usually be adapted to cover cases not explicitly 
handled. For example, a collection of images obtained under various 
lighting conditions could be represented by using the frame dimension to 
index the lighting condition. 
.PP
Each image specifies the sizes of its four band interpretation dimensions. 
For a stereo pair of color images, for example, the size of the viewpoint 
dimension is two, the size of the color dimension is three, and the 
remaining dimensions have sizes of one. The dimension sizes are often 
abbreviated as \fBnframes\fP, \fBnviewpoints\fP, \fBncolors\fP, and 
\fBncomponents\fP. Their product should always equal the number of bands in 
the image. These macros exist for accessing the sizes: 
.RS
.PP
.B int VistaIOImageNFrames (VistaIOImage \fIimage\fP)
.PP
.B int VistaIOImageNViewpoints (VistaIOImage \fIimage\fP)
.PP
.B int VistaIOImageNColors (VistaIOImage \fIimage\fP)
.PP
.B int VistaIOImageNComponents (VistaIOImage \fIimage\fP)
.RE
.PP
Each macro may be used as rvalue to obtain the size of a dimension, or as 
an lvalue to set it. 
.PP
The four dimensions are mapped onto the single dimension, band, according 
to a particular ordering: component varies most rapidly, then color, then 
viewpoint, and finally frame. A macro is available for computing this 
mapping: 
.RS
.HP 10n
.na
.nh
.ft B
int VistaIOBandIndex (VistaIOImage \fIimage\fP, int \fIframe\fP, int\ \fIviewpoint\fP,
int\ \fIcolor\fP, int\ \fIcomponent\fP)
.ft
.ad
.hy
.RE
.PP
\fBVistaIOBandIndex\fP returns the index of the band that corresponds to a
particular combination of frame, viewpoint, channel, and component indices.
.PP
An image's attribute list may include attributes indicating how the image
employs the four band interpretation dimensions. One attribute for each
dimension provides the first level of description. Its value is an integer
code, with some standard codes defined for common uses. Below is a list of
the four attributes and their standard values. Shown in are both the
symbolic constants that can be used C programs to refer to the integer
values, and (in parentheses) the keywords used to represent the values
externally, in Vista data files.
.RS 4n
.PP
\fBframe_interp\fP, which currently has no standard values defined for it
.PP
\fBviewpoint_interp\fP, which has this standard value:
.RS 4n
.IP "\fBVistaIOBandInterpStereoPair\fP (\fBstereo_pair\fP)"
The two viewpoints represent (respectively) the left and right images of a 
stereo pair.
.RE
.PP
\fBcolor_interp\fP, which has these standard values:
.RS 4n
.IP "\fBVistaIOBandInterpRGB\fP (\fBrgb\fP)"
The three colors represent (respectively) red, green, and blue color 
channels.
.RE
.PP
\fBcomponent_interp\fP, which has these standard values:
.RS 4n
.IP "\fBVistaIOBandInterpComplex\fP (\fBcomplex\fP)"
The two components represent (respectively) the real and imaginary 
components of a complex image.
.IP "\fBVistaIOBandInterpGradient\fP (\fBgradient\fP)"
There is a single component representing gradient magnitude, two
components representing (respectively) the x (rightward) and y (upward)
components of gradient, or three representing the x, y, and z (forward in
band sequence) components of gradient.
.IP "\fBVistaIOBandInterpIntensity\fP (\fBintensity\fP)"
There is a single component representing image intensity. For integer pixel
representations, pixel values normally span the range between zero and the
maximum representable pixel values (e.g., [0,127] for \fBVistaIOSByte\fP pixels).
For floating point pixel representations, pixel values normally span the
range [\-1,+1].
.IP "\fBVistaIOBandInterpOrientation\fP (\fBorientation\fP)"
There is a single component representing orientation. Pixel values express
orientation in radians, counterclockwise from the direction of increasing
column number (rightward).
.RE
.RE
.PP
To prevent accidental misspellings of the attribute names you should use 
these symbolic constants: 
.RS
.PP
.nf
.ft B
#define VistaIOFrameInterpAttr "frame_interp"
#define VistaIOViewpointInterpAttr "viewpoint_interp"
#define VistaIOColorInterpAttr "color_interp"
#define VistaIOComponentInterpAttr "component_interp"
.ft
.fi
.RE
.PP
A dictionary, \fBVistaIOBandInterpDict\fP, defines the mapping between the band
interpretation codes (e.g., \fBVistaIOBandInterpComplex\fP) and their keywords
(e.g., \fBcomplex\fP):
.RS
.PP
.B VistaIODictEntry VistaIOBandInterpDict[];
.RE
.PP
For each of the four band interpretation dimensions there is a routine you 
can use to simultaneously check both the dimension's size and, if present, 
its interpretation attribute. The \fBVistaIOBandInterp\fP(3) man page describes 
the four routines. 
.SS "Pixel Aspect Ratio"
Pixel aspect ratio is defined as the ratio of pixel width to pixel height. 
An image may include, on its attribute list, an attribute specifying this 
ratio as a floating point value. The attribute has the name 
\fBpixel_aspect_ratio\fP and a symbolic constant exists for referring to 
it: 
.RS
.PP
.nf
.ft B  
#define VistaIOPixelAspectRatioAttr "pixel_aspect_ratio"
.fi
.RE
.PP
When the attribute is absent, a pixel aspect ratio of 1.0 is assumed.
.SS "Calling Conventions"
A Vista library routine that processes one image to produce another usually
takes three or more arguments, like this:
.RS
.HP 10n
.na
.nh
.B VistaIOImage VistaIOProcessImage (VistaIOImage\ \fIsrc\fP, VistaIOImage\ \fIdest\fP,
.B VistaIOBand\ \fIband\fP)
.ad
.hy
.RE
.PP
The first argument specifies the \fIsource\fP image to be processed. The
second specifies the \fIdestination\fP image, to contain the result. You
generally have three choices for how this destination image is provided:
.RS 2n
.IP a) 4n
you can have the routine create a destination image. If you pass
.SB NULL
for \fIdest\fP, the routine will create and return a destination image that
is appropriate for the source image and for the type of operation being
performed on it:
.RS
.PP
.B 	dest = VistaIOProcessImage (src, NULL, band);
.RE
.IP b)
you can supply a destination image provided it has the correct properties
(usually, an appropriate size and pixel representation):
.RS
.PP
.nf
.B 	dest = VistaIOCreateImageLike (src);
.B 	VistaIOProcessImage (src, dest, band);
.fi
.RE
.IP c)
you can specify the same image as both source and destination, in which 
case the source pixel values will be replaced by destination pixel values. 
This choice is only available for operations where the source and 
destination images have the same size and pixel representation. 
.RS
.PP
.B 	VistaIOProcessImage (src, src, band);
.RE
.RE
.PP
In all cases, the routine will return the destination image if successful,
and
.SB NULL
otherwise. Moreover, if
.SB NULL 
is returned, the routine will already have called \fBVistaIOWarning\fP(3) to
issue a warning message describing the problem.
.PP
The third argument to most image processing routines, \fIband\fP, may
specify a particular band of the source image to be processed; or it may be
the constant \fBVistaIOAllBands\fP (defined as \-1) to indicate that all bands of
the source image are to be processed. When a particular band is specified,
\fIband\fP must be at least 0 and less than the number of bands in the
source image; the destination image will usually have a single band to
contain the result. When \fBVistaIOAllBands\fP is specified, the destination
image will usually have the same number of bands as the source image.
.PP
Normally a routine will copy the source image's attribute list to the 
destination image, replacing any attributes the destination image had 
already. The sizes of the four band interpretation dimensions 
(\fBnframes\fP, \fBnviewpoints\fP, etc.) are also copied. When appropriate, 
however, a routine may delete or modify the attributes and dimensional 
sizes as it copies them from source to destination. For example, a routine 
that converts an RGB color image to a grey-scale one 
(\fBVistaIORGBImageToGray\fP(3)) expects a source image with the properties 
\fBncolors:\ 3\fP and \fBcolor_interp: rgb\fP; the destination image 
it produces has \fBncolors:\ 1\fP and no \fBcolor_interp\fP attribute. 
.SS "Image Representation in Memory"
.nf
.ft B
.ta 25n
typedef struct {
.ft
.RS
.ft B
int nbands;	/* number of bands */
int nrows;	/* number of rows */
int ncolumns;	/* number of columns */
VistaIORepnKind pixel_repn;	/* representation of pixel values */
unsigned long flags;	/* various flags */
VistaIOAttrList attributes;	/* list of other image attributes */
VistaIOPointer data;	/* array of image pixel values */
VistaIOPointer *row_index;	/* ptr to first pixel of each row */
VistaIOPointer *band_index;	/* ptr to first row of each band */
int nframes;	/* number of motion frames */
int nviewpoints;	/* number of camera viewpoints */
int ncolors;	/* number of color channels */
int ncomponents;	/* number of vector components */
.ft
.RE
.ft B
} VistaIOImageRec, *VistaIOImage;
.DT
.ft
.fi
.PP
An image is represented in memory by a value of type \fBVistaIOImage\fP, which 
points to a \fBVistaIOImageRec\fP structure. Programmers using images will 
usually not need to access this structure's fields directly from their code 
since there are Vista library routines and macros available for most 
purposes. However, when debugging, one may occasionally need to examine a 
\fBVistaIOImageRec\fP structure's fields directly. The following paragraphs 
describe the fields.
.PP
The \fBnbands\fP, \fBnrows\fP, and \fBncolumns\fP fields of the structure 
describe how many bands, rows, and columns the image has. Its 
\fBpixel_repn\fP field specifies how the image's pixel values are 
represented; it contains one of the constants \fBVistaIOBitRepn\fP, 
\fBVistaIOUByteRepn\fP, \fBVistaIOSByteRepn\fP, \fBVistaIOShortRepn\fP, \fBVistaIOLongRepn\fP, 
\fBVistaIOFloatRepn\fP, or \fBVistaIODoubleRepn\fP. Its \fBattributes\fP field contains 
the list of attributes associated with the image. 
.PP
An image's pixel values are stored in a contiguous block of memory where 
they are arranged as follows. Within each band pixel values are ordered, 
beginning with the pixel at row 0, column 0, proceeding to row 0, column 1, 
etc., and ending with the highest numbered row and column. Each band's 
array of pixel values occupies a separate block of memory, and these blocks 
are arranged contiguously. All of band 0's pixel values are first, followed 
by all of band 1's, etc. In summary, pixel values are ordered by band, 
then by row within each band, and then by column. The pixel values 
themselves are of type \fBVistaIOBit\fB, \fBVistaIOUByte\fP, ..., or \fBVistaIODouble\fP.
.PP
The \fBdata\fP field of a \fBVistaIOImageRec\fP points to the block of memory
containing pixel values. The \fBrow_index\fP field points to a vector of
pointers to the first pixel value of each row within each band; this vector
is of length (\fBnbands\fP * \fBnrows\fP) and it is indexed by an
expression of the form (\fIband\fP\ *\ \fBnrows\fP\ +\ \fIrow\fP). The
\fBband_index\fP field points to a vector of pointers to the first
\fBrow_index\fP entry of each band; this vector is of length \fBnbands\fP
and it is indexed by band number.
.PP
Individual bits of a \fBVistaIOImageRec\fP's \fBflags\fP field are used to denote 
various things. One bit is currently defined: 
.IP \fBVistaIOImageSingleAlloc\fP 21n
This bit, if nonzero, indicates that the \fBVistaIOImageRec\fP, the block of pixel
values, the row index, and the band index were all obtained with a single
call to \fBVistaIOMalloc\fP(3). If the bit is zero, these things were allocated
separately and therefore they must be released separately.
.PP
The \fBnframes\fP, \fBnviewpoints\fP, \fBncolors\fP, and \fBncomponents\fP
fields describe the number of motion frames, camera positions, color
channels, and vector components that the image's various bands represent.
Together they should account for all bands of the image \(em i.e., their
product should equal \fBnbands\fP. The image's bands are ordered according
to these fields, with component index incrementing most rapidly and frame
index incrementing least rapidly.
.SS "Image Representation in a File"
.nf
.ft B
\fIattribute-name\fP: image {
.RS
nbands: \fInbands\fP
nrows: \fInrows\fP
ncolumns: \fIncolumns\fP
repn: \fIpixel-representation\fP
nframes: \fInframes\fP
nviewpoints: \fInviewpoints\fP
ncolors: \fIncolors\fP
ncomponents: \fIncomponents\fP
data: \fIdata-offset\fP
length: \fIdata-length\fP
\fIother attributes\fP
.RE
}
.PP
\fIpixel-representation\fP ::= 
.RS
\fBbit\fP | \fBubyte\fP | \fBsbyte\fP | \fBshort\fP | \fBlong\fP | \
\fBfloat\fP | \fBdouble\fP
.RE
.fi
.PP
An image is represented in a Vista data file as an attribute. The 
attribute's value is an object of type \fBimage\fP containing the 
following attributes in any order:
.RS 2n
.IP \fBnbands\fP 10n
an integer-valued attribute specifying the number of bands in the image.
.IP \fBnrows\fP
an integer-valued attribute specifying the number of rows in the image.
.IP \fBncolumns\fP
an integer-valued attribute specifying the number of columns in the image.
.IP \fBrepn\fP
a string-valued attribute specifying the image's pixel value representation 
with one of the following keywords: \fBbit\fP, \fBubyte\fP, \fBsbyte\fP, 
\fBshort\fP, \fBlong\fP, \fBfloat\fP, or \fBdouble\fP. 
.IP \fBnframes\fP
an integer-valued attribute specifying the number of motion frames
represented by the image's bands.
.IP \fBnviewpoints\fP
an integer-valued attribute specifying the number of camera viewpoints
represented by the image's bands.
.IP \fBncolors\fP
an integer-valued attribute specifying the number of color
channels represented by the image's bands.
.IP \fBncomponents\fP
an integer-valued attribute specifying the number of vector
components represented by the image's bands.
.IP \fBdata\fP
an integer-valued attribute specifying the offset of the image's pixel 
data within the binary data section of the file
.IP \fBlength\fP
an integer-valued attribute specifying the size, in bytes, of the image's 
pixel data
.RE
.PP
An \fBnbands\fP, \fBnframes\fP, \fBnviewpoints\fP, \fBncolors\fP, or 
\fBncomponents\fP attribute may be omitted if its value is 1. Moreover, the 
\fBimage\fP object's attribute list may contain any other attributes 
associated with the image. See, for example, the data file listed under 
``EXAMPLES'', below.
.SS "Pixel Representation in a File"
Image pixel values are represented in binary form in the binary data 
section of a file. They occupy a contiguous block in which pixel values are 
ordered by band, row, and column, as in memory. 
.PP
Single-bit pixel values are packed eight to a byte, beginning with
the most-significant bit of each byte. Pixel values of more than 8 bits are
packed into multiple bytes, beginning with the most-significant byte of the
pixel value. Consecutive pixel values are packed together, without
intervening bits for padding or alignment. If necessary, however, the
entire block of pixel values is padded so that its length is a multiple of
8 bits.
.PP
Each kind of pixel is represented as follows in the Vista data file:
.RS
.IP \fBVistaIOBit\fP 10n
as a 1-bit unsigned integer
.IP \fBVistaIOUByte\fP
as an 8-bit unsigned integer
.IP \fBVistaIOSByte\fP
as an 8-bit two's-complement integer
.IP \fBVistaIOShort\fP
as a 16-bit two's-complement integer
.IP \fBVistaIOLong\fP
as a 32-bit two's-complement integer
.IP \fBVistaIOFloat\fP
as a 32-bit IEEE floating-point number
.IP \fBVistaIODouble\fP
as a 64-bit IEEE floating point number
.RE
.PP
Note that a pixel's representation in a Vista data file is independent of 
the form it takes when stored in memory on any particular machine. Thus a 
\fBVistaIOBit\fP pixel may occupy 8 bits in the main memory of a Sun SPARCstation 
32 bits on a Cray machine, but it always occupies a single bit in a Vista 
data file. 
.SH EXAMPLES
This code fragment sets all pixels with 1 in a one-band image of 
single-bit pixels:
.PP
.RS
.ft B
for (i = 0; i < VistaIOImageNRows (image); i++)
.RS
for (j = 0; j < VistaIOImageNColumns (image); j++)
.RS
VistaIOPixel (image, 0, i, j, VistaIOBit) = 1;
.RE
.RE
.ft
.RE
.fi
.PP
The previous example may be made more efficient by avoiding the
repeated computation of pixel addresses:
.PP
.RS
.ft B
VistaIOBit *p = & VistaIOPixel (image, 0, 0, 0, VistaIOBit);
.PP
.ft B
for (i = 0; i < VistaIOImageNPixels (image); i++)
.RS
*p++ = 1;
.RE
.ft
.RE
.PP
This code fragment creates an image of complex pixel values:
.PP
.RS
.ft B
.na
.nh
.ft B
image = VistaIOCreateImage (2, 256, 256, VistaIOFloatRepn);
.HP 10n
.ft B
VistaIOImageNFrames\ (image)\ = VistaIOImageNViewpoints\ (image)\ = 
VistaIOImageNColors\ (image)\ =\ 1;
.PP
.ft B
VistaIOImageNComponents (image) = 2;
.HP 10n
.ft B
VistaIOSetAttr (VistaIOImageAttrList (image), VistaIOComponentInterpAttr,
NULL, VistaIOLongRepn, (VistaIOLong)\ VistaIOBandInterpComplex);
.ad
.hy
.RE
.PP
Here is an example of a Vista data file containing two images:
.PP
.nf
.RS
.ft B
V-data 2 {
.RS
one: image {
.RS
nbands: 2
nrows: 256
ncolumns: 256
ncomponents: 2
component_interp: complex
repn: float
data: \fIoffset of first image's pixel values\fP
length: 524288
name: "UFO sighted over VistaIOancouver"
pixel_aspect_ratio: 1.25
.RE
}
two: image {
.RS
nrows: 32
ncolumns: 32
repn: ubyte
data: \fIoffset of second image's pixel values\fP
length: 128
name: "UFO icon"
.RE
}
.RE
}
^L
.I first image's pixel values
.I second image's pixel values
.fi
.SH "SEE ALSO"
.na
.nh
.BR VistaIOattribute (3)

.ad
.hy
.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>
.SH "LIST OF ROUTINES"
The following table summarizes the Vista library routines that operate on
images. Many of these routine are documented elsewhere, by a section 3
man page named for the routine.
.PP
For creating and destroying images in memory:
.RS 2n
.IP \fBVistaIOCreateImage\fP 20n
Create an image.
.IP \fBVistaIOCreateImageLike\fP
Create one image like another.
.IP \fBVistaIODestroyImage\fP
Release memory occupied by an image.
.RE
.PP
For fetching and storing pixel values:
.RS 2n
.IP \fBVistaIOGetPixel\fP 20n
Fetch a pixel value with any pixel representation.
.IP \fBVistaIOSetPixel\fP
Store a pixel value with any pixel representation.
.IP \fBVistaIOSelectBand\fP
Select bands of image pixels for processing.
.IP \fBVistaIOSelectDestIamge\fP
Select a destination for an image processing operation.
.RE
.PP
For getting band interpretation information:
.RS 2n
.IP \fBVistaIOImageFrameInterp\fP 20n
Report meaning of frame dimension.
.IP \fBVistaIOImageColorInterp\fP
Report meaning of color dimension.
.IP \fBVistaIOImageComponentInterp\fP
Report meaning of component dimension.
.IP \fBVistaIOImageViewpointInterp\fP
Report meaning of viewpoint dimension.
.RE
.PP
For reading and writing images:
.RS 2n
.IP \fBVistaIOReadImages\fP 20n
Read a set of images from a data file.
.IP \fBVistaIOReadPlain\fP
Read an image in Vista plain file format.
.IP \fBVistaIOReadPnm\fP
Read an image in Portable Anymap (PNM) format.
.IP \fBVistaIOReadUbcIff\fP
Read an image in UBC image file format.
.IP \fBVistaIOWriteImages\fP
Write a set of images to a data file.
.IP \fBVistaIOWriteUbcIff\fP
Write an image in UBC image file format.
.RE
.PP
For comparing images:
.RS 2n
.IP \fBVistaIOSameImageRange\fP 20n
Test whether two images have the same size and pixel representation.
.IP \fBVistaIOSameImageSize\fP
Test whether two images have the same size.
.RE
.PP
For copying images:
.RS 2n
.IP \fBVistaIOCombineBands\fP 20n
Copy selected bands of pixel values from various source images to a single
destination image.
.IP \fBVistaIOCopyBand\fP
Copy one or all bands of pixel values from one image to another.
.IP \fBVistaIOCopyImage\fP
Copy one image to another.
.IP \fBVistaIOCopyImageAttrs\fP
Copy one image's attributes to another.
.IP \fBVistaIOCopyImagePixels\fP
Copy one image's pixel values to another.
.RE
.PP
For converting an image's pixel representation:
.RS 2n
.IP \fBVistaIOConvertImageCopy\fP 20n
Convert an image's pixel representation while simply copying pixel values.
.IP \fBVistaIOConvertImageLinear\fP
Convert an image's pixel representation using some linear mapping of pixel
values.
.IP \fBVistaIOConvertImageOpt\fP
Convert an image's pixel representation while mapping the actual range of
source pixel values to the full range of possible destination pixel values.
.IP \fBVistaIOConvertImageRange\fP
Convert an image's pixel representation while mapping the full range of
possible source pixel values to the full range of possible destination
pixel values.
.RE
.PP
For rotating or transposing an image:
.RS 2n
.IP \fBVistaIOFlipImage\fP 20n
Flip an image horizontally or vertically.
.IP \fBVistaIORotateImage\fP
Rotate an image by any angle.
.IP \fBVistaIOTransposeImage\fP
Transpose the rows and columns of an image.
.RE
.PP
For changing the size of an image:
.RS 2n
.IP \fBVistaIOCropImage\fP 20n
Extract a rectangular region from an image.
.IP \fBVistaIOExpandImage\fB
Increase the size of an image by an integer factor. 
.IP \fBVistaIOReduceImage\fB
Decrease the size of an image by an integer factor.
.IP \fBVistaIOScaleImage\fB
Scale the size of an image, up or down, by any factor.
.RE
.PP
For filtering and transforming images:
.RS 2n
.IP \fBVistaIOAdjustImage\fP 20n
Adjust image brightness and/or contrast.
.IP \fBVistaIOCanny\fP
Detect edges in an image using a Canny operator.
.IP \fBVistaIOConvolveImage\fP
Convolve an image with a mask.
.IP \fBVistaIOGaussianConvolveImage\fP
Convolve an image with a Gaussian filter or its derivative.
.IP \fBVistaIOImageFFT\fP
Compute a forward or inverse Fourier transform.
.IP \fBVistaIOImageGradient\fP
Compute the horizontal and vertical components of image gradient.
.IP \fBVistaIOImageOp\fP
Perform an arithmetic or logical operation on an image's pixel values.
.IP \fBVistaIOInvertImage\fP
Invert an image's pixel values, swapping black and white.
.IP \fBVistaIOLinkImage\fP
Create an edge set by linking connected, non-zero image pixels.
.IP \fBVistaIONegateImage\fP
Negate an image's pixel values.
.IP \fBVistaIOZeroCrossings\fP
Mark the zero crossings in an image.
.RE
.PP
For computing image statistics:
.RS 2n
.IP \fBVistaIOImageStats\fP 20n
Compute the minimum, maximum, mean, and variance of an image's pixel values.
.RE
.PP
For working with complex images:
.RS 2n
.IP \fBVistaIOBuildComplexImage 20n
Build a complex image from separate images of real and imaginary
components.
.IP \fBVistaIOImageMagnitude\fP
Compute the magnitude of a complex image.
.IP \fBVistaIOImagePhase\fP
Compute the phase of a complex image, or the gradient direction of a 
two-component gradient image.
.RE
.PP
For displaying or rendering images:
.RS 2n
.IP \fBVistaIOImageBandToPS\fP 20n
Render an image band using PostScript.
.IP \fBVistaIORGBImageToPS\fP
Render an RGB color image using PostScript.
.IP \fBVistaIOImageView\fP
An X Toolkit widget for displaying an image.
.IP \fBVistaIOImageWindowSize\fP
Compute appropriate window dimensions for displaying an image.
.RE
.PP
For filling images with patterns:
.RS 2n
.IP \fBVistaIOFillImage\fP 20n
Fill an image with a constant pixel value.
.IP \fBVistaIORampImage\fP
Fill an image with an intensity ramp.
.IP \fBVistaIOSineGratingImage\fP
Fill an image with a sine grating.
.IP \fBVistaIOZonePlateImage\fP
Fill an image with a zone plate pattern.
.IP \fBVistaIOBilinearNoiseImage\fP
Fill an image with a random mixture of two pixel values.
.IP \fBVistaIONormalNoiseImage\fP
Fill an image with pixel values drawn from a normal distribution.
.IP \fBVistaIOUniformNoiseImage\fP
Fill an image with pixel values drawn from a uniform distribution.
.RE
.PP
Miscellaneous:
.RS 2n
.IP \fBVistaIOOptFlowWLS\fP 20n
compute optical flow by weighted least squares.
.RE