Main Page | Modules | Alphabetical List | Class List | Directories | Class Members

Matrices


Functions

void cpl_matrix_dump (const cpl_matrix *matrix, FILE *stream)
 Print a matrix.
cpl_matrix * cpl_matrix_new (int rows, int columns)
 Create a zero matrix of given size.
cpl_matrix * cpl_matrix_wrap (int rows, int columns, double *data)
 Create a new matrix from existing data.
void cpl_matrix_delete (cpl_matrix *matrix)
 Delete a matrix.
void * cpl_matrix_unwrap (cpl_matrix *matrix)
 Delete a matrix, but not its data buffer.
int cpl_matrix_get_nrow (const cpl_matrix *matrix)
 Get the number of rows of a matrix.
int cpl_matrix_get_ncol (const cpl_matrix *matrix)
 Get the number of columns of a matrix.
double * cpl_matrix_get_data (const cpl_matrix *matrix)
 Get the pointer to a matrix data buffer, or NULL in case of error.
double cpl_matrix_get (const cpl_matrix *matrix, int row, int column)
 Get the value of a matrix element.
cpl_error_code cpl_matrix_set (cpl_matrix *matrix, int row, int column, double value)
 Write a value to a matrix element.
cpl_matrix * cpl_matrix_duplicate (const cpl_matrix *matrix)
 Make a copy of a matrix.
cpl_matrix * cpl_matrix_extract (const cpl_matrix *matrix, int start_row, int start_column, int step_row, int step_column, int nrows, int ncolumns)
 Extract a submatrix from a matrix.
cpl_matrix * cpl_matrix_extract_row (const cpl_matrix *matrix, int row)
 Extract a matrix row.
cpl_matrix * cpl_matrix_extract_column (const cpl_matrix *matrix, int column)
 Copy a matrix column.
cpl_matrix * cpl_matrix_extract_diagonal (const cpl_matrix *matrix, int diagonal)
 Extract a matrix diagonal.
cpl_error_code cpl_matrix_fill (cpl_matrix *matrix, double value)
 Write the same value to all matrix elements.
cpl_error_code cpl_matrix_fill_row (cpl_matrix *matrix, double value, int row)
 Write the same value to a matrix row.
cpl_error_code cpl_matrix_fill_column (cpl_matrix *matrix, double value, int column)
 Write the same value to a matrix column.
cpl_error_code cpl_matrix_fill_diagonal (cpl_matrix *matrix, double value, int diagonal)
 Write the same value to a matrix diagonal.
cpl_error_code cpl_matrix_copy (cpl_matrix *matrix, const cpl_matrix *submatrix, int row, int col)
 Write the values of a matrix into another matrix.
cpl_error_code cpl_matrix_fill_window (cpl_matrix *matrix, double value, int row, int col, int nrow, int ncol)
 Write the same value into a submatrix of a matrix.
cpl_error_code cpl_matrix_shift (cpl_matrix *matrix, int rshift, int cshift)
 Shift matrix elements.
cpl_error_code cpl_matrix_threshold_small (cpl_matrix *matrix, double tolerance)
 Rounding to zero very small numbers in matrix.
int cpl_matrix_is_zero (const cpl_matrix *matrix, double tolerance)
 Check for zero matrix.
int cpl_matrix_is_diagonal (const cpl_matrix *matrix, double tolerance)
 Check if a matrix is diagonal.
int cpl_matrix_is_identity (const cpl_matrix *matrix, double tolerance)
 Check for identity matrix.
cpl_error_code cpl_matrix_swap_rows (cpl_matrix *matrix, int row1, int row2)
 Swap two matrix rows.
cpl_error_code cpl_matrix_swap_columns (cpl_matrix *matrix, int column1, int column2)
 Swap two matrix columns.
cpl_error_code cpl_matrix_swap_rowcolumn (cpl_matrix *matrix, int row)
 Swap a matrix column with a matrix row.
cpl_error_code cpl_matrix_flip_rows (cpl_matrix *matrix)
 Reverse order of rows in matrix.
cpl_error_code cpl_matrix_flip_columns (cpl_matrix *matrix)
 Reverse order of columns in matrix.
cpl_matrix * cpl_matrix_transpose_create (const cpl_matrix *matrix)
 Create transposed matrix.
cpl_error_code cpl_matrix_sort_rows (cpl_matrix *matrix, int mode)
 Sort matrix by rows.
cpl_error_code cpl_matrix_sort_columns (cpl_matrix *matrix, int mode)
 Sort matrix by columns.
cpl_error_code cpl_matrix_erase_rows (cpl_matrix *matrix, int start, int count)
 Delete rows from a matrix.
