Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Matrices


Functions

void cpl_matrix_dump (cpl_matrix *matrix)
 Print a matrix. More...

cpl_matrix * cpl_matrix_new (int rows, int columns)
 Create a zero matrix of given size. More...

cpl_matrix * cpl_matrix_new_from_data (double *data, int rows, int columns)
 Create a new matrix from existing data. More...

cpl_matrix * cpl_matrix_new_constant (double value, int rows, int columns)
 Create a new matrix initialised to a given value. More...

cpl_matrix * cpl_matrix_new_identity (int size)
 Create an identity matrix. More...

cpl_matrix * cpl_matrix_new_diagonal (double *diagonal, int size)
 Create a diagonal matrix. More...

void cpl_matrix_delete (cpl_matrix *matrix)
 Delete a matrix. More...

void cpl_matrix_delete_but_data (cpl_matrix *matrix)
 Delete a matrix, but not its data buffer. More...

int cpl_matrix_get_nrow (cpl_matrix *matrix)
 Get the number of rows of a matrix. More...

int cpl_matrix_get_ncol (cpl_matrix *matrix)
 Get the number of columns of a matrix. More...

double * cpl_matrix_get_data (cpl_matrix *matrix)
 Get the pointer to a matrix data buffer. More...

double cpl_matrix_get (cpl_matrix *matrix, int row, int column)
 Get the value of a matrix element. More...

cpl_error_code cpl_matrix_set (cpl_matrix *matrix, int row, int column, double value)
 Write a value to a matrix element. More...

cpl_matrix * cpl_matrix_duplicate (cpl_matrix *matrix)
 Make a copy of a matrix. More...

cpl_matrix * cpl_matrix_extract (cpl_matrix *matrix, int start_row, int start_column, int step_row, int step_column, int nrows, int ncolumns)
 Copy a submatrix from a matrix. More...

cpl_matrix * cpl_matrix_extract_row (cpl_matrix *matrix, int row)
 Copy a matrix row. More...

cpl_error_code cpl_matrix_copy_row (cpl_matrix *matrix, double *values, int row)
 Write an array of values to a matrix row. More...

cpl_matrix * cpl_matrix_extract_column (cpl_matrix *matrix, int column)
 Copy a matrix column. More...

cpl_error_code cpl_matrix_copy_column (cpl_matrix *matrix, double *values, int column)
 Write an array of values to a matrix column. More...

cpl_matrix * cpl_matrix_extract_diagonal (cpl_matrix *matrix, int diagonal)
 Copy a matrix diagonal. More...

cpl_error_code cpl_matrix_copy_diagonal (cpl_matrix *matrix, double *values, int diagonal)
 Write an array of values to a matrix diagonal. More...

cpl_error_code cpl_matrix_fill (cpl_matrix *matrix, double value)
 Write the same value to all matrix elements. More...

cpl_error_code cpl_matrix_fill_row (cpl_matrix *matrix, double value, int row)
 Write the same value to a matrix row. More...

cpl_error_code cpl_matrix_fill_column (cpl_matrix *matrix, double value, int column)
 Write the same value to a matrix column. More...

cpl_error_code cpl_matrix_fill_diagonal (cpl_matrix *matrix, double value, int diagonal)
 Write the same value to a matrix diagonal. More...

cpl_error_code cpl_matrix_copy_submatrix (cpl_matrix *matrix, cpl_matrix *submatrix, int row, int col)
 Write the values of a matrix into another matrix. More...

cpl_error_code cpl_matrix_fill_submatrix (cpl_matrix *matrix, double value, int row, int col, int nrow, int ncol)
 Write the same value into a submatrix of a matrix. More...

cpl_error_code cpl_matrix_shift (cpl_matrix *matrix, int rshift, int cshift)
 Shift matrix elements. More...

cpl_error_code cpl_matrix_chop (cpl_matrix *matrix, double tolerance)
 Rounding to zero very small numbers in matrix. More...

int cpl_matrix_is_zero (cpl_matrix *matrix, double tolerance)
 Check for zero matrix. More...

int cpl_matrix_is_diagonal (cpl_matrix *matrix, double tolerance)
 Check if a matrix is diagonal. More...

int cpl_matrix_is_identity (cpl_matrix *matrix, double tolerance)
 Check for identity matrix. More...

cpl_error_code cpl_matrix_swap_rows (cpl_matrix *matrix, int row1, int row2)
 Swap two matrix rows. More...

cpl_error_code cpl_matrix_swap_columns (cpl_matrix *matrix, int column1, int column2)
 Swap two matrix columns. More...

cpl_error_code cpl_matrix_swap_rowcolumn (cpl_matrix *matrix, int row)
 Swap a matrix column with a matrix row. More...

cpl_error_code cpl_matrix_flip_rows (cpl_matrix *matrix)
 Reverse order of rows in matrix. More...

cpl_error_code cpl_matrix_flip_columns (cpl_matrix *matrix)
 Reverse order of columns in matrix. More...

cpl_matrix * cpl_matrix_transpose (cpl_matrix *matrix)
 Create transposed matrix. More...

cpl_error_code cpl_matrix_sort_rows (cpl_matrix *matrix, int mode)
 Sort matrix by rows. More...

cpl_error_code cpl_matrix_sort_columns (cpl_matrix *matrix, int mode)
 Sort matrix by columns. More...

cpl_error_code cpl_matrix_delete_rows (cpl_matrix *matrix, int start, int count)
 Delete rows from a matrix. More...

cpl_error_code cpl_matrix_delete_columns (cpl_matrix *matrix, int start, int count)
 Delete columns from a matrix. More...

cpl_error_code cpl_matrix_reshape (cpl_matrix *matrix, int top, int bottom, int left, int right)
 Reshape a matrix. More...

cpl_error_code cpl_matrix_resize (cpl_matrix *matrix, int rows, int columns)
 Resize a matrix. More...

