## NAME

         libimage - CVIPtools toolkit library containing routines for
         image type conversion, memory management, etc.

## SYNOPSIS

         #include <CVIPimage.h>

## DESCRIPTION

      TYPES AND CONSTANTS
          typedef enum {PBM, PGM, PPM, EPS, TIF, GIF, RAS, ITX, IRIS, CCC, BIN, VIP, GLR, BTC, BRC, HUF, ZVL, ARITH, BTC2, BTC3, DPC, ZON, ZON2, SAFVR, JPG} IMAGE_FORMAT;

         typedef enum {BINARY, GRAY_SCALE, RGB, HSL, HSV, SCT, CCT, LUV, LAB, XYZ}
         COLOR_FORMAT;

         typedef struct {
            IMAGE_FORMAT image_format;
            COLOR_FORMAT color_space;
            int bands;
            Matrix **image_ptr;
            HISTORY story;
         } Image;

         typedef enum {CVIP_BYTE, CVIP_SHORT, CVIP_INTEGER, CVIP_FLOAT, CVIP_DOUBLE} CVIP_TYPE;
         typedef enum {REAL, COMPLEX} FORMAT;

         typedef struct {
            CVIP_TYPE data_type;
            FORMAT data_format;
            unsigned int rows;
            unsigned int cols;
            void **rptr;
            void **iptr;
         } Matrix;

