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, cpl_size row, cpl_size 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, cpl_size start, cpl_size count)
	Delete columns from a matrix.

cpl_error_code	cpl_matrix_erase_rows (cpl_matrix *matrix, cpl_size start, cpl_size 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, cpl_size start_row, cpl_size start_column, cpl_size step_row, cpl_size step_column, cpl_size nrows, cpl_size ncolumns)
	Extract a submatrix from a matrix.

cpl_matrix *	cpl_matrix_extract_column (const cpl_matrix *matrix, cpl_size column)
	Copy a matrix column.

cpl_matrix *	cpl_matrix_extract_diagonal (const cpl_matrix *matrix, cpl_size diagonal)
	Extract a matrix diagonal.

cpl_matrix *	cpl_matrix_extract_row (const cpl_matrix *matrix, cpl_size 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, cpl_size column)
	Write the same value to a matrix column.

cpl_error_code	cpl_matrix_fill_diagonal (cpl_matrix *matrix, double value, cpl_size diagonal)
	Write a given value to all elements of a given matrix diagonal.

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

cpl_error_code	cpl_matrix_fill_window (cpl_matrix *matrix, double value, cpl_size row, cpl_size col, cpl_size nrow, cpl_size 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, cpl_size row, cpl_size 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, cpl_size row, cpl_size *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, cpl_size row, cpl_size *column)
	Find position of minimum value of matrix elements.

cpl_size	cpl_matrix_get_ncol (const cpl_matrix *matrix)
	Get the number of columns of a matrix.

cpl_size	cpl_matrix_get_ncol_ (const cpl_matrix *matrix)
	Get the number of columns of a matrix.

cpl_size	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 (cpl_size rows, cpl_size 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, cpl_size top, cpl_size bottom, cpl_size left, cpl_size right)
	Reframe a matrix.

void	cpl_matrix_set_ (cpl_matrix *matrix, cpl_size row, cpl_size column, double value)
	Write a value to a matrix element.

cpl_error_code	cpl_matrix_set_size (cpl_matrix *matrix, cpl_size rows, cpl_size columns)
	Resize a matrix.

cpl_error_code	cpl_matrix_shift (cpl_matrix *matrix, cpl_size rshift, cpl_size 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_matrix *	cpl_matrix_solve_svd (const cpl_matrix coeff, const cpl_matrix rhs)
	Solve a linear system in a least square sense using an SVD factorization.

cpl_matrix *	cpl_matrix_solve_svd_threshold (const cpl_matrix coeff, const cpl_matrix rhs, int mode, double tolerance)
	Solve a linear system in a least square sense using an SVD factorization discarding singular values below a given threshold.

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, cpl_size column1, cpl_size column2)
	Swap two matrix columns.

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

