vutils(3)

NAME
vutils - VIFF image utilities

DESCRIPTION
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.

For an explanation of all the following routines in greater detail, with explanations of all arguments to each routine, see the section on vutils in the Khoros Programmer's Manual, chapter 8, Libraries.

ALL programs that utilize these routines MUST include the statement:

#include "vinclude.h"

AVAILABLE ROUTINES

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.

int append_comment(image_comment, new_comment)
char *image_comment;
char *new_comment;

copyheader()

Copy the image header from one image to another.

copyheader(image1, image2);
struct xvimage *image1;
struct xvimage *image2;

copyimage()

Copy the entire image from one struct xvimage pointer to another. This routine will return a pointer to the xvimage structure upon success, NULL on failure.

struct xvimage *copyimage(image);
struct xvimage *image;

copyimagedata()

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.

int copyimagedata(image1, image2, malloc_flag);
struct xvimage *image1;
struct xvimage **image2;
int malloc_flag;

copylocationdata()

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.

int copylocationdata(image1, image2, malloc_flag);
struct xvimage *image1;
struct xvimage **image2;
int malloc_flag;

copymapdata()

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.

int copymapdata(image1, image2, malloc_flag);
struct xvimage *image1;
struct xvimage **image2;
int malloc_flag;

create_comment()

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.

int create_comment(resulting_comment, new_comment, original_comment)
char *resulting_comment
char *new_comment;
char *original_comment;

createimage()

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.

struct xvimage *createimage(col_size, row_size, data_storage_type,
num_of_images, num_data_bands, comment, map_row_size, map_col_size,
map_scheme, map_storage_type, location_type, location_dim),
unsigned long col_size, row_size, data_storage_type, num_of_images;
unsigned long num_data_bands, map_row_size, map_col_size, map_scheme;
unsigned long map_storage_type, location_type, location_dim;
char *comment;

create_image_list()

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.

struct xvimage **create_image_list(image_num);
unsigned int image_num;

block_read()

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.

int block_read(fid, input, size)
int fid;
int size;
char *input;

check_file_type()

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.

int check_file_type(fid)
int fid;

read_raw()

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.

float *read_raw(fid, offset, points, type, mach_type)
int fid, offset, type, mach_type;
int *points;

write_raw()

This routine writes a raw data array to the desired file, specified by fid.

int write_raw(fid, data, num_bytes)
int fid;
char *data;
int num_bytes;

read_ascii()

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.

float *read_ascii(file, points)
FILE *file;
int *points;

write_ascii()

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.

int write_ascii(file, points, ncols, num_points)
FILE *file;
float *points;
int ncols, num_points;

readimage()

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.

struct xvimage *readimage(filename)
char *filename

writeimage()

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.

int writeimage(filename, image)
char *filename;
struct xvimage *image;

machorder()

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.

int machorder(mach_name)
char *mach_name

machtype()

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.

long machtype(name)
char *name

ieeetonss()

The ieeetonss routine converts from type IEEE short to type NS short on a NS machine.

ieeetonss(s)
short *s;

nstoieees()

The nstoieees routine converts from type NS short to type IEEE short on a IEEE machine.

nstoieees(s)
short *s;

ieeetodecs()

The ieeetodecs routine converts from type IEEE short to type DEC short on a DEC machine.

ieeetodecs(s)
short *s;

dectoieees()

The dectoieees routine converts from type DEC short to type IEEE short on a IEEE machine.

dectoieees(s)
short *s;

dectonss()

The dectonss routine converts from type DEC short to type NS short on a NS machine.

dectonss(s)
short *s;

ieeetonsl()

The ieeetonsl routine converts from type IEEE long to type NS long on a NS machine.

ieeetonsl(l)
long *l;

nstoieeel()

The nstoieeel routine converts from type NS long to type IEEE long on a IEEE machine.

nstoieeel(l)
long *l;

ieeetodecl()

The ieeetodecl routine converts from type IEEE long to type DEC long on a DEC machine.

ieeetodecl(l)
long *l;

dectoieeel()

The dectoieeel routine converts from type DEC long to type IEEE long on a IEEE machine.

dectoieeel(l)
long *l;

dectonsl()

The dectonss routine converts from type DEC long to type NS long on a NS machine.

dectonsl(l)
long *l;

nstodecl()

The nstodecl routine converts from type NS long to type DEC long on a DEC machine.

nstodecl(l)
long *l;

ieeetonsf()

The ieeetonsf routine converts from type IEEE float to type NS float on a NS machine.

ieeetonsf(f)
float *f;

nstoieeef()

The nstoieeef routine converts from type NS float to type IEEE float on a IEEE machine.

nstoieeef(f)
float *f;

ieeetodecf()

The ieeetodecf routine converts from type IEEE float to type DEC float on a DEC machine.

ieeetodecf(f)
float *f;

dectoieeef()

he dectoieeef routine converts from type DEC float to type IEEE float on a IEEE machine.

dectoieeef(f)
float *f;

dectonsf()

The dectonsf routine converts from type DEC float to type NS float on a NS machine.

dectonsf(f)
float *f;

nstodecf()

The nstodecf routine converts from type NS float to type DEC float on a DEC machine.

nstodecf(f)
float *f;

load_vector()

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 ixel 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.

char **load_vector(image, border, num_vects, dimension)
struct xvimage *image;
int border;
int *num_vects;
int *dimension;

unload_vector()

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.

char *unload_vector(input_vector, border, type, num_vects, dimension, nr, nc)
char **input_vector;
int border, type, num_vects, dimension, nr, nc;

dload_vector()

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. 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. Dload_vector will return a NULL upon failure.

char **dload_vector(image, num_vects, dimension, process_dir)
struct xvimage *image;
int process_dir;
int *num_vects;
int *dimension;

dunload_vector()

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. 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. Dunload_vector will return a 0 upon failure and a 1 upon success, and a 0 upon failure.

int dunload_vector(input_vector, image, type, num_vects, dimension, process_dir)
char **input_vector;
struct xvimage *image
int type, num_vects, dimension, process_dir);

set_color_space_model()

The set_color_space_model routine will set an image's colorspace model based on the model parameter.

set_color_space_model(image, model)
struct xvimage *image;
int model;

imagesize()

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.

int imagesize(image,dsize,dcount,msize,mcount,lsize,lcount)
struct xvimage *image;
int *dsize, *dcount, *msize, *mcount, *lsize, *lcount;