Functions
cpl_error_code	cpl_bivector_copy (cpl_bivector self, const cpl_bivector other)
	Copy contents of a bivector into another bivector.

void	cpl_bivector_delete (cpl_bivector *f)
	Delete a cpl_bivector.

void	cpl_bivector_dump (const cpl_bivector f, FILE stream)
	Dump a cpl_bivector as ASCII to a stream.

cpl_bivector *	cpl_bivector_duplicate (const cpl_bivector *in)
	Duplicate a cpl_bivector.

cpl_size	cpl_bivector_get_size (const cpl_bivector *in)
	Get the size of the cpl_bivector.

cpl_vector *	cpl_bivector_get_x (cpl_bivector *in)
	Get a pointer to the x vector of the cpl_bivector.

const cpl_vector *	cpl_bivector_get_x_const (const cpl_bivector *in)
	Get a pointer to the x vector of the cpl_bivector.

double *	cpl_bivector_get_x_data (cpl_bivector *in)
	Get a pointer to the x data part of the cpl_bivector.

const double *	cpl_bivector_get_x_data_const (const cpl_bivector *in)
	Get a pointer to the x data part of the cpl_bivector.

cpl_vector *	cpl_bivector_get_y (cpl_bivector *in)
	Get a pointer to the y vector of the cpl_bivector.

const cpl_vector *	cpl_bivector_get_y_const (const cpl_bivector *in)
	Get a pointer to the y vector of the cpl_bivector.

double *	cpl_bivector_get_y_data (cpl_bivector *in)
	Get a pointer to the y data part of the cpl_bivector.

const double *	cpl_bivector_get_y_data_const (const cpl_bivector *in)
	Get a pointer to the y data part of the cpl_bivector.

cpl_error_code	cpl_bivector_interpolate_linear (cpl_bivector fout, const cpl_bivector fref)
	Linear interpolation of a 1d-function.

cpl_bivector *	cpl_bivector_new (cpl_size n)
	Create a new cpl_bivector.

cpl_bivector *	cpl_bivector_read (const char *filename)
	Read a list of values from an ASCII file and create a cpl_bivector.

cpl_error_code	cpl_bivector_sort (cpl_bivector self, const cpl_bivector other, cpl_sort_direction dir, cpl_sort_mode mode)
	Sort a cpl_bivector.

void	cpl_bivector_unwrap_vectors (cpl_bivector *f)
	Free memory associated to a cpl_bivector, excluding the two vectors.

cpl_bivector *	cpl_bivector_wrap_vectors (cpl_vector x, cpl_vector y)
	Create a new cpl_bivector from two cpl_vectors.

Detailed Description

This module provides functions to handle cpl_bivector.

A cpl_bivector is composed of two vectors of the same size. It can be used to store 1d functions, with the x and y positions of the samples, offsets in x and y or simply positions in an image.

This module provides among other things functions for interpolation and for sorting one vector according to another.

Synopsis:: #include "cpl_bivector.h"

Function Documentation

◆ cpl_bivector_copy()

cpl_error_code cpl_bivector_copy	(	cpl_bivector *	self,
		const cpl_bivector *	other
	)

Copy contents of a bivector into another bivector.

Parameters

self	destination cpl_vector
other	source cpl_vector

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_vector_set_size() if source and destination have different sizes.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_bivector_get_x(), cpl_bivector_get_x_const(), cpl_bivector_get_y(), cpl_bivector_get_y_const(), CPL_ERROR_NONE, and cpl_vector_copy().

◆ cpl_bivector_delete()

void cpl_bivector_delete ( cpl_bivector * f )

Delete a cpl_bivector.

Parameters

f	cpl_bivector to delete

Returns: void

This function deletes a bivector. If the input bivector f is NULL, nothing is done, and no error is set.

References cpl_free(), and cpl_vector_delete().

Referenced by cpl_apertures_get_fwhm(), cpl_flux_get_noise_ring(), cpl_geom_img_offset_combine(), cpl_image_fit_gaussian(), cpl_wlcalib_slitmodel_delete(), and cpl_wlcalib_slitmodel_set_catalog().