cpl_error_code cpl_matrix_merge (cpl_matrix *matrix1, cpl_matrix *matrix2, int mode)
 Merge two matrices. More...

cpl_error_code cpl_matrix_add (cpl_matrix *matrix1, cpl_matrix *matrix2)
 Add two matrices. More...

cpl_error_code cpl_matrix_subtract (cpl_matrix *matrix1, cpl_matrix *matrix2)
 Subtract a matrix from another. More...

cpl_error_code cpl_matrix_multiply (cpl_matrix *matrix1, cpl_matrix *matrix2)
 Multiply two matrices element by element. More...

cpl_error_code cpl_matrix_divide (cpl_matrix *matrix1, cpl_matrix *matrix2)
 Divide a matrix by another element by element. More...

cpl_error_code cpl_matrix_const_op (cpl_matrix *matrix, double value, int operation)
 Constant arithmetic on a matrix. More...

cpl_error_code cpl_matrix_add_constant (cpl_matrix *matrix, double value)
 Add a scalar to a matrix. More...

cpl_error_code cpl_matrix_multiply_constant (cpl_matrix *matrix, double value)
 Multiply a matrix by a scalar. More...

cpl_error_code cpl_matrix_logarithm (cpl_matrix *matrix, double base)
 Compute the logarithm of matrix elements. More...

cpl_error_code cpl_matrix_exponential (cpl_matrix *matrix, double base)
 Compute the exponential of matrix elements. More...

cpl_error_code cpl_matrix_power (cpl_matrix *matrix, double exponent)
 Compute a power of matrix elements. More...

cpl_matrix * cpl_matrix_product (cpl_matrix *matrix1, cpl_matrix *matrix2)
 Rows-by-columns product of two matrices. More...

cpl_error_code cpl_matrix_echelon (cpl_matrix *matrix)
 Reduce the matrix in row echelon form. More...

double cpl_matrix_determinant (cpl_matrix *matrix)
 Compute the determinant of a matrix. More...

cpl_matrix * cpl_matrix_solve_system (cpl_matrix *coeff, cpl_matrix *nonhomo)
 Solution of a linear system. More...

cpl_matrix * cpl_matrix_inverse (cpl_matrix *matrix)
 Find a matrix inverse. More...

cpl_matrix * cpl_matrix_leastsq (cpl_matrix *coeff, cpl_matrix *nonhomo)
 Solution of an equation using a pseudo-inverse. More...

double cpl_matrix_mean (cpl_matrix *matrix)
 Find the mean of matrix elements. More...

double cpl_matrix_stdev (cpl_matrix *matrix)
 Find the standard deviation of matrix elements. More...

double cpl_matrix_median (cpl_matrix *matrix)
 Find the median of matrix elements. More...

double cpl_matrix_min (cpl_matrix *matrix)
 Find the minimum value of matrix elements. More...

double cpl_matrix_max (cpl_matrix *matrix)
 Find the maximum value of matrix elements. More...

cpl_error_code cpl_matrix_minpos (cpl_matrix *matrix, int *row, int *column)
 Find position of minimum value of matrix elements. More...

cpl_error_code cpl_matrix_maxpos (cpl_matrix *matrix, int *row, int *column)
 Find position of the maximum value of matrix elements. More...


Detailed Description

This module provides functions to create, destroy and use a cpl_matrix. The elements of a cpl_matrix with M rows and N columns are counted from 0,0 to M-1,N-1. The matrix element 0,0 is the one at the upper left corner of a matrix.

Note:
All matrix functions assume valid pointers as arguments. Only in the particular case of a NULL pointer the functions will stop with an assertion failure, unless differently specified in the documentation.
Synopsis:
   #include <cpl_matrix.h>

Function Documentation

cpl_error_code cpl_matrix_add cpl_matrix *    matrix1,
cpl_matrix *    matrix2
 

Add two matrices.

Parameters:
matrix1  Pointer to first matrix.
matrix2  Pointer to second matrix.
Returns:
CPL_ERROR_NONE on success.
Add two matrices element by element. The two matrices must have identical sizes, or an assertion failure will be generated. The result is written to the first matrix.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_add_constant cpl_matrix *    matrix,
double    value
 

Add a scalar to a matrix.

Parameters:
matrix  Pointer to matrix.
value  Value to add.
Returns:
CPL_ERROR_NONE on success.
Add the same value to each matrix element.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_chop cpl_matrix *    matrix,
double    tolerance
 

Rounding to zero very small numbers in matrix.

Parameters:
matrix  Pointer to matrix to be chopped.
tolerance  Max tolerated rounding to zero.
Returns:
CPL_ERROR_NONE on success.
After specific manipulations of a matrix some of its elements may theoretically be expected to be zero (for instance, as a result of multiplying a matrix by its inverse). However, because of numerical noise, such elements may turn out not to be exactly zero. With this function any very small number in the matrix is turned to exactly zero. If the tolerance is zero or negative, a default threshold of DBL_EPSILON is used.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_const_op cpl_matrix *    matrix,
double    value,
int    operation
 

Constant arithmetic on a matrix.

Parameters:
matrix  Pointer to matrix.
value  Constant operand.
operation  Operation to perform.
Returns:
CPL_ERROR_NONE on success. If a not supported operation is specified, a CPL_ERROR_UNSUPPORTED_MODE is returned. If the specified constant is zero, and the specified operation is '/', a CPL_ERROR_DIVISION_BY_ZERO is returned. If any matrix element is not positive, and the specified operation is either 'l' or '^' a CPL_ERROR_ILLEGAL_INPUT is returned.
Possible operations are:

  • '+' Addition
  • '-' Subtraction
  • '*' Multiplication
  • '/' Division
  • 'l' Logarithm
  • '^' Power
  • 'e' Exponentiation
