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.