cpl_error_code cpl_matrix_erase_columns (cpl_matrix *matrix, int start, int count)
 Delete columns from a matrix.
cpl_error_code cpl_matrix_resize (cpl_matrix *matrix, int top, int bottom, int left, int right)
 Reframe a matrix.
cpl_error_code cpl_matrix_set_size (cpl_matrix *matrix, int rows, int columns)
 Resize a matrix.
cpl_error_code cpl_matrix_append (cpl_matrix *matrix1, const cpl_matrix *matrix2, int mode)
 Append a matrix to another.
cpl_error_code cpl_matrix_add (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Add two matrices.
cpl_error_code cpl_matrix_subtract (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Subtract a matrix from another.
cpl_error_code cpl_matrix_multiply (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Multiply two matrices element by element.
cpl_error_code cpl_matrix_divide (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Divide a matrix by another element by element.
cpl_error_code cpl_matrix_add_scalar (cpl_matrix *matrix, double value)
 Add a scalar to a matrix.
cpl_error_code cpl_matrix_subtract_scalar (cpl_matrix *matrix, double value)
 Subtract a scalar to a matrix.
cpl_error_code cpl_matrix_multiply_scalar (cpl_matrix *matrix, double value)
 Multiply a matrix by a scalar.
cpl_error_code cpl_matrix_divide_scalar (cpl_matrix *matrix, double value)
 Divide a matrix by a scalar.
cpl_error_code cpl_matrix_logarithm (cpl_matrix *matrix, double base)
 Compute the logarithm of matrix elements.
cpl_error_code cpl_matrix_exponential (cpl_matrix *matrix, double base)
 Compute the exponential of matrix elements.
cpl_error_code cpl_matrix_power (cpl_matrix *matrix, double exponent)
 Compute a power of matrix elements.
cpl_matrix * cpl_matrix_product_create (const cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Rows-by-columns product of two matrices.
cpl_error_code cpl_matrix_do_echelon (cpl_matrix *matrix)
 Reduce the matrix in row echelon form.
double cpl_matrix_get_determinant (const cpl_matrix *matrix)
 Compute the determinant of a matrix.
cpl_matrix * cpl_matrix_solve (const cpl_matrix *coeff, const cpl_matrix *rhs)
 Solution of a linear system.
cpl_matrix * cpl_matrix_invert_create (const cpl_matrix *matrix)
 Find a matrix inverse.
cpl_matrix * cpl_matrix_solve_normal (const cpl_matrix *coeff, const cpl_matrix *rhs)
 Solution of a normal equation using a pseudo-inverse.
double cpl_matrix_get_mean (const cpl_matrix *matrix)
 Find the mean of all matrix elements.
double cpl_matrix_get_stdev (const cpl_matrix *matrix)
 Find the standard deviation of matrix elements.
double cpl_matrix_get_median (const cpl_matrix *matrix)
 Find the median of matrix elements.
double cpl_matrix_get_min (const cpl_matrix *matrix)
 Find the minimum value of matrix elements.
double cpl_matrix_get_max (const cpl_matrix *matrix)
 Find the maximum value of matrix elements.
cpl_error_code cpl_matrix_get_minpos (const cpl_matrix *matrix, int *row, int *column)
 Find position of minimum value of matrix elements.
cpl_error_code cpl_matrix_get_maxpos (const cpl_matrix *matrix, int *row, int *column)
 Find position of the maximum value of matrix elements.

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. The CPL matrix functions work properly only in the case the matrices elements do not contain garbage (such as NaN or infinity).

Synopsis:
   #include <cpl_matrix.h>

Function Documentation

cpl_error_code cpl_matrix_add cpl_matrix *  matrix1,
const cpl_matrix *  matrix2
 

Add two matrices.

Parameters:
matrix1 Pointer to first matrix.
matrix2 Pointer to second matrix.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any input matrix is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The specified matrices do not have the same size.

Add two matrices element by element. The two matrices must have identical sizes. The result is written to the first matrix.

cpl_error_code cpl_matrix_add_scalar 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

Add the same value to each matrix element.

cpl_error_code cpl_matrix_append cpl_matrix *  matrix1,
const cpl_matrix *  matrix2,
int  mode
 

Append a matrix to another.

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.
Errors:
CPL_ERROR_NULL_INPUT Any input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT mode is neither 0 nor 1.
CPL_ERROR_INCOMPATIBLE_INPUT Matrices cannot be joined as indicated by mode.

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. 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.

cpl_error_code cpl_matrix_copy cpl_matrix *  matrix,
const 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix or submatrix are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE No overlap exists between the two matrices.

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, but an error condition is set.

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.

cpl_error_code cpl_matrix_divide cpl_matrix *  matrix1,
const 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.
Errors:
CPL_ERROR_NULL_INPUT Any input matrix is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The specified matrices do not have the same size.

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. The result is written to the first matrix. No check is made against a division by zero.

cpl_error_code cpl_matrix_divide_scalar cpl_matrix *  matrix,
double  value
 

Divide a matrix by a scalar.

Parameters:
matrix Pointer to matrix.
value Divisor.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_DIVISION_BY_ZERO The input value is 0.0.

Divide each matrix element by the same value.

cpl_error_code cpl_matrix_do_echelon cpl_matrix *  matrix  ) 
 

Reduce the matrix in row echelon form.

Parameters:
matrix Pointer to matrix to manipulate.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.

void cpl_matrix_dump const cpl_matrix *  matrix,
FILE *  stream
 

Print a matrix.

Parameters:
matrix The matrix to print
stream The output stream
Returns:
Nothing.
This function is intended just for debugging. It just prints the elements of a matrix, ordered in rows and columns, to the specified stream or FILE pointer. If the specified stream is NULL, it is set to stdout. The function used for printing is the standard C fprintf().

cpl_matrix* cpl_matrix_duplicate const cpl_matrix *  matrix  ) 
 

Make a copy of a matrix.

Parameters:
matrix Matrix to be duplicated.
Returns:
Pointer to the new matrix, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

A copy of the input matrix is created. To destroy the duplicated matrix the function cpl_matrix_delete() should be used.

cpl_error_code cpl_matrix_erase_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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified start is outside the matrix boundaries.
CPL_ERROR_ILLEGAL_INPUT count is not positive.
CPL_ERROR_ILLEGAL_OUTPUT Attempt to delete all the columns of matrix.

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 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_erase_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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified start is outside the matrix boundaries.
CPL_ERROR_ILLEGAL_INPUT count is not positive.
CPL_ERROR_ILLEGAL_OUTPUT Attempt to delete all the rows of matrix.

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 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.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT The input base is not positive.

Each matrix element is replaced by its exponential in the specified base. The base must be positive.

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

Extract 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, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The start position is outside the matrix boundaries.
CPL_ERROR_ILLEGAL_INPUT While nrows and ncolumns are greater than 1, the specified steps are not positive.

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 is returned, and this matrix would have sizes smaller than nrows x ncolumns. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_extract_column const 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, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The column is outside the matrix boundaries.

If a MxN matrix is given in input, the extracted row is a new Mx1 matrix. The column number is counted from 0. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_extract_diagonal const cpl_matrix *  matrix,
int  diagonal
 

Extract 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, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The diagonal is outside the matrix boundaries (see description below).

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 set an error condition, and a NULL pointer would be returned. To destroy the new matrix the function cpl_matrix_delete() should be used.

cpl_matrix* cpl_matrix_extract_row const cpl_matrix *  matrix,
int  row
 

Extract a matrix row.

Parameters:
matrix Pointer to the matrix containing the row.
row Sequence number of row to copy.
Returns:
Pointer to new matrix, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The row is outside the matrix boundaries.

If a MxN matrix is given in input, the extracted row is a new 1xN matrix. The row number is counted from 0. 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified column is outside the matrix boundaries.

Write the same value to a matrix column. Columns are counted starting from 0.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified diagonal is outside the matrix boundaries (see description below).

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.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified row is outside the matrix boundaries.

Write the same value to a matrix row. Rows are counted starting from 0.

cpl_error_code cpl_matrix_fill_window 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified start position is outside the matrix boundaries.
CPL_ERROR_ILLEGAL_INPUT nrow or ncol are not 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

The order of the rows in the matrix is reversed in place.

double cpl_matrix_get const 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, or 0.0 in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The accessed element is beyond the matrix boundaries.

Get the value of a matrix element. The matrix rows and columns are counted from 0,0.

double* cpl_matrix_get_data const cpl_matrix *  matrix  ) 
 

Get the pointer to a matrix data buffer, or NULL in case of error.

Parameters:
matrix Input matrix.
Returns:
Pointer to the matrix data buffer.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.

double cpl_matrix_get_determinant const cpl_matrix *  matrix  ) 
 

Compute the determinant of a matrix.

Parameters:
matrix Pointer to matrix.
Returns:
Matrix determinant. In case of error, 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT The input matrix is not square.

The input matrix must be a square matrix. In case of a 1x1 matrix, the matrix single element value is returned.

double cpl_matrix_get_max const cpl_matrix *  matrix  ) 
 

