.sp 2
.NH 1 "VISUALIZATION/IMAGE FILE FORMAT (VIFF)"
.XS
\s12\*(SN  VISUALIZATION/IMAGE FILE FORMAT (VIFF)\s0
.XE
.sp 2
.PP
The Khoros Visualization/Image File format and internal data structure
format (the \fIxvimage structure\fP - see \f(CWKHOROS_HOME/include/viff.h\fP) 
was designed to facilitate
the interchange of data, not only between data processing
functions within Khoros, but also between researchers that
want to exchange data and information.  VIFF was designed to be
comprehensive; image processing is an extremely diverse field
with different applications requiring different information
about an image.  The VIFF header includes information
necessary for an application program to properly
interpret the data and perform basic error checking.
The VIFF data structure has been applied to both 1D and 2D data processing
applications and 3D visualization.  The VIFF format was also designed to be
extensible; since new applications and new methods of processing
image data are sure to be developed in the future, the file format can be 
extended by adding new fields.  There is currently plenty of
reserve space in the 1024 byte header, or the spare fields can be used.
.sp 2
.NH 2 "VIFF FILE ORGANIZATION"
.XS
      \*(SN  VIFF FILE ORGANIZATION
.XE
.sp
.PP
The Khoros Image File Format is organized as 1024 bytes 
of header followed by map(s), location data and then image data.
The header also contains information identifying the header 
format used.  
This file format (while on disk) or data structure (struct *xvimage, while in 
memory) has evolved from originally supporting only \fIimages\fP
to supporting multi-dimensional data.  The data may be an
image in the normal sense, or it may be sets of vectors.  The
difference is indicated by carefully examining the values of
the various fields.  Information on an existing file can be obtained by
using \fBvfileinfo\fP.
.PP
The fields can be grouped into five categories:
.IP \(bx
administration - file management information,
.IP \(bx
data storage - describes how the data is stored but not how
it is to be interpreted,
.IP \(bx
location data - describes the spatial location of the data (this is optional),
.IP \(bx
data mapping - describes how the stored data should be mapped or
interpreted (no mapping is also valid),
.IP \(bx
color space - in the case of images, indicates what coordinate
space and model is being used.
.LP
Please refer to the table in section J.4 and the examples that follow 
for specific information about all fields in the header.
.sp 2
.NH 2 "FILE FORMAT TERMINOLOGY"
.XS
      \*(SN  FILE FORMAT TERMINOLOGY
.XE
.sp 2
.NH 3 "Image & Imagedata"
.XS
              \*(SN  Image & Imagedata
.XE
.sp
.PP
There are several working terms that must be defined
for the context of the VIFF file format discussion.  An \fIimage\fP 
is a two-dimensional, multiband array of data with either implied or 
explicit data locations. Note that while the pointer to the image data
(\fIimagedata\fP) is a single dimensional array, \fIconceptually,\fP
the image should be thought of as two dimensional.  It is important
to remember that the VIFF image is oriented so that (0,0) is at the 
upper left hand corner of the image. The column index, X, proceeds across
the image to the right;  the row index, Y, proceeds from the top of the
image to the bottom.
.sp 2
.NH 3 "Pixels, Bands & Vectors"
.XS
              \*(SN  Pixels, Bands & Vectors
.XE
.sp
.PP
At each location, implied or explicit, there is a \fIpixel\fP that may
have one or more values. If there is more than one value at a pixel location, 
for example in an RGB image, these data values are separated into \fIbands\fP.  
This means that an image can have one or more bands; these bands are stored 
sequentially. For instance, in an RGB image, the Red band is followed by the 
Green band, which is followed by Blue band.  Taken as a group, the three pixel
values describe a single color value.  
.PP
For multidimensional data, the concept of a \fIvector\fP may be more 
appropriate.  Vectors are stored exactly like images, except that the 
number of bands is interpreted to mean the \fIvector dimension\fP.  Vectors 
can have either implied or explicit location data, just like the pixels of 
an image.
.sp 2
.NH 3 "Implicit VS. Explicit Locations"
.XS
              \*(SN  Implicit VS. Explicit Locations
.XE
.PP
When we refer to the \fIimplied location\fP of a pixel, we refer to the
fact that imagedata[x * row_size + y] = pixel intensity value, where row_size
is the width of the image (ie, number of columns);  here, x is the horizontal
index of the pixel, and y is the vertical index of the pixel;  because the 
x and y values in this image are implied, we call this type of image 
\fIimplicit\fP.  When an image is implicit, there is no need for location data,
as this would be redundant.  A one dimensional image with \fIimplied 
locations\fP data can be represented by setting either the column size or the
row size to one (1).
.PP
A VIFF image can have \fIexplicit location\fP data, where each pixel can have
an N dimensional location in space.  This concept can be explained as the 
imagedata value being an attribute at some location in N-dimensional space. 
To specify an attribute in two dimensional space, for example, we explicitly 
store the values of x and y, as opposed to allowing their values to be implied. 
To access the x value, we look up location[i * row_size + j];  
to access the y value, we would up location[(i * row_size + j) + row_size * 
col_size].  Here, i is the horizontal index of the image and location data, 
j is the vertical index of the image and location data;  row_size is again the 
width of the image (ie, number of columns) and col_size is the height of the
image (ie, number of rows). As in the \fIimplicit\fP image, the 
imagedata value is 
located at imagedata[i * row_size + j].  For an image, the location dimension 
would be two.  A typical use of this interpretation is digital 
elevation data, where the image consists of elevation values; the two 
dimensional location data provides the X and Y spatial coordinates.
.PP
The \fIexplicit\fP N dimensional location information is completely independent of the vector dimension or the number of bands.
For multiband data with explicit locations, the concept can be understood
as the multiband imagedata values being a set of attributes at some location
in N-dimensional space.  
.sp 2
.NH 3 "An Aside on One Dimensional Data"
.XS
              \*(SN  An Aside on One Dimensional Data
.XE
.PP
Given the above description, it is unclear how best to represent sets of
1D data.  There are actually two interpretations that make sense and
are supported in the digital signal processing library (dspl).   
A single one dimensional
implicitly located data set can be stored as a single band with the
product of row size and column size giving the number of elements. 
Alternatively, it may be represented as a
single pixel with the number of bands giving the number of elements (row
size=col size=1 in this case).  A group of 1D data sets 
can then be stored as a set of bands, where the band number can indicate
either the length of the data set or the number of data sets.  Similarly,
the row_size times the col_size can indicate the length of the data set or
the number of data sets.  These two interpretations lead to the idea
of processing \fIdown vectors\fP or processing \fIacross bands\fP.
.PP
A multiband image may have several spatial organization interpretations 
while it is being processed in Khoros.  A multiband image may first be
processed down 1D vectors and later may be processed as a multiband 2D image.
.sp 2
.NH 3 "Image Maps, Map Types, Map Enable and Map Schemes"
.XS
              \*(SN  Image Maps, Map Types, Map Enable and Map Schemes
.XE
.PP
Any image may contain \fImaps\fP.  A map provides additional information 
associated with the imagedata.  Most often, the map field is used to provide
color information, but is not limited to the storage of color information only. 
The size of a map is defined by \fImap_row_size\fP (the number of columns in
the map) and \fImap_col_size\fP (the number of rows in the map).
Any pixel value found in the imagedata serves as an index into one of the 
map rows.  The number of columns in that map row determines the number of 
pieces of information that are described by the map, and accessed via the
pixel value.  For example, when the map is used to store RGB colors, a pixel
value of 5 found in the imagedata will index row 5 of the map.  At row 5,
three values will be found: one each for the red, green, and blue 
color components of pixel value 5.
.PP
There are two different \fImap types\fP that are set with the \fImap_enable\fP
field.  The first is \fIoptional\fP, and the second is \fIforced\fP.  
If the map_enable field is set to optional, this indicates that the imagedata 
is valid by itself, or is valid after indexing into the map.
.PP
If the map_enable field is set to force, the image data is NOT valid until
it it indexed into the map.  When the map_enable field is set to forced,
this implies that the imagedata itself is not meaningful;  it serves only as
an index into the map, where the actual information is stored.
.PP
The \fImap scheme\fP defines how the maps are to be used with the
image(s).  If the \fImap scheme\fP is one-per-band, then each band in a 
multiband image will have its own map (images with only one band should always
have a map scheme of one-per-band.  If, on the other hand, the \fImap scheme\fP
is shared, then all data bands will share a single map.  If the \fImap scheme\fP
is cycled, then a single band image uses multiple maps.  This could be used in
an animation sequence of a single scene;  for example, it would be appropriate
for the animation of a sunset sequence of different colors in a single band
of an image.
.sp 2
.NH 2 "VIFF HEADER POINTERS"
.XS
      \*(SN  VIFF HEADER POINTERS
.XE
.sp
.PP
When the data is in memory, pointers that are part of the xvimage
structure are used to address the data.  The \fIvutils\fP library 
provides basic utilities to read and initialize the pointers. A brief
description of each of the pointers in the VIFF format is provided below:
.IP "char *imagedata "
Points to a sequence of images; an image is
made up of bands, and the bands are in a sequence.  Alternatively,
imagedata can point to vectors, where the vector dimension is
the number of bands and the vector elements are across the bands.
.IP "char *maps "
Points to a sequence of 2-dimensional maps; a map 
is organized as stacked columns.  A imagedata data value 
indexes into a map row.
.IP "float *location "
Points to bands of coordinate values. For example, if you are using
two dimensional explicit locations, then there would be a band
of x's followed by a band of y's.
The number of locations or the number of pixels in a band is always
the product of row size and column size.  The 1D interpretation mentioned
above does not require that either row size or col size be set to one.  The
convention is that the length of a 1D signal is the product of the two.
.PP
To convert other types of image files into VIFF format for use in Khoros, 
use one of the several file format conversion routines (see the section on 
File Formats in Chapter 8 of the Khoros Programmer's Manual, or the man 
pages on file_formats).
.bp
.NH 2 "VIFF HEADER FIELDS"
.XS
      \*(SN  VIFF HEADER FIELDS
.XE
.sp 2
.nr PS 10
.LP
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
char 
identifier; 
.fi
T}:T{
.na
A one byte
magic number that identifies a VIFF file
.ad
T}:T{
.na
XV_FILE_MAGIC_NUM
.ad
T}

_

T{
.nf
char 
file_type; 
.fi
T}:T{
.na
A one byte code indicating Khoros file type (currently
only VIFF).
.ad
T}:T{
.na
XV_FILE_TYPE_XVIFF
.ad
T}

_

T{
.nf
char 
release; 
.fi
T}:T{
.na
A one byte code indicating the specific release of the
viff.h file (currently 0); this does not have to agree with
the Khoros system release number.
.ad
T}:T{
.na
XV_IMAGE_REL_NUM
.ad
T}

_

T{
.nf
char 
version; 
.fi
T}:T{
.na
A one byte code indicating the specific version of the
viff.h file (currently 3);  this does not have to agree with
the Khoros system version number.
For example, version 1 release 0 is referred to as 
viff 1.0.
.ad
T}:T{
.na
XV_IMAGE_VER_NUM
.ad
T}

_

T{
.nf
char 
comment[512]; 
.fi
T}:T{
.na
A 512 byte space available for any use, but currently is
used in Khoros as a comment field to document the VIFF data file.
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
char 
machine_dep; 
.fi
T}:T{
.na
A one byte code indicating how the particular architecture
that the image was last processed on treats data.  Currently
supported are DEC order, IEEE order and NS order.  Supported
machines include the VAX, SUN, SONY News, Silicon Graphics, 
Motorola, Encore, Sequent, MIPS, DEC, IBM, Apollo, and NeXT.
.ad
T}:T{
.na
VFF_DEP_IEEEORDER
VFF_DEP_DECORDER
VFF_DEP_NSORDER
VFF_DEP_BIGENDIAN
VFF_DEP_LITENDIAN
.ad
T}

.TE
.nr PS 11
.bp
.nr PS 10
.LP
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
unsigned long
row_size, 
col_size;
.fi
T}:T{
.na
These two unsigned long fields indicate data size,
specifically, the number of data items in a band.
row_size indicates the length of a row (the number of columns,
or the image width) in pixels.  col_size indicates the 
length of a column (the number of rows, or the image height) 
in pixels.  Images with row and column sizes of zero are 
sometimes valid, and indicate that only the map information 
is important.  The product of the two values is the total number
of data items present.  
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
unsigned long
subrow_size; 
.fi
T}:T{
.na
This unsigned long field specifies the length of any subrows
in the image.  This is useful when one wants pixel vectors 
to represent 2D objects (images). The size of each pixel "image"
would be subrow_size (columns) by num_data_bands/subrow_size (rows).
This field may be ignored except by routines that need the 2D
interpretation. 
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
unsigned long
startx,
starty; 
.fi
T}:T{
.na
These two long fields indicate the location of a
subimage in a parent image.  The image is a sub image
if startx and starty have values greater than zero.
startx and starty locate the upper left hand corner
of where the image was extracted.
This applies to 2D data that has implicit locations.
.ad
T}:T{
.na
VFF_NOTSUB
.ad
T}

_

T{
.nf
float
pixsizx,
pixsizy;
.fi
T}:T{
.na
These two floats specify the actual pixel size in meters
at the time of digitization.  This information is needed
to do true measurements and calculate true frequencies.
The ratio of these fields will give you the aspect ratio
of the digitized pixel.  Most CCD camera's are not one-to-one.
These values may not have a meaning if the data is 
VFF_LOC_EXPLICIT.
.ad
T}:T{
.na
none
.ad
T}

.TE
.nr PS 11
.bp
.nr PS 10
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
unsigned long
location_type;
.fi
T}:T{
.na
This unsigned long field indicates 
whether the image data has implicit 
or explicit locations.
.sp
If the locations are implicit, the field
location_dim must be set to zero (0), and 
the location data will be empty.
.sp
If the locations are explicit, the field
location_dim indicates the dimensionality of the
space (1D, 2D and 3D will be most common).
The explicit location data is pointed to by
location, and is stored as bands of coordinates.  
For example, if (location_dim = 2), implying 2D locations, the
location data would be stored; x1, x2, . . . , xn;
y1, y2, . . . , yn.  
.ad
T}:T{
.na
VFF_LOC_IMPLICIT
VFF_LOC_EXPLICIT
.ad
T}

_

T{
.nf
unsigned long
location_dim;
.fi
T}:T{
.na
This unsigned long indicates the dimensionality of the
location space of data.  Zero-, one-, and two- 
dimensionalities  will be most common.  If the location_type
is implicit, this field must be set to zero (0). If the 
location_type is explicit, this field is set to the 
dimensionality correctly describing the data.  Remember that
3-dimensional image data is represented with location_dim = 2 (x & y);
the third dimension (pixel intensity) is stored in the imagedata.  
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
unsigned long
num_of_images;
.fi
T}:T{
.na
This unsigned long indicates the 
the number of images (not bands) pointed to by *imagedata.
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
unsigned long
num_data_bands;
.fi
T}:T{
.na
This unsigned long indicates the number of
bands per image or the dimensionality of vectors.
In some cases, it may be convenient to think of an
image pixel as a vector (when there is more than one
band).
.ad
T}:T{
.na
none
.ad
T}

.TE
.nr PS 11
.bp
.nr PS 10
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
unsigned long
data_storage_type;
.fi
T}:T{
.na
This unsigned long field indicates the data storage type
of the pixel or vector data.  Currently, bit, byte, 
short, integer, float, float complex, double, and double 
complex data types are supported.  The BIT storage type 
stores the bits in packed unsigned chars and pads to
a byte;  the order is Least Significant Bit (LSB) first.  
.ad
T}:T{
.na
VFF_TYP_BIT
.br
VFF_TYP_1_BYTE
.br
VFF_TYP_2_BYTE
.br
VFF_TYP_4_BYTE
.br
VFF_TYP_FLOAT
.br
VFF_TYP_COMPLEX
.br
VFF_TYP_DOUBLE
.br
VFF_TYP_DCOMPLEX
.br
.ad
T}

_

T{
.nf
unsigned long
data_encode_scheme;
.fi
T}:T{
.na
This unsigned long field  
contains the information that specifies the encoding
or compression method used for storage of the data.
Only the raw and compress encoding schemes
are supported in Khoros 1.0.
.ad
T}:T{
.na
VFF_DES_RAW
.br
VFF_DES_COMPRESS
.br
VFF_DES_RLE
.br
VFF_DES_TRANSFORM
.br
VFF_DES_CCITT
.br
VFF_DES_ADPCM
.br
VFF_DES_GENERIC
.ad
T}

_

T{
.nf
unsigned long
map_scheme;
.fi
T}:T{
.na
This unsigned long field specifies the type of mapping that should
occur.  The map is an array, where the
data pointed to by *imagedata is used as an 
index into rows of the array.
.br
.sp
ONEPERBAND indicates that each data band has a map.  CYCLE is
for when a single band is displayed by cycling through maps.
SHARED is for when there is only one map for all bands to share.
The GROUP mapping scheme is for future Khoros development, and
should not be used as of Khoros 1.0.
.ad
T}:T{
.na
VFF_MS_NONE
.br
VFF_MS_ONEPERBAND
.br
VFF_MS_CYCLE
.br
VFF_MS_SHARED
.br
VFF_MS_GROUP
.ad
T}

_

T{
.nf
unsigned long
map_storage_type;
.fi
T}:T{
.na
This unsigned long field indicates the type
of data in the map.  Data in the map may be of type
char, short, integer, float, or complex.  
This is also the resulting data type after a mapping has been done.
.ad
T}:T{
.na
VFF_MAPTYP_NONE
VFF_MAPTYP_1_BYTE
VFF_MAPTYP_2_BYTE
VFF_MAPTYP_4_BYTE
VFF_MAPTYP_FLOAT
VFF_MAPTYP_COMPLEX
.ad
T}

.TE
.nr PS 11
.bp
.nr PS 10
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
unsigned long
map_row_size,
map_col_size;
.fi
T}:T{
.na
These two unsigned long fields indicate the number of
rows in the 2D map and the number of columns in the map.
The maps are stored as a sequence of columns (stacked
columns).
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
unsigned long
map_subrow_size;
.fi
T}:T{
.na
This unsigned long field specifies the number of subrows
in a map.  This is useful when using the output vector from 
the map is a 2D image, rather than just a vector. 
The size of the 2D image would be: map_subrow_size (columns) by
map_row_size/map_subrow_size (rows). This field may be ignored
except by routines that need the 2D interpretation. 
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
unsigned long
map_enable;
.fi
T}:T{
.na
This unsigned long field specifies if the image data will be
valid regardless of whether or not it has been sent through a map.
In some cases the mapping is optional (VFF_MAP_OPTIONAL),  while in others,
the data must be mapped in order for it to have a valid meaning 
(VFF_MAP_FORCE).  See the previous section on FILE FORMAT TERMINOLOGY for 
a more detailed explanation of the map_enable field.
.ad
T}:T{
.na
VFF_MAP_OPTIONAL
VFF_MAP_FORCE
.ad
T}

_

T{
.nf
unsigned long
maps_per_cycle;
.fi
T}:T{
.na
This unsigned long field specifies the number of
maps that would constitute one cycle when the cycled map scheme type
is used. Of course, this field is only valid 
when map_scheme is set to VFF_MS_CYCLE.
.ad
T}:T{
.na
none
.ad
T}

.TE
.nr PS 11
.bp
.nr PS 10
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
unsigned long
color_space_model;
.fi
T}:T{
.na
This unsigned long field indicates 
the color space or the coordinate system being
used to interpret the image bands.
.sp
.br
The color space model defines use the following convention:
.nf
NTSC: National Television Systems Committee
CIE:  Commission Internationale de L'Eclairage
UCS:  Universal Chromaticity Scale
RGB:  Red Component, Green Component, Blue Component
CMY:  Cyan Component, Magenta Component, Yellow Component
YIQ:  Luminance, I and Q represent chrominance
HSV:  Hue, Saturation & Value
IHS:  Intensity, Hue & Saturation
.fi
.sp
.br
Most color map models only make sense when the map_scheme is set to 
VFF_MS_ONEPERBAND and the map_row_size = 3 and the num_data_bands = 1;
alternatively, the map_scheme may be set to VFF_MS_NONE and the 
map_row_size = 0, and the num_data_bands = 3.  The exceptions to this are:
VFF_CM_NONE indicates that no color space model has been assigned,
VFF_CM_GENERIC indicates that a color space is valid, but is
being defined by the user.
VFF_CM_genericRGB would imply that VFF_MS_ONEPERBAND is set with
map_row_size = 3 and num_data_bands = 1.  genericRGB is an RGB image
but doesn't conform to a standard.
.ad
T}:T{
.na
VFF_CM_NONE
.br
VFF_CM_ntscRGB
.br
VFF_CM_ntscCMY
.br
VFF_CM_ntscYIQ
.br
VFF_CM_HSV
.br
VFF_CM_HLS
.br
VFF_CM_IHS
.br
VFF_CM_cieRGB
.br
VFF_CM_cieXYZ
.br
VFF_CM_cieUVW
.br
VFF_CM_cieucsUVW
.br
VFF_CM_cieucsSOW
.br
VFF_CM_cieucsLab
.br
VFF_CM_cieucsLuv
.br
VFF_CM_GENERIC
.br
VFF_CM_genericRGB
.ad
T}

_

T{
.nf
unsigned long
ispare1,
ispare2;
float
fspare1,
fspare2;
.fi
T}:T{
.na
Spare fields available for user defined fields.  These
fields are not supported except for reading and writing 
correctly with respect to machine dependencies.
.ad
T}:T{
.na
none
.ad
T}
.TE
.nr PS 11
.bp
.nr PS 10
.TS
center box tab(:) expand ;
c s s
l 1 | lw(3.0i) 1 | lp
l 1 | lw(3.0i) 1 | lp-4 .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Description:Defines\fP
_

T{
.nf
reserve
.fi
T}:T{
.na
Reserve space is allocated so that the
total length of the header is 1024 bytes and
so that more fields can be added.
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
char *maps;
.fi
T}:T{
.na
This is a pointer to the beginning of the map data.  
When it is used, it must be cast to the proper data type.
.ad
T}:T{
.na
none
.ad
T}

_

T{
.nf
float *location;
.fi
T}:T{
.na
This is a pointer to the beginning of the location data. 
The dimensionality of the location data is given in the field
location_dim. (location_dim specifies the number of
bands of coordinates.) The number of coordinate values per 
band is row_size*col_size.  
.ad
T}:T{
.na
none
.ad
T}

_


T{
.nf
char *imagedata;
.fi
T}:T{
.na
This is a pointer to the beginning of the image data.  When it
is used in an image processing routine it
must be cast to the proper data type.
.ad
T}:T{
.na
none
.ad
T}

.TE
.bp
.nr PS 11
.NH 2 "EXAMPLES USING THE VIFF FORMAT"
.XS
      \*(SN  EXAMPLES USING THE VIFF FORMAT
.XE
.sp
.PP
The table above succinctly describes each field and its meaning,
but it is helpful to have an example to follow to reinforce
the ideas.  The following narrative describes the use of the
most difficult fields 
(location_type, location_dim. num_data_bands, map_scheme,
map_row_size, map_col_size, map_enable and color_space_model) by 
tracking an image through a typical Khoros image processing application .
.PP
You will probably begin your image processing task by acquiring 
an image using an eight bit digital to analog converter.   When
this image is first brought into the Khoros, it would usually
be declared as:
.nr PS 10
.sp
.LP
.TS
center box tab(:) expand ;
c s s
l | l | l .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Defines:Description\fP
_
location_type:VFF_LOC_IMPLICIT:a normal digitized image
location_dim:don't care:
data_storage_type:VFF_TYP_1_BYTE:8 bit data
num_data_bands:1:one band per image
map_scheme:VFF_MS_NONE:no mapping
map_row_size:don't care:
map_col_size:don't care:
map_enable:VFF_MAP_OPTIONAL:don't need to map
color_space_model:VFF_CM_NONE:no color model
.TE
.nr PS 11
.sp
.LP
Next, you probably will process this image with several of the
Khoros programs.  As you do this, you are not likely to
change the above fields but may change the data_storage_type
field from VFF_TYPE_BYTE to some other type.
.PP
As you view the resulting image with editimage, you may
want to \fIenhance\fP the image.  This will change the
fields so that the data is interpreted correctly.  For instance,
if you add "color" to your grey image and save the
result, the header fields should be:
.bp
.nr PS 10
.LP
.TS
center box tab(:) expand ;
c s s
l | l | l .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Defines:Description\fP
_
location_type:VFF_LOC_IMPLICIT:a normal digitized image
location_dim:don't care:
data_storage_type:VFF_TYP_1_BYTE:8 bit data
num_data_bands:1:one band per image
map_scheme:VFF_MS_ONEPERBAND:one map
map_row_size:3:map pixels through
::three columns
map_col_size:256:256 rows in the
::map
map_storage_type:VFF_MAPTYP_1_BYTE:8 bit map result
map_enable:VFF_MAP_OPTIONAL:don't have to map
color_space_model:VFF_CM_genericRGB:pseudo colored
.TE
.nr PS 11
.sp
.LP
The displayed image may be enhanced even further by adding
overlays to the image.  The displayed overlay and image 
are saved by executing getimage (vman getimage).  getimage actually
does a screen dump into a VIFF file.  If the screen
is an eight plane display, then the resulting fields are:
.nr PS 10
.sp
.LP
.TS
center box tab(:) expand ;
c s s
l | l | l .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Defines:Description\fP
_
location_type:VFF_LOC_IMPLICIT:a normal digitized image
location_dim:don't care:
data_storage_type:VFF_TYP_1_BYTE:8 bit data
num_data_bands:1:one band per image
map_scheme:VFF_MS_ONEPERBAND:one map
map_row_size:3:map pixels through
::three columns
map_col_size:256:256 rows in the
::map
map_storage_type:VFF_MAPTYP_1_BYTE:8 bit map result
map_enable:VFF_MAP_FORCE:must be mapped!
color_space_model:VFF_CM_genericRGB:RGB interpretation
.TE
.nr PS 11
.sp
.LP
This means that the image data only has meaning if it is
mapped through the three color map columns.
.bp
.PP
Let's return to the image as it was when it was first
brought into the Khoros and look at vector data representations.
You may use a Khoros routine that extracts features
of an image at sparse, explicit locations.  This is best
stored as vector data.
.nr PS 10
.sp
.LP
.TS
center box tab(:) expand ;
c s s
l | l | l .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Defines:Description\fP
_
location_type:VFF_LOC_EXPLICIT:explicit locations
location_dim:2:x and y locations
data_storage_type:VFF_TYP_FLOAT:real numbers
num_data_bands:7:each vector has 
::seven elements
map_scheme:VFF_MS_NONE:no map
map_row_size:don't care:
map_col_size:don't care:
map_storage_type:don't care:
map_enable:VFF_MAP_OPTIONAL:don't have to map
color_space_model:VFF_CM_NONE:
.TE
.nr PS 11
.sp
.LP
In the case that you want to have a vector for each pixel
location in the image and also want a color map for
each vector band (elements), 
then the fields should be specified as follows:
.nr PS 10
.sp
.LP
.TS
center box tab(:) expand ;
c s s
l | l | l .
.sp
.ps 11
\fBKhoros Image File Format Header Fields\fP
.ps 10
.sp
_
.sp
\fBField:Defines:Description\fP
_
location_type:VFF_LOC_IMPLICIT:a normal digitized image
location_dim:don't care:
data_storage_type:VFF_TYP_1_BYTE:8 bit data
num_data_bands:3:three bands per image
map_scheme:VFF_MS_ONEPERBAND:one map per band
map_row_size:1:map vector bands
::through one column
map_col_size:256:256 rows in the
::map
map_storage_type:VFF_MAPTYP_1_BYTE:8 bit map result
map_enable:VFF_MAP_OPTIONAL:don't have to map
color_space_model:VFF_CM_ntscRGB:red, green, blue
.TE
.nr PS 11
.sp
.LP
This is an example of a typical RGB image.