When logarithm or exponentiation are computed, the passed constant represents the base of the logarithm or of the exponentiation operation. An assertion failure would be generated by specifying a non positive base for the 'l' or the 'e' operation. All the available operations are in practice carried out by the functions

Refer to the documentation of those functions for more details on the corresponding operation. As an example, the two following calls are equivalent:

   cpl_matrix_const_op(matrix, 1.23, '^');
   cpl_matrix_power(matrix, 1.23);

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_copy_column cpl_matrix *    matrix,
double *    values,
int    column
 

Write an array of values to a matrix column.

Parameters:
matrix  Pointer to matrix to be accessed.
values  Array of values to write.
column  Sequence number of column to overwrite.
Returns:
CPL_ERROR_NONE on success.
If either matrix or values are NULL, an assertion failure will be generated. The input values are physically copied to the indicated matrix column. No check is performed on the buffer length, which is assumed to be equal to the number of rows in the matrix. The column number is counted from 0, and an assertion failure would be generated if the specified column were outside the matrix boundaries.

cpl_error_code cpl_matrix_copy_diagonal cpl_matrix *    matrix,
double *    values,
int    diagonal
 

Write an array of values to a matrix diagonal.

Parameters:
matrix  Pointer to the matrix to access
values  Array of values to write.
diagonal  Sequence number of diagonal to copy.
Returns:
CPL_ERROR_NONE on success.
If either matrix or values are NULL, an assertion failure will be generated. The input values are physically copied to the indicated matrix diagonal. No check is performed on the buffer length, which is assumed to be equal to the smaller dimension of the matrix. The diagonal number is counted from 0, corresponding to the diagonal starting at element (0,0). A square matrix has just one diagonal; if M != N, the number of diagonals in the matrix is |M - N| + 1. To specify a diagonal sequence number outside this range would generate an assertion failure.

cpl_error_code cpl_matrix_copy_row cpl_matrix *    matrix,
double *    values,
int    row
 

Write an array of values to a matrix row.

Parameters:
matrix  Pointer to matrix to be accessed.
values  Array of values to write.
row  Sequence number of row to overwrite.
Returns:
CPL_ERROR_NONE on success.
If either matrix or values are NULL, an assertion failure will be generated. The input values are physically copied to the indicated matrix row. No check is performed on the buffer length, which is assumed to be equal to the number of columns in the matrix. The row number is counted from 0, and an assertion failure would be generated if the specified row were outside the matrix boundaries.

cpl_error_code cpl_matrix_copy_submatrix cpl_matrix *    matrix,
cpl_matrix *    submatrix,
int    row,
int    col
 

Write the values of a matrix into another matrix.

Parameters:
matrix  Pointer to matrix to be modified.
submatrix  Pointer to matrix to get the values from.
row  Position of row 0 of submatrix in matrix.
col  Position of column 0 of submatrix in matrix.
Returns:
CPL_ERROR_NONE on success. If there is no overlap between the two matrices, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned.
The values of submatrix are written to matrix starting at the indicated row and column. There are no restrictions on the sizes of submatrix: just the parts of submatrix overlapping matrix are copied. There are no restrictions on row and col either, that can also be negative. If the two matrices do not overlap, nothing is done, and CPL_ERROR_ACCESS_OUT_OF_RANGE is returned.

void cpl_matrix_delete cpl_matrix *    matrix
 

Delete a matrix.

Parameters:
matrix  Pointer to a matrix to be deleted.
Returns:
Nothing.
This function frees all the memory associated to a matrix. If matrix is NULL, nothing is done.

void cpl_matrix_delete_but_data cpl_matrix *    matrix
 

Delete a matrix, but not its data buffer.

Parameters:
matrix  Pointer to a matrix to be deleted.
Returns:
Nothing.
This function deallocates all the memory associated to a matrix, with the exception of its data buffer. This type of destructor should be used on matrices created with the cpl_matrix_new_from_data() constructor, if the data buffer specified then was not allocated using the functions of the cpl_memory module. In such a case, the data buffer should be deallocated separately. See the documentation of the function cpl_matrix_new_from_data(). If matrix is NULL, nothing is done.

cpl_error_code cpl_matrix_delete_columns cpl_matrix *    matrix,
int    start,
int    count
 

Delete columns from a matrix.

Parameters:
matrix  Pointer to matrix to be modified.
start  First column to delete.
count  Number of columns to delete.
Returns:
CPL_ERROR_NONE on success. An attempt to delete all columns from the matrix causes a CPL_ERROR_ILLEGAL_OUTPUT to be returned.
A portion of the matrix data is physically removed. The pointer to matrix data may change, therefore pointers previously retrieved by calling cpl_matrix_get_data() should be discarded. The first column to delete must be within the matrix boundaries, and the number of columns to delete must be greater than zero, or an assertion failure would be generated. The specified segment can extend beyond the end of the matrix, but the attempt to remove all matrix columns is flagged as an error because zero length matrices are illegal. Columns are counted starting from 0.

cpl_error_code cpl_matrix_delete_rows cpl_matrix *    matrix,
int    start,
int    count
 

Delete rows from a matrix.

Parameters:
matrix  Pointer to matrix to be modified.
start  First row to delete.
count  Number of rows to delete.
Returns:
CPL_ERROR_NONE on success. An attempt to delete all rows from the matrix causes a CPL_ERROR_ILLEGAL_OUTPUT to be returned.
A portion of the matrix data is physically removed. The pointer to matrix data may change, therefore pointers previously retrieved by calling cpl_matrix_get_data() should be discarded. The first row to delete must be within the matrix boundaries, and the number of rows to delete must be greater than zero, or an assertion failure would be generated. The specified segment can extend beyond the end of the matrix, but the attempt to remove all matrix rows is flagged as an error because zero length matrices are illegal. Rows are counted starting from 0.

