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.