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.