double cpl_matrix_determinant cpl_matrix *    matrix
 

Compute the determinant of a matrix.

Parameters:
matrix  Pointer to matrix.
Returns:
Matrix determinant.
The input matrix must be a square matrix, or an assertion failure would be generated. In case of a 1x1 matrix, the matrix single element value is returned.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_divide cpl_matrix *    matrix1,
cpl_matrix *    matrix2
 

Divide a matrix by another element by element.

Parameters:
matrix1  Pointer to first matrix.
matrix2  Pointer to second matrix.
Returns:
CPL_ERROR_NONE on success.
Divide each element of the first matrix by the corresponding element of the second one. The two matrices must have the same number of rows and columns, or an assertion failure will be generated. The result is written to the first matrix. No check is done against a division by zero.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

void cpl_matrix_dump cpl_matrix *    matrix
 

Print a matrix.

Parameters:
matrix  The matrix to print
Returns:
Nothing.
This function is intended just for debugging. It just prints the elements of a matrix, ordered in rows and columns. The function used for printing is the standard C printf().

cpl_matrix* cpl_matrix_duplicate cpl_matrix *    matrix
 

Make a copy of a matrix.

Parameters:
matrix  Matrix to be duplicated.
Returns:
Pointer to the new matrix.
A copy of the input matrix is created. If the input matrix is NULL, a NULL is returned and a CPL_ERROR_NULL_INPUT is set. To destroy the duplicated matrix the function cpl_matrix_delete() should be used.

cpl_error_code cpl_matrix_echelon cpl_matrix *    matrix
 

Reduce the matrix in row echelon form.

Parameters:
matrix  Pointer to matrix to manipulate.
Returns:
CPL_ERROR_NONE on success.
The input matrix is reduced in row echelon form using the Gauss elimination method. A matrix is in row echelon form when:

  1. Any row consisting of zeroes is below any row that contains at least one non-zero value.
  2. The first (from left to right) non-zero entry of any row is to the left of the first non-zero entry of any lower row.
  3. The first non-zero entry of every row is equal to 1.0.
Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_exponential cpl_matrix *    matrix,
double    base
 

Compute the exponential of matrix elements.

Parameters:
matrix  Target matrix.
base  Exponential base.
Returns:
CPL_ERROR_NONE on success.
Each matrix element is replaced by its exponential in the specified base. The base must be positive, or an assertion failure will be generated.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_matrix* cpl_matrix_extract cpl_matrix *    matrix,
int    start_row,
int    start_column,
int    step_row,
int    step_column,
int    nrows,
int    ncolumns
 

Copy a submatrix from a matrix.

Parameters:
matrix  Pointer to the input matrix.
start_row  Matrix row where to begin extraction.
start_column  Matrix column where to begin extraction.
step_row  Step between extracted rows.
step_column  Step between extracted columns.
nrows  Number of rows to extract.
ncolumns  Number of columns to extract.
Returns:
Pointer to the new matrix.
If the input matrix is NULL, a NULL is returned and a CPL_ERROR_NULL_INPUT is set. Otherwise the new matrix will include the nrows x ncolumns values read from the input matrix elements starting from position (start_row, start_column), in a grid of steps step_row and step_column. If the extraction parameters exceed the input matrix boundaries, just the overlap matrix is returned. Such matrix would have sizes smaller than nrows x ncolumns. Only in case the start element is outside the input matrix boundaries, or the specified steps are zero or negative, the function would stop with an assertion failure. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_extract_column cpl_matrix *    matrix,
int    column
 

Copy a matrix column.

Parameters:
matrix  Pointer to matrix containing the column.
column  Sequence number of column to copy.
Returns:
Pointer to new matrix.
If the input matrix pointer is NULL, a NULL pointer is returned and a CPL_ERROR_NULL_INPUT is set. Otherwise if a MxN matrix is given in input, the extracted column is a Mx1 matrix. The column number is counted from 0, and an assertion failure would be generated if the specified column were outside the matrix boundaries. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_extract_diagonal cpl_matrix *    matrix,
int    diagonal
 

Copy a matrix diagonal.

Parameters:
matrix  Pointer to the matrix containing the diagonal.
diagonal  Sequence number of the diagonal to copy.
Returns:
Pointer to the new matrix.
If the input matrix pointer is NULL, a NULL is returned and a CPL_ERROR_NULL_INPUT is set. Otherwise, if a MxN matrix is given in input, the extracted diagonal is a Mx1 matrix if N >= M, or a 1xN matrix if N < M. The diagonal number is counted from 0, corresponding to the matrix diagonal starting at element (0,0). A square matrix has just one diagonal; if M != N, the number of diagonals in the matrix is |M - N| + 1. To specify a diagonal sequence number outside this range would generate an assertion failure. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_extract_row cpl_matrix *    matrix,
int    row
 

Copy a matrix row.

Parameters:
matrix  Pointer to the matrix containing the row.
row  Sequence number of row to copy.
Returns:
Pointer to new matrix.
If the input matrix pointer is NULL, a NULL pointer is returned and a CPL_ERROR_NULL_INPUT is set. Otherwise if a MxN matrix is given in input, the extracted row is a 1xN matrix. The row number is counted from 0, and an assertion failure would be generated if the specified row were outside the matrix boundaries. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_error_code cpl_matrix_fill cpl_matrix *    matrix,
double    value
 

Write the same value to all matrix elements.

Parameters:
matrix  Pointer to the matrix to access
value  Value to write
Returns:
CPL_ERROR_NONE on success.
Write the same value to all matrix elements.

cpl_error_code cpl_matrix_fill_column cpl_matrix *    matrix,
double    value,
int    column
 

Write the same value to a matrix column.

