#include "clipm_priv_matrix.h"
#include "clipm_math.h"
#include "clipm_priv_checks.h"
#include "clipm_compatibility_replacements.h"
#include "clipm_priv_error.h"
#include <math.h>

Macros
#define	clipm_COPY_WINDOW_TO_MATRIX(TYPE, image, imsize, windowsize, buffer_start, out_buffer, flip)

Functions

cpl_matrix *	clipm_priv_matrix_new_from_image_window (const cpl_image *image, const cpl_size window_xxyy[4], const int vflip)
	Extract an image window into a matrix, flip vertically. More...

cpl_error_code	clipm_priv_matrix_round (cpl_matrix *matrix)
	Round the elements of a matrix to the nearest integer. More...

cpl_matrix *	clipm_priv_matrix_get_median_rows (const cpl_matrix *matrix)
	Get the medians of the values in the matrix rows respectively. More...

cpl_matrix *	clipm_priv_matrix_get_mean_rows (const cpl_matrix *matrix)
	Get the means of the values in the matrix rows respectively. More...

cpl_matrix *	clipm_priv_matrix_select_cols (const cpl_matrix matrix, const int selection, int select_nonzero)
	Return selected columns in a new matrix. More...

cpl_error_code	clipm_priv_matrix_copy_col_vector (cpl_matrix matrix, const cpl_vector vector, cpl_size col, cpl_size start_row)
	Copy the content of a vector into a matrix column (or a part of it). More...

cpl_error_code	clipm_priv_matrix_copy_vector_col (cpl_vector vector, const cpl_matrix matrix, cpl_size col, cpl_size start_row)
	Copy the content of a matrix column (or a part of it) into a vector. More...

cpl_error_code	clipm_priv_matrix_transform_create_rot2d (double angle, const double centre_xy[2], cpl_matrix transform, cpl_matrix shift)
	Create a 2d rotation matrix. More...

cpl_error_code	clipm_priv_matrix_transform_invert (const cpl_matrix transf, const cpl_matrix shift, cpl_matrix inv_transf, cpl_matrix inv_shift)
	Compute the inverse transform. More...

cpl_matrix *	clipm_priv_matrix_transform_points (const cpl_matrix points, const cpl_matrix transformation, const cpl_matrix *shift)
	Transform a pointlist. More...

cpl_matrix *	clipm_priv_matrix_create_corners_rectangle (const double centre_xy[2], double angle, const double size_lw[2])
	Create a matrix containing the corner points of a rectangle. More...

void	clipm_priv_matrix_null (cpl_matrix **m)
	Delete a CPL matrix object and set the pointer to NULL. More...

Macro Definition Documentation

#define clipm_COPY_WINDOW_TO_MATRIX	(	TYPE,
		image,
		imsize,
		windowsize,
		buffer_start,
		out_buffer,
		flip
	)

Value:

do { \
    const TYPE  *imdata; \
    double      *out_data; \
    cpl_size    x, \
                y, \
                vstep = 1; \
    imdata = cpl_image_get_data_const(image); \
    /* start at top image window border*/ \
    imdata += buffer_start[1]*imsize[0] + buffer_start[0]; \
    if (flip) \
    { \
        imdata += (windowsize[1]-1)*imsize[0]; \
        vstep *= -1; \
    } \
    out_data = out_buffer; \
    for (y = 0; y < windowsize[1]; y++) { \
        for (x = 0; x < windowsize[0]; x++) \
            *(out_data++) = imdata[x]; \
        imdata += vstep * imsize[0]; /* go up/down one image row */ \
    } \
} while (0)

Function Documentation

cpl_error_code clipm_priv_matrix_copy_col_vector	(	cpl_matrix *	matrix,
		const cpl_vector *	vector,
		cpl_size	col,
		cpl_size	start_row
	)

Copy the content of a vector into a matrix column (or a part of it).

Parameters

matrix	Modified matrix
vector	Input vector
col	Matrix column index
start_row	Index of the starting matrix row

Returns: CPL error code

Principle:: A vector is copied into a column of the provided matrix, starting at the matrix row start_row. Only the number of vector elements is copied. start_row plus the vector's size must be less than or equal to the number of matrix rows.

Error Handling:

This function can return the following error codes:

