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