Parameters:
matrix  Pointer to the matrix to access
value  Value to write
column  Sequence number of column to overwrite
Returns:
CPL_ERROR_NONE on success.
Write the same value to a matrix column. Columns are counted starting from 0. If the specified column number is outside the matrix boundaries, an assertion failure would be generated.

cpl_error_code cpl_matrix_fill_diagonal cpl_matrix *    matrix,
double    value,
int    diagonal
 

Write the same value to a matrix diagonal.

Parameters:
matrix  Matrix to access
value  Value to write
diagonal  Sequence number of diagonal to overwrite
Returns:
CPL_ERROR_NONE on success.
Write the same value to a matrix diagonal. The diagonal number is counted from 0, corresponding to the diagonal starting at element (0,0). A square matrix has just one diagonal; if M != N, the number of diagonals in the matrix is |M - N| + 1, counted along the longer side of the matrix. If the specified diagonal number is outside this range, an assertion failure would be generated.

cpl_error_code cpl_matrix_fill_row cpl_matrix *    matrix,
double    value,
int    row
 

Write the same value to a matrix row.

Parameters:
matrix  Matrix to access
value  Value to write
row  Sequence number of row to overwrite.
Returns:
CPL_ERROR_NONE on success.
Write the same value to a matrix row. Rows are counted starting from 0. If the specified row number is outside the matrix boundaries, an assertion failure would be generated.

cpl_error_code cpl_matrix_fill_submatrix cpl_matrix *    matrix,
double    value,
int    row,
int    col,
int    nrow,
int    ncol
 

Write the same value into a submatrix of a matrix.

Parameters:
matrix  Pointer to matrix to be modified.
value  Value to write.
row  Start row of matrix submatrix.
col  Start column of matrix submatrix.
nrow  Number of rows of matrix submatrix.
ncol  Number of columns of matrix submatrix.
Returns:
CPL_ERROR_NONE on success.
To avoid assertion failures, row and col should be within the matrix boundaries, and nrow and ncol should be positive. The specified value is written to matrix starting at the indicated row and column; nrow and ncol can exceed the input matrix boundaries, just the range overlapping the matrix is used in that case.

cpl_error_code cpl_matrix_flip_columns cpl_matrix *    matrix
 

Reverse order of columns in matrix.

Parameters:
matrix  Pointer to matrix to be reversed.
Returns:
CPL_ERROR_NONE on success.
The order of the columns in the matrix is reversed in place.

cpl_error_code cpl_matrix_flip_rows cpl_matrix *    matrix
 

Reverse order of rows in matrix.

Parameters:
matrix  Pointer to matrix to be reversed.
Returns:
CPL_ERROR_NONE on success.
The order of the rows in the matrix is reversed in place.

double cpl_matrix_get cpl_matrix *    matrix,
int    row,
int    column
 

Get the value of a matrix element.

Parameters:
matrix  Pointer to a matrix.
row  Matrix element row.
column  Matrix element column.
Returns:
Value of the specified matrix element.
The matrix rows and columns are counted from 0,0. Out of range indexes are illegal and would cause an assertion failure.

double* cpl_matrix_get_data cpl_matrix *    matrix
 

Get the pointer to a matrix data buffer.

Parameters:
matrix  Input matrix.
Returns:
Pointer to the matrix data buffer.
A cpl_matrix object includes an array of values of type double. This function returns a pointer to this internal array, whose first element corresponds to the cpl_matrix element 0,0. The internal array contains in sequence all the cpl_matrix rows. For instance, in the case of a 3x4 matrix, the array elements
            0 1 2 3 4 5 6 7 8 9 10 11
would correspond to the following matrix elements:
            0  1  2  3
            4  5  6  7
            8  9 10 11

Note:
Use at your own risk: direct manipulation of matrix data rules out any check performed by the matrix object interface, and may introduce inconsistencies between the information maintained internally, and the actual matrix data and structure.

int cpl_matrix_get_ncol cpl_matrix *    matrix
 

Get the number of columns of a matrix.

Parameters:
matrix  Pointer to the matrix to examine.
Returns:
Number of matrix columns, or zero in case of failure.
Determine the number of columns in a matrix. If matrix is NULL, zero is returned and a CPL_ERROR_NULL_INPUT is set.

int cpl_matrix_get_nrow cpl_matrix *    matrix
 

Get the number of rows of a matrix.

Parameters:
matrix  Pointer to the matrix to examine.
Returns:
Number of matrix rows, or zero in case of failure.
Determine the number of rows in a matrix. If matrix is NULL, zero is returned and a CPL_ERROR_NULL_INPUT is set.

cpl_matrix* cpl_matrix_inverse cpl_matrix *    matrix
 

Find a matrix inverse.

Parameters:
matrix  Pointer to matrix to invert.
Returns:
Inverse matrix. If the matrix cannot be inverted, a NULL is returned, and a CPL_ERROR_SINGULAR_MATRIX is set.
The input must be a square matrix, or an assertion failure would be generated. If the input matrix is singular, a NULL pointer is returned, and a CPL_ERROR_SINGULAR_MATRIX is set. To destroy the new matrix the function cpl_matrix_delete() should be used.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

int cpl_matrix_is_diagonal cpl_matrix *    matrix,
double    tolerance
 

Check if a matrix is diagonal.

Parameters:
matrix  Pointer to matrix to be checked.
tolerance  Max tolerated rounding to zero.
Returns:
1 in case of diagonal matrix, 0 otherwise.
A threshold may be specified to consider zero any number that is close enough to zero. If the specified tolerance is zero or negative, a default of DBL_EPSILON is used.

Note:
If the input matrix is not square, 0 is always returned. This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

int cpl_matrix_is_identity cpl_matrix *    matrix,
double    tolerance
 

Check for identity matrix.