cpl_error_code	cpl_matrix_swap_rows (cpl_matrix *matrix, cpl_size row1, cpl_size 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 (cpl_size rows, cpl_size 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_matrix_add()

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

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_add_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_append()

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

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_matrix_copy(), and cpl_matrix_resize().

◆ cpl_matrix_copy()

cpl_error_code cpl_matrix_copy	(	cpl_matrix *	matrix,
		const cpl_matrix *	submatrix,
		cpl_size	row,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_append(), cpl_matrix_duplicate(), and cpl_matrix_resize().

◆ cpl_matrix_decomp_chol()

cpl_error_code cpl_matrix_decomp_chol ( cpl_matrix * self )

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

Parameters

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

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_SINGULAR_MATRIX, cpl_matrix_get_ncol_(), and CPL_SIZE_FORMAT.

◆ cpl_matrix_delete()

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.

References cpl_free().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_solve(), cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), cpl_matrix_solve_svd_threshold(), cpl_vector_fit_gaussian(), cpl_wcs_delete(), and cpl_wcs_platesol().

◆ cpl_matrix_divide()

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

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_divide_scalar()

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.

References CPL_ERROR_DIVISION_BY_ZERO, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_dump()

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

References CPL_SIZE_FORMAT.

◆ cpl_matrix_duplicate()

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.

References CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_matrix_copy().

Referenced by cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_solve(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

◆ cpl_matrix_erase_columns()

cpl_error_code cpl_matrix_erase_columns	(	cpl_matrix *	matrix,
		cpl_size	start,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_realloc().

◆ cpl_matrix_erase_rows()

cpl_error_code cpl_matrix_erase_rows	(	cpl_matrix *	matrix,
		cpl_size	start,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_realloc().

◆ cpl_matrix_exponential()

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.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_extract()

cpl_matrix * cpl_matrix_extract	(	const cpl_matrix *	matrix,
		cpl_size	start_row,
		cpl_size	start_column,
		cpl_size	step_row,
		cpl_size	step_column,
		cpl_size	nrows,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_malloc().

Referenced by cpl_matrix_extract_column(), and cpl_matrix_extract_row().

◆ cpl_matrix_extract_column()

cpl_matrix * cpl_matrix_extract_column	(	const cpl_matrix *	matrix,
		cpl_size	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.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_extract().

◆ cpl_matrix_extract_diagonal()

cpl_matrix * cpl_matrix_extract_diagonal	(	const cpl_matrix *	matrix,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NULL_INPUT, and cpl_malloc().

◆ cpl_matrix_extract_row()

cpl_matrix * cpl_matrix_extract_row	(	const cpl_matrix *	matrix,
		cpl_size	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.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_extract().

◆ cpl_matrix_fill()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_fill_column()

cpl_error_code cpl_matrix_fill_column	(	cpl_matrix *	matrix,
		double	value,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_fill_diagonal()

cpl_error_code cpl_matrix_fill_diagonal	(	cpl_matrix *	matrix,
		double	value,
		cpl_size	diagonal
	)

Write a given value to all elements of a given matrix diagonal.

Parameters

matrix	Matrix to modify
value	Value to write to diagonal
diagonal	Number of diagonal to overwrite, 0 for main, positive for above main, negative for below main

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

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_SIZE_FORMAT.

◆ cpl_matrix_fill_row()

cpl_error_code cpl_matrix_fill_row	(	cpl_matrix *	matrix,
		double	value,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_fill_window()

cpl_error_code cpl_matrix_fill_window	(	cpl_matrix *	matrix,
		double	value,
		cpl_size	row,
		cpl_size	col,
		cpl_size	nrow,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_flip_columns()

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.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_matrix_swap_columns().

◆ cpl_matrix_flip_rows()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_get()

double cpl_matrix_get	(	const cpl_matrix *	matrix,
		cpl_size	row,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_wcs_platesol().

◆ cpl_matrix_get_data()

double * cpl_matrix_get_data ( 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:

1  2  3
5  6  7
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.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_solve_svd_threshold().

◆ cpl_matrix_get_data_const()

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

matrix Input matrix.

Returns: Pointer to the matrix data buffer.

See also: cpl_matrix_get_data

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter(), and cpl_wcs_platesol().

◆ cpl_matrix_get_determinant()

double cpl_matrix_get_determinant ( const cpl_matrix * matrix )

Compute the determinant of a matrix.

Parameters

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

References cpl_array_delete(), cpl_array_wrap_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_ERROR_SINGULAR_MATRIX, CPL_ERROR_UNSPECIFIED, cpl_errorstate_get(), cpl_errorstate_set(), cpl_malloc(), cpl_matrix_delete(), cpl_matrix_duplicate(), and CPL_SIZE_FORMAT.

◆ cpl_matrix_get_max()

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.

References cpl_matrix_get_maxpos().

◆ cpl_matrix_get_maxpos()

cpl_error_code cpl_matrix_get_maxpos	(	const cpl_matrix *	matrix,
		cpl_size *	row,
		cpl_size *	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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_get_max().

◆ cpl_matrix_get_mean()

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

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_vector_fit_gaussian().

◆ cpl_matrix_get_median()

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.

References CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

◆ cpl_matrix_get_min()

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.

References cpl_matrix_get_minpos().

◆ cpl_matrix_get_minpos()

cpl_error_code cpl_matrix_get_minpos	(	const cpl_matrix *	matrix,
		cpl_size *	row,
		cpl_size *	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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_get_min().

◆ cpl_matrix_get_ncol()

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

References CPL_ERROR_NULL_INPUT, and cpl_matrix_get_ncol_().

Referenced by cpl_image_filter(), cpl_test_get_bytes_matrix(), and cpl_wcs_convert().

◆ cpl_matrix_get_ncol_()

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

Note: No error checking in this internal function!

See also: cpl_matrix_get_ncol

Referenced by cpl_matrix_decomp_chol(), cpl_matrix_get_ncol(), cpl_matrix_solve_chol(), cpl_polynomial_fit(), cpl_ppm_match_points(), and cpl_vector_fill_polynomial_fit_residual().

◆ cpl_matrix_get_nrow()

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

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter(), cpl_matrix_solve_svd_threshold(), cpl_polynomial_fit(), cpl_test_get_bytes_matrix(), cpl_wcs_convert(), and cpl_wcs_platesol().

◆ cpl_matrix_get_stdev()

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

References CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_invert_create()

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

References cpl_array_delete(), cpl_array_wrap_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), cpl_matrix_delete(), cpl_matrix_duplicate(), cpl_matrix_new(), and cpl_matrix_set_().

◆ cpl_matrix_is_diagonal()

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.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_is_identity().

◆ cpl_matrix_is_identity()

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.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_is_diagonal().

◆ cpl_matrix_is_zero()

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.

References CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_logarithm()

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.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_multiply()

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

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_multiply_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_new()

cpl_matrix * cpl_matrix_new	(	cpl_size	rows,
		cpl_size	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.

References cpl_calloc(), CPL_ERROR_ILLEGAL_INPUT, and cpl_malloc().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_invert_create(), cpl_matrix_resize(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

◆ cpl_matrix_power()

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

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_product_create()

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

References cpl_ensure, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_matrix_wrap().

Referenced by cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

◆ cpl_matrix_resize()

cpl_error_code cpl_matrix_resize	(	cpl_matrix *	matrix,
		cpl_size	top,
		cpl_size	bottom,
		cpl_size	left,
		cpl_size	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.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), cpl_matrix_copy(), cpl_matrix_new(), and cpl_matrix_unwrap().

Referenced by cpl_matrix_append(), and cpl_matrix_set_size().

◆ cpl_matrix_set_()

void cpl_matrix_set_	(	cpl_matrix *	matrix,
		cpl_size	row,
		cpl_size	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: void

Note: No error checking in this internal function!

See also: cpl_matrix_set

Referenced by cpl_fit_image_gaussian(), and cpl_matrix_invert_create().

◆ cpl_matrix_set_size()

cpl_error_code cpl_matrix_set_size	(	cpl_matrix *	matrix,
		cpl_size	rows,
		cpl_size	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.

References CPL_ERROR_NONE, and cpl_matrix_resize().

◆ cpl_matrix_shift()

cpl_error_code cpl_matrix_shift	(	cpl_matrix *	matrix,
		cpl_size	rshift,
		cpl_size	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.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

◆ cpl_matrix_solve()

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

Solution of a linear system.

Parameters

coeff	A non-singular N by N matrix.
rhs	A 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.

References cpl_array_delete(), cpl_array_wrap_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), cpl_matrix_delete(), and cpl_matrix_duplicate().

◆ cpl_matrix_solve_chol()

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

Solve a L*transpose(L)-system.

Parameters

self	N by N L*transpose(L)-matrix from cpl_matrix_decomp_chol()
rhs	M 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().

References cpl_ensure_code, CPL_ERROR_DIVISION_BY_ZERO, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_matrix_get_ncol_().

◆ cpl_matrix_solve_normal()

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

coeff	The N by M matrix of coefficients, where N >= M.
rhs	An 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().

References cpl_ensure, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_matrix_delete(), cpl_matrix_product_create(), and cpl_matrix_transpose_create().

◆ cpl_matrix_solve_svd()

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

Solve a linear system in a least square sense using an SVD factorization.

Parameters

coeff	An N by M matrix of linear system coefficients, where N >= M
rhs	An N by 1 matrix with the right hand side of the system

Returns: A newly allocated M by 1 matrix containing the solution vector 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_ILLEGAL_INPUT	The matrix rhs has more than one column.

The function solves a linear system of the form Ax = b for the solution vector x, where A is represented by the argument coeff and b by the argument rhs. The linear system is solved using the singular value decomposition (SVD) of the coefficient matrix, based on a one-sided Jacobi orthogonalization. When solving the linear system all singular values are taken into account, regardless of their magnitude. This is equivalent to calling cpl_matrix_solve_svd_threshold() with mode set to 2 and a threshold value of 0.

The returned solution matrix should be deallocated using cpl_matrix_delete().

See also: cpl_matrix_solve_svd_threshold()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_matrix_delete(), cpl_matrix_duplicate(), cpl_matrix_new(), cpl_matrix_product_create(), cpl_matrix_transpose_create(), cpl_vector_delete(), cpl_vector_get_data_const(), and cpl_vector_new().

◆ cpl_matrix_solve_svd_threshold()

cpl_matrix * cpl_matrix_solve_svd_threshold	(	const cpl_matrix *	coeff,
		const cpl_matrix *	rhs,
		int	mode,
		double	tolerance
	)

Solve a linear system in a least square sense using an SVD factorization discarding singular values below a given threshold.

Parameters

coeff	An N by M matrix of linear system coefficients, where N >= M
rhs	An N by 1 matrix with the right hand side of the system
mode	Cutoff mode selector for small singular values.
tolerance	Factor used to compute the cutoff value if mode is set to `2`.

Returns: A newly allocated M by 1 matrix containing the solution vector or NULL on error.

Errors

CPL_ERROR_NULL_INPUT	coeff or rhs is a `NULL` pointer.
CPL_ERROR_INCOMPATIBLE_INPUT	coeff and rhs do not have the same number of rows.
CPL_ILLEGAL_INPUT	The matrix rhs has more than one column, or an illegal mode or tolerance was given.

The function solves a linear system of the form Ax = b for the solution vector x, where A is represented by the argument coeff and b by the argument rhs. The linear system is solved using the singular value decomposition (SVD) of the coefficient matrix, based on a one-sided Jacobi orthogonalization. When solving the linear system singular values which are less or equal than a given cutoff value are treated as zero.

The argument mode is used to select the computation of the cutoff value for small singular values. If mode is set to 0 the machine precision (DBL_EPSILON) is used as the cutoff factor. If mode is 1, the cutoff factor is computed as $10 \times\text{\texttt{DBL\_EPSILON}} \times \max(N, M)$ , and if mode is 2 the argument tolerance, a value in the range . is used as the cutoff factor. The actual cutoff value, is then given by the cutoff factor times the biggest singular value obtained from the SVD of the input matrix coeff.

The returned solution matrix should be deallocated using cpl_matrix_delete().

See also: cpl_matrix_solve_svd()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_matrix_delete(), cpl_matrix_duplicate(), cpl_matrix_get_data(), cpl_matrix_get_nrow(), cpl_matrix_new(), cpl_matrix_product_create(), cpl_matrix_transpose_create(), CPL_MAX, cpl_vector_delete(), cpl_vector_get_data_const(), cpl_vector_get_max(), and cpl_vector_new().

◆ cpl_matrix_sort_columns()

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

References cpl_calloc(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

◆ cpl_matrix_sort_rows()

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

References cpl_calloc(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

◆ cpl_matrix_subtract()

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

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_subtract_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_swap_columns()

cpl_error_code cpl_matrix_swap_columns	(	cpl_matrix *	matrix,
		cpl_size	column1,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_flip_columns().

◆ cpl_matrix_swap_rowcolumn()

cpl_error_code cpl_matrix_swap_rowcolumn	(	cpl_matrix *	matrix,
		cpl_size	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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_swap_rows()

cpl_error_code cpl_matrix_swap_rows	(	cpl_matrix *	matrix,
		cpl_size	row1,
		cpl_size	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.

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_threshold_small()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

◆ cpl_matrix_transpose_create()

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.

References CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_matrix_wrap().

Referenced by cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

◆ cpl_matrix_unwrap()

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.

References cpl_free().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_resize(), and cpl_vector_fit_gaussian().

◆ cpl_matrix_wrap()

cpl_matrix * cpl_matrix_wrap	(	cpl_size	rows,
		cpl_size	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

1  2  3
5  6  7
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.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_malloc().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_product_create(), cpl_matrix_transpose_create(), cpl_vector_fit_gaussian(), and cpl_wcs_convert().

Functions

Detailed Description

Function Documentation

◆ cpl_matrix_add()

◆ cpl_matrix_add_scalar()

◆ cpl_matrix_append()

◆ cpl_matrix_copy()

◆ cpl_matrix_decomp_chol()

◆ cpl_matrix_delete()

◆ cpl_matrix_divide()

◆ cpl_matrix_divide_scalar()

◆ cpl_matrix_dump()

◆ cpl_matrix_duplicate()

◆ cpl_matrix_erase_columns()

◆ cpl_matrix_erase_rows()

◆ cpl_matrix_exponential()

◆ cpl_matrix_extract()

◆ cpl_matrix_extract_column()

◆ cpl_matrix_extract_diagonal()

◆ cpl_matrix_extract_row()

◆ cpl_matrix_fill()

◆ cpl_matrix_fill_column()

◆ cpl_matrix_fill_diagonal()

◆ cpl_matrix_fill_row()

◆ cpl_matrix_fill_window()

◆ cpl_matrix_flip_columns()

◆ cpl_matrix_flip_rows()

◆ cpl_matrix_get()

◆ cpl_matrix_get_data()

◆ cpl_matrix_get_data_const()

◆ cpl_matrix_get_determinant()

◆ cpl_matrix_get_max()

◆ cpl_matrix_get_maxpos()

◆ cpl_matrix_get_mean()

◆ cpl_matrix_get_median()

◆ cpl_matrix_get_min()

◆ cpl_matrix_get_minpos()

◆ cpl_matrix_get_ncol()

◆ cpl_matrix_get_ncol_()

◆ cpl_matrix_get_nrow()

◆ cpl_matrix_get_stdev()

◆ cpl_matrix_invert_create()

◆ cpl_matrix_is_diagonal()

◆ cpl_matrix_is_identity()

◆ cpl_matrix_is_zero()

◆ cpl_matrix_logarithm()

◆ cpl_matrix_multiply()

◆ cpl_matrix_multiply_scalar()

◆ cpl_matrix_new()

◆ cpl_matrix_power()

◆ cpl_matrix_product_create()

◆ cpl_matrix_resize()

◆ cpl_matrix_set_()

◆ cpl_matrix_set_size()

◆ cpl_matrix_shift()

◆ cpl_matrix_solve()

◆ cpl_matrix_solve_chol()

◆ cpl_matrix_solve_normal()

◆ cpl_matrix_solve_svd()

◆ cpl_matrix_solve_svd_threshold()

◆ cpl_matrix_sort_columns()

◆ cpl_matrix_sort_rows()

◆ cpl_matrix_subtract()

◆ cpl_matrix_subtract_scalar()

◆ cpl_matrix_swap_columns()

◆ cpl_matrix_swap_rowcolumn()

◆ cpl_matrix_swap_rows()

◆ cpl_matrix_threshold_small()

◆ cpl_matrix_transpose_create()

◆ cpl_matrix_unwrap()

◆ cpl_matrix_wrap()