## NAME

         libroi  -  CVIPtools  toolkit  library  for  region/area  of
         interest designation, manipulation of an image

## SYNOPSIS

         #include <CVIProi.h>

## DESCRIPTION

      TYPES AND CONSTANTS
         typedef struct {

               unsigned x;
               unsigned y;
               unsigned dx;
               unsigned dy;

               Image *dataP;

         } ROI;

      FUNCTION CATEGORIES

         ****************************************************
         ROI *new_ROI(void)
         ****************************************************

         Description: ROI class constructor. Creates a  new  instance
         of an ROI structure.  Author(s): Gregory Hance.

         ****************************************************
         void delete_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

         Description:  ROI  class  destructor.   Author(s):   Gregory
         Hance.

         ****************************************************
         void asgnImage_ROI(ROI *roiP, Image *imageP, unsigned x, unsigned y,
         unsigned dx, unsigned dy)
         ****************************************************

         <roiP> - pointer to a ROI object
         <imageP> - pointer to an Image object
         <x> - horizontal offset of region from pixel location (0,0)
         <y> - vertical offset of region from pixel location (0,0)
         <dx> - width of region (number of columns)
         <dy> - height of region (number of rows)

         Description: assigns an ROI to an image. Note that  the  ROI
         will  retain all of the same attributes as the parent image,
         with the exception that some additional information describ-
         ing  the  specific area/region of interest will be included.
         Author(s): Gregory Hance.

         ****************************************************
         void asgnFullImage_ROI(ROI *roiP, Image *imageP)
         ****************************************************

         <roiP> - pointer to an ROI object
         <imageP> - pointer to an Image object

         Description:  assign  ROI  as  the  full  image   dimension.
         Author(s): Gregory Hance.

         ****************************************************
         unsigned getHorOffset_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

         Description: returns the horizontal offset of the  ROI  from
         pixel (0,0).  Author(s): Gregory Hance.

         ****************************************************
         unsigned getVerOffset_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

         Description: returns the vertical offset  of  the  ROI  from
         pixel (0,0).  Author(s): Gregory Hance.

         ****************************************************
         unsigned getHorSize_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

         Description: returns the height/horizontal size of the  ROI.
         Author(s): Gregory Hance.

         ****************************************************
         unsigned getVerSize_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

         Description: returns the width/vertical  size  of  the  ROI.
         Author(s): Gregory Hance.

         ****************************************************
         unsigned getNoOfRows_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

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

         ****************************************************
         unsigned getNoOfCols_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

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

         ****************************************************
         unsigned getNoOfBands_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

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

         ****************************************************
         FORMAT getDataFormat_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

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

         ****************************************************
         CVIP_TYPE getDataType_ROI(ROI *roiP)
         ****************************************************

         <roiP> - pointer to an ROI object

         Description: returns the data type of the  ROI.   Author(s):
         Gregory Hance.

         ****************************************************
         void *getRealRow_ROI(ROI *roiP, unsigned y, unsigned band_no)
         ****************************************************

         <roiP> - pointer to an ROI object
         <y> - row number to reference
         <band_no> - band number to reference
         Description: returns a reference/pointer to a  real  row  of
         data  from  the ROI.  NOTE: the row returned is with respect
         to the ROI and not the image. (i.e.  getRealRow_ROI(roi,5,0)
         will  return row 5 of the ROI which is actually a pointer to
         the pixel sample at row = (5 + vertical offset), col = (hor-
         izontal offset) of the image ) Author(s): Gregory Hance.

         ****************************************************
         void *getRow_ROI(ROI *roiP, unsigned y, unsigned band_no)
         ****************************************************

         <roiP> - pointer to an ROI object
         <y> - row number to reference
         <band_no> - band number to reference

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

         ****************************************************
         void *getImagRow_ROI(ROI *roiP, unsigned y, unsigned band_no)
         ****************************************************
         Si
         <roiP> - pointer to an ROI object
         <y> - row number to reference
         <band_no> - band number to reference

         Description: returns a reference/pointer to an imaginary row
         of data from the ROI.  Author(s): Gregory Hance.

         ****************************************************
         type getRealPixel_ROI(ROI *roiP, type, unsigned x, unsigned y, unsigned band_no)
         ****************************************************

         <roiP> - pointer to an ROI object
         <type> - the name of a valid "C", CVIPtools image data type such as byte, short,
         int, float or double
         <x> - column number to reference
         <y> - row number to reference
         <band_no> - band number to reference

         Description: returns a real pixel sample  from  the  ROI  of
         type  <type>.   NOTE:  the pixel returned is with respect to
         the     ROI     and      not      the      image.      (i.e.
         getRealPixel_ROI(roi,byte,3,5,0) will return a pixel located
         at row 5 and column 3 of the ROI which is actually the pixel
         sample  at  row = (5 + "vertical offset") , col = (3 + "hor-
         izontal offset") of the parent  image.   Author(s):  Gregory
         Hance.

         ****************************************************
         type getPixel_ROI(ROI *roiP, type, unsigned x, unsigned y, unsigned band_no)
         ****************************************************
         <roiP> - pointer to an ROI object
         <type> - the name of a valid "C", CVIPtools image data type such as byte, short,
         int, float or double
         <x> - column number to reference
         <y> - row number to reference
         <band_no> - band number to reference

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

         ****************************************************
         type getImagPixel_ROI(ROI *roiP, type, unsigned x, unsigned y, unsigned band_no)
         ****************************************************

         <roiP> - pointer to an ROI object
         <type> - the name of a valid "C", CVIPtools image data type such as byte, short,
         int, float or double
         <x> - column number to reference
         <y> - row number to reference
         <band_no> - band number to reference

         Description: returns an imaginary pixel sample from the  ROI
         of type <type>.  Author(s): Gregory Hance.

         ****************************************************
         void setRealPixel_ROI(ROI *roiP, type, unsigned x, unsigned y,
         unsigned band_no, type pixel)
         ****************************************************

         <roiP> - pointer to an ROI object
         <type> - the name of a valid "C", CVIPtools image data type such as byte, short,
         int, float or double
         <x> - column number to reference
         <y> - row number to reference
         <band_no> - band number to reference
         <pixel> - datum to be placed at the above location

         Description: writes a real pixel sample to the ROI  of  type
         <type>.   NOTE: the pixel written is with respect to the ROI
         and          not          the          image.          (i.e.
         setRealPixel_ROI(roi,byte,3,5,0,200)  will  write to a pixel
         located at row 5 and column 3 of the ROI which  is  actually
         the pixel sample at row = (5 + "vertical offset") , col = (3
         + "horizontal offset") of the parent image.

         Author(s): Gregory Hance.

         ****************************************************
         void setPixel_ROI(ROI *roiP, type, unsigned x, unsigned y,
         unsigned band_no, type pixel)
         ****************************************************

         <roiP> - pointer to an ROI object
         <type> - the name of a valid "C", CVIPtools image data type such as byte, short,
         int, float or double
         <x> - column number to reference
         <y> - row number to reference
         <band_no> - band number to reference
         <pixel> - datum to be placed at the above location

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

         ****************************************************
         void setImagPixel_ROI(ROI *roiP, type, unsigned x, unsigned y,
         unsigned band_no, type pixel)
         ****************************************************

         <roiP> - pointer to an ROI object
         <type> - the name of a valid "C", CVIPtools image data type such as byte, short,
         int, float or double
         <x> - column number to reference
         <y> - row number to reference
         <band_no> - band number to reference
         <pixel> - datum to be placed at the above location

         Description:  set/write  imaginary  pixel  sample  to   ROI.
         Author(s): Gregory Hance.

         ****************************************************
         void unloadRow_ROI(void *roiP, void *rowP, unsigned y, unsigned band_no)
         ****************************************************

         <roiP> - pointer to an ROI object
         <rowP> - buffer to unload data into
         <row> - row to unload
         <band_no> - band number of the row to unload

         Description: unload row of data from ROI at row <y> into the
         buffer <rowP>.  Author(s): Gregory Hance.

         ****************************************************
         void loadRow_ROI(void *roiP, void *rowP, unsigned y, unsigned band_no)
         ****************************************************

         <roiP> - pointer to an ROI object
         <rowP> - buffer to unload data into
         <row> - row to unload
         <band_no> - band number of the row to unload

         Description: load data from the buffer <rowP> into  the  ROI
         at row <y>.

## BUGS

         none as of yet

## SEE ALSO

         CVIPtools library quick reference guide

## AUTHOR

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