Parameters:
matrix  Pointer to matrix to be checked.
tolerance  Max tolerated rounding to zero, or to one.
Returns:
1 in case of identity matrix, 0 otherwise.
A threshold may be specified to consider zero any number that is close enough to zero, and 1 any number that is close enough to 1. If the specified tolerance is zero or negative, a default of DBL_EPSILON is used.

Note:
If the input matrix is not square, 0 is always returned. This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

int cpl_matrix_is_zero cpl_matrix *    matrix,
double    tolerance
 

Check for zero matrix.

Parameters:
matrix  Pointer to matrix to be checked.
tolerance  Max tolerated rounding to zero.
Returns:
1 in case of zero matrix, 0 otherwise.
After specific manipulations of a matrix some of its elements may theoretically be expected to be zero. However, because of numerical noise, such elements may turn out not to be exactly zero. In this specific case, if any of the matrix element is not exactly zero, the matrix would not be classified as a null matrix. A threshold may be specified to consider zero any number that is close enough to zero. If the specified tolerance is zero or negative, a default of DBL_EPSILON is used.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_matrix* cpl_matrix_leastsq cpl_matrix *    coeff,
cpl_matrix *    nonhomo
 

Solution of an equation using a pseudo-inverse.

Parameters:
coeff  Matrix coefficient.
nonhomo  Nonhomogeneous term.
Returns:
Solution matrix.
Given the equation:

   coeff * X = nonhomo

where X is the unknown column matrix, the pseudo-inverse solution to this equation is defined as:

 solution = nonhomo * transp(coeff) * inverse(coeff * transp(coeff))

The solution matrix is solving the equation according to a least-squares criterion. To destroy this matrix the function cpl_matrix_delete() should be used.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_logarithm cpl_matrix *    matrix,
double    base
 

Compute the logarithm of matrix elements.

Parameters:
matrix  Pointer to matrix.
base  Logarithm base.
Returns:
CPL_ERROR_NONE on success. If any matrix element is not positive a CPL_ERROR_ILLEGAL_INPUT is returned.
Each matrix element is replaced by its logarithm in the specified base. The base must be positive, or an assertion failure will be generated. If any matrix element is not positive the matrix will not be modified and a CPL_ERROR_ILLEGAL_INPUT will be returned.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

double cpl_matrix_max cpl_matrix *    matrix
 

Find the maximum value of matrix elements.

Parameters:
matrix  Pointer to matrix.
Returns:
Maximum value.
The maximum value of all matrix elements is found.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_maxpos cpl_matrix *    matrix,
int *    row,
int *    column
 

Find position of the maximum value of matrix elements.

Parameters:
matrix  Input matrix.
row  Returned row position of maximum.
column  Returned column position of maximum.
Returns:
CPL_ERROR_NONE on success.
The position of the maximum value of all matrix elements is found. If more than one matrix element have a value corresponding to the maximum, the lowest element row number is returned in row. If more than one maximum matrix elements have the same row number, the lowest element column number is returned in column. An assertion failure is generated in case of NULL input pointers.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

double cpl_matrix_mean cpl_matrix *    matrix
 

Find the mean of matrix elements.

Parameters:
matrix  Pointer to matrix.
Returns:
Mean.
The mean value of all matrix elements is calculated.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

double cpl_matrix_median cpl_matrix *    matrix
 

Find the median of matrix elements.

Parameters:
matrix  Pointer to matrix.
Returns:
Median.
The median of all matrix elements is calculated. The median is computed using the function cpl_tools_median_double().

cpl_error_code cpl_matrix_merge cpl_matrix *    matrix1,
cpl_matrix *    matrix2,
int    mode
 

Merge two matrices.

Parameters:
matrix1  Pointer to first matrix.
matrix2  Pointer to second matrix.
mode  Matrices connected horizontally (0) or vertically (1).
Returns:
CPL_ERROR_NONE on success.
If mode is set to 0, the matrices must have the same number of rows, and are connected horizontally with the first matrix on the left. If mode is set to 1, the matrices must have the same number of columns, and are connected vertically with the first matrix on top. Failing this condition, an assertion failure would be generated. Also a mode different from 0 or 1 would cause an assertion failure. The first matrix is expanded to include the values from the second matrix, while the second matrix is left untouched.

Note:
The pointer to the first matrix data buffer may change, therefore pointers previously retrieved by calling cpl_matrix_get_data() should be discarded.

double cpl_matrix_min cpl_matrix *    matrix
 

Find the minimum value of matrix elements.

Parameters:
matrix  Pointer to matrix.
Returns:
Minimum value.
The minimum value of all matrix elements is found.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_minpos cpl_matrix *    matrix,
int *    row,
int *    column
 

Find position of minimum value of matrix elements.

Parameters:
matrix  Input matrix.
row  Returned row position of minimum.
column  Returned column position of minimum.
Returns:
CPL_ERROR_NONE on success.
The position of the minimum value of all matrix elements is found. If more than one matrix element have a value corresponding to the minimum, the lowest element row number is returned in row. If more than one minimum matrix elements have the same row number, the lowest element column number is returned in column. An assertion failure is generated in case of NULL input pointers.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_multiply cpl_matrix *    matrix1,
cpl_matrix *    matrix2
 

Multiply two matrices element by element.

Parameters:
matrix1  Pointer to first matrix.
matrix2  Pointer to second matrix.
Returns:
CPL_ERROR_NONE on success.
Multiply the two matrices element by element. The two matrices must have the same number of rows and columns, or an assertion failure would be generated. The result is written to the first matrix.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity). To obtain the rows-by-columns product between two matrices, cpl_matrix_product() should be used instead.

cpl_error_code cpl_matrix_multiply_constant cpl_matrix *    matrix,
double    value
 

Multiply a matrix by a scalar.

Parameters:
matrix  Pointer to matrix.
value  Multiplication factor.
Returns:
CPL_ERROR_NONE on success.
Multiply each matrix element by the same factor.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_matrix* cpl_matrix_new int    rows,
int    columns
 