## FUNCTIONS

          The following functions are included in this manpage:

          cast_Image               getRealPixel_Image
          delete_Image             getRealRow_Image
          dump_Image               getRow_Image
          duplicate_Image          history_add
          getBandVector_Image      history_check
          getBand_Image            history_copy
          getColorSpace_Image      history_get
          getDataFormat_Image      history_print
          getDataType_Image        history_show
          getFileFormat_Image      makeComplex_Image
          getImagPixel_Image       makeReal_Image
          getImagRow_Image         new_Image
          getNoOfBands_Image       setBand_Image
          getNoOfCols_Image        setImagPixel_Image
          getNoOfRows_Image        setPixel_Image
          getPixel_Image           setRealPixel_Image

      MEMORY MANAGEMENT
         =====================================================================
         Image *new_Image(IMAGE_FORMAT image_format, COLOR_FORMAT color_space,
         int bands, int heigth, int width, CVIP_TYPE data_type,
         FORMAT data_format)
         =====================================================================

         <image_format> - original file format of image
         <color_space> - current color space of image
         <bands> - number of spectral bands
         <height> - height of image (no. of rows)
         <width> - width of image (no. of cols)
         <data_type> - current data type of image
         <data_format> - specifies real or complex data

         Returns: pointer  to  Image  structure.  Description:  Image
         class  constructor.  creates  a  new instance of a CVIPtools
         Image structure.The Image structure is the primary means  of
         data  transport  in CVIPtools. Ordinarily the developer does
         not have to worry about allocating an Image structure in the
         sense that the function read_Image(...) returns a pointer to
         an Image structure that has been initialized to the specifi-
         cations  of  a  particular image. Diagnostics returns a NULL
         pointer w/ respective error message when a memory allocation
         request can not be satisfied.  Author(s): Gregory Hance.

         =====================================================================
         void delete_Image(Image *A)
         =====================================================================

         <A> - pointer to Image structure

         Description: Image class destructor. Free all elements of an
         Image  structure.   Diagnostics:  complains if the structure
         passed is not valid.  Author(s): Gregory Hance.

      Image DISPLAY
         =====================================================================
         Image *duplicate_Image(const Image *a)
         =====================================================================

         <a> - pointer to Image structure

         Returns:  pointer  to  new  Image  structure.   Description:
         creates  a new instance of the Image structure pointed to by
         <a>. This function is useful if one wants to pass  an  Image
         structure  to  a  function to be processed while maintaining
         the integrity of the original image.  Diagnostics: complains
         and  returns  NULL  pointer  upon memory allocation failure.
         Author(s): Gregory Hance.

      CASTING TO NEW TYPES - FORMATS
         =====================================================================
         int cast_Image(Image *src, CVIP_TYPE dtype)
         =====================================================================

         <src> - pointer to Image structure
         <type> - new data type

         Returns: 0 or 1.  Description: casts an Image structure into
         a  more  precise  data  type.  Diagnostics: returns 1 if the
         cast can be performed (i.e. the type specified by <type>  is
         more  precise  than that of <src> and 0 if the type of <src>
         is more precise than that of <type>. If the  types  are  the
         same  or  0  is  returned  then  <src>  is  left  untouched.
         Author(s): Gregory Hance.

         =====================================================================
         void makeComplex_Image(Image *src)
         =====================================================================

         <src> - pointer to "real" Image structure

         Description: create a "complex" Image structure  by  reallo-
         cating  the  storage  the associated with the Image -- <src>
         Diagnostics: complains when an invalid  Image  structure  is
         passed.  Author(s): Gregory Hance.

         =====================================================================
         void makeReal_Image(Image *src)
         =====================================================================

         <src> - pointer to "complex" Image structure

         Description: create a "real" Image structure by reallocating
         the storage the associated with the Image -- <src>. Diagnos-
         tics: complains when an invalid Image structure  is  passed.
         Author(s): Gregory Hance.

      IMPORTING & EXPORTING DATA
         =====================================================================
         void getBandVector_Image(Image *imageP, void *vecP)
         =====================================================================

         <imageP> - pointer to an Image object
         <vecP> - pointer to a vector that will reference the image data bands

         Description: unload the Image bands into a vector Author(s):
         Gregory Hance.

         =====================================================================
         unsigned getNoOfRows_Image(Image *image)
         =====================================================================
         <image> - pointer to an Image object

         Description: returns the height  of  an  Image.   Author(s):
         Gregory Hance.

         =====================================================================
         unsigned getNoOfCols_Image(Image *image)
         =====================================================================

         <image> - pointer to an Image object

         Description: returns the width of an Image.  Author(s): Gre-
         gory Hance.

         =====================================================================
         CVIP_TYPE getDataType_Image(Image *image)
         =====================================================================

         <image> - pointer to an Image object

         Description:  returns  the  data  type  of  an  Image  (e.g.
         CVIP_BYTE,CVIP_FLOAT, etc.)  Author(s): Gregory Hance.

         =====================================================================
         FORMAT getDataFormat_Image(Image *image)
         =====================================================================

         <image> - pointer to an Image object

         Description: returns the data format of an image (i.e.  REAL
         or COMPLEX).  Author(s): Gregory Hance.

         =====================================================================
         IMAGE_FORMAT getFileFormat_Image(Image *image)
         =====================================================================

         <image> - pointer to an Image object

         Description: returns the  file  format  of  an  Image  (e.g.
         PPM,PGM,etc.).  Author(s): Gregory Hance.

         =====================================================================
         COLOR_FORMAT getColorSpace_Image(Image *image)
         =====================================================================

         <image> - pointer to an Image object

         Description: returns the  color  space  of  an  Image  (e.g.
         RGB,GRAY, etc.).  Author(s): Gregory Hance.

         =====================================================================
         unsigned getNoOfBands_Image(Image *image)
         =====================================================================

         <image> - pointer to an Image object

         Description: returns the number of data bands in  an  Image.
         Author(s): Gregory Hance.

         =====================================================================
         Matrix *getBand_Image(Image *image, unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <band> - band number to reference (0 ... bands-1)

         Description: returns a band  of  Image  data  as  a  Matrix.
         Author(s): Gregory Hance.

         =====================================================================
         Matrix *setBand_Image(Image *image, unsigned band, unsigned band_no)
         =====================================================================

         <image> - pointer to an Image object
         <band> - new band number to reference
         <band_no> - band number to reference (0 ... bands-1)

         Description: add a new reference to a band of  matrix  data.
         Sets band_no equal to band.  Author(s): Gregory Hance.

         =====================================================================
         void *getRealRow_Image(Image *image, unsigned row, unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)

         Description: returns a reference to a real row of image data
         in  band  <band>  at  row offset <row>..  Author(s): Gregory
         Hance.

         =====================================================================
         void *getRow_Image(Image *image, unsigned row, unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)

         Description:  same as "getRealRow_Image" Author(s):  Gregory
         Hance.

         =====================================================================
         void *getImagRow_Image(Image *image, unsigned row, unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)

         Description:  returns a reference to  an  imaginary  row  of
         image  data  in band <band> at row offset <row>.  Author(s):
         Gregory Hance.

         =====================================================================
         type getRealPixel_Image(Image *image, type, unsigned col, unsigned row,
         unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <type> - the name of a valid "C", CVIPtools data type (i.e. one of byte,
         short, int, float or double)
         <col> - column number to reference (0 ... cols-1)
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)

         Description: read a real pixel sample  of  image  data  from
         band  <band>  at  row  offset <row> and column offset <col>.
         Author(s): Gregory Hance.

         =====================================================================
         type getPixel_Image(Image *image, type, unsigned col, unsigned row,
         unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <type> - the name of a valid "C", CVIPtools data type (i.e. one of byte,
         short, int, float or double)
         <col> - column number to reference (0 ... cols-1)
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)

         Description: same as "getRealPixel_Image" Author(s): Gregory
         Hance.

         =====================================================================
         type getImagPixel_Image(Image *image, type, unsigned col, unsigned row,
         unsigned band)
         =====================================================================

         <image> - pointer to an Image object
         <type> - the name of a valid "C", CVIPtools data type (i.e. one of byte,
         short, int, float or double)
         <col> - column number to reference (0 ... cols-1)
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)

         Description: read an imaginary pixel sample  of  image  data
         from  band  <band>  at  row  offset  <row> and column offset
         <col>.  Author(s): Gregory Hance.

         =====================================
         void history_add(image, newstuff)
         =====================================

         Image *image;

         HISTORY newstuff;

         Adds the contents in the structure pointed to by newstuff to the
         image history.

         #include "CVIPimage.h"
         HISTORY stuff;
         int *hptr;
         stuff = (HISTORY)malloc(sizeof(struct history));
         stuff->packetP = (PACKET *)malloc(sizeof(PACKET));
         stuff->packetP->dsize=1;
         stuff->packetP->dtype=(CVIP_TYPE *)malloc(sizeof(CVIP_TYPE));
         stuff->packetP->dtype[0]=CVIP_INTEGER;
         hptr=(int *)malloc(sizeof(int));
         hptr[0]=block_size;
         stuff->packetP->dptr=(void **)malloc(sizeof(void *)*dsize);
         stuff->packetP->dptr=(void *)(int *)hptr;
         stuff->next=(HISTORY)NULL;
         stuff->ftag=WALSH;
         history_add(input_Image, stuff);

         Arve Kjoelen, Southern Illinois University at Edwardsville, 1993.

         The document history_doc.frame contained in $CVIPHOME/docs contains a
         complete listing of the routines supported by the history structure
         along with additional documentation.

         ============================================================
         CVIP_BOOLEAN history_check(PROGRAMS routine, Image *your_image)
         ============================================================

         Determines whether the CVIPtools program specified by 'routine' has been
         performed on the image.  returns CVIP_YES if the program has been performed, returns CVIP_NO if the program has not been performed on that image.

         #include "CVIPimage.h"
         #include "CVIPdef.h"
         #include "CVIPtools.h"
         Image *my_image;
         if(history_check(FFT, my_image) {
            ...
         }
         else {
            ...
         }

         Arve Kjoelen, Southern Illinois University at Edwardsville, 1993.

         The document history_doc.frame contained in $CVIPHOME/docs contains a
         complete listing of the routines supported by the history structure
         along with additional documentation.

         =====================================================
         HISTORY history_get(Image *image, PROGRAMS routine)
         =====================================================

         Checks whether the CVIPtools program specified by 'routine' has been
         performed on the image.  Returns a pointer to the history structure
         containing information about the program.  If the program has not been
         performed on the image, (HISTORY)NULL is returned.

         /* This sample code extracts the blocksize of a previously */
         /* performed FFT from the history structure of an image.   */
         #include "CVIPimage.h"
         #include "CVIPdef.h"
         #include "CVIPtools.h"
         Image *my_image;
         HISTORY story;
         int *dataptr;
         int blocksize;
         if(history_check(HAAR, my_image) {
            story=(HISTORY)history_get(my_image, HAAR);
            dataptr=(int *)story->packetP->dptr;
            blocksize=dataptr[0];

         The document history_doc.frame contained in $CVIPHOME/docs contains a
         complete listing of the routines supported by the history structure
         along with additional documentation.

         ====================================
         void history_show(Image *your_image)
         ====================================

         This routine checks the image history structure for entries (programs
         that have been performed on the structure). It then passes each entry
         to the function history_print, which prints the processing history to stdout.

         AUTHOR Arve Kjoelen, Southern Illinois University at Edwardsville, 1993

         SEE ALSO
         The document history_doc.frame contained in $CVIPHOME/docs contains a
         complete listing of the routines supported by the history structure
         along with additional documentation.

         ====================================
         void history_print(HISTORY stuff)
         ====================================

         This routine performs the actual output of the information associated
         with the history structure passed to it.

         The document history_doc.frame contained in $CVIPHOME/docs contains a
         complete listing of the routines supported by the history structure
         along with additional documentation.

         ===================================================
         void history_copy(Image *fromimage, Image *toimage
         ===================================================

         Copies the history information contained in fromimage to to image.

         #include "CVIPimage.h"
         Image *fromimage, *toimage;
         (void)history_copy(fromimage, toimage);

         =====================================================================
         void setRealPixel_Image(Image *image, type, unsigned col, unsigned row,
         unsigned band, type pixel)
         =====================================================================

         <image> - pointer to an Image object
         <type> - the name of a valid "C", CVIPtools data type (i.e. one of byte,
         short, int, float or double)
         <col> - column number to reference (0 ... cols-1)
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)
         <pixel> - pixel sample of type <type>

         Description: write a real pixel sample of image data to band
         <band>   at  row  offset  <row>  and  column  offset  <col>.
         Author(s): Gregory Hance.

         =====================================================================
         void setPixel_Image(Image *image, type, unsigned col, unsigned row,
         unsigned band, type pixel)
         =====================================================================

         <image> - pointer to an Image object
         <type> - the name of a valid "C", CVIPtools data type (i.e. one of byte,
         short, int, float or double)
         <col> - column number to reference (0 ... cols-1)
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)
         <pixel> - pixel sample of type <type>

         Description: same as "setRealPixel_Image".  Author(s):  Gre-
         gory Hance.

         =====================================================================
         void setImagPixel_Image(Image *image, type, unsigned col, unsigned row,
         unsigned band, type pixel)
         =====================================================================

         <image> - pointer to an Image object
         <type> - the name of a valid "C", CVIPtools data type (i.e. one of byte,
         short, int, float or double)
         <col> - column number to reference (0 ... cols-1)
         <row> - row number to reference (0 ... rows-1)
         <band> - band number to reference (0 ... bands-1)
         <pixel> - pixel sample of type <type>

         Description: write an imaginary pixel sample of  image  data
         to  band <band> at row offset <row> and column offset <col>.
         Author(s): Gregory Hance.

      MISC.
         =====================================================================
         CVIP_BOOLEAN dump_Image(Image *src)
         =====================================================================

         <src> - pointer to Image structure

         Returns: 1 upon success; 0 upon failure. Description:  print
         the contents of an Image structure Diagnostics: returns 0 if
         the pointer to the Image structure is not valid.  Author(s):
         Gregory Hance.

## BUGS

         none as of yet

## SEE ALSO

         CVIPtools library quick reference guide

## AUTHOR

         Copyright (C) 1992, 1993 SIUE - by Gregory Hance  and  Scott
         Umbaugh.

## SEE ALSO

         libconverter(for read_Image, write_Image)

## AUTHOR

         Copyright (C) 1995 SIUE - by Scott Umbaugh.