NAME

     libband - CVIPtools toolkit library for the data handling of
     multi-spectral imagery

SYNOPSIS

     #include <CVIPband.h>
     #include <CVIPimage.h>
     cc ... libband.a libmatrix.a libcli.a

     libband includes the following utilities:

                            assemble_bands
                            bandcast
                            bandcopy
                            band_minmax
                            extract_band
                            matalloc
                            matfree
                            vecalloc
                            vecfree

DESCRIPTION

  ASSEMBLE MULTI-SPECTRAL Image FROM MONOCHROME ImageS
     ===========================================================
      Image *assemble_bands(Image **inImgs, int noimgs);
     ===========================================================

     <inImgs> - Pointer to array of image pointers
     <noimgs> - number of image pointers contained in the array.

     Returns: Pointer to new image structure.   Description:  add
     monochrome image planes to create
                  a multispectral image.  Diagnostics: - Supports
     COMPLEX data formats.
                  - If any color images are passed, only their
                    first color band is used.
                  - Adds history entry for operation.
                  - Returns NULL if error is encountered.

  CAST DATA BANDS
     =========================================================
      MATRIX **bandcast(MATRIX **srcBANDS, int no_of_bands,
      CVIP_TYPE data_type);
     =========================================================

     <srcBANDS> - pointer to an array of MATRIX pointers
     <no_of_bands> - number of spectral data bands
     <data_type> - data type to be promoted to

     Returns: pointer to new array of MATRIX pointers  cast  into
     the  specified  data  type  Description: cast the data of an
     image pointed to by <srcBANDS> into  a  more  precise  type.
     Diagnostics:  returns  with  NULL  pointer and error message
     when cast cannot be performed.

  COPY DATA BANDS
     =======================================================
     void bandcopy(MATRIX **, MATRIX **, int);
     =======================================================

     <srcBANDS> - pointer to an array of MATRIX pointers
     <desBANDS> - pointer to an array of MATRIX pointers
     <no_of_bands> - number of spectral data bands

     Description: copy the data pointed  to  be  <srcBANDS>  into
     that of <desBANDS>.

  FIND MIN AND MAX
     =================================================================
     void *band_minmax(MATRIX *const *bands, unsigned int no_of_bands,
     CVIP_TYPE data_type, int bstart, int bstop);
     =================================================================

     <bands> - pointer to array of MATRIX pointers
     containing image data
     <no_of_bands> - number of spectral bands
     <data_type> - type of image data
     <bstart> - starting band
     <bstop> - stopping band

     Returns: Pointer to array containing pairs of min.  and  and
     max.  values.  Array will have same data type as image data.
     Description: find the maximum and  minimum  values  of  each
     band  of  an  image  from <bstart> to <bstop>.  Diagnostics:
     returns NULL pointer w/ error message  if  bstop  <  bstart,
     etc.

  EXTRACT ONE BAND FROM MULTI-SPECTRAL Images
     ==========================================================
      Image *extract_band(Image *inImg, int bandno);
     ==========================================================

     <inImgs> - Pointer to image
     <bandno> - band number to be extracted from the image.

      Returns: Pointer to new image structure.
      Description: Create a monochrome image from a color
                   image by extracting a color plane.
      Diagnostics: - Supports COMPLEX data formats.
                   - Adds history entry for operation.
                   - Returns NULL if error is encountered.

     ===============================================================
     void *matalloc( unsigned int depth, unsigned int rows,
     unsigned int cols, size_t size );
     ===============================================================

     <depth> - depth of matrix
     <rows> - number of rows in matrix
     <cols> - number of columns in matrix
     <size> - size of each matrix element (e.g.
     sizeof(float))

     Returns: triple pointer to a new instance  of  an  array  of
     matrices  Description: allocate an array of <depth> matrices
     each with <rows> rows and <cols> cols with an  element  size
     of  <size>.  NOTE: use matfree(...) to free the matrix Diag-
     nostics: returns NULL pointer w/ corresponding error message
     upon memory allocation failure.

     =====================================================
     void matfree(void *matP, unsigned int no_of_planes);
     =====================================================

     <matP> - pointer to matrix allocated w/ matalloc
     <number_of_planes> - depth of matrix (number of
     data bands)

     Description: free the memory associated with a matrix  allo-
     cated by matalloc

  MEMORY MANAGEMENT
     ===============================================================
     void *vecalloc( unsigned int no_of_vecs, unsigned int vdim,
     size_t size );
     ===============================================================

     <no_of_vecs> - number of vectors to allocate
     <vdim> - dimension of each vector
     <size> - size of each vector element (e.g.
     sizeof(float))

     Returns: double pointer to a new instance  of  an  array  of
     vectors.   Description:  allocate  an  array of <no_of_vecs>
     vectors each of size <vdim> with an element size of  <size>.
     NOTE:  use  vecfree(...)  to  free  the  vector Diagnostics:
     returns NULL pointer w/  corresponding  error  message  upon
     memory allocation error

     =====================================================
     void vecfree(void *vecP, unsigned int no_of_vecs);
     =====================================================

     <vecP> - pointer to vector allocated w/ vecalloc
     <number_of_vecs> - number of vectors (number of
     data bands)

     Description: free the memory associated with a vector  allo-
     cated by vecalloc

BUGS

     none as of yet

SEE ALSO

     CVIPtools

AUTHOR

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