Create a zero matrix of given size.

Parameters:
rows  Number of matrix rows.
columns  Number of matrix columns.
Returns:
Pointer to new matrix.
This function allocates and initialises to zero a matrix of given size. Zero or negative sizes are illegal, and would cause an assertion failure if they are used. To destroy this matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_new_constant double    value,
int    rows,
int    columns
 

Create a new matrix initialised to a given value.

Parameters:
value  Value to write to all matrix elements.
rows  Number of matrix rows.
columns  Number of matrix columns.
Returns:
Pointer to new matrix;
This function allocates and initialises to a given value a matrix of given size. Zero or negative sizes are illegal, and would cause an assertion failure if they are used. To destroy this matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_new_diagonal double *    diagonal,
int    size
 

Create a diagonal matrix.

Parameters:
diagonal  Values to write to the matrix diagonal.
size  Number of matrix rows and columns.
Returns:
Pointer to new matrix.
This function allocates a square size x size diagonal matrix. A zero or negative size is illegal, and would cause an assertion failure if it is used. An assertion failure will be caused also by a NULL input pointer. Note that the size of the data buffer is not checked in any way, and it is expected to match the specified matrix size. The data buffer is physically copied, so it could be deallocated also while the matrix is still in use. To destroy this matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_new_from_data double *    data,
int    rows,
int    columns
 

Create a new matrix from existing data.

Parameters:
data  Existing data buffer.
rows  Number of matrix rows.
columns  Number of matrix columns.
Returns:
Pointer to new matrix.
This function creates a new matrix that will encapsulate the given data. Zero or negative sizes are illegal, and if used they would generate an assertion failure. An assertion failure will be caused also by a NULL input pointer. Note that the size of the input data array is not checked in any way, and it is expected to match the specified matrix sizes. The input arrays is supposed to contain in sequence all the new cpl_matrix rows. For instance, in the case of a 3x4 matrix, the input array should contain 12 elements
            0 1 2 3 4 5 6 7 8 9 10 11
that would correspond to the matrix elements
            0  1  2  3
            4  5  6  7
            8  9 10 11 
The data buffer is not copied, so it should not be deallocated while the matrix is still in use: the function cpl_matrix_delete() would take care of deallocating it. To avoid problems with the memory managment, the specified data buffer should be allocated using the functions of the cpl_memory module, and also statically allocated data should be strictly avoided. If this were not the case, this matrix should not be destroyed using cpl_matrix_delete(), but cpl_matrix_delete_but_data() should be used instead; moreover, functions implying memory handling (as cpl_matrix_resize(), or cpl_matrix_delete_row() ) should not be used.

cpl_matrix* cpl_matrix_new_identity int    size
 

Create an identity matrix.

Parameters:
size  Number of matrix rows and columns.
Returns:
Pointer to new matrix.
This function allocates a square size x size identity matrix. A zero or negative size is illegal, and would cause an assertion failure if it is used. To destroy this matrix the function cpl_matrix_delete() should be used.

cpl_error_code cpl_matrix_power cpl_matrix *    matrix,
double    exponent
 

Compute a power of matrix elements.

Parameters:
matrix  Pointer to matrix.
exponent  Constant exponent.
Returns:
CPL_ERROR_NONE on success. If any matrix element is incompatible with the specified exponent, a CPL_ERROR_ILLEGAL_INPUT is returned.
Each matrix element is replaced by its power to the specified exponent. If the specified exponent is not negative, all matrix elements must be not negative; if the specified exponent is negative, all matrix elements must be positive; otherwise, a CPL_ERROR_ILLEGAL_INPUT is returned and the matrix will be left unchanged. If the exponent is zero, then any (non negative) matrix element would be assigned the value 1.0.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_matrix* cpl_matrix_product cpl_matrix *    matrix1,
cpl_matrix *    matrix2
 

Rows-by-columns product of two matrices.

Parameters:
matrix1  Pointer to left side matrix.
matrix2  Pointer to right side matrix.
Returns:
Pointer to product matrix.
The number of columns of the first matrix must be equal to the number of rows of the second matrix, or an assertion failure would be generated. To destroy the new matrix the function cpl_matrix_delete() should be used.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_reshape cpl_matrix *    matrix,
int    top,
int    bottom,
int    left,
int    right
 

Reshape a matrix.

Parameters:
matrix  Pointer to matrix to be modified.
top  Extra rows on top.
bottom  Extra rows on bottom.
left  Extra columns on left.
right  Extra columns on right.
Returns:
CPL_ERROR_NONE on success. An attempt to reshape the matrix to 0x0 (or less) causes a CPL_ERROR_ILLEGAL_INPUT to be returned.
The input matrix is reframed according to specifications. Extra rows and column on the sides might also be negative, as long as they are compatible with the matrix sizes: the input matrix would be reduced in size accordingly, but an attempt to remove all matrix columns and/or rows is flagged as an error because zero length matrices are illegal. The old matrix elements contained in the new shape are left unchanged, and new matrix elements added by the reshaping are initialised to zero. No reshaping (i.e., all the extra rows set to zero) would not be flagged as an error.

Note:
The pointer to the matrix data buffer may change, therefore pointers previously retrieved by calling cpl_matrix_get_data() should be discarded.

cpl_error_code cpl_matrix_resize cpl_matrix *    matrix,
int    rows,
int    columns
 

Resize a matrix.

Parameters:
matrix  Pointer to matrix to be resized.
rows  New number of rows.
columns  New number of columns.
Returns:
CPL_ERROR_NONE on success. An attempt to resize the matrix to 0x0 (or less) causes a CPL_ERROR_ILLEGAL_INPUT to be returned.
The input matrix is resized according to specifications. The old matrix elements contained in the resized matrix are left unchanged, and new matrix elements added by an increase of the matrix number of rows and/or columns are initialised to zero. Zero length matrices are illegal, and specifying a non-positive number of rows or columns would generate an assertion failure.

