Common Pipeline Library Reference Manual  5.3.1
Functions
Matrices

Functions

cpl_error_code cpl_matrix_add (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Add two matrices.
cpl_error_code cpl_matrix_add_scalar (cpl_matrix *matrix, double value)
 Add a scalar to 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_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_decomp_chol (cpl_matrix *self)
 Replace a matrix by its Cholesky-decomposition, L * transpose(L) = A.
void cpl_matrix_delete (cpl_matrix *matrix)
 Delete a matrix.
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_divide_scalar (cpl_matrix *matrix, double value)
 Divide a matrix by a scalar.
void cpl_matrix_dump (const cpl_matrix *matrix, FILE *stream)
 Print a matrix.
cpl_matrix * cpl_matrix_duplicate (const cpl_matrix *matrix)
 Make a copy of 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_erase_rows (cpl_matrix *matrix, int start, int count)
 Delete rows from a matrix.
cpl_error_code cpl_matrix_exponential (cpl_matrix *matrix, double base)
 Compute the exponential of matrix elements.
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_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_matrix * cpl_matrix_extract_row (const cpl_matrix *matrix, int row)
 Extract a matrix row.
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_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_fill_row (cpl_matrix *matrix, double value, int row)
 Write the same value to a matrix row.
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_flip_columns (cpl_matrix *matrix)
 Reverse order of columns in matrix.
cpl_error_code cpl_matrix_flip_rows (cpl_matrix *matrix)
 Reverse order of rows in matrix.
double cpl_matrix_get (const cpl_matrix *matrix, int row, int column)
 Get the value of a matrix element.
double * cpl_matrix_get_data (cpl_matrix *matrix)
 Get the pointer to a matrix data buffer, or NULL in case of error.
const double * cpl_matrix_get_data_const (const cpl_matrix *matrix)
 Get the pointer to a matrix data buffer, or NULL in case of error.
double cpl_matrix_get_determinant (const cpl_matrix *matrix)
 Compute the determinant of a matrix.
double cpl_matrix_get_max (const cpl_matrix *matrix)
 Find the maximum 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.
double cpl_matrix_get_mean (const cpl_matrix *matrix)
 Find the mean of all 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.
cpl_error_code cpl_matrix_get_minpos (const cpl_matrix *matrix, int *row, int *column)
 Find position of minimum value of matrix elements.
int cpl_matrix_get_ncol (const cpl_matrix *matrix)
 Get the number of columns of a matrix.
int cpl_matrix_get_nrow (const cpl_matrix *matrix)
 Get the number of rows of a matrix.
double cpl_matrix_get_stdev (const cpl_matrix *matrix)
 Find the standard deviation of matrix elements.
cpl_matrix * cpl_matrix_invert_create (const cpl_matrix *matrix)
 Find a matrix inverse.
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.
int cpl_matrix_is_zero (const cpl_matrix *matrix, double tolerance)
 Check for zero matrix.
cpl_error_code cpl_matrix_logarithm (cpl_matrix *matrix, double base)
 Compute the logarithm of matrix elements.
cpl_error_code cpl_matrix_multiply (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Multiply two matrices element by element.
cpl_error_code cpl_matrix_multiply_scalar (cpl_matrix *matrix, double value)
 Multiply a matrix by a scalar.
cpl_matrix * cpl_matrix_new (int rows, int columns)
 Create a zero matrix of given size.
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_resize (cpl_matrix *matrix, int top, int bottom, int left, int right)
 Reframe a matrix.
cpl_error_code cpl_matrix_set (cpl_matrix *matrix, int row, int column, double value)
 Write a value to a matrix element.
cpl_error_code cpl_matrix_set_size (cpl_matrix *matrix, int rows, int columns)
 Resize a matrix.
cpl_error_code cpl_matrix_shift (cpl_matrix *matrix, int rshift, int cshift)
 Shift matrix elements.
cpl_matrix * cpl_matrix_solve (const cpl_matrix *coeff, const cpl_matrix *rhs)
 Solution of a linear system.
cpl_error_code cpl_matrix_solve_chol (const cpl_matrix *self, cpl_matrix *rhs)
 Solve a L*transpose(L)-system.
cpl_matrix * cpl_matrix_solve_normal (const cpl_matrix *coeff, const cpl_matrix *rhs)
 Solution of overdetermined linear equations in a least squares sense.
cpl_error_code cpl_matrix_sort_columns (cpl_matrix *matrix, int mode)
 Sort matrix by columns.
cpl_error_code cpl_matrix_sort_rows (cpl_matrix *matrix, int mode)
 Sort matrix by rows.
cpl_error_code cpl_matrix_subtract (cpl_matrix *matrix1, const cpl_matrix *matrix2)
 Subtract a matrix from another.
cpl_error_code cpl_matrix_subtract_scalar (cpl_matrix *matrix, double value)
 Subtract a scalar to a matrix.
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_swap_rows (cpl_matrix *matrix, int row1, int row2)
 Swap two matrix rows.
cpl_error_code cpl_matrix_threshold_small (cpl_matrix *matrix, double tolerance)
 Rounding to zero very small numbers in matrix.
cpl_matrix * cpl_matrix_transpose_create (const cpl_matrix *matrix)
 Create transposed matrix.
void * cpl_matrix_unwrap (cpl_matrix *matrix)
 Delete a matrix, but not its data buffer.
cpl_matrix * cpl_matrix_wrap (int rows, int columns, double *data)
 Create a new matrix from existing data.

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:
matrix1Pointer to first matrix.
matrix2Pointer 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:
matrixPointer to matrix.
valueValue 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:
matrix1Pointer to first matrix.
matrix2Pointer to second matrix.
modeMatrices 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:
matrixPointer to matrix to be modified.
submatrixPointer to matrix to get the values from.
rowPosition of row 0 of submatrix in matrix.
colPosition 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.

cpl_error_code cpl_matrix_decomp_chol ( cpl_matrix *  self)

Replace a matrix by its Cholesky-decomposition, L * transpose(L) = A.

Parameters:
selfN by N symmetric positive-definite matrix to decompose
Returns:
CPL_ERROR_NONE on success, or the relevant CPL error code
Note:
Only the upper triangle of self is read, L is written in the lower triangle
If the matrix is singular the elements of self become undefined
See also:
Golub & Van Loan, Matrix Computations, Algorithm 4.2.1 (Cholesky: Gaxpy Version).
Errors:
CPL_ERROR_NULL_INPUT An input pointer is NULL.
CPL_ERROR_ILLEGAL_INPUT self is not an n by n matrix.
CPL_ERROR_SINGULAR_MATRIX self is not symmetric, positive definite.
void cpl_matrix_delete ( cpl_matrix *  matrix)

Delete a matrix.

Parameters:
matrixPointer 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:
matrix1Pointer to first matrix.
matrix2Pointer 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:
matrixPointer to matrix.
valueDivisor.
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.

void cpl_matrix_dump ( const cpl_matrix *  matrix,
FILE *  stream 
)

Print a matrix.

Parameters:
matrixThe matrix to print
streamThe 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:
matrixMatrix 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:
matrixPointer to matrix to be modified.
startFirst column to delete.
countNumber 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:
matrixPointer to matrix to be modified.
startFirst row to delete.
countNumber 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:
matrixTarget matrix.
baseExponential 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:
matrixPointer to the input matrix.
start_rowMatrix row where to begin extraction.
start_columnMatrix column where to begin extraction.
step_rowStep between extracted rows.
step_columnStep between extracted columns.
nrowsNumber of rows to extract.
ncolumnsNumber 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:
matrixPointer to matrix containing the column.
columnSequence 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:
matrixPointer to the matrix containing the diagonal.
diagonalSequence 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:
matrixPointer to the matrix containing the row.
rowSequence 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:
matrixPointer to the matrix to access
valueValue 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:
matrixPointer to the matrix to access
valueValue to write
columnSequence 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:
matrixMatrix to access
valueValue to write
diagonalSequence 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:
matrixMatrix to access
valueValue to write
rowSequence 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:
matrixPointer to matrix to be modified.
valueValue to write.
rowStart row of matrix submatrix.
colStart column of matrix submatrix.
nrowNumber of rows of matrix submatrix.
ncolNumber 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:
matrixPointer 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:
matrixPointer 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:
matrixPointer to a matrix.
rowMatrix element row.
columnMatrix 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 ( cpl_matrix *  matrix)

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

Parameters:
matrixInput 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.
const double* cpl_matrix_get_data_const ( const cpl_matrix *  matrix)

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

Parameters:
matrixInput matrix.
Returns:
Pointer to the matrix data buffer.
See also:
cpl_matrix_get_data
double cpl_matrix_get_determinant ( const cpl_matrix *  matrix)

Compute the determinant of a matrix.

Parameters:
matrixPointer to n by n 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.
CPL_ERROR_UNSPECIFIED The input matrix is near-singular with a determinant so close to zero that it cannot be represented by a double.

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:
matrixPointer 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:
matrixInput matrix.
rowReturned row position of maximum.
columnReturned 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:
matrixPointer 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:
matrixPointer 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:
matrixPointer 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:
matrixInput matrix.
rowReturned row position of minimum.
columnReturned 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:
matrixPointer 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:
matrixPointer 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:
matrixPointer 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:
matrixPointer 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_ILLEGAL_INPUT self is not an n by n matrix.
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:
matrixPointer to matrix to be checked.
toleranceMax 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:
matrixPointer to matrix to be checked.
toleranceMax 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:
matrixPointer to matrix to be checked.
toleranceMax 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:
matrixPointer to matrix.
baseLogarithm 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:
matrix1Pointer to first matrix.
matrix2Pointer 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:
matrixPointer to matrix.
valueMultiplication 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:
rowsNumber of matrix rows.
columnsNumber 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:
matrixPointer to matrix.
exponentConstant 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 exactly 0.5 the (faster) sqrt() will be applied instead of pow(). 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:
matrix1Pointer to left side matrix.
matrix2Pointer 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:
matrixPointer to matrix to be modified.
topExtra rows on top.
bottomExtra rows on bottom.
leftExtra columns on left.
rightExtra 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:
matrixInput matrix.
rowMatrix element row.
columnMatrix element column.
valueValue 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:
matrixPointer to matrix to be resized.
rowsNew number of rows.
columnsNew 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:
matrixPointer to matrix to be modified.
rshiftShift in the vertical direction.
cshiftShift 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.

cpl_matrix* cpl_matrix_solve ( const cpl_matrix *  coeff,
const cpl_matrix *  rhs 
)

Solution of a linear system.

Parameters:
coeffA non-singular N by N matrix.
rhsA matrix containing one or more right-hand-sides.
Note:
rhs must have N rows and may contain more than one column, which each represent an independent right-hand-side.
Returns:
A newly allocated solution matrix with the size as rhs, or NULL on error.
Errors:
CPL_ERROR_NULL_INPUT Any input is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT coeff is not a square matrix.
CPL_ERROR_INCOMPATIBLE_INPUT coeff and rhs do not have the same number of rows.
CPL_ERROR_SINGULAR_MATRIX coeff is singular (to working precision).

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

coeff * X = rhs

coeff must be an NxN matrix, and rhs a NxM matrix. M greater than 1 means that multiple independent right-hand-sides are solved for. To destroy the solution matrix the function cpl_matrix_delete() should be used.

cpl_error_code cpl_matrix_solve_chol ( const cpl_matrix *  self,
cpl_matrix *  rhs 
)

Solve a L*transpose(L)-system.

Parameters:
selfN by N L*transpose(L)-matrix from cpl_matrix_decomp_chol()
rhsM right-hand-sides to be replaced by their solution
Returns:
CPL_ERROR_NONE on success, or the relevant CPL error code
See also:
cpl_matrix_decomp_chol()
Note:
Only the lower triangle of self is accessed
Errors:
CPL_ERROR_NULL_INPUT An input pointer is NULL.
CPL_ERROR_ILLEGAL_INPUT self is not an n by n matrix.
CPL_ERROR_INCOMPATIBLE_INPUT The specified matrices do not have the same number of rows.
CPL_ERROR_DIVISION_BY_ZERO The main diagonal of L contains a zero. This error can only occur if the L*transpose(L)-matrix does not come from a successful call to cpl_matrix_decomp_chol().
cpl_matrix* cpl_matrix_solve_normal ( const cpl_matrix *  coeff,
const cpl_matrix *  rhs 
)

Solution of overdetermined linear equations in a least squares sense.

Parameters:
coeffThe N by M matrix of coefficients, where N >= M.
rhsAn N by K matrix containing K right-hand-sides.
Note:
rhs may contain more than one column, which each represent an independent right-hand-side.
Returns:
A newly allocated M by K solution matrix, or NULL on error.
Errors:
CPL_ERROR_NULL_INPUT Any input is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT coeff and rhs do not have the same number of rows.
CPL_ERROR_SINGULAR_MATRIX The matrix is (near) singular and a solution cannot be computed.

The following 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 MxK matrix of the unknowns, and rhs the NxK matrix containing the K right hand side(s).

The solution to the normal equations is known to be a least-squares solution, i.e. the 2-norm of coeff * X - rhs is minimized by the solution to transpose(coeff) * coeff * X = transpose(coeff) * rhs.

In the case that coeff is square (N is equal to M) it gives a faster and more accurate result to use cpl_matrix_solve().

The solution matrix should be deallocated with the function cpl_matrix_delete().

cpl_error_code cpl_matrix_sort_columns ( cpl_matrix *  matrix,
int  mode 
)

Sort matrix by columns.

Parameters:
matrixPointer to matrix to be sorted.
modeSorting 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:
matrixPointer to matrix to be sorted.
modeSorting 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:
matrix1Pointer to first matrix.
matrix2Pointer 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:
matrixPointer to matrix.
valueValue 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:
matrixPointer to matrix to be modified.
column1One matrix column.
column2Another 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:
matrixPointer to matrix to be modified.
rowMatrix 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:
matrixPointer to matrix to be modified.
row1One matrix row.
row2Another 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:
matrixPointer to matrix to be chopped.
toleranceMax 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:
matrixPointer 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:
matrixPointer 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:
dataExisting data buffer.
rowsNumber of matrix rows.
columnsNumber 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.