CPL_ERROR_NULL_INPUT: matrix or vector is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE:
- col < 0, or col >= the number of columns of the matrix, or
- start_row < 0, or
- start_row + the vector's size > the number of matrix rows

In the case of error, the matrix is not modified.

cpl_error_code clipm_priv_matrix_copy_vector_col	(	cpl_vector *	vector,
		const cpl_matrix *	matrix,
		cpl_size	col,
		cpl_size	start_row
	)

Copy the content of a matrix column (or a part of it) into a vector.

Parameters

vector	Modified vector
matrix	Input matrix
col	Matrix column index
start_row	Index of the starting matrix row

Returns: CPL error code

Principle:: A matrix column, starting at row start_row, is copied into the provided vector. Only the number of vector elements is regarded. start_row plus the vector's size must be less than or equal to the number of matrix rows.

Error Handling:

This function can return the following error codes:

CPL_ERROR_NULL_INPUT: vector or matrix is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE:
- col < 0, or col >= the number of columns of the matrix, or
- start_row < 0, or
- start_row + the vector's size > the number of matrix rows

In the case of error, the vector is not modified.

cpl_matrix* clipm_priv_matrix_create_corners_rectangle	(	const double	centre_xy[2],
		double	angle,
		const double	size_lw[2]
	)

Create a matrix containing the corner points of a rectangle.

Parameters

centre_xy	Centre coordinate as (x,y) tuple
angle	Orientation
size_lw	Length and width as a data tuple, the first entry (size_lw[0]) will point into the direction of angle

Returns: The matrix of size 2x4, NULL in the case of error

The output matrix will contain (x,y) tuples in 4 columns, respectively.

Error Handling:

CPL_ERROR_NULL_INPUT: if any input pointer is NULL

Todo:

implement unit test

cpl_matrix* clipm_priv_matrix_get_mean_rows ( const cpl_matrix * matrix )

Get the means of the values in the matrix rows respectively.

Parameters

matrix N x M input matrix

Returns: N x 1 output matrix, NULL on error

Principle:: The output matrix has one column and the same number of rows as the input matrix, with each column containing the mean of all values in the same row in the input matrix.

Error Handling:: If matrix is NULL, CPL_ERROR_NULL_INPUT is set and NULL is returned.

cpl_matrix* clipm_priv_matrix_get_median_rows ( const cpl_matrix * matrix )

Get the medians of the values in the matrix rows respectively.

Parameters

matrix N x M input matrix

Returns: N x 1 output matrix, NULL on error

Principle:: The output matrix has one column and the same number of rows as the input matrix, with each column containing the median of all values in the same row in the input matrix.

Error Handling:: If matrix is NULL, CPL_ERROR_NULL_INPUT is set and NULL is returned.

cpl_matrix* clipm_priv_matrix_new_from_image_window	(	const cpl_image *	image,
		const cpl_size	window_xxyy[4],
		const int	vflip
	)

Extract an image window into a matrix, flip vertically.

Parameters

image	Input image (FITS convention)
window_xxyy	Coordinate buffer (FITS) of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
vflip	Flag whether to vertically flip the data buffer

Returns: The matrix

Principle:

The image data (from a window) is copied into a matrix.
If vflip is not zero, then the data are flipped vertically (in terms of indexing) to respect the FITS convention.
Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Error Handling:

Possible error codes set in this function:

CPL_ERROR_NULL_INPUT if image is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_ACCESS_OUT_OF_RANGE if a coordinate is out of the image range

Example:: With vflip != 0, the following image content
column 1 2 3 4

row __________________

4 | A B C D

3 | E F G H

2 | I J K L

1 | M N O P

*

together with the window {2, 4, 2, 4} will result in the matrix:
column 0 1 2

row __________________

0 | B C D

1 | F G H

2 | J K L

*

Todo:: Remove when cpl_matrix_new_from_image_window() is available.

void clipm_priv_matrix_null ( cpl_matrix ** m )

Delete a CPL matrix object and set the pointer to NULL.

Parameters

m	Pointer to matrix pointer

Returns: Nothing

The following code is executed:

   if (m != NULL)
   {
       cpl_matrix_delete(*m);  // checks for NULL pointer
       *m = NULL;
   }
* 

Error Handling:: No error can occur here.