Find the maximum value of matrix elements.

Parameters:
matrix Pointer to matrix.
Returns:
Maximum value. In case of error, 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

The maximum value of all matrix elements is found.

cpl_error_code cpl_matrix_get_maxpos const 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.

double cpl_matrix_get_mean const cpl_matrix *  matrix  ) 
 

Find the mean of all matrix elements.

Parameters:
matrix Pointer to matrix.
Returns:
Mean. In case of error 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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_get_median const cpl_matrix *  matrix  ) 
 

Find the median of matrix elements.

Parameters:
matrix Pointer to matrix.
Returns:
Median. In case of error 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

The median value of all matrix elements is calculated.

double cpl_matrix_get_min const cpl_matrix *  matrix  ) 
 

Find the minimum value of matrix elements.

Parameters:
matrix Pointer to matrix.
Returns:
Minimum value. In case of error, 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

The minimum value of all matrix elements is found.

cpl_error_code cpl_matrix_get_minpos const 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.

int cpl_matrix_get_ncol const 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

Determine the number of columns in a matrix.

int cpl_matrix_get_nrow const 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

Determine the number of rows in a matrix.

double cpl_matrix_get_stdev const cpl_matrix *  matrix  ) 
 

Find the standard deviation of matrix elements.

Parameters:
matrix Pointer to matrix.
Returns:
Standard deviation. In case of error, or if a matrix is 1x1, 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