Note:
The pointer to the matrix data buffer may change, therefore pointers previously retrieved by calling cpl_matrix_get_data() should be discarded.

cpl_error_code cpl_matrix_set cpl_matrix *    matrix,
int    row,
int    column,
double    value
 

Write a value to a matrix element.

Parameters:
matrix  Input matrix.
row  Matrix element row.
column  Matrix element column.
value  Value to write.
Returns:
CPL_ERROR_NONE on success.
The matrix rows and columns are counted from 0,0. Out of range indexes are illegal and would cause an assertion failure.

cpl_error_code cpl_matrix_shift cpl_matrix *    matrix,
int    rshift,
int    cshift
 

Shift matrix elements.

Parameters:
matrix  Pointer to matrix to be modified.
rshift  Shift in the vertical direction.
cshift  Shift in the horizontal direction.
Returns:
CPL_ERROR_NONE on success.
The performed shift operation is cyclical (toroidal), i.e., matrix elements shifted out of one side of the matrix get shifted in from its opposite side. There are no restrictions on the values of the shift. Positive shifts are always in the direction of increasing row/column numbers.

Note:
The pointer to the matrix data buffer may change, therefore pointers previously retrieved by calling cpl_matrix_get_data() should be discarded.

cpl_matrix* cpl_matrix_solve_system cpl_matrix *    coeff,
cpl_matrix *    nonhomo
 

Solution of a linear system.

Parameters:
coeff  Matrix coefficient.
nonhomo  Nonhomogeneous term.
Returns:
Solution matrix. If coeff is a singular matrix, a NULL is returned and a CPL_ERROR_SINGULAR_MATRIX is set.
Compute the solution of a system of N equations with N unknowns:

coeff * X = nonhomo

coeff must be an NxN matrix, and nonhomo a Nx1 matrix (a one-column matrix). If such conditions are not fulfilled, an assertion failure is generated. To destroy the solution matrix the function cpl_matrix_delete() should be used.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_sort_columns cpl_matrix *    matrix,
int    mode
 

Sort matrix by columns.

Parameters:
matrix  Pointer to matrix to be sorted.
mode  Sorting mode: 1, by value, 0, by absolute value.
Returns:
CPL_ERROR_NONE on success.
The matrix elements of the top row are used as reference for the column sorting, if there are identical the values of the second row are considered, etc. Columns with the largest values go on the right. If mode is equal to zero, the columns are sorted according to their absolute values (zeroes at left).

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_sort_rows cpl_matrix *    matrix,
int    mode
 

Sort matrix by rows.

Parameters:
matrix  Pointer to matrix to be sorted.
mode  Sorting mode: 1, by value, 0, by absolute value.
Returns:
CPL_ERROR_NONE on success.
The matrix elements of the leftmost column are used as reference for the row sorting, if there are identical the values of the second column are considered, etc. Rows with the greater values go on top. If mode is equal to zero, the rows are sorted according to their absolute values (zeroes at bottom).

double cpl_matrix_stdev cpl_matrix *    matrix
 

Find the standard deviation of matrix elements.

Parameters:
matrix  Pointer to matrix.
Returns:
Standard deviation.
The standard deviation of all matrix elements is calculated. If a matrix is 1x1, 0.0 is returned.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_subtract cpl_matrix *    matrix1,
cpl_matrix *    matrix2
 

Subtract a matrix from another.

Parameters:
matrix1  Pointer to first matrix.
matrix2  Pointer to second matrix.
Returns:
CPL_ERROR_NONE on success.
Subtract the second matrix from the first one element by element. The two matrices must have identical sizes, or an assertion failure would be generated. The result is written to the first matrix.

Note:
This function works properly only in the case all the elements of the input matrix do not contain garbage (such as NaN or infinity).

cpl_error_code cpl_matrix_swap_columns cpl_matrix *    matrix,
int    column1,
int    column2
 

Swap two matrix columns.

Parameters:
matrix  Pointer to matrix to be modified.
column1  One matrix column.
column2  Another matrix column.
Returns:
CPL_ERROR_NONE on success.
The values of two given matrix columns are exchanged. Columns are counted starting from 0. Any column number outside the matrix boundaries would generate an assertion failure. If the same column number is given twice, nothing is done and a CPL_ERROR_NONE is still returned.

cpl_error_code cpl_matrix_swap_rowcolumn cpl_matrix *    matrix,
int    row
 

Swap a matrix column with a matrix row.

Parameters:
matrix  Pointer to matrix to be modified.
row  Matrix row.
Returns:
CPL_ERROR_NONE on success.
The input matrix must be square, or an assertion failure would be generated. The values of the indicated row are exchanged with the column having the same sequence number. Rows and columns are counted starting from 0. Any index outside the matrix boundaries would generate an assertion failure.

cpl_error_code cpl_matrix_swap_rows cpl_matrix *    matrix,
int    row1,
int    row2
 

Swap two matrix rows.

Parameters:
matrix  Pointer to matrix to be modified.
row1  One matrix row.
row2  Another matrix row.
Returns:
CPL_ERROR_NONE on success.
The values of two given matrix rows are exchanged. Rows are counted starting from 0. Any row number outside the matrix boundaries would generate an assertion failure. If the same row number is given twice, nothing is done and a CPL_ERROR_NONE is still returned.

cpl_matrix* cpl_matrix_transpose cpl_matrix *    matrix
 

Create transposed matrix.

Parameters:
matrix  Pointer to matrix to be transposed.
Returns:
Pointer to transposed matrix.
The transposed of the input matrix is created. To destroy the new matrix the function cpl_matrix_delete() should be used.


Generated on Mon May 24 14:58:05 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002