cpl_error_code clipm_priv_matrix_round ( cpl_matrix * matrix )

Round the elements of a matrix to the nearest integer.

Parameters

matrix The matrix

Returns: CPL error code

Principle:: Element by element, the elements are rounded.

Error Handling:: If matrix is NULL, CPL_ERROR_NULL_INPUT is returned.

Todo:: : Remove when cpl_matrix_round() is available.

cpl_matrix* clipm_priv_matrix_select_cols	(	const cpl_matrix *	matrix,
		const int *	selection,
		int	select_nonzero
	)

Return selected columns in a new matrix.

Parameters

matrix	N x M input matrix
selection	Integer buffer of size M containing the selection flags
select_nonzero	Flag to either select columns with a selection flag equal to zero or different from zero

Returns: N x nselected output matrix, NULL on error

Principle:: If select_nonzeros is 0, then all columns with selection[column]==0 are selected, otherwise all columns with selection[column]!=0 are selected.

Error Handling:

The following error cases may occur, and the corresponding error codes set:

CPL_ERROR_NULL_INPUT: matrix is NULL
CPL_ERROR_DATA_NOT_FOUND: no columns are selected

In the case of error, NULL is returned.

cpl_error_code clipm_priv_matrix_transform_create_rot2d	(	double	angle,
		const double	centre_xy[2],
		cpl_matrix **	transform,
		cpl_matrix **	shift
	)

Create a 2d rotation matrix.

Parameters

angle	Rotation angle
centre_xy	(Optional) rotation centre (double buffer of size 2), if it is NULL, then (0, 0) is assumed as centre
transform	(Optional output) transformation matrix
shift	(Optional output) shift vector

Returns: CPL error code

Error Handling:: No error should occur in this function.

cpl_error_code clipm_priv_matrix_transform_invert	(	const cpl_matrix *	transf,
		const cpl_matrix *	shift,
		cpl_matrix **	inv_transf,
		cpl_matrix **	inv_shift
	)

Compute the inverse transform.

Parameters

transf	Input transformation matrix
shift	Input shift vector
inv_transf	Output transformation matrix
inv_shift	Output shift vector

Returns: CPL error code

Principle:: The following expression "out = transf * in + shift" is inverted so that "in = inv_transf * out + inv_shift".

Error Handling:

The following error codes can be set and returned:

CPL_ERROR_NULL_INPUT: any input is NULL
CPL_ERROR_ILLEGAL_INPUT: transf is not a square matrix
CPL_ERROR_SINGULAR_MATRIX: transf cannot be inverted
CPL_ERROR_INCOMPATIBLE_INPUT: the number of columns of transf is not equal to the number of rows of shift

Todo:

implement unit test

cpl_matrix* clipm_priv_matrix_transform_points	(	const cpl_matrix *	points,
		const cpl_matrix *	transformation,
		const cpl_matrix *	shift
	)

Transform a pointlist.

Parameters

points	ND x NP (number of dimensions, times number of points) matrix containing the point coordinates
transformation	The ND x ND square transformation matrix, can be NULL
shift	The ND x 1 shift matrix (vector), can be NULL

Returns: The transformed points, NULL on error

Transformation:: The transformation is done by the following formula (where K denotes the column of points):
$point_K' = transformation \times point_K + shift$

Parameter Details:

The matrices points and shift are expected in the following forms:
$points = \left( \begin{array}{lllc} x_0 & x_1 & \cdots & x_{NP-1} \\ y_0 & y_1 & \cdots & y_{NP-1} \\ z_0 & z_1 & \cdots & z_{NP-1} \\ \vdots & \vdots & & \vdots \end{array} \right)$ , and $shift = \left( \begin{array}{c} s_x\\ s_y\\ s_z\\ \vdots \end{array} \right)$ .

Constraints:

The number of dimensions (ND) can be any > 0.
The number of points (NP) can be any > 0.
The transformation matrix must be square (ND x ND)
The shift matrix represents a vector and must be of size ND x 1
If transformation and shift are both NULL, then points is just copied.

Error Handling:

CPL_ERROR_NULL_INPUT if points is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the sizes of the input parameters do not fit together
CPL_ERROR_ILLEGAL_INPUT:
- if shift has more than one column
- if transformation is not square

Macros

Functions

Macro Definition Documentation

Function Documentation