The standard deviation 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).

cpl_matrix* cpl_matrix_invert_create const cpl_matrix *  matrix  ) 
 

Find a matrix inverse.

Parameters:
matrix Pointer to matrix to invert.
Returns:
Inverse matrix. In case of error a NULL is returned.
Errors:
CPL_ERROR_NULL_INPUT Any input is a NULL pointer.
CPL_ERROR_SINGULAR_MATRIX matrix cannot be inverted.

The input must be a square matrix. To destroy the new matrix the function cpl_matrix_delete() should be used.

Note:
When calling cpl_matrix_invert_create() with a nearly singular matrix, it is possible to get a result containin NaN values without any error code being set.

int cpl_matrix_is_diagonal const 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. If a NULL pointer is passed, or the input matrix is not square, -1 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

A threshold may be specified to consider zero any number that is close enough to zero. If the specified tolerance is negative, a default of DBL_EPSILON is used. A zero tolerance may also be specified. No error is set if the input matrix is not square.

int cpl_matrix_is_identity const 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. If a NULL pointer is passed, or the input matrix is not square, -1 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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 negative, a default of DBL_EPSILON is used. A zero tolerance may also be specified. No error is set if the input matrix is not square.

int cpl_matrix_is_zero const 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. If a NULL pointer is passed, -1 is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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 negative, a default of DBL_EPSILON is used. A zero tolerance may also be specified.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT The input base, or any matrix element, is not positive.

Each matrix element is replaced by its logarithm in the specified base. The base and all matrix elements must be positive. If this is not the case, the matrix would not be modified.

cpl_error_code cpl_matrix_multiply cpl_matrix *  matrix1,
const 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.
Errors:
CPL_ERROR_NULL_INPUT Any input matrix is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The specified matrices do not have the same size.

Multiply the two matrices element by element. The two matrices must have identical sizes. The result is written to the first matrix.

Note:
To obtain the rows-by-columns product between two matrices, cpl_matrix_product_create() should be used instead.

cpl_error_code cpl_matrix_multiply_scalar 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

Multiply each matrix element by the same factor.

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, or NULL in case of error.
Errors:
CPL_ERROR_ILLEGAL_INPUT rows or columns are not positive numbers.

This function allocates and initialises to zero a matrix of given size. 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT Any matrix element is not compatible with the specified exponent (see description below).

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, an error condition is set 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.

cpl_matrix* cpl_matrix_product_create const cpl_matrix *  matrix1,
const 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, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT Any input matrix is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The number of columns of the first matrix is not equal to the number of rows of the second matrix.

Rows-by-columns product of two matrices. The number of columns of the first matrix must be equal to the number of rows of the second matrix. To destroy the new matrix the function cpl_matrix_delete() should be used.

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

Reframe 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_OUTPUT Attempt to shrink matrix to zero size (or less).

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_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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The accessed element is beyond the matrix boundaries.

Write a value to a matrix element. The matrix rows and columns are counted from 0,0.

cpl_error_code cpl_matrix_set_size 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ILLEGAL_OUTPUT Attempt to shrink matrix to zero size (or less).

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.

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_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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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 indexes.

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 const cpl_matrix *  coeff,
const cpl_matrix *  rhs
 

Solution of a linear system.