◆ cpl_bivector_dump()

void cpl_bivector_dump	(	const cpl_bivector *	f,
		FILE *	stream
	)

Dump a cpl_bivector as ASCII to a stream.

Parameters

f	Input cpl_bivector to dump or NULL
stream	Output stream, accepts `stdout` or `stderr` or NULL

Returns: void

Comment lines start with the hash character.

stream may be NULL in which case stdout is used.

Note: In principle a cpl_bivector can be saved using cpl_bivector_dump() and re-read using cpl_bivector_read(). This will however introduce significant precision loss due to the limited accuracy of the ASCII representation.

References cpl_bivector_get_size(), cpl_vector_get_data_const(), and cpl_vector_get_size().

◆ cpl_bivector_duplicate()

cpl_bivector * cpl_bivector_duplicate ( const cpl_bivector * in )

Duplicate a cpl_bivector.

Parameters

in	cpl_bivector to duplicate

Returns: 1 newly allocated cpl_bivector or NULL on error

The returned object must be deallocated using cpl_bivector_delete()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the input bivector contains vectors of different sizes

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), cpl_vector_duplicate(), and cpl_vector_get_size().

◆ cpl_bivector_get_size()

cpl_size cpl_bivector_get_size ( const cpl_bivector * in )

Get the size of the cpl_bivector.

Parameters

in	the input bivector

Returns: The size or a negative number on error

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the input bivector contains vectors of different sizes

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_vector_get_size().

