.NH 1 "VUTILS LIBRARY"
.XS
\s12\*(SN  VUTILS LIBRARY\s0
.XE
.sp 2
.NH 2 "INTRODUCTION TO THE VUTILS LIBRARY"
.XS
      \*(SN  INTRODUCTION
.XE
.sp 2
.PP
The vutils library contains routines used to perform general image
and ascii file manipulations. This includes operations to read and
write images, adjust the organization of image data, create and copy
information provided by the VIFF header structure, and machine
type conversions for the VIFF structure.
.sp 2
ALL programs that utilize these routines MUST include the statement:
.sp
#include "vinclude.h"
.sp 2
.NH 2 "COPYING and CREATING UTILITIES"
.XS
      \*(SN  COPYING and CREATING UTILITIES
.XE
.LP
.sp 2
.NH 3 "append_comment()"
.XS
              \*(SN   append_comment()
.XE
.sp
.LP
The routine append_comment appends a new comment string
to the existing VIFF comment field.
If the number of characters in
the new string plus the size of the original comment
exceeds the maximum allowable field comment size,
the new string will be truncated to comply with the max comment size.
.sp 2
.B
.sp
int append_comment(image_comment, new_comment)
.br
char *image_comment;
.br
char *new_comment;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image_comment: 10
A character pointer to the VIFF comment field.
.IP new_comment: 10
A character pointer to the new string to append to the original comment.
.LP
=====================================================================
.sp 4
.NH 3 " copyheader()"
.XS
              \*(SN   copyheader()
.XE
.sp
.LP
Copy the image header from one image to another.
.sp 2
.B
.sp
copyheader(image1, image2)
.br
struct xvimage *image1;
.br
struct xvimage *image2;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image1: 10
The source VIFF image to copy the header from.
.IP image2: 10
The destination VIFF image. The caller must allocate the memory for
the image structure.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " copyimage()"
.XS
              \*(SN   copyimage()
.XE
.sp
.LP
Copy the image from xvimage pointer to another. This routine will return
a pointer to the xvimage structure upon success, NULL on failure. 
.sp 2
.B
.sp
struct xvimage *copyimage(image)
.br
struct xvimage *image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP image: 10
The source VIFF image to copy.
.sp
=====================================================================
.bp
.sp 4
.NH 3 " copyimagedata()"
.XS
              \*(SN   copyimagedata()
.XE
.sp
.LP
Copy the image data from one image to another. This routine will return
a 1 upon success and a 0 upon failure. The header for image2 will be
adjusted based on the new map parameters.
.sp 2
.B
.sp
int copyimagedata(image1, image2, malloc_flag)
.br
struct xvimage *image1;
.br
struct xvimage **image2;
.br
int malloc_flag;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP image1: 10
The source VIFF image to copy data from.
.IP image2: 10
The destination VIFF image. 
.IP malloc_flag: 10
If the malloc_flag is set to 1, then this routine will malloc space
for the data in image2. If the malloc_flag is set to 0, the image data
from image1 is directly copied to image2.
.LP
=====================================================================
.sp 4
.NH 3 " copylocationdata()"
.XS
              \*(SN   copylocationdata()
.XE
.sp
.LP
Copy the image location data from one image to another. This routine will return
a 1 upon success and a 0 upon failure. The header for image2 will be
adjusted based on the new map parameters.
.sp 2
.B
.sp
int copylocationdata(image1, image2, malloc_flag)
.br
struct xvimage *image1;
.br
struct xvimage **image2;
.br
int malloc_flag;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP image1: 10
The source VIFF image to copy the location data from.
.IP image2: 10
The destination VIFF image to receive the location data. 
.IP malloc_flag: 10
If the malloc_flag is set to 1, then this routine will malloc space
for the location data in image2. If the malloc_flag is set to 0, the image 
location data from image1 is directly copied to image2.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " copymapdata()"
.XS
              \*(SN   copymapdata()
.XE
.sp
.LP
Copy the image map data from one image to another. This routine will return
a 1 upon success and a 0 upon failure.
The header for image2 will be
adjusted based on the new map parameters.
.sp 2
.B
.sp
int copymapdata(image1, image2, malloc_flag)
.br
struct xvimage *image1;
.br
struct xvimage **image2;
.br
int malloc_flag;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP image1: 10
The source VIFF image to copy the map data from.
.IP image2: 10
The destination VIFF image to receive the map data. 
.IP malloc_flag: 10
If the malloc_flag is set to 1, then this routine will malloc space
for the map data in image2. If the malloc_flag is set to 0, the image map data
from image1 is directly copied to image2. 
.LP
=====================================================================
.bp
.sp 4
.NH 3 "create_comment()"
.XS
              \*(SN   create_comment()
.XE
.sp
.LP
The routine is very similar the append_comment routine. 
The create_comment routine take a new comment string and
places it in the image comment field, and then appends to the image comment
field as much of the original comment as possible.
If the number of characters in
the new string plus the size of the original comment
exceeds the maximum allowable field comment size,
the original comment  string will be truncated to comply with the maximum 
comment size. This routine will return the resulting comment in the
variable resulting_comment.
.sp 2
.B
.sp
int create_comment(resulting_comment, new_comment, original_comment)
.br
char *resulting_comment
.br
char *new_comment;
.br
char *original_comment;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP resulting_comment: 10
A character pointer to the resulting comment field. This string must
be allocated by the caller and is returned containing the 
concatenation of the new and original comment string.
.IP new_comment: 10
A character pointer to the new string to add to the comment field.
.IP original_comment: 10
A character pointer to the original image comment.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " createimage()"
.XS
              \*(SN   createimage()
.XE
.sp
.LP
This routine will create a generic VIFF image. The memory for the
image structure, the image data, the image map data, and the image location
data will be allocated based on the parameters passed in. A NULL is
returned in the event the routine fails, otherwise a point to the
new image is returned. The image header fields that are 
not passed into this routine are set as follows:
.RS
.IP identifier 20
XV_FILE_MAGIC_NUM
.IP file_type 20
XV_FILE_TYPE_XVIFF
.IP release 20
XV_IMAGE_REL_NUM
.IP version 20
XV_IMAGE_VER_NUM
.IP machine_dep 20
current machine type
.IP startx 20
-1
.IP starty 20
-1
.IP pixsizx 20
1.0
.IP pixsizy 20
1.0
.IP data_encode_scheme 20
VFF_DES_RAW
.IP map_enable 20
VFF_MAP_OPTIONAL
.IP maps_per_cycle 20
0
.IP color_space_model 20
VFF_CM_NONE
.RE
.B
.sp
struct xvimage *createimage(col_size, row_size, data_storage_type, 
.in +1.0i
.br
num_of_images, num_data_bands, comment, map_row_size, map_col_size,
.br
map_scheme, map_storage_type, location_type, location_dim),
.in -1.0i
.br
unsigned long col_size, row_size, data_storage_type, num_of_images;
.br
unsigned long num_data_bands, map_row_size, map_col_size, map_scheme;
.br
unsigned long map_storage_type, location_type, location_dim;
.br
char *comment;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP col_size: 10
The column size (number of rows) in the image data.
.IP row_size: 10
The row size (number of columns) in the image data.
.IP data_storage_type: 10
The data storage type. Must be one the of following: 
.RS
byte data - VFF_TYP_1_BYTE
.br
short data - VFF_TYP_2_BYTE
.br
long data - VFF_TYP_4_BYTE
.br
float data - VFF_TYP_FLOAT
.br
double data - VFF_TYP_DOUBLE
.br
complex data - VFF_TYP_COMPLEX
.br
double complex data - VFF_TYP_DCOMPLEX
.RE
.IP num_of_images: 10
The number of images in the file. At this time should always be set to 1.
.IP num_data_bands: 10
The number of data bands the image data is to contain.
.IP comment: 10
A character pointer to a string to be used as the image comment.
.IP map_row_size: 10
The map row size specifies the size of the rows in the map. Note that this
is the same as the number of columns the map is to have. If the map is to
contain 256 RGB values, then the map row size would be set to 3. If the
image is to contain 1 grey level map the the map row size would be set to 1.
.IP map_col_size: 10
The map column size specifies the size of the columns the map is to have.
Note that this is the same as the number of rows. If the map is to
contain 256 RGB values, then the map column size would be set to 256. If the
image is to contain 1 grey level map of 256 values, the the map column 
size would be set to 256.
.IP map_scheme: 10
The map_scheme specifies the type a image map system to be used. At this time
this field should be set to one of the following:
.RS
.RS
No map - VFF_MS_NONE
.br
Each data band has its own map - VFF_MS_ONEPERBAND
.br
All data band share the same map - VFF_MS_SHARED
.RE
.RE
.IP map_storage_type: 10
The map_storage_type specifies the type of data stored in the map. This
field must be set to one of the following types:
.RS
.RS
No map exists - VFF_MAPTYP_NONE
.br
Byte map data - VFF_MAPTYP_1_BYTE
.br
Short map data - VFF_MAPTYP_2_BYTE
.br
Long map data - VFF_MAPTYP_4_BYTE
.br
Float map data - VFF_MAPTYP_FLOAT
.br
Double map data - VFF_MAPTYP_DOUBLE
.br
Complex map data - VFF_MAPTYP_COMPLEX
.RE
.RE
.IP location_type: 10
The location_type specifies whether or not the image data is 
implicit or explicit. If the image data is implicit then the row and
column information implies the location of the image data. If the 
data is explicit then location data exists. The valid type for
location_type are VFF_LOC_IMPLICIT or VFF_LOC_EXPLICIT.
.IP location_dim: 10
The dimension of the location data. If the location data is to have XYZ
coordinates the location dimension would be 3.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " create_image_list()"
.XS
              \*(SN   create_image_list()
.XE
.sp
.LP
The create_image_list routine will create a list of pointers to 
xvimage structures. Memory is allocated for both 
the list and each xvimage structure. Create_image_list returns a 
pointer to a list of pointers to xvimage structures upon success and
NULL upon failure.
.sp 2
.B
.sp
struct xvimage **create_image_list(image_num);
.br
unsigned int image_num;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image_num: 10
The number of images to be created in the list.
.LP
=====================================================================
.bp
.sp2
.NH 2 "INPUT and OUTPUT UTILITIES"
.XS
      \*(SN  INPUT and OUTPUT UTILITIES
.XE
.sp 2
.LP
.NH 3 "block_read()"
.XS
              \*(SN   block_read()
.XE
.sp
.LP
block_read is a routine that performs a block read on the number of 
desired blocks. This is useful when the input is coming from standard input, 
since the standard system read can return without reading all the 
desired blocks. 
.B
.sp
int block_read(fid, input, size)
.br
int fid;
.br
int size;
.br
char *input; 
.sp 
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP fid: 10
The file descriptor in which to read from.
.IP input: 10
A character pointer where the bytes will be read and stored to.
.IP size:
An integer specifying the number of bytes to be read.
.LP
=====================================================================
.sp 4
.NH 3 " check_file_type()"
.XS
              \*(SN   check_file_type()
.XE
.sp
.LP
Checks the input file to see if it is an KHOROS VIFF file. 
If a 1 is returned the the file is a KHOROS VIFF file, otherwise
it is not a KHOROS VIFF file.
.sp 2
.B
.sp
int check_file_type(fid)
.br
int fid;
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP fid: 10
The file identifier to read from.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " read_raw()"
.XS
              \*(SN   read_raw()
.XE
.sp
.LP
Read data in from a raw data file. Regardless of the data type read,
the data will be converted to float before handed back to the caller.
If the mach_type parameter is specified as a valid machine type the
data read in will be converted to that machine type. Read_raw returns
a single array of data points read and the number of data points read.
If read_raw fails, a NULL is returned.
.sp 2
.B
.sp
float *read_raw(fid, offset, points, type, mach_type)
.br
int fid, offset, type, mach_type;
.br
int *points;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP fid: 10
The File descriptor pointing to the stream in which the raw point 
data is located.
.br
.IP offset: 10
The number of bytes to offset from the beginning of the file.
.IP type: 10
The type of data to be read in. 
The data type must be one the of following: 
.RS
.RS
byte data - VFF_TYP_1_BYTE
.br
short data - VFF_TYP_2_BYTE
.br
long data - VFF_TYP_4_BYTE
.br
float data - VFF_TYP_FLOAT
.br
complex data - VFF_TYP_COMPLEX
.RE
.RE
.IP mach_type: 10
Specifies the machine type of the data. The valid values for
this parameter are:
.RS
.RS
VFF_DEP_IEEEORDER
.br
VFF_DEP_NSORDER
.br
VFF_DEP_DECORDER
.RE
.RE
.IP points: 10
Returns the number of data points read in, and that are contained
in the returned array.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " write_raw()"
.XS
              \*(SN   write_raw()
.XE
.sp
.LP
This routine writes a raw data array to the desired file, specified by fid.
.sp 2
.B
.sp
int write_raw(fid, data, num_bytes)
.br
int fid;
.br
char *data;
.br
int num_bytes;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP fid: 10
The file descriptor pointing to the stream in which the raw floating 
point data is located.
.IP data: 10
The raw data array to written to fid.
.IP num_bytes: 10
The number of bytes found in the raw data array to write.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " read_ascii()"
.XS
              \*(SN   read_ascii()
.XE
.sp
.LP
The  read_ascii routine reads an ascii file passing back a floating point 
array of values. Read_ascii will ignore any comment that begins with
a "%" "*" "#" or "!". Also an error will occur and be printed to standard
error in the event a non-numerical value is found. Read_ascii will
return an array of data points of type float. If read_ascii fails a NULL
is returned. The points parameter will contain the number of points read
in. Note, number is exponential notation will be read in correctly.
.sp 2
.B
.sp
float *read_ascii(file, points)
.br
FILE *file;
.br
int *points;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP file: 10
A file descriptor pointing to the stream in which the ascii data is located.
.IP points: 10
Returns the number of data points read in, and that are contained
in the returned array.
.LP
=====================================================================
.sp 4
.NH 3 " write_ascii()"
.XS
              \*(SN   write_ascii()
.XE
.sp
.LP
The write_ascii routine will write a float data array to the 
desired ascii file. Write_ascii will return a 0 upon failure and a
1 upon success.
.sp 2
.B
.sp
int write_ascii(file, points, ncols, num_points)
.br
FILE *file;
.br
float *points;
.br
int ncols, num_points;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP file: 10
A file descriptor pointing to the file in which to write the values
contained in the points array.
.IP points: 10
A float array containing the data to be written to the ascii file.
.IP ncols: 10
The number of columns in the ascii file to write the data to.
.IP num_points: 10
The number of points found in the points array.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " readimage()"
.XS
              \*(SN   readimage()
.XE
.sp
.LP
The readimage routine will read a Khoros VIFF image from a specified
file. To read from standard input the filename must be a "-". Readimage
will expand filenames that begin with KHOROS_HOME or with a "~".
Readimage will convert the image header and data to the current machine
type as necessary. This routine will return a NULL upon failure and
an xvimage structure upon success. 
.sp 2
.B
.sp
struct xvimage *readimage(filename)
.br
char *filename
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to read the VIFF image from. Note, this filename
may start with KHOROS_HOME, ~, . or /. Readimage will expand out the filename.
.LP
=====================================================================
.sp 4
.NH 3 " writeimage()"
.XS
              \*(SN   writeimage()
.XE
.sp
.LP
The writeimage routine will write a Khoros VIFF image to a file specified
by filename. 
If the filename specified is a "-" or a "#", then the image
is written to standard output or standard error respectively. Writeimage
will return a 0 upon failure and a 1 upon success.
.sp 2
.B
.sp
int writeimage(filename, image)
.br
char *filename;
.br
struct xvimage *image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP filename: 10
The name of the file to write the VIFF image to. Note, this filename
may start with KHOROS_HOME, ~, . or /.
.IP image: 10
A pointer to the xvimage structure to write to the file specified by
filename.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " machorder()"
.XS
              \*(SN   machorder()
.XE
.sp
.LP
This routine will return the machine order given a machine name. The 
Machine name must be contained in machdefs.h in KHOROS_HOME/include.
In the case the machine name passed in to machorder does not exist
in the machdefs.h file, the value 255 is returned. Note, a machine type
of 255 is considered as undefined.
.sp 2
.B
.sp
int machorder(mach_name)
.br
char *mach_name
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP mach_name: 10
The name of the machine to find the machine type for. The machine
name must be exactly as defined in KHOROS_HOME/include/machdefs.h.
The value returned is either VFF_DEP_IEEEORDER, VFF_DEP_NSORDER or
VFF_DEP_DECORDER.
.LP
=====================================================================
.sp 4
.NH 3 " machtype()"
.XS
              \*(SN   machtype()
.XE
.sp
.LP
The machtype routine will determine what byte order the current
machine type is. This is machine dependent code. The machines
that are supported can be found it the include file in 
KHOROS_HOME/include/machdefs.h. If the current machine is not defined
in machtype, then the value of 255 is returned.  If the name parameter is
set to NULL, then the machine name is not returned. If the name parameter
is passed in as an allocated string the machine name is copied into that
string.
.sp 2
.B
.sp
long machtype(name)
.br
char *name
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP name: 10
Returns a pointer to string containing the name of the current machine. If the
name parameter is NULL, The machine name is not passed back. Note, the 
caller must allocate memory for the string if the current machine name is 
desired.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " ieeetonss()"
.XS
              \*(SN   ieeetonss()
.XE
.sp
.LP
The ieeetonss routine converts from type IEEE short to 
type NS short on a NS  machine.
.sp 2
.B
.sp
ieeetonss(s)
.br
short *s;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP s: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " nstoieees()"
.XS
              \*(SN   nstoieees()
.XE
.sp
.LP
The nstoieees routine converts from type NS short to 
type IEEE short on a IEEE machine.
.sp 2
.B
.sp
nstoieees(s)
.br
short *s;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP s: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " ieeetodecs()"
.XS
              \*(SN   ieeetodecs()
.XE
.sp
.LP
The ieeetodecs routine converts from type IEEE short to 
type DEC short on a DEC machine.
.sp 2
.B
.sp
ieeetodecs(s)
.br
short *s;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP s: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " dectoieees()"
.XS
              \*(SN   dectoieees()
.XE
.sp
.LP
The dectoieees routine converts from type DEC short to 
type IEEE short on a IEEE machine.
.sp 2
.B
.sp
dectoieees(s)
.br
short *s;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP s: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " dectonss()"
.XS
              \*(SN   dectonss()
.XE
.sp
.LP
The dectonss routine converts from type DEC short to 
type NS short on a NS  machine.
.sp 2
.B
.sp
dectonss(s)
.br
short *s;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP s: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " nstodecs()"
.XS
              \*(SN   nstodecs()
.XE
.sp
.LP
The nstodecs routine converts from type NS short to 
type DEC short on a DEC  machine.
.sp 2
.B
.sp
nstodecs(s)
.br
short *s;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP s: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " ieeetonsl()"
.XS
              \*(SN   ieeetonsl()
.XE
.sp
.LP
The ieeetonsl routine converts from type IEEE long to 
type NS long on a NS  machine.
.sp 2
.B
.sp
ieeetonsl(l)
.br
long *l;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP l: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " nstoieeel()"
.XS
              \*(SN   nstoieeel()
.XE
.sp
.LP
The nstoieeel routine converts from type NS long to 
type IEEE long on a IEEE machine
.sp 2
.B
.sp
nstoieeel(l)
.br
long *l;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP l: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " ieeetodecl()"
.XS
              \*(SN   ieeetodecl()
.XE
.sp
.LP
The ieeetodecl routine converts from type IEEE long to 
type DEC long on a DEC machine.
.sp 2
.B
.sp
ieeetodecl(l)
.br
long *l;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP l: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " dectoieeel()"
.XS
              \*(SN   dectoieeel()
.XE
.sp
.LP
The dectoieeel routine converts from type DEC long to 
type IEEE long on a IEEE machine.
.sp 2
.B
.sp
dectoieeel(l)
.br
long *l;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP l: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " dectonsl()"
.XS
              \*(SN   dectonsl()
.XE
.sp
.LP
The dectonss routine converts from type DEC long to 
type NS long on a NS  machine
.sp 2
.B
.sp
dectonsl(l)
.br
long *l;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP l: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " nstodecl()"
.XS
              \*(SN   nstodecl()
.XE
.sp
.LP
The nstodecl routine converts from type NS long to 
type DEC long on a DEC  machine.
.sp 2
.B
.sp
nstodecl(l)
.br
long *l;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP l: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " ieeetonsf()"
.XS
              \*(SN   ieeetonsf()
.XE
.sp
.LP
The ieeetonsf routine converts from type IEEE float to 
type NS float on a NS  machine.
.sp 2
.B
.sp
ieeetonsf(f)
.br
float *f;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP f: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " nstoieeef()"
.XS
              \*(SN   nstoieeef()
.XE
.sp
.LP
The nstoieeef routine converts from type NS float to 
type IEEE float on a IEEE machine.
.sp 2
.B
.sp
nstoieeef(f)
.br
float *f;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP f: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " ieeetodecf()"
.XS
              \*(SN   ieeetodecf()
.XE
.sp
.LP
The ieeetodecf routine converts from type IEEE float to 
type DEC float on a DEC machine.
.sp 2
.b
.sp
ieeetodecf(f)
.br
float *f;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP f: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " dectoieeef()"
.XS
              \*(SN   dectoieeef()
.XE
.sp
.LP
The dectoieeef routine converts from type DEC float to 
type IEEE float on a IEEE machine.
.sp 2
.B
.sp
dectoieeef(f)
.br
float *f;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP f: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " dectonsf()"
.XS
              \*(SN   dectonsf()
.XE
.sp
.LP
The dectonsf routine converts from type DEC float to 
type NS float on a NS  machine
.sp 2
.B
.sp
dectonsf(f)
.br
float *f;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP f: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.sp 4
.NH 3 " nstodecf()"
.XS
              \*(SN   nstodecf()
.XE
.sp
.LP
The nstodecf routine converts from type NS float to 
type DEC float on a DEC  machine.
.sp 2
.B
.sp
nstodecf(f)
.br
float *f;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP f: 10
Takes the value passed in, performs the necessary conversion and returns
the converted value.
.LP
=====================================================================
.bp
.sp2
.NH 2 "DATA MANIPULATION UTILITIES"
.XS
      \*(SN  DATA MANIPULATION UTILITIES
.XE
.sp 2
.LP
.NH 3 "load_vector()"
.XS
              \*(SN   load_vector()
.XE
.sp
.LP
The load_vector routine takes a multiband image and rearranges the data so 
that the data is stored as a list of vectors.
Each pixel in a multiband image can be thought of
as a vector looking down all the bands. Thus, each
pixel is a vector with dimension = number of data bands.
This routine will scan the image row by row making
a linear 2-dimensional array, where the first array index
points to a vector (which corresponds to some pixel),
the second array index contains the values for that
pixel looking down the bands on the image.
When a border is specified a row and column on each
side of the image is dropped. If the data is complex then each
data point has a real and imaginary part.
.LP
This routine returns a pointer to a 2-dimensional array. The
caller should cast the returned data to the appropriate type.
.B
.sp
char **load_vector(image, border, num_vects, dimension)
.br
struct xvimage *image;
.br
int border;
.br
int *num_vects;
.br
int *dimension;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP image: 10
A xvimage structure pointer to the image to vectorize.
.IP border: 10
The border width to skip.
.IP num_vects:
Returns the total number of vectors loaded into the array.
.IP dimension: 10
Returns the dimension of each vector.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " unload_vector()"
.XS
              \*(SN   unload_vector()
.XE
.sp
.LP
The unload_vector routine takes a 2-D array of vectorized data and 
rearranges the data so that the data is stored in an image format.
Each vector represents a pixel and the dimension of the
vector represents the number of data bands for the image.
So the mth element of the vector represents the pixel in
the mth data band.
The image is built by filling row by row from the
linear vector data. The border parameter specified is equal on all sides.
Unload_vector returns a pointer to a character array containing the
image data. Upon failure NULL is returned.
.sp 2
.B
.sp
char *unload_vector(input_vector, border, type, num_vects, dimension, nr, nc)
.br
char **input_vector;
.br
int border, type, num_vects, dimension, nr, nc;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP input_vector: 10
A pointer to the 2-D array of vectorized data.
.IP border: 10
The border width to skip around the image. This allows padding of an equal
width on all sides of the image.
.IP num_vects: 10
The total number of vectors contained in the 2-D array of vectorized data.
.IP dimension: 10
The dimension of each vector in the  2-D array of vectorized data.
.IP type: 
The type of data contained in the 2-D array of vectorized data. This must
be one of the following:
.RS
.RS
byte data - VFF_TYP_1_BYTE
.br
short data - VFF_TYP_2_BYTE
.br
long data - VFF_TYP_4_BYTE
.br
float data - VFF_TYP_FLOAT
.br
double data - VFF_TYP_DOUBLE
.br
complex data - VFF_TYP_COMPLEX
.br
double complex data - VFF_TYP_DCOMPLEX
.RE
.RE
.IP nr:
The number of rows desired in the resulting image.
.IP nc:
The number of columns desired in the resulting image.
.LP
Note, the number of columns times the number of rows must be equal
to the number of vectors in the 2-D array of vectorized data minus
the 4 times the border (border on each side).
.LP
=====================================================================
.bp
.sp 4
.NH 3 "dload_vector()"
.XS
              \*(SN   dload_vector()
.XE
.sp
.LP
The dload_vector routine is a dsp utility which takes a multiband
VIFF image and rearranges the data so that the it is stored as 
a list of vectors.
.LP
Dload_vector should be called at the beginning of each 
dsp routine to convert data to vector format.  It formats 
the data according to the process direction (DSP_VECTOR,
DSP_BAND) passed in.  
A **char vector data array is returned, and the values for
the num_vects and dimension are set.  The
caller should cast the returned data to the appropriate type. 
Dload_vector will return a NULL upon failure. 
.LP
The dimension parameter refers
to the number of points in each vector.  If the data
is complex, dimension is the number of complex PAIRS
per vector.
.LP
Dload_vector checks that number of image data bands is 
at least 1.  If data processing is in DSP_VECTOR direction,
Calls load_vector.  If data processing is in DSP_BAND 
direction, assigns data to 2 dimensional vector array.
.LP
DSP_VECTOR Processing Direction:
Each pixel in a multiband image can be thought of
as a vector looking down all the bands. Thus, each
pixel is a vector with dimension = number of data bands.
This format is obtained if the parameter, process_dir,
passed to dload_vector is DSP_VECTOR (0).
Memory is allocated for the vector array by load_vector.
.LP
When process_dir = DSP_VECTOR, dload_vector will scan the 
image row by row making a linear 
2-dimensional array, where the first array index
points to a vector (which corresponds to some pixel),
the second array index contains the values for that
pixel looking down the bands on the image.
Memory is allocated for the vector array in dload_vector.
.LP
DSP_BAND Processing Direction:
If process_dir is DSP_BAND (1), the calling routine requires
that each data band be represented as a vector.  Therefore
dload_vector will return a 2-dimensional array where
each band is a vector of dimension rows*cols.  
.LP
Data type can be of any type except BIT.
.LP
This routine returns a pointer to a 2-dimensional array. The
caller should cast the returned data to the appropriate type.
.B
.sp
char **dload_vector(image, num_vects, dimension, process_dir)
.br
struct xvimage *image;
.br
int process_dir;
.br
int *num_vects;
.br
int *dimension;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.LP
.IP image: 10
A xvimage structure pointer to the image to vectorize.
.IP process_dir: 10
a flag set to DSP_VECTOR (0) the data is to be vectorized down the bands,
and set to DSP_BAND (1) if each band is to be returned as a vector.
.IP num_vects:
Returns the total number of vectors loaded into the array.
.IP dimension: 10
Returns the dimension of each vector.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " dunload_vector()"
.XS
              \*(SN   dunload_vector()
.XE
.sp
.LP
The dunload_vector routine takes a 2-D array of vectorized data and 
rearranges the data so that the data is stored in an image format.
.LP
Dunload_vector should be called at the end of any dsp
routine that calls dload_vector.  This routine loads
the vector array back into an (multiband) image format.
Again, dunload_vector arranges the output data according to 
the process_dir variable (DSP_VECTOR or DSP_BAND) passed in.
.LP
dunload_vector does the following:
.IP 1.
Loads the data into image format (done differently
for vector vs. band processing directions)
You pass in a pointer to the xvimage structure
and dunload_vector assigns the data to a 1-d
data array, and then assigns this array to 
image->imagedata.
.IP 2.
If process direction = DSP_VECTOR, resets 
image->num_data_bands to dimension, and calls
unload_vector.
.IP 3.
If process direction is DSP_BAND, resets image->col_size
and/or image->row_size if dimension of data has been
altered.  (ie. dimension != rows*cols).  New row and
col sizes are set according to the following rules
(dim already divided by 2 if data is complex.):
.in +1.0i
if (num_rows = 1) then num_cols = dim/num_rows
.br
else if (num_cols = 1) then num_rows = dim/num_cols
.br
else if (dimension divisible by num_rows) then num_cols = dim/num_rows
.br
else if (dimension divisible by num_cols) then num_rows = dim/num_cols
else num_rows = 1, num_cols = dimension.
.in -1.0i
.IP 4.
Sets image->data_storage_type to type passed in.
.LP
.IP "DSP_VECTOR Process Direction:"
If the parameter process_dir = DSP_VECTOR (0), each 
vector represents a pixel and the dimension of the
vector represents the number of data bands for the image.
So the mth element of vector t represents pixel t in
the mth data band.  Therefore, the image is built by 
filling row by row from the linear vector data.
.IP "DSP_BAND Process Direction:"
If the parameter process_dir = DSP_BAND (1), each vector
represents a band and the dimension of the vectors
is given by rows*cols.  In this case, the image is
built by assigning each vector to a band in the 
output image.
.LP
Dunload_vector will return a 0 upon failure and a 1 upon success.
.sp 2
.B
.sp
int dunload_vector(input_vector, image, type, num_vects, dimension, process_dir)
.br
char **input_vector;
.br
struct xvimage *image
.br
int type, num_vects, dimension, process_dir);
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP input_vector: 10
A pointer to the 2-D array of vectorized data.
.IP image: 10
a pointer to the image to which the unvectorized data is assigned. Memory
for the new data will be allocated.
.IP num_vects: 10
The total number of vectors contained in the 2-D array of vectorized data.
.IP dimension: 10
The dimension of each vector in the  2-D array of vectorized data.
.IP type: 
The type of data contained in the 2-D array of vectorized data. This must
be one of the following:
.RS
.RS
byte data - VFF_TYP_1_BYTE
.br
short data - VFF_TYP_2_BYTE
.br
long data - VFF_TYP_4_BYTE
.br
float data - VFF_TYP_FLOAT
.br
double data - VFF_TYP_DOUBLE
.br
complex data - VFF_TYP_COMPLEX
.br
double complex data - VFF_TYP_DCOMPLEX
.RE
.RE
.IP process_dir: 
a flag set to DSP_VECTOR (0) the data is to be vectorized down the bands,
and set to DSP_BAND (1) if each band is to be returned as a vector.
.LP
=====================================================================
.bp
.sp2
.NH 2 "GENERAL UTILITIES"
.XS
      \*(SN  GENERAL UTILITIES
.XE
.sp 2
.LP
.NH 3 " freeimage()"
.XS
              \*(SN   freeimage()
.XE
.sp
.LP
This routine frees a Khoros xvimage structure. All data (image data,
map data, and location data) will be freed.
.sp 2
.B
.sp
freeimage(image)
.br
struct xvimage *image;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image: 10
A pointer to the xvimage structure to free.
.LP
=====================================================================
.bp
.sp 4
.NH 3 " set_color_space_model()"
.XS
              \*(SN   set_color_space_model()
.XE
.sp
.LP
The set_color_space_model routine will set an image's colorspace
model based on the model parameter.
.sp 2
.B
.sp
set_color_space_model(image, model)
.br
struct xvimage *image;
.br
int model;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP image: 10
A pointer to the structure line and specifies the left side line in the
output image that corresponds to one side of a pixel in the input image.
.IP model: 10
The color space model to set the image color_space_model field to. The
following list defines the valid values for the model parameter:
.RS
.RS
0 = VFF_CM_NONE
.br
1 = VFF_CM_ntscRGB
.br 
2 = VFF_CM_ntscCMY
.br
3 = VFF_CM_ntscYIQ
.br
4 = VFF_CM_HSV
.br
5 = VFF_CM_HLS
.br
6 = VFF_CM_IHS
.br
7 = VFF_CM_cieRGB
.br
8 = VFF_CM_cieXYZ
.br
9 = VFF_CM_cieUVW
.br
10 = VFF_CM_cieucsUVW
.br
11 = VFF_CM_cieucsSOW
.br
12 = VFF_CM_cieucsLab
.br
13 = VFF_CM_cieucsLuv
.br
14 = VFF_CM_GENERIC
.br
15 = VFF_CM_VFF_CM_genericRGb
.RE
.RE
.LP
=====================================================================
.bp
.sp 4
.NH 3 " imagesize()"
.XS
              \*(SN   imagesize()
.XE
.sp
.LP
The imagesize routine computes the size of the data fields in a VIFF
image. Also computed is the number of data pixels, the number of maps
cells and the number of location points. Imagesize will return a 1 upon
success and a 0 upon failure.
.sp 2
.B
.sp
int imagesize(image,dsize,dcount,msize,mcount,lsize,lcount)
.br
struct xvimage *image;
.br
int *dsize, *dcount, *msize, *mcount, *lsize, *lcount;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP dsize: 10
Returns the number of bytes contained in the imagedata field of 
the VIFF structure. This is computed by rows * columns * number of
data bands * sizeof data types.
.IP dcount: 10
Returns the number of pixels contained in the imagedata field of the 
VIFF structure.
.IP msize: 10
Returns the number of bytes contained in the map data field of the
VIFF structure.
.IP mcount: 10
Returns the total number of map cells.
.IP lsize: 
Returns the total number of bytes contained in the location data
field of the VIFF structure.
.IP lcount:
Returns the total number of location points.
.LP
=====================================================================