Parameters:
coeff Matrix coefficient.
rhs Non-homogeneous term.
Returns:
Solution matrix. In case of error a NULL is returned.
Errors:
CPL_ERROR_NULL_INPUT Any input is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT coeff is not a square matrix, or rhs is not a one-column matrix.
CPL_ERROR_INCOMPATIBLE_INPUT coeff and rhs do not have the same number of rows.
CPL_ERROR_SINGULAR_MATRIX coeff cannot be inverted.

Compute the solution of a system of N equations with N unknowns:

coeff * X = rhs

coeff must be an NxN matrix, and rhs a Nx1 matrix (a one-column matrix). To destroy the solution matrix the function cpl_matrix_delete() should be used.

Note:
When calling cpl_matrix_solve() with a nearly singular matrix, it is possible to get a result containin NaN values without any error code being set.

cpl_matrix* cpl_matrix_solve_normal const cpl_matrix *  coeff,
const cpl_matrix *  rhs
 

Solution of a normal equation using a pseudo-inverse.

Parameters:
coeff Matrix coefficient.
rhs Nonhomogeneous term.
Returns:
Solution matrix. In case of error a NULL is returned.
Errors:
CPL_ERROR_NULL_INPUT Any input is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT rhs is not a one-column matrix.
CPL_ERROR_INCOMPATIBLE_INPUT coeff and rhs do not have the same number of rows.
CPL_ERROR_SINGULAR_MATRIX The linear system has no solutions.

The following redundant linear system of N equations and M unknowns is given:

   coeff * X = rhs

where coeff is the NxM matrix of the coefficients, X is the Mx1 matrix of the unknowns, and rhs the Nx1 matrix representing the nonhomogeneous terms. Then the pseudo-inverse solution to this equation is defined as:

 X = inverse(transp(coeff)) * coeff) * transp(coeff) * rhs

The solution matrix is solving the equation according to a least-squares criterion. Note that the number of unknowns can be greater, equal, or less than the number of equations. To destroy the solution matrix the function cpl_matrix_delete() should be used.

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: 0, by absolute value, otherwise by value.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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).

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: 0, by absolute value, otherwise by value.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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).

cpl_error_code cpl_matrix_subtract cpl_matrix *  matrix1,
const 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.
Errors:
CPL_ERROR_NULL_INPUT Any input matrix is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The specified matrices do not have the same size.

Subtract the second matrix from the first one element by element. The two matrices must have identical sizes. The result is written to the first matrix.

cpl_error_code cpl_matrix_subtract_scalar cpl_matrix *  matrix,
double  value
 

Subtract a scalar to a matrix.

Parameters:
matrix Pointer to matrix.
value Value to subtract.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

Subtract the same value to each matrix element.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE Any of the specified columns is outside the matrix boundaries.

The values of two given matrix columns are exchanged. Columns are counted starting from 0. If the same column number is given twice, nothing is done and no error is set.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The specified row is outside the matrix boundaries.
CPL_ERROR_ILLEGAL_INPUT The input matrix is not square.

The values of the indicated row are exchanged with the column having the same sequence number. Rows and columns are counted starting from 0.

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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE Any of the specified rows is outside the matrix boundaries.

The values of two given matrix rows are exchanged. Rows are counted starting from 0. If the same row number is given twice, nothing is done and no error is set.

cpl_error_code cpl_matrix_threshold_small 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.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

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.

cpl_matrix* cpl_matrix_transpose_create const cpl_matrix *  matrix  ) 
 

Create transposed matrix.

Parameters:
matrix Pointer to matrix to be transposed.
Returns:
Pointer to transposed matrix. If a NULL pointer is passed, a NULL pointer is returned.
Errors:
CPL_ERROR_NULL_INPUT The input matrix is a NULL pointer.

The transposed of the input matrix is created. To destroy the new matrix the function cpl_matrix_delete() should be used.

void* cpl_matrix_unwrap cpl_matrix *  matrix  ) 
 

Delete a matrix, but not its data buffer.

Parameters:
matrix Pointer to a matrix to be deleted.
Returns:
Pointer to the internal data buffer.
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_wrap() 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_wrap(). If matrix is NULL, nothing is done, and a NULL pointer is returned.

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

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, or NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT The input data is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT rows or columns are not positive numbers.

This function creates a new matrix that will encapsulate the given data. At any error condition, a NULL pointer would be returned. 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 array 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_unwrap() should be used instead; moreover, functions implying memory handling (as cpl_matrix_set_size(), or cpl_matrix_delete_row() ) should not be used.


Generated on Mon Sep 26 14:38:17 2005 for Common Pipeline Library Reference Manual by  doxygen 1.4.1