Index: trunk/psLib/src/math/psMatrix.h =================================================================== --- trunk/psLib/src/math/psMatrix.h (revision 597) +++ trunk/psLib/src/math/psMatrix.h (revision 760) @@ -1,74 +1,172 @@ -#if !defined(PS_MATRIX_H) -#define PS_MATRIX_H - -/** \file psMatrix.h - * \brief matrix math operators - * \ingroup MathGroup +/** @file psMatrix.h + * + * @brief Provides functions for linear algebra operations on psImages and psVectors. + * + * Functions are provided to: + * Transpose a psImage + * Compute LUD + * Solve LUD + * Matrix inversion + * Calculate determinant + * Matrix addition + * Matrix subtraction + * Matrix multiplication + * Calculate Eigenvectors + * Convert matrix to vector + * Convert vector to matrix + * + * These functions treat psImages as if they were matrices, therefore there is no psMatrix. These functions + * operate only with psF32 and psF64 data types. + * + * @author Ross Harman, MHPCC + * + * @version $Revision: 1.2 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-05-24 21:10:03 $ + * + * Copyright 2004 Maui High Performance Computing Center, University of Hawaii */ -/** Functions **************************************************************/ -/** \addtogroup MathGroup Math Utilities - * \{ +#ifndef PSMATRIX_H +#define PSMATRIX_H + +/******************************************************************************/ +/* DEFINE STATEMENTS */ +/******************************************************************************/ + +// None + +/******************************************************************************/ +/* TYPE DEFINITIONS */ +/******************************************************************************/ + +// None + +/*****************************************************************************/ +/* FUNCTION PROTOTYPES */ +/*****************************************************************************/ + +/** LU Decomposition of psImage matrix. + * + * Performs a LU decomposition on a psImage matrix and returns the LU matrix. If the user specifies NULL as the + * outImage argument, then the decomposition is done in-place and inImage will hold the inverted image. The input + * image must be square. This function operates only with psF32 and psF64 data types. + * + * @return psImage*: Pointer to LU decomposed psImage. */ +psImage *psMatrixLUD( + psImage *outImage, ///< Image to return, or NULL. + psVector *outPerm, ///< Output permutation vector used by psMatrixLUSolve. + psImage *inImage ///< Image to decompose. +); +/** LU Solution of psImage matrix. + * + * Solves for and returns the psVector, {x} in the equation [A]{x} = {b}. If the user specifies NULL as the + * outVector argument, then the solution for {x} is done in-place and inVector will hold the modified values. + * The input image must be square. This function operates only with psF32 and psF64 data types. + * + * @return psVector*: Pointer to psVector solution of matrix equation. + */ +psVector *psMatrixLUSolve( + psVector *outVector, ///< Vector to return, or NULL. + const psImage *luImage, ///< LU-decomposed matrix. + const psVector *inVector, ///< Vector right-hand-side of equation. + const psVector *inPerm ///< Permutation vector resulting from psMatrixLUD function. +); -/* Linear Algebra */ +/** Invert psImage matrix. + * + * Inverts a psImage matrix and returns the determinant as an option through the argument list. If the user + * specifies NULL as the outImage argument, then the inversion is done in-place and inImage will hold the + * inverted image. The input image must be square. This function operates only with psF32 and psF64 data types. + * + * @return psImage*: Pointer to inverted psImage. + */ +psImage *psMatrixInvert( + psImage *outImage, ///< Image to return, or NULL for in-place substitution. + const psImage *inImage, ///< Image to be inverted + float *restrict det ///< Determinant to return, or NULL +); -/** Invert matrix. Not using restrict, to allow inversion to be done in-place */ -psImage * -psMatrixInvert(psImage *out, ///< Matrix to return, or NULL - const psImage *myMatrix, ///< Matrix to be inverted - float *restrict determinant ///< Determinant to return, or NULL - ); +/** Calculate psImage matrix determinant. + * + * Calculates the determinant of a psImage matrix and returns the floating point determinant. The input + * image must be square. This function operates only with psF32 and psF64 data types. + * + * @return float: Determinant from psImage. + */ +float psMatrixDeterminant( + const psImage *restrict inMatrix ///< Image used to calculate determinant. +); -/** Matrix determinant */ -float -psMatrixDeterminant(const psImage *restrict myMatrix ///< Matrix to get determinant for - ); +/** Performs basic psImage matrix operations. + * + * Performs psImage matrix operations for: addition, subtraction, multiplication. For addition, each element + * of the input image is added to the corresponding element of the output matrix. Subtraction works in a + * similar manner. For multiplication, the function performs a classical matrix multiplication involving row + * and column operations. For matrix multiplication, the number of columns must match the number of rows for + * inImage1 and inImage2, respectively. Matrix division is not defined for this function. If the user + * specifies NULL as the outImage argument, then a new psImage will be created and returned. This function + * operates only with psF32 and psF64 data types. + * + * @return psImage*: Pointer to resulting psImage. + */ +psImage *psMatrixOp( + psImage *outImage, ///< Matrix to return, or NULL. + psImage *inImage1, ///< First input image. + const char op, ///< Operation to perform: "+", "-", "*". + psImage *inImage2 ///< Second input image. +); -/** Matrix operation: addition, subtraction, multiplication */ -psImage * -psMatrixOp(psImage *out, ///< Matrix to return, or NULL - const psImage *matrix1, ///< Matrix 1 - const char *op, ///< Operation to perform: "+", "-", "*" - const psImage *matrix2 ///< Matrix 2 - ); +/** Transpose matrix. + * + * Performs psImage matrix transpose by substituting existing rows for columns. The input image must be + * square. If the user specifies NULL as the outImage argument, then a new psImage will be created + * and returned. This function operates only with psF32 and psF64 data types. + * + * @return psImage*: Pointer to transposed psImage. + */ +psImage *psMatrixTranspose( + psImage *outImage, ///< Image to return, or NULL + const psImage *inImage ///< Image to transpose +); -/** Transpose Matrix */ -psImage * -psMatrixTranspose(psImage *out, ///< Matrix to return, or NULL - const psImage *myMatrix ///< Matrix to transpose - ); +/** Calculate matrix eigenvectors. + * + * Calculates the eigenvectors for a matrix. The input image must be square. If the user specifies NULL as + * the outImage argument, then a new psImage will be created and returned. This function operates only with + * psF32 and psF64 data types. + * + * @return psImage*: Pointer to matrix of Eigenvectors. + */ +psImage *psMatrixEigenvectors( + psImage *outImage, ///< Eigenvectors to return, or NULL. + psImage *inImage ///< Input image. +); -/** LU Decomposition of a matrix */ -psImage * -psMatrixLUD(psImage *out, ///< Matrix to return, or NULL - psImage *myMatrix ///< Matrix to decompose - ); +/** Convert matrix to vector. + * + * Converts a 1-d matrix into a vector. If the user specifies NULL as the outVector argument, then a new psImage will be created + * and returned. This function operates only with psF32 and psF64 data types. + * + * @return psVector*: Pointer to psVector. + */ +psVector *psMatrixToVector( + psVector *outVector, ///< Vector to return, or NULL. + psImage *inImage ///< Image to convert. +); -/** LU Solution. Solves for and returns x in the equation Ax = b */ -psVector * -psMatrixLUSolve(psVector *out, ///< Vector to return, or NULL - const psImage *luMatrix, ///< LU-decomposed matrix - const psVector *rhsVector ///< right-hand-side of the equation - ); - -/***********************************************************************************************************/ - -/* Conversions */ - -/** Convert matrix to vector. Intended for a 1-d matrix. */ -psVector * -psMatrixToVector(psVector *out, ///< Vector to return, or NULL - psImage *myMatrix ///< Matrix to convert - ); - -/** Convert vector to matrix. */ -psImage * -psVectorToMatrix(psImage *out, ///< Matrix to return, or NULL - psVector *myVector ///< Vector to convert - ); - -/* \} */ // End of MathGroup Functions +/** Convert vector to matrix. + * + * Converts a vector to a 1-d psImage matrix into a vector. If the user specifies NULL as the outImage + * argument, then a new psImage will be created and returned. This function operates only with psF32 and + * psF64 data types. + * + * @return psVector*: Pointer to psIamge. + */ +psImage *psVectorToMatrix( + psImage *outImage, ///< Matrix to return, or NULL. + psVector *inVector ///< Vector to convert. +); #endif