Introduction
Vista represents an image as one or more two-dimensional arrays of pixel values. Each two-dimensional
array, called a band, 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.
An image in memory is referred to by the C pointer type VistaIOImage. In data files it's identified by
the type name image, and in memory, by the VistaIORepnKind code VistaIOImageRepn. 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 VistaIOReadFile(3),
VistaIOWriteFile(3), and VistaIOGetAttr(3).
CreatingandDestroyingImages
The following routines create and destroy images.
VistaIOImageVistaIOCreateImage(intnbands,intnrows,intncolumns,VistaIOPixelRepnpixel_repn)VistaIOCreateImage 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 pix‐el_repn argument is described below, under ``Pixel Representation''. (See VistaIOCreateImage(3) for
details.)
voidVistaIODestroyImage(VistaIOImageimage)VistaIODestroyImage releases the memory occupied by image, including that occupied by its pixel
data and attribute list.
ImageSize
An image's numbers of bands, row, and columns are sometimes abbreviated as nbands, nrows, and ncolumns.
The following macros access those numbers.
intVistaIOImageNBands(VistaIOImageimage)intVistaIOImageNRows(VistaIOImageimage)intVistaIOImageNColumns(VistaIOImageimage)VistaIOImageNBands, VistaIOImageNRows, VistaIOImageNColumns return the number of bands, rows, and
columns that image has.
intVistaIOImageNPixels(VistaIOImageimage)VistaIOImageNPixels returns the number of pixel values image has altogether (i.e., the product
nbands * nrows * ncolumns).
PixelRepresentation
An image's pixel values may have any of the following types: VistaIOBit, VistaIOUByte, VistaIOSByte, Vis‐taIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble. 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
short and long) to ensure software portability.
The following macros return information about an image's pixel representation:
VistaIORepnKindVistaIOPixelRepn(VistaIOImageimage)VistaIOPixelRepn returns a code indicating image's pixel representation. If image has VistaIOBit
pixels, for example, it returns VistaIOBitRepn.
size_tVistaIOPixelSize(VistaIOImageimage)VistaIOPixelSize returns the size, in bytes, used for storing a single pixel of image (i.e, a pix‐
el within a single band, row, and column). This value depends on machine architecture.
intVistaIOPixelPrecision(VistaIOImageimage)VistaIOPixelPrecision returns the minimum size, in bits, needed for representing a single pixel of
image. This value does not depend on machine architecture, but only on the kind of pixel value
representation used by image. If image has VistaIOBit pixels, for example, this macro returns 1.
VistaIOStringConstVistaIOPixelRepnName(VistaIOImageimage)VistaIOPixelRepnName returns a string describing the type of pixel value representation used by
image. For example, if image has VistaIOBit pixels, the string ``bit'' is returned.
VistaIODoubleVistaIOPixelMaxValue(VistaIOImageimage)VistaIOPixelMaxValue returns the maximum value that a pixel of image may have. For example, if im‐age has VistaIOSByte pixels, it returns 127.0.
VistaIODoubleVistaIOPixelMinValue(VistaIOImageimage)VistaIOPixelMinValue returns the minimum value that a pixel of image may have. For example, if im‐age has VistaIOSByte pixels, it returns -128.0.
size_tVistaIOImageSize(VistaIOImageimage)VistaIOImageSize returns the size, in bytes, of image's block of pixel data, which contains the
values of all pixels in all bands. This value depends on machine architecture.
PixelVistaIOalues
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.
typeVistaIOPixel(VistaIOImageimage,intband,introw,intcolumn,type)VistaIOPixel accesses the pixel at a specified band, row and column in an image whose pixels are of
a specified type. The pixel type, type, must be one of VistaIOBit, VistaIOUByte, VistaIOSByte, Vis‐taIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble. 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.
VistaIOPointerVistaIOPixelPtr(VistaIOImageimage,intband,introw,intcolumn)VistaIOPixelPtr 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 appro‐
priate type for the pixel. For example:
pixel=VistaIOPixelPtr(image,band,row,column);if(VistaIOPixelRepn(image)==VistaIOBitRepn)*(VistaIOBit*)pixel=new_value;else ...
type**VistaIOPixelArray(VistaIOImageimage,type)VistaIOPixelArray 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:
VistaIOUByte**pixels=VistaIOPixelArray(image,VistaIOUByte);pixels[band][row][column]=new_value;VistaIOPointerVistaIOImageData(VistaIOImageimage)VistaIOImageData returns a pointer to image's block of pixel data. The block has the size Vis‐taIOImageSize(image) bytes.
OtherImageAttributes
In addition to its pixel values an image may have any number of other attributes; they are represented as
an attribute list.
VistaIOAttrListVistaIOImageAttrList(VistaIOImageimage)VistaIOImageAttrList 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:
VistaIOGetAttr(VistaIOImageAttrList(image),VistaIONameAttr, ...)
or as an lvalue to manipulate the entire list:
VistaIODestroyAttrList(VistaIOImageAttrList(image));VistaIOImageAttrList(image)=VistaIOCopyAttrList(other_list);BandInterpretation
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 — 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:
frame covers the various frames of a motion sequence
viewpoint covers, for example, the left and right channels of a stereo pair
color covers, for example, the red, green, and blue channels of a color image
component covers, for example, the real and imaginary components of a complex image
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 ex‐
plicitly 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.
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
nframes, nviewpoints, ncolors, and ncomponents. Their product should always equal the number of bands in
the image. These macros exist for accessing the sizes:
intVistaIOImageNFrames(VistaIOImageimage)intVistaIOImageNViewpoints(VistaIOImageimage)intVistaIOImageNColors(VistaIOImageimage)intVistaIOImageNComponents(VistaIOImageimage)
Each macro may be used as rvalue to obtain the size of a dimension, or as an lvalue to set it.
The four dimensions are mapped onto the single dimension, band, according to a particular ordering: com‐
ponent varies most rapidly, then color, then viewpoint, and finally frame. A macro is available for com‐
puting this mapping:
intVistaIOBandIndex(VistaIOImageimage,intframe,intviewpoint,intcolor,intcomponent)VistaIOBandIndex returns the index of the band that corresponds to a particular combination of frame,
viewpoint, channel, and component indices.
An image's attribute list may include attributes indicating how the image employs the four band interpre‐
tation 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.
frame_interp, which currently has no standard values defined for it
viewpoint_interp, which has this standard value:
VistaIOBandInterpStereoPair (stereo_pair)
The two viewpoints represent (respectively) the left and right images of a stereo pair.
color_interp, which has these standard values:
VistaIOBandInterpRGB (rgb)
The three colors represent (respectively) red, green, and blue color channels.
component_interp, which has these standard values:
VistaIOBandInterpComplex (complex)
The two components represent (respectively) the real and imaginary components of a complex
image.
VistaIOBandInterpGradient (gradient)
There is a single component representing gradient magnitude, two components representing
(respectively) the x (rightward) and y (upward) components of gradient, or three repre‐
senting the x, y, and z (forward in band sequence) components of gradient.
VistaIOBandInterpIntensity (intensity)
There is a single component representing image intensity. For integer pixel representa‐
tions, pixel values normally span the range between zero and the maximum representable
pixel values (e.g., [0,127] for VistaIOSByte pixels). For floating point pixel represen‐
tations, pixel values normally span the range [-1,+1].
VistaIOBandInterpOrientation (orientation)
There is a single component representing orientation. Pixel values express orientation in
radians, counterclockwise from the direction of increasing column number (rightward).
To prevent accidental misspellings of the attribute names you should use these symbolic constants:
#defineVistaIOFrameInterpAttr"frame_interp"#defineVistaIOViewpointInterpAttr"viewpoint_interp"#defineVistaIOColorInterpAttr"color_interp"#defineVistaIOComponentInterpAttr"component_interp"
A dictionary, VistaIOBandInterpDict, defines the mapping between the band interpretation codes (e.g.,
VistaIOBandInterpComplex) and their keywords (e.g., complex):
VistaIODictEntryVistaIOBandInterpDict[];
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 VistaIOBandInterp(3)
man page describes the four routines.
PixelAspectRatio
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
pixel_aspect_ratio and a symbolic constant exists for referring to it:
#defineVistaIOPixelAspectRatioAttr"pixel_aspect_ratio"
When the attribute is absent, a pixel aspect ratio of 1.0 is assumed.
CallingConventions
A Vista library routine that processes one image to produce another usually takes three or more argu‐
ments, like this:
VistaIOImageVistaIOProcessImage(VistaIOImagesrc,VistaIOImagedest,VistaIOBandband)
The first argument specifies the source image to be processed. The second specifies the destination im‐
age, to contain the result. You generally have three choices for how this destination image is provided:
a) you can have the routine create a destination image. If you pass NULL for dest, 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:
dest=VistaIOProcessImage(src,NULL,band);
b) you can supply a destination image provided it has the correct properties (usually, an appropriate
size and pixel representation):
dest=VistaIOCreateImageLike(src);VistaIOProcessImage(src,dest,band);
c) you can specify the same image as both source and destination, in which case the source pixel val‐
ues 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.
VistaIOProcessImage(src,src,band);
In all cases, the routine will return the destination image if successful, and NULL otherwise. Moreover,
if NULL is returned, the routine will already have called VistaIOWarning(3) to issue a warning message
describing the problem.
The third argument to most image processing routines, band, may specify a particular band of the source
image to be processed; or it may be the constant VistaIOAllBands (defined as -1) to indicate that all
bands of the source image are to be processed. When a particular band is specified, band 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 VistaIOAllBands is specified, the destination image will usually have
the same number of bands as the source image.
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
(nframes, nviewpoints, 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 (VistaIORGBImageToGray(3)) expects a source image
with the properties ncolors:3 and color_interp:rgb; the destination image it produces has ncolors:1
and no color_interp attribute.
ImageRepresentationinMemorytypedefstruct{intnbands;/*numberofbands*/intnrows;/*numberofrows*/intncolumns;/*numberofcolumns*/VistaIORepnKindpixel_repn;/*representationofpixelvalues*/unsignedlongflags;/*variousflags*/VistaIOAttrListattributes;/*listofotherimageattributes*/VistaIOPointerdata;/*arrayofimagepixelvalues*/VistaIOPointer*row_index;/*ptrtofirstpixelofeachrow*/VistaIOPointer*band_index;/*ptrtofirstrowofeachband*/intnframes;/*numberofmotionframes*/intnviewpoints;/*numberofcameraviewpoints*/intncolors;/*numberofcolorchannels*/intncomponents;/*numberofvectorcomponents*/}VistaIOImageRec,*VistaIOImage;
An image is represented in memory by a value of type VistaIOImage, which points to a VistaIOImageRec
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 VistaIOImageRec structure's fields directly. The fol‐
lowing paragraphs describe the fields.
The nbands, nrows, and ncolumns fields of the structure describe how many bands, rows, and columns the
image has. Its pixel_repn field specifies how the image's pixel values are represented; it contains one
of the constants VistaIOBitRepn, VistaIOUByteRepn, VistaIOSByteRepn, VistaIOShortRepn, VistaIOLongRepn,
VistaIOFloatRepn, or VistaIODoubleRepn. Its attributes field contains the list of attributes associated
with the image.
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 VistaIOBit,Vis‐taIOUByte,...,orVistaIODouble.
The data field of a VistaIOImageRec points to the block of memory containing pixel values. The row_index
field points to a vector of pointers to the first pixel value of each row within each band; this vector
is of length (nbands * nrows) and it is indexed by an expression of the form (band * nrows + row). The
band_index field points to a vector of pointers to the first row_index entry of each band; this vector is
of length nbands and it is indexed by band number.
Individual bits of a VistaIOImageRec's flags field are used to denote various things. One bit is current‐
ly defined:
VistaIOImageSingleAlloc
This bit, if nonzero, indicates that the VistaIOImageRec, the block of pixel values,
the row index, and the band index were all obtained with a single call to VistaIOMa‐lloc(3). If the bit is zero, these things were allocated separately and therefore
they must be released separately.
The nframes, nviewpoints, ncolors, and ncomponents 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 — i.e., their product should equal nbands. The image's bands
are ordered according to these fields, with component index incrementing most rapidly and frame index in‐
crementing least rapidly.
ImageRepresentationinaFileattribute-name:image{nbands:nbandsnrows:nrowsncolumns:ncolumnsrepn:pixel-representationnframes:nframesnviewpoints:nviewpointsncolors:ncolorsncomponents:ncomponentsdata:data-offsetlength:data-lengthotherattributes}pixel-representation ::=
bit | ubyte | sbyte | short | long | float | double
An image is represented in a Vista data file as an attribute. The attribute's value is an object of type
image containing the following attributes in any order:
nbands an integer-valued attribute specifying the number of bands in the image.
nrows an integer-valued attribute specifying the number of rows in the image.
ncolumns an integer-valued attribute specifying the number of columns in the image.
repn a string-valued attribute specifying the image's pixel value representation with one of the
following keywords: bit, ubyte, sbyte, short, long, float, or double.
nframes an integer-valued attribute specifying the number of motion frames represented by the image's
bands.
nviewpoints
an integer-valued attribute specifying the number of camera viewpoints represented by the im‐
age's bands.
ncolors an integer-valued attribute specifying the number of color channels represented by the im‐
age's bands.
ncomponents
an integer-valued attribute specifying the number of vector components represented by the im‐
age's bands.
data an integer-valued attribute specifying the offset of the image's pixel data within the binary
data section of the file
length an integer-valued attribute specifying the size, in bytes, of the image's pixel data
An nbands, nframes, nviewpoints, ncolors, or ncomponents attribute may be omitted if its value is 1.
Moreover, the image object's attribute list may contain any other attributes associated with the image.
See, for example, the data file listed under ``EXAMPLES'', below.
PixelRepresentationinaFile
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.
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 mul‐
tiple of 8 bits.
Each kind of pixel is represented as follows in the Vista data file:
VistaIOBit
as a 1-bit unsigned integer
VistaIOUByte
as an 8-bit unsigned integer
VistaIOSByte
as an 8-bit two's-complement integer
VistaIOShort
as a 16-bit two's-complement integer
VistaIOLong
as a 32-bit two's-complement integer
VistaIOFloat
as a 32-bit IEEE floating-point number
VistaIODouble
as a 64-bit IEEE floating point number
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 VistaIOBit 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.
Install Now
PNG Icons