Referenced by cpl_bivector_dump(), cpl_bivector_interpolate_linear(), cpl_bivector_sort(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_plot_bivector(), and cpl_plot_bivectors().

◆ cpl_bivector_get_x()

cpl_vector * cpl_bivector_get_x ( cpl_bivector * in )

Get a pointer to the x vector of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the x vector or NULL on error

The returned pointer refers to an already created cpl_vector.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_bivector_copy(), and cpl_geom_img_offset_combine().

◆ cpl_bivector_get_x_const()

const cpl_vector * cpl_bivector_get_x_const ( const cpl_bivector * in )

Get a pointer to the x vector of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the x vector or NULL on error

See also: cpl_bivector_get_x

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_bivector_copy(), cpl_bivector_interpolate_linear(), cpl_geom_img_offset_saa(), and cpl_polynomial_fit_2d_create().

◆ cpl_bivector_get_x_data()

double * cpl_bivector_get_x_data ( cpl_bivector * in )

Get a pointer to the x data part of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the double x array or NULL on error

See also: cpl_vector_get_data The returned pointer refers to already allocated data.

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

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, CPL_ERROR_NULL_INPUT, and cpl_vector_get_data().

Referenced by cpl_apertures_get_fwhm(), cpl_bivector_interpolate_linear(), cpl_bivector_sort(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), cpl_image_fit_gaussian(), and cpl_image_iqe().

◆ cpl_bivector_get_x_data_const()

const double * cpl_bivector_get_x_data_const ( const cpl_bivector * in )

Get a pointer to the x data part of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the double x array or NULL on error

See also: cpl_bivector_get_x_data

References cpl_ensure, CPL_ERROR_NULL_INPUT, and cpl_vector_get_data_const().

Referenced by cpl_bivector_interpolate_linear(), cpl_bivector_sort(), cpl_flux_get_noise_ring(), cpl_geom_img_offset_fine(), cpl_plot_bivector(), and cpl_plot_bivectors().

◆ cpl_bivector_get_y()

cpl_vector * cpl_bivector_get_y ( cpl_bivector * in )

Get a pointer to the y vector of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the y vector or NULL on error

The returned pointer refers to an already created cpl_vector.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_bivector_copy(), and cpl_geom_img_offset_combine().

◆ cpl_bivector_get_y_const()

const cpl_vector * cpl_bivector_get_y_const ( const cpl_bivector * in )

Get a pointer to the y vector of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the y vector or NULL on error

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_bivector_copy(), cpl_geom_img_offset_saa(), and cpl_polynomial_fit_2d_create().

◆ cpl_bivector_get_y_data()

double * cpl_bivector_get_y_data ( cpl_bivector * in )

Get a pointer to the y data part of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the double y array or NULL on error

See also: cpl_vector_get_x_data

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure, CPL_ERROR_NULL_INPUT, and cpl_vector_get_data().

Referenced by cpl_apertures_get_fwhm(), cpl_bivector_interpolate_linear(), cpl_bivector_sort(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), and cpl_image_iqe().

◆ cpl_bivector_get_y_data_const()

const double * cpl_bivector_get_y_data_const ( const cpl_bivector * in )

Get a pointer to the y data part of the cpl_bivector.

Parameters

in	a cpl_bivector

Returns: Pointer to the double y array or NULL on error

See also: cpl_bivector_get_y_data

References cpl_ensure, CPL_ERROR_NULL_INPUT, and cpl_vector_get_data_const().

Referenced by cpl_bivector_interpolate_linear(), cpl_bivector_sort(), cpl_flux_get_noise_ring(), cpl_geom_img_offset_fine(), cpl_plot_bivector(), and cpl_plot_bivectors().

◆ cpl_bivector_interpolate_linear()

cpl_error_code cpl_bivector_interpolate_linear	(	cpl_bivector *	fout,
		const cpl_bivector *	fref
	)

Linear interpolation of a 1d-function.

Parameters

fout	Preallocated with X-vector set, to hold interpolation in Y
fref	Reference 1d-function

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_

fref must have both its abscissa and ordinate defined. fout must have its abscissa defined and its ordinate allocated.

The linear interpolation will be done from the values in fref to the abscissa points in fout.

For each abscissa point in fout, fref must either have two neigboring abscissa points such that xref_i < xout_j < xref{i+1}, or a single identical abscissa point, such that xref_i == xout_j.

This is ensured by monotonely growing abscissa points in both fout and fref (and by min(xref) <= min(xout) and max(xout) < max(xref)).

However, for efficiency reasons (since fref can be very long) the monotonicity is only verified to the extent necessary to actually perform the interpolation.

This input requirement implies that extrapolation is not allowed.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_DATA_NOT_FOUND if fout has an endpoint which is out of range
CPL_ERROR_ILLEGAL_INPUT if the monotonicity requirement on the 2 input abscissa vectors is not met.

References cpl_bivector_get_size(), cpl_bivector_get_x_const(), cpl_bivector_get_x_data(), cpl_bivector_get_x_data_const(), cpl_bivector_get_y_data(), cpl_bivector_get_y_data_const(), cpl_ensure_code, CPL_ERROR_DATA_NOT_FOUND, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and cpl_vector_find().

◆ cpl_bivector_new()

cpl_bivector * cpl_bivector_new ( cpl_size n )

Create a new cpl_bivector.

Parameters

n	Positive number of points

Returns: 1 newly allocated cpl_bivector or NULL on error

The returned object must be deallocated using cpl_bivector_delete() or cpl_bivector_unwrap_vectors(), provided the two cpl_vectors are deallocated separately.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_ILLEGAL_INPUT if n is < 1.

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, cpl_malloc(), and cpl_vector_new().

Referenced by cpl_apertures_get_fwhm(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), and cpl_image_iqe().

◆ cpl_bivector_read()

cpl_bivector * cpl_bivector_read ( const char * filename )

Read a list of values from an ASCII file and create a cpl_bivector.

Parameters

filename Name of the input ASCII file

Returns: 1 newly allocated cpl_bivector or NULL on error

See also: cpl_vector_load

The input ASCII file must contain two values per line.

The returned object must be deallocated using cpl_bivector_delete() Two columns of numbers are expected in the input file.

In addition to normal files, FIFO (see man mknod) are also supported.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_FILE_IO if the file cannot be read
CPL_ERROR_BAD_FILE_FORMAT if the file contains no valid lines

References cpl_bivector_wrap_vectors(), cpl_ensure, CPL_ERROR_BAD_FILE_FORMAT, CPL_ERROR_FILE_IO, CPL_ERROR_NULL_INPUT, cpl_vector_delete(), cpl_vector_new(), cpl_vector_set(), and cpl_vector_set_size().

◆ cpl_bivector_sort()

cpl_error_code cpl_bivector_sort	(	cpl_bivector *	self,
		const cpl_bivector *	other,
		cpl_sort_direction	dir,
		cpl_sort_mode	mode
	)

Sort a cpl_bivector.

Parameters

self	cpl_bivector to hold sorted result
other	Input cpl_bivector to sort, may equal self
dir	CPL_SORT_ASCENDING or CPL_SORT_DESCENDING
mode	CPL_SORT_BY_X or CPL_SORT_BY_Y

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

The values in the input are sorted according to direction and mode, and the result is placed self which must be of the same size as other.

As for qsort(): If two members compare as equal, their order in the sorted array is undefined.

In place sorting is supported.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if self and other have different sizes
CPL_ERROR_ILLEGAL_INPUT if dir is neither CPL_SORT_DESCENDING nor CPL_SORT_ASCENDING.
CPL_ERROR_UNSUPPORTED_MODE if self and other are the same or point to the same underlying arrays, or if mode is neither CPL_SORT_BY_X nor CPL_SORT_BY_Y

References cpl_bivector_get_size(), cpl_bivector_get_x_data(), cpl_bivector_get_x_data_const(), cpl_bivector_get_y_data(), cpl_bivector_get_y_data_const(), cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_ERROR_UNSUPPORTED_MODE.

◆ cpl_bivector_unwrap_vectors()

void cpl_bivector_unwrap_vectors ( cpl_bivector * f )

Free memory associated to a cpl_bivector, excluding the two vectors.

Parameters

f	cpl_bivector to delete

Returns: void

See also: cpl_bivector_wrap_vectors

References cpl_free().

Referenced by cpl_plot_column(), and cpl_polynomial_fit().

◆ cpl_bivector_wrap_vectors()

cpl_bivector * cpl_bivector_wrap_vectors	(	cpl_vector *	x,
		cpl_vector *	y
	)

Create a new cpl_bivector from two cpl_vectors.

Parameters

x	the x cpl_vector
y	the y cpl_vector

Returns: 1 cpl_bivector or NULL on error

Note: The input cpl_vectors must have identical sizes. Afterwards one of those two vectors may be resized, which will corrupt the bivector. Such a corrupted bivector should not be used any more, but rather deallocated, using cpl_bivector_unwrap_vectors() or cpl_bivector_delete().

The returned object must be deallocated using cpl_bivector_delete() or with cpl_bivector_unwrap_vectors(), provided the two cpl_vectors are deallocated separately.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the input vectors have different sizes

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_vector_get_size().

Referenced by cpl_bivector_read(), cpl_plot_column(), cpl_polynomial_fit(), and cpl_ppm_match_positions().

Functions

Detailed Description

Function Documentation

◆ cpl_bivector_copy()

◆ cpl_bivector_delete()

◆ cpl_bivector_dump()

◆ cpl_bivector_duplicate()

◆ cpl_bivector_get_size()

◆ cpl_bivector_get_x()

◆ cpl_bivector_get_x_const()

◆ cpl_bivector_get_x_data()

◆ cpl_bivector_get_x_data_const()

◆ cpl_bivector_get_y()

◆ cpl_bivector_get_y_const()

◆ cpl_bivector_get_y_data()

◆ cpl_bivector_get_y_data_const()

◆ cpl_bivector_interpolate_linear()

◆ cpl_bivector_new()

◆ cpl_bivector_read()

◆ cpl_bivector_sort()

◆ cpl_bivector_unwrap_vectors()

◆ cpl_bivector_wrap_vectors()