## NAME

         libmatrix  -  CVIPtools  toolkit   library   for   numerical
         analysis/linear algebra and matrix manipulation

## SYNOPSIS

         #include <CVIPmatrix.h>

## DESCRIPTION

      TYPES AND CONSTANTS
         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:

         CANG                     getImagVal_Matrix
         CASSIGN                  getNoOfCols_Matrix
         CMAG                     getNoOfRows_Matrix
         CMUL                     getRealData_Matrix
         MAGSQ                    getRealRow_Matrix
         POL2REC                  getRealVal_Matrix
         REC2POL                  getRow_Matrix
         add_Matrix               getVal_Matrix
         copy_Matrix              invert_Matrix
         covariance_Matrix        makeComplex_Matrix
         crop_Matrix              makeReal_Matrix
         delete_Matrix            mult_Matrix
         det_Matrix               multPWise_Matrix
         eigenSystem_Matrix       new_Matrix
         fastCopy_Matrix          print_Matrix
         getDataFormat_Matrix     rect2pol_Matrix
         getData_Matrix           scale_Matrix
         getDataType_Matrix       sub_Matrix
         getImagData_Matrix       transpose_Matrix
         getImagRow_Matrix        and_Matrix
         clone_Matrix             duplicate_Matrix
         setRealVal_Matrix        setVal_Matrix
         setImagVal_Matrix        conj_Matrix
         mag_Matrix               square_mag_Matrix       sqrt_Matrix
         divide_Matrix

      MEMORY MANAGEMENT
         ===========================================================
         Matrix *new_Matrix(unsigned int rows, unsigned int cols, CVIP_TYPE data_type,
         FORMAT data_format)
         ===========================================================

         <rows> - number of rows for new matrix
         <cols> - nuber of cols for new matrix
         <data_type> - one of CVIP_BYTE, CVIP_SHORT, CVIP_INTEGER, CVIP_FLOAT or CVIP_DOUBLE
         <data_format> - one of REAL or IMAGINARY

         Returns: a pointer to the newly allocated  Matrix  structure
         Description: Matrix class constructor. allocates a structure
         of type Matrix with <rows> x <cols> data  elements  of  type
         <data_type>.   The  Matrix  structure  contains two members,
         **rptr and **iptr which are used to reference the  real  and
         imaginary  data  respectively. The matrix data is contiguous
         in the sense that a reference to the address  of  the  first
         element  may be used to dereference all others. Diagnostics:
         returns NULL pointer w/  corresponding  error  message  upon
         memory allocation failure.  Author(s): Gregory Hance.

         ===========================================================
         void delete_Matrix(Matrix *A)
         ===========================================================

         <A> - pointer to a Matrix structure

         Description: Matrix class Destructor. Frees all memory asso-
         ciated with a Matrix structure.  NOTE: Matrix structure must
         be allocated be new_Matrix Diagnostics: returns  with  error
         message when invalid Matrix structure is passed.  Author(s):
         Gregory Hance.

      MATRIX MANIPULATION
         ===========================================================
         unsigned getNoOfRows_Matrix(Matrix *matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

         Description: returns number of  rows  in  a  Matrix  object.
         Author(s): Gregory Hance.

         ===========================================================
         unsigned getNoOfCols_Matrix(Matrix *matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

         Description: returns number of columns in a  Matrix  object.
         Author(s): Gregory Hance.
         ===========================================================
         CVIP_TYPE getDataType_Matrix(Matrix *matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

         Description:  returns  data  type  of  Matrix  object  (e.g.
         CVIP_BYTE,CVIP_FLOAT,etc.).  Author(s): Gregory Hance.

         ===========================================================
         FORMAT getDataFormat_Matrix(Matrix *matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

         Description: returns data format of a  Matrix  object  (i.e.
         REAL or COMPLEX).  Author(s): Gregory Hance.

         ===========================================================
         void *getRealData_Matrix(Matrix *matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

         Description: returns reference to the real data of a  Matrix
         object (mapped into rows).  Author(s): Gregory Hance.

         ===========================================================
         void *getData_Matrix(Matrix *matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

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

         ===========================================================
         void *getRealRow_Matrix(Matrix *matrix, unsigned row)
         ===========================================================

         <matrix> - pointer to a Matrix object
         <row> - row number (0 ... rows-1)

         Description: returns a reference to a row of real data  from
         a Matrix object.  Author(s): Gregory Hance.

         ===========================================================
         void *getRow_Matrix(Matrix *matrix, unsigned row)
         ===========================================================

         <matrix> - pointer to a Matrix object
         <row> - row number (0 ... rows-1)
         Description: same as "getRealRow_Matrix".   Author(s):  Gre-
         gory Hance.

         ===========================================================
         void *getImagData_Matrix(matrix)
         ===========================================================

         <matrix> - pointer to a Matrix object

         Description: returns a reference to the imaginary data of  a
         Matrix object (mapped into rows).  Author(s): Gregory Hance.

         ===========================================================
         void *getImagRow_Matrix(matrix,row)
         ===========================================================

         <matrix> - pointer to a Matrix object.
         <row> - row number (0 ... rows-1)

         Description: returns a reference to a row of imaginary  data
         from a Matrix object.  Author(s): Gregory Hance.

         ===========================================================
         type getRealVal_Matrix(Matrix *matrix, type, unsigned x, unsigned y)
         ===========================================================

         <matrix> - pointer to a Matrix object
         <type> - valid "C" data type (i.e.one of byte, short, int, float or double)
         <x> - column offset
         <y> - row offset

         Description: returns a "real" element from a Matrix  object.
         Author(s): Gregory Hance.

         ===========================================================
         <type> getVal_Matrix(Matrix *matrix, type, unsigned x, unsigned y)
         ===========================================================

         <matrix> - pointer to a Matrix object
         <type> - valid "C"data type (i.e.one of byte, short, int, float or double)
         <x> - column offset
         <y> - row offset

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

         ===========================================================
         <type> getImagVal_Matrix(Matrix *matrix, type, unsigned x, unsigned y)
         ===========================================================

         <matrix> - pointer to a Matrix object
         <type> - valid "C" data type (i.e. one of byte, short, int, float or double
         <x> - column offset
         <y> - row offset

         Description: returns an "imaginary" element  from  a  Matrix
         object.  Author(s): Gregory Hance.

      BINARY ARITHMETIC OPERATORS
         ===========================================================
         Matrix *add_Matrix(const Matrix *A,const Matrix *B);
         ===========================================================

         <A> - pointer to first matrix
         <B> -pointer to second matrix

         Returns: pointer to  resultant  matrix  containing,  <A>+<B>
         Description:  adds  the contents of <A> to that of <B>. Uses
         the PWISE_MAT macro to do  all  25  combinations  of  matrix
         types.  Promotes  to  most precise type of <A> and <B>. Sup-
         ports complex matrices.  Diagnostics: returns  NULL  pointer
         w/ error message when matrix sizes do not agree.  Author(s):
         Gregory Hance.

         ===========================================================
         Matrix *sub_Matrix(const Matrix *A,const Matrix *B);
         ===========================================================

         <A> - pointer to first matrix
         <B> -pointer to second matrix

         Returns: pointer to  resultant  matrix  containing,  <A>-<B>
         Description: subtracts the contents of <B> from that of <A>.
         Uses the PWISE_MAT macro to do all 25 combinations of matrix
         types.  Promotes  to  most precise type of <A> and <B>. Sup-
         ports complex matrices Diagnostics: returns NULL pointer  w/
         error  message  when  matrix sizes do not agree.  Author(s):
         Gregory Hance.

      MATRIX MULTIPLICATION
         ===========================================================
         Matrix *multPWise_Matrix(const Matrix *A, const Matrix *B)
         ===========================================================

         <A> - pointer to first matrix
         <B> -pointer to second matrix

         Returns: pointer to  resultant  matrix  containing,  <A>*<B>
         Description:  multiplies  the  contents  of <B> from that of
         <A>.  Uses the PWISE_MULT macro to do all 25 combinations of
         matrix  types. Promotes to most precise type of <A> and <B>.
         Supports complex matrices Diagnostics: returns NULL  pointer
         w/ error message when matrix sizes do not agree.  Author(s):
         Gregory Hance.

         ===========================================================
         Matrix *mult_Matrix(const Matrix *A,const Matrix *B)
         ===========================================================

         <A> - pointer to first Matrix structure
         <B> - pointer to second Matrix structure

         Returns: pointer to Matrix structure containing the  result-
         ing  vector  multiplication,  <A>x<B>  Description:  peforms
         Matrix cross product of <A> and  <B>.   Promotes  result  to
         most precise type of <A> and <B>.  Uses MULT_MAT macro to do
         all 25 type combinations of matrices.  Diagnostics:  returns
         NULL  pointer  w/  error  message  when...   of  rows in <B>
         ...problems w/ Matrix structure.  Author(s): Gregory Hance.

         ===========================================================
         Matrix *sqrt_Matrix(Matrix *a)
         ===========================================================

         <a> - pointer to Matrix structure

         Returns:  pointer  to  Matrix  structure  containing  matrix
         square root.

         Description: Computes the square root of each element of the
         passed matrix, works on both REAL and COMPLEX matrices.

         Diagnostics: Frees up old matrix.

         Author: Arve Kjoelen

      GENERAL MATRIX UTILTIES
         ===========================================================
         void print_Matrix(const Matrix *A)
         ===========================================================

         <A> - pointer to venerable Matrix structure

         Description: Prints out the contents of a  matrix  structure
         in row - column format.  Diagnostics: Row 1: <col.1> <col.2>
         ...  <col.N>  ...  Row  N:  <col.1>  <col.3>  ...   <col.N>.
         Author(s): Gregory Hance.

         ============================================================
         CVIP_BOOLEAN conj_Matrix(Matrix *A)
         ============================================================

         <A> - pointer to Matrix structure

         Returns: 1 upons success, 0 upon failure (A is real or NULL)
         Description:  Calculates  the  complex conjugate of a Matrix
         structure IN PLACE.  Diagnostics: If it is desired  to  keep
         the  original,  call  duplicate_Matrix  first.  Author: Arve
         Kjoelen

         ===========================================================
         CVIP_BOOLEAN copy_Matrix(const Matrix *A, Matrix *B, CVIP_BOOLEAN force)
         ===========================================================

         <A> - pointer to source matrix
         <B> - pointer to destination matrix
         <force> - force operation even if matrix
         <B> is of a less precise type than <A>.

         Returns: 1 upon success, 0 upon  failure  Description:  Copy
         the  contents  of  <A>  into <B>. Uses the macro MAT_COPY to
         support all 25 combinations of matrix  types.   Diagnostics:
         returns 1 upon success and 0 upon failure; matrix sizes must
         agree and if <force> is CVIP_NO then  copy_Matrix  will  not
         perform   the   copy  if  <B>  is  less  precise  than  <A>.
         Author(s): Gregory Hance.

         ===========================================================
         CVIP_BOOLEAN fastCopy_Matrix(const Matrix *A, Matrix *B)
         ===========================================================

         <A> - pointer to source matrix
         <B> - pointer to destination matrix

         Returns: 1 upon success, 0 upon  failure  Description:  Copy
         the  contents  of  <A>  into  <B>.  Uses  a faster method of
         transfering data than in copy_Matrix  for  matrices  of  the
         same  type.   Diagnostics: returns 1 upon success and 0 upon
         failure; matrix sizes must agree  and  fastCopy_Matrix  will
         not  perform  the  copy  if  <B>  is  less precise than <A>.
         Author(s): Gregory Hance.

         Matrix *duplicate_Matrix(const Matrix *A, FORMAT df)

         <A> - pointer to source matrix
         <df> - data format of new matrix (REAL or IMAGINARY)

         Returns: pointer to new instance of matrix <A>  Description:
         Creates  an exact duplicate of the original matrix <A>, with
         the exception that the format can be altered. If the  format
         is specified to be less precise than that of A then the ima-
         ginary data is truncated.  Author(s): Gregory Hance.

         ===========================================================
         Matrix *scale_Matrix(const Matrix *a, double s)
         ===========================================================
         <a> - pointer to Matrix structure
         <s> - coefficient to multiply by each element
         of matrix <a>

         Returns:  pointer  to  Matrix  structure  containing  scaled
         matrix  (type float or double) Description: Scales each ele-
         ment of the matrix <a> by some  coefficient  <s>.  All  data
         types less precise than CVIP_FLOAT or promoted. Diagnostics:
         prints message of type of promotion being made.   Author(s):
         Gregory Hance.

         ===========================================================
         Matrix *crop_Matrix(const Matrix *a, unsigned int, unsigned int, unsigned int, unsigned int)
         ===========================================================

         <a> - pointer to source matrix
         <row_offset> - offset of row from 0
         <col_offset> - offset of column from 0
         <rows> - number of rows
         <cols> - number of columns

         Returns: Returns the new smaller matrix as a  pointer  to  a
         new  Matrix  structure  using  the  row  and col offsets and
         number of <rows> and <cols> in the result matrix.   Descrip-
         tion:  forms  a  sub-matrix  of given size and location from
         original Diagnostics: returns NULL ptr. w/ error  msg.  when
         submatrix  size  exceeds  that of parent matrix.  Author(s):
         Gregory Hance.

      MATRIX ALGEBRA, NUMERICAL ANALYSIS
         ===========================================================
         double det_Matrix(const Matrix *A)
         ===========================================================

         <A> - pointer to Matrix structure

         Returns: double value equal to the determinant of the matrix
         Description:  Finds  the  determinant  of  the input matrix.
         Allocates and frees a matrix for  the  determinant  calcula-
         tion.  Exits  and  prints  error  message  on invalid Matrix
         structure.  Diagnostics: returns 0  w/  corresponding  error
         message  when matrix is not square. Can not handle a complex
         matrix.  Author(s): Gregory Hance.

         ===========================================================
         Matrix *invert_Matrix(const Matrix *A)
         ===========================================================

         <A> - pointer to matrix to be inverted

         Returns: pointer to inverted matrix (promoted to  type  dou-
         ble)  Description:  finds  the  inverse  of matrix <A> using
         Gauss-Jordan elimination with full pivoting (not your  usual
         half  pivot  I guess... ) ALSO... this routine will find the
         inverse of  a  complex  matrix!  Diagnostics:  returns  NULL
         pointer and issues error message with singular matrices, bad
         Matrix structures.  Author(s): Gregory Hance.

         ===========================================================
         Matrix *transpose_Matrix(const Matrix *A)
         ===========================================================

         <A> - pointer to Matrix structure

         Returns: pointer to new matrix structure of same  type  con-
         taining  the  transposed  matrix Description: transposes the
         matrix <A> by copying to a new matrix. In  case  you  didn't
         now   that  means  interchange  the  rows  w/  the  columns.
         Author(s): Gregory Hance.

         ===========================================================
         Matrix *covariance_Matrix(float **bvecP, unsigned int no_of_bands,
         unsigned int vdim)
         ===========================================================

         <bvecP> - pointer to an array of band vectors of type float
         <no_of_bands> - number of data bands
         <vdim> - vector dimension (no. of pixels)

         Returns: pointer to covariance matrix  Description:  returns
         the covariance matrix of the band vector.  The dimensions of
         the matrix are equal to the number of data bands. (e.g.) for
         an RGB image with 3 data bands the covariance matrix is...
                         _           _
                        |             |
                        | Crr Cgr Cbr |
                        |             |
                        | Crg Cgg Cbg |
                        |             |
                        | Crb Cgb Cbb |
                        |             |
                        |_           _| 3x3
         Author(s): Gregory Hance.

         ===========================================================
         Matrix *eigenSystem_Matrix(Matrix *a)
         ===========================================================

         <a> - pointer to MATRIX structure

         Returns: pointer to  Matrix  structure  containing  rows  of
         eigenvectors.    Description:  This  function  computes  the
         eigenvalues and corresponding eigenvectors of  a  real  sym-
         metric  matrix. The eigen matrix is returned in terms of row
         vectors.  The routine also sorts the eigenvalues in descend-
         ing order, and rearranges the rows correspondingly.
                          En = {E1, E2, E3, ..., En}
                             _                   _
                            |                     |
                            | E11 E12 E13 . . E1n |
                            |                     |
                            | E21 E22 E23 . . E2n |
                            |                     |
                            | E31 E32 E33 . . E3n |
                            |        . . .        |
                            | En1 En2 En3 . . Enn |
                            |_                   _| nxn
         Author(s): Gregory Hance.

      COMPLEX MATRIX UTILITIES
         ===========================================================
         void CASSIGN(Matrix *matrix, type, int row, int col, int r, int i)
         ===========================================================

         <matrix> - pointer to Matrix structure
         <type> - valid C data type for matrix
         <row> - row of matrix
         <col> - column of matrix
         <r> - real component of data
         <i> - imaginary component of data

         Description: this macro will assign a complex  number  to  a
         matrix

         double CANG(double r, double i)

         Description: This macro will compute the phasor angle  of  a
         complex number

         double CMAG(double r, double i)

         Description: This macro will compute the magnitude of a com-
         plex number

         double MAGSQ(double r, double i)

         Description: macro to compute the  magnitude  squared  of  a
         complex number

         void CMUL(type, r3, i3, r1, i1, r2, i2)

         Description: macro to perform complex multiply and store the
         result in <r3> and <i3>

         void REC2POL(type, m, p, r,i)
         Description: macro to perform rectangular to  polar  coordi-
         nate conversion

         void POL2REC(type, r, i, m, p)

         Description: macro to perform polar to  rectangular  coordi-
         nate conversion

         ===========================================================
         CVIP_BOOLEAN makeComplex_Matrix(Matrix *real_Matrix, CVIP_BOOLEAN verbose)
         ===========================================================

         <real_Matrix> - pointer to real matrix
         <verbose> - speak to me

         Returns: 1 - upon success, 0  -  upon  failure  Description:
         reallocates  twice  the amount of memory already assigned to
         <real_Matrix> to make a complex.  The new complex  data  can
         be referenced through **iptr of the Matrix structure.  real-
         loc() is used to keep the new data address' contiguous  with
         that  of  the real data...  rather than allocate a new block
         of memory.  This has potential advantages when peforming the
         same  operation  on  both data sets (real & imag.)  Diagnos-
         tics: returns a NULL pointer  and  warning  message  when...
         Author(s): Gregory Hance.

         ===========================================================
         CVIP_BOOLEAN makeReal_Matrix(Matrix *complex_Matrix, CVIP_BOOLEAN verbose)
         ===========================================================

         complex_Matrix - pointer to matrix structure
         verbose - should i speak?

         Returns: 1 - upon success, 0  -  upon  failure  Description:
         reallocates   the   amount   of   memory   associated   with
         complex_Matrix to that of a real matrix Diagnostics: returns
         NULL  pointer  and error message when...  Author(s): Gregory
         Hance.

         ===========================================================
         Matrix *rect2pol_Matrix(Matrix *A, int dir)
         ===========================================================

         <A> - pointer to Matrix structure
         <dir> - type of transformation
         (1) - rectangular to polar
         (anything else) - polar to rectangular

         Returns: pointer to Matrix structure containing the  desired
         transformation  (type float or double) Description: Performs
         transformation from rectangular to polar coordinates or from
         polar to rectangular coordinates depending upon the value of
         <dir>.  Values less than type CVIP_FLOAT are promoted. If  a
         matrix  of  type double is passed the result will be double.
         Diagnostics: returns with NULL pointer and  message  when...
         -  matrix  is not complex also informs user when a promotion
         takes      place.       Author(s):      Gregory       Hance.
         ===========================================================
         Matrix  *and_Matrix(const  Matrix  *A,  const   Matrix   *B)
         ===========================================================

          <A> - pointer to Matrix structure
          <B> - pointer to Matrix structure

         Returns: pointer to resultant matrix containing, <A>&<B>
         Description: ands the contents of <A> to that of  <B>.  Uses
         the  PWISE_MAT  macro  to  do all 15 combinations of integer
         matrix types.  Promotes to most precise type of <A> and <B>.
         Supports complex matrices.
         Diagnostics: returns NULL  pointer  w/  error  message  when
         matrix sizes do not agree.
         Author(s):                  Gregory                   Hance.
         ===========================================================
         Matrix  *clone_Matrix(const  Matrix  *matP,  CVIP_TYPE   dt)
         ===========================================================

          <matP> - pointer to Matrix structure
          <dt> - valid C data type for matrix

         Returns: New matrix copy.
         Description: Uses function new_Matrix to provide quick  copy
         of imput matrix.
         Diagnostics: None.
         Author(s):                  Gregory                   Hance.
         ===========================================================
         Matrix  *duplicate_Matrix(const  Matrix   *A,   FORMAT   df)
         ===========================================================

          <A> - pointer to source matrix
          <df> - data format of new matrix (REAL or IMAGINARY)

         Returns: pointer to new instance of matrix <A>.
         Description: Creates an  exact  duplicate  of  the  original
         matrix  <A>,  with  the  exception  that  the  format can be
         altered. If the format is specified to be less precise  than
         that of A then the imaginary data is truncated.
         Diagnostics: None.
         Author(s):                  Gregory                   Hance.
         ===========================================================
         <type>  setRealVal_Matrix(Matrix  *matrix,  CVIP_TYPE  type,
         unsigned      x,      unsigned     y,     type     val     )
         ===========================================================

          <matrix> - pointer to a Matrix object
          <type> - valid "C" data type (i.e. one of byte, short, int,
         float or double)
          <x> - column offset
          <y> - row offset
          <val> - value to place into matrix

         Description: inserts <val> as a "real"  element  at  row  y,
         column x  of matrix.
         Author(s):                  Gregory                   Hance.
         ===========================================================
         <type>   setVal_Matrix(Matrix   *matrix,   CVIP_TYPE   type,
         unsigned      x,      unsigned     y,     type     val     )
         ===========================================================

          <matrix> - pointer to a Matrix object
          <type> - valid "C" data type (i.e. one of byte, short, int,
         float or double)
          <x> - column offset
          <y> - row offset
          <val> - value to place into matrix

         Description: Same as setREalVal_Matrix; inserts <val>  as  a
         "real" element at row y, column x  of matrix.
         Author(s):                  Gregory                   Hance.
         ===========================================================
         <type>  setImagVal_Matrix(Matrix  *matrix,  CVIP_TYPE  type,
         unsigned      x,      unsigned     y,     type     val     )
         ===========================================================

          <matrix> - pointer to a Matrix object
          <type> - valid "C" data type (i.e. one of byte, short, int,
         float or double)
          <x> - column offset
          <y> - row offset
          <val> - value to place into matrix

         Description: inserts <val> as an "imaginary" element at  row
         y, column x  of matrix.
         Author(s): Gregory Hance.

## BUGS

         none as of yet

## SEE ALSO

         CVIPmatrix.h, CVIPcomplex.h, m_file.h, m_CovEig.h

## AUTHOR

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