cpl_error_code	cpl_imagelist_add (cpl_imagelist in1, const cpl_imagelist in2)
	Add two image lists, the first one is replaced by the result.

cpl_error_code	cpl_imagelist_subtract (cpl_imagelist in1, const cpl_imagelist in2)
	Subtract two image lists, the first one is replaced by the result.

cpl_error_code	cpl_imagelist_multiply (cpl_imagelist in1, const cpl_imagelist in2)
	Multiply two image lists, the first one is replaced by the result.

cpl_error_code	cpl_imagelist_divide (cpl_imagelist in1, const cpl_imagelist in2)
	Divide two image lists, the first one is replaced by the result.

cpl_error_code	cpl_imagelist_add_image (cpl_imagelist imlist, const cpl_image img)
	Add an image to an image list.

cpl_error_code	cpl_imagelist_subtract_image (cpl_imagelist imlist, const cpl_image img)
	Subtract an image from an image list.

cpl_error_code	cpl_imagelist_multiply_image (cpl_imagelist imlist, const cpl_image img)
	Multiply an image list by an image.

cpl_error_code	cpl_imagelist_divide_image (cpl_imagelist imlist, const cpl_image img)
	Divide an image list by an image.

cpl_error_code	cpl_imagelist_add_scalar (cpl_imagelist *imlist, double addend)
	Elementwise addition of a scalar to each image in the imlist.

cpl_error_code	cpl_imagelist_subtract_scalar (cpl_imagelist *imlist, double subtrahend)
	Elementwise subtraction of a scalar from each image in the imlist.

cpl_error_code	cpl_imagelist_multiply_scalar (cpl_imagelist *imlist, double factor)
	Elementwise multiplication of the imlist with a scalar.

cpl_error_code	cpl_imagelist_divide_scalar (cpl_imagelist *imlist, double divisor)
	Elementwise division of each image in the imlist with a scalar.

cpl_error_code	cpl_imagelist_logarithm (cpl_imagelist *imlist, double base)
	Compute the elementwise logarithm of each image in the imlist.

cpl_error_code	cpl_imagelist_exponential (cpl_imagelist *imlist, double base)
	Compute the elementwise exponential of each image in the imlist.

cpl_error_code	cpl_imagelist_power (cpl_imagelist *imlist, double exponent)
	Compute the elementwise power of each image in the imlist.

cpl_error_code	cpl_imagelist_normalise (cpl_imagelist *imlist, cpl_norm mode)
	Normalize each image in the list.

cpl_error_code	cpl_imagelist_threshold (cpl_imagelist *imlist, double lo_cut, double hi_cut, double assign_lo_cut, double assign_hi_cut)
	Threshold all pixel values to an interval.

cpl_image *	cpl_image_new_from_accepted (const cpl_imagelist *imlist)
	Create a contribution map from the bad pixel maps of the images.

cpl_image *	cpl_imagelist_collapse_create (const cpl_imagelist *imlist)
	Average an imagelist to a single image.

cpl_image *	cpl_imagelist_collapse_minmax_create (const cpl_imagelist *self, cpl_size nlow, cpl_size nhigh)
	Average with rejection an imagelist to a single image.

cpl_image *	cpl_imagelist_collapse_sigclip_create (const cpl_imagelist self, double kappalow, double kappahigh, double keepfrac, cpl_collapse_mode mode, cpl_image contrib)
	Collapse an imagelist with kappa-sigma-clipping rejection.

cpl_image *	cpl_imagelist_collapse_median_create (const cpl_imagelist *self)
	Create a median image from the input imagelist.

cpl_imagelist *	cpl_imagelist_swap_axis_create (const cpl_imagelist *ilist, cpl_swap_axis mode)
	Swap the axis of an image list.

cpl_imagelist *	cpl_imagelist_new (void)
	Create an empty imagelist.

cpl_imagelist *	cpl_imagelist_load (const char *filename, cpl_type im_type, cpl_size xtnum)
	Load a FITS file extension into a list of images.

cpl_imagelist *	cpl_imagelist_load_window (const char *filename, cpl_type im_type, cpl_size xtnum, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
	Load images windows from a FITS file extension into an image list.

cpl_size	cpl_imagelist_get_size (const cpl_imagelist *imlist)
	Get the number of images in the imagelist.

cpl_image *	cpl_imagelist_get (cpl_imagelist *imlist, cpl_size inum)
	Get an image from a list of images.

const cpl_image *	cpl_imagelist_get_const (const cpl_imagelist *imlist, cpl_size inum)
	Get an image from a list of images.

cpl_error_code	cpl_imagelist_set (cpl_imagelist self, cpl_image im, cpl_size pos)
	Insert an image into an imagelist.

cpl_image *	cpl_imagelist_unset (cpl_imagelist *self, cpl_size pos)
	Remove an image from an imagelist.

void	cpl_imagelist_empty (cpl_imagelist *self)
	Empty an imagelist and deallocate all its images.

void	cpl_imagelist_unwrap (cpl_imagelist *self)
	Free memory used by a cpl_imagelist object, except the images.

void	cpl_imagelist_delete (cpl_imagelist *self)
	Free all memory used by a cpl_imagelist object including the images.

cpl_error_code	cpl_imagelist_cast (cpl_imagelist self, const cpl_imagelist other, cpl_type type)
	Cast an imagelist, optionally in-place.

cpl_imagelist *	cpl_imagelist_duplicate (const cpl_imagelist *imlist)
	Copy an image list.

cpl_error_code	cpl_imagelist_erase (cpl_imagelist imlist, const cpl_vector valid)
	Reject one or more images in a list according to an array of flags.

cpl_error_code	cpl_imagelist_save (const cpl_imagelist self, const char filename, cpl_type type, const cpl_propertylist *plist, unsigned mode)
	Save an imagelist to disk in FITS format.

int	cpl_imagelist_is_uniform (const cpl_imagelist *imlist)
	Determine if an imagelist contains images of equal size and type.

cpl_error_code	cpl_imagelist_dump_structure (const cpl_imagelist self, FILE stream)
	Dump structural information of images in an imagelist.

cpl_error_code	cpl_imagelist_dump_window (const cpl_imagelist self, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, FILE stream)
	Dump pixel values of images in a CPL imagelist.

Detailed Description

This module provides functions to create, use, and destroy a cpl_imagelist. A cpl_imagelist is an ordered list of cpl_images. All images in a list must have the same pixel-type and the same dimensions. It is allowed to insert the same image into different positions in the list. Different images in the list are allowed to share the same bad pixel map.

Synopsis:: #include "cpl_imagelist.h"

Function Documentation

◆ cpl_image_new_from_accepted()

cpl_image * cpl_image_new_from_accepted ( const cpl_imagelist * imlist )

Create a contribution map from the bad pixel maps of the images.

Parameters

imlist The imagelist

Returns: The contributions map (a CPL_TYPE_INT cpl_image) or NULL on error

See also: cpl_imagelist_is_uniform()

The returned map counts for each pixel the number of good pixels in the list. The returned map has to be deallocated with cpl_image_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 image list is not valid

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_image_add_scalar(), cpl_image_get_bpm_const(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_new(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), and CPL_TYPE_INT.

Referenced by cpl_imagelist_collapse_create().

◆ cpl_imagelist_add()

cpl_error_code cpl_imagelist_add	(	cpl_imagelist *	in1,
		const cpl_imagelist *	in2
	)

Add two image lists, the first one is replaced by the result.

Parameters

in1	first input image list (modified)
in2	image list to add

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_add()

The two input lists must have the same size, the image number n in the list in2 is added to the image number n in the list in1.

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 images have different sizes

◆ cpl_imagelist_add_image()

cpl_error_code cpl_imagelist_add_image	(	cpl_imagelist *	imlist,
		const cpl_image *	img
	)

Add an image to an image list.

Parameters

imlist	input image list (modified)
img	image to add

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_add()

The passed image is added to each image of the passed image list.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

◆ cpl_imagelist_add_scalar()

cpl_error_code cpl_imagelist_add_scalar	(	cpl_imagelist *	imlist,
		double	addend
	)

Elementwise addition of a scalar to each image in the imlist.

Parameters

imlist	Imagelist to be modified in place.
addend	Number to add

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_add_scalar()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_add_scalar().

◆ cpl_imagelist_cast()

cpl_error_code cpl_imagelist_cast	(	cpl_imagelist *	self,
		const cpl_imagelist *	other,
		cpl_type	type
	)

Cast an imagelist, optionally in-place.

Parameters

self	Destination imagelist
other	Source imagelist, or NULL to cast in-place
type	If called with empty self, cast to this pixel-type

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_cast()

Note: If called with a non-empty self in an out-of-place cast, the input images are cast to the type already present in self and appended to the output list. In this case the parameter type is ignored.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if the destination pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the same pointer is passed twice
CPL_ERROR_ILLEGAL_INPUT if the passed type is invalid
CPL_ERROR_TYPE_MISMATCH if the passed image type is complex and requested casting type is non-complex.
CPL_ERROR_INVALID_TYPE if the passed pixel type is not supported

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), cpl_image_cast(), cpl_image_delete(), cpl_image_get_bpm_const(), cpl_image_get_type(), cpl_image_unset_bpm(), cpl_imagelist_delete(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_new(), cpl_imagelist_set(), cpl_imagelist_unset(), and cpl_malloc().

◆ cpl_imagelist_collapse_create()

cpl_image * cpl_imagelist_collapse_create ( const cpl_imagelist * imlist )

Average an imagelist to a single image.

Parameters

imlist the input images list

Returns: the average image or NULL on error case.

See also: cpl_imagelist_is_uniform()

The returned image has to be deallocated with cpl_image_delete().

The bad pixel maps of the images in the input list are taken into account, the result image pixels are flagged as rejected for those where there were no good pixel at the same position in the input image list.

For integer pixel types, the averaging is performed using integer division.

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 image list is not valid

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_image_accept_all(), cpl_image_add(), cpl_image_delete(), cpl_image_divide(), cpl_image_duplicate(), cpl_image_fill_rejected(), cpl_image_get_bpm_const(), cpl_image_new_from_accepted(), and cpl_imagelist_is_uniform().

◆ cpl_imagelist_collapse_median_create()

cpl_image * cpl_imagelist_collapse_median_create ( const cpl_imagelist * self )

Create a median image from the input imagelist.

Parameters

self	The input image list

Returns: The median image of the input pixel type or NULL on error

Note: The created image has to be deallocated with cpl_image_delete()

The input image list can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE.

On success each pixel in the created image is the median of the values on the same pixel position in the input image list. If for a given pixel all values in the input image list are rejected, the resulting pixel is set to zero and flagged as rejected.

The median is defined here as the middle value of an odd number of sorted samples and for an even number of samples as the mean of the two central values. Note that with an even number of samples the median may not be among the input samples.

Also, note that in the case of an even number of integer data, the mean value will be computed using integer arithmetic. Cast your integer data to a floating point pixel type if that is not the desired behavior.

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 image list is not valid
CPL_ERROR_INVALID_TYPE if the passed image list pixel type is not supported

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_imagelist_get_const(), and cpl_imagelist_is_uniform().

◆ cpl_imagelist_collapse_minmax_create()

cpl_image * cpl_imagelist_collapse_minmax_create	(	const cpl_imagelist *	self,
		cpl_size	nlow,
		cpl_size	nhigh
	)

Average with rejection an imagelist to a single image.

Parameters

self	The image list to average
nlow	Number of low rejected values
nhigh	Number of high rejected values

Returns: The average image or NULL on error

Note: The returned image has to be deallocated with cpl_image_delete().

The input images are averaged, for each pixel position the nlow lowest pixels and the nhigh highest pixels are discarded for the average computation.

The input image list can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE. The created image will be of the same type.

On success each pixel in the created image is the average of the non-rejected values on the pixel position in the input image list.

For a given pixel position any bad pixels (i.e. values) are handled as follows: Given n bad values on a given pixel position, n/2 of those values are assumed to be low outliers and n/2 of those values are assumed to be high outliers. Any low or high rejection will first reject up to n/2 bad values and if more values need to be rejected that rejection will take place on the good values. This rationale behind this is to allow the rejection of outliers to include bad pixels without introducing a bias. If for a given pixel all values in the input image list are rejected, the resulting pixel is set to zero and flagged as rejected.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an the input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the input image list is not valid or if the sum of the rejections is not lower than the number of images or if nlow or nhigh is negative
CPL_ERROR_INVALID_TYPE if the passed image list type is not supported

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), and cpl_imagelist_is_uniform().

◆ cpl_imagelist_collapse_sigclip_create()

cpl_image * cpl_imagelist_collapse_sigclip_create	(	const cpl_imagelist *	self,
		double	kappalow,
		double	kappahigh,
		double	keepfrac,
		cpl_collapse_mode	mode,
		cpl_image *	contrib
	)

Collapse an imagelist with kappa-sigma-clipping rejection.

Parameters

self	The input imagelist
kappalow	kappa-factor for lower clipping threshold
kappahigh	kappa-factor for upper clipping threshold
keepfrac	The fraction of values to keep (0.0 < keepfrac <= 1.0)
mode	Clipping mode, CPL_COLLAPSE_MEAN or CPL_COLLAPSE_MEDIAN
contrib	Pre-allocated integer-image for contribution map or NULL

Returns: The collapsed image or NULL on error case.

Note: The returned image has to be deallocated with cpl_image_delete().

The collapsing is an iterative process which will stop when it converges (i.e. an iteration did not reject any values for a given pixel) or when the next iteration would reduce the fraction of values to keep to less than or equal to keepfrac.

A call with keepfrac == 1.0 will thus perform no clipping.

Supported modes: CPL_COLLAPSE_MEAN: The center value of the acceptance range will be the mean. CPL_COLLAPSE_MEDIAN: The center value of the acceptance range will be the median. CPL_COLLAPSE_MEDIAN_MEAN: The center value of the acceptance range will be the median in the first iteration and in subsequent iterations it will be the mean.

For each pixel position the pixels whose value is higher than center + kappahigh * stdev or lower than center - kappalow * stdev are discarded for the subsequent center and stdev computation, where center is defined according to the clipping mode, and stdev is the standard deviation of the values at that pixel position. Since the acceptance interval must be non-empty, the sum of kappalow and kappahigh must be positive. A typical call has both kappalow and kappahigh positive.

The minimum number of values that the clipping can select is 2. This is because the clipping criterion is based on the sample standard deviation, which needs at least two values to be defined. This means that all calls with (positive) values of keepfrac less than 2/n will behave the same. To ensure that the values in (at least) i planes out of n are kept, keepfrac can be set to (i - 0.5) / n, e.g. to keep at least 50 out of 100 values, keepfrac can be set to 0.495.

The output pixel is set to the mean of the non-clipped values, also in the median mode. Regardless of the input pixel type, the mean is computed in double precision. The result is then cast to the output-pixel type, which is identical to the input pixel type.

The input parameter contrib is optional. It must be either NULL or point to a pre-allocated image of type CPL_TYPE_INT and size equal to the images in the imagelist. On success, it will contain the contribution map, i.e. the number of kept (non-clipped) values after the iterative process on every pixel.

Bad pixels are ignored from the start. This means that with a sufficient number of bad pixels, the fraction of good values will be less than keepfrac. In this case no iteration is performed at all. If there is at least one good value available, then the mean will be based on the good value(s). If for a given pixel position there are no good values, then that pixel is set to zero, rejected as bad and if available the value in the contribution map is set to zero.

The input imagelist can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_DATA_NOT_FOUND if there are less than 2 images in the list
CPL_ERROR_ILLEGAL_INPUT if the sum of kappalow and kappahigh is non-positive,
CPL_ERROR_ACCESS_OUT_OF_RANGE if keepfrac is outside the required interval which is 0.0 < keepfrac <= 1.0
CPL_ERROR_TYPE_MISMATCH if contrib is non-NULL but not of type CPL_TYPE_INT
CPL_ERROR_INCOMPATIBLE_INPUT if contrib is non-NULL but of a size incompatible with the input imagelist
CPL_ERROR_INVALID_TYPE if the type of the input imagelist is unsupported
CPL_ERROR_UNSUPPORTED_MODE if the passed mode is none of the above listed

References cpl_ensure, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, cpl_image_get_data_int(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), and CPL_TYPE_INT.

◆ cpl_imagelist_delete()

void cpl_imagelist_delete ( cpl_imagelist * self )

Free all memory used by a cpl_imagelist object including the images.

Parameters

self	The image list or NULL

Returns: Nothing

See also: cpl_imagelist_empty(), cpl_imagelist_unwrap()

References cpl_imagelist_empty(), and cpl_imagelist_unwrap().

Referenced by cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_combine(), cpl_imagelist_cast(), and cpl_imagelist_load_frameset().

◆ cpl_imagelist_divide()

cpl_error_code cpl_imagelist_divide	(	cpl_imagelist *	in1,
		const cpl_imagelist *	in2
	)

Divide two image lists, the first one is replaced by the result.

Parameters

in1	first input image list (modified)
in2	image list to divide

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_divide(); cpl_imagelist_add()

◆ cpl_imagelist_divide_image()

cpl_error_code cpl_imagelist_divide_image	(	cpl_imagelist *	imlist,
		const cpl_image *	img
	)

Divide an image list by an image.

Parameters

imlist	input image list (modified)
img	image for division

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_divide(); cpl_imagelist_add_image()

◆ cpl_imagelist_divide_scalar()

cpl_error_code cpl_imagelist_divide_scalar	(	cpl_imagelist *	imlist,
		double	divisor
	)

Elementwise division of each image in the imlist with a scalar.

Parameters

imlist	Imagelist to be modified in place.
divisor	Non-zero number to divide with

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_imagelist_add_scalar()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_divide_scalar().

◆ cpl_imagelist_dump_structure()

cpl_error_code cpl_imagelist_dump_structure	(	const cpl_imagelist *	self,
		FILE *	stream
	)

Dump structural information of images in an imagelist.

Parameters

self	Imagelist to dump
stream	Output stream, accepts `stdout` or `stderr`

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_FILE_IO if a write operation fails

References cpl_ensure_code, CPL_ERROR_FILE_IO, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_image_dump_structure(), and cpl_imagelist_get_const().

◆ cpl_imagelist_dump_window()

cpl_error_code cpl_imagelist_dump_window	(	const cpl_imagelist *	self,
		cpl_size	llx,
		cpl_size	lly,
		cpl_size	urx,
		cpl_size	ury,
		FILE *	stream
	)

Dump pixel values of images in a CPL imagelist.

Parameters

self	Imagelist to dump
llx	Specifies the window position
lly	Specifies the window position
urx	Specifies the window position
ury	Specifies the window position
stream	Output stream, accepts `stdout` or `stderr`

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_FILE_IO if a write operation fails
CPL_ERROR_ACCESS_OUT_OF_RANGE if the defined window is not in the image
CPL_ERROR_ILLEGAL_INPUT if the window definition is wrong (e.g llx > urx)

References cpl_ensure_code, CPL_ERROR_FILE_IO, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_image_dump_window(), and cpl_imagelist_get_const().

◆ cpl_imagelist_duplicate()

cpl_imagelist * cpl_imagelist_duplicate ( const cpl_imagelist * imlist )

Copy an image list.

Parameters

imlist Source image list.

Returns: 1 newly allocated image list, or NULL on error.

Copy an image list into a new image list object. The returned image list must be deallocated using cpl_imagelist_delete().

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, cpl_image_duplicate(), cpl_imagelist_new(), and cpl_imagelist_set().

◆ cpl_imagelist_empty()

void cpl_imagelist_empty ( cpl_imagelist * self )

Empty an imagelist and deallocate all its images.

Parameters

self	The image list or NULL

Returns: Nothing

See also: cpl_imagelist_empty(), cpl_imagelist_delete()

Note: If self is NULL nothing is done and no error is set.

After the call the image list can be populated again. It must eventually be deallocted with a call to cpl_imagelist_delete().

References cpl_image_delete(), cpl_image_get_bpm_const(), cpl_image_unset_bpm(), and cpl_imagelist_unset().

Referenced by cpl_imagelist_delete().

◆ cpl_imagelist_erase()

cpl_error_code cpl_imagelist_erase	(	cpl_imagelist *	imlist,
		const cpl_vector *	valid
	)

Reject one or more images in a list according to an array of flags.

Parameters

imlist	Non-empty imagelist to examine for image rejection.
valid	Vector of flags (>=-0.5: valid, <-0.5: invalid)

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

This function takes an imagelist and a vector of flags. The imagelist and vector must have equal lengths.

Images flagged as invalid are removed from the list.

The removal of image(s) will reduce the length of the list accordingly.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the vector size and the image list size are different

References cpl_ensure_code, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_image_delete(), cpl_image_get_bpm_const(), cpl_image_unset_bpm(), cpl_vector_get(), and cpl_vector_get_size().

◆ cpl_imagelist_exponential()

cpl_error_code cpl_imagelist_exponential	(	cpl_imagelist *	imlist,
		double	base
	)

Compute the elementwise exponential of each image in the imlist.

Parameters

imlist	Imagelist to be modified in place.
base	Base of the exponential.

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_exponential()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_exponential().

◆ cpl_imagelist_get()

cpl_image * cpl_imagelist_get	(	cpl_imagelist *	imlist,
		cpl_size	inum
	)

Get an image from a list of images.

Parameters

imlist	the image list
inum	the image id (from 0 to number of images-1)

Returns: A pointer to the image or NULL in error case.

The returned pointer refers to already allocated data.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if inum is bigger thant the list size
CPL_ERROR_ILLEGAL_INPUT if inum is negative

References cpl_ensure, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fft_imagelist(), and cpl_imagelist_swap_axis_create().

◆ cpl_imagelist_get_const()

const cpl_image * cpl_imagelist_get_const	(	const cpl_imagelist *	imlist,
		cpl_size	inum
	)

Get an image from a list of images.

Parameters

imlist	the image list
inum	the image id (from 0 to number of images-1)

Returns: A pointer to the image or NULL in error case.

See also: cpl_imagelist_get

References cpl_ensure, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fft_imagelist(), cpl_fit_imagelist_polynomial(), cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_image_new_from_accepted(), cpl_imagelist_cast(), cpl_imagelist_collapse_median_create(), cpl_imagelist_collapse_minmax_create(), cpl_imagelist_collapse_sigclip_create(), cpl_imagelist_dump_structure(), cpl_imagelist_dump_window(), cpl_imagelist_swap_axis_create(), and cpl_test_get_bytes_imagelist().

◆ cpl_imagelist_get_size()

cpl_size cpl_imagelist_get_size ( const cpl_imagelist * imlist )

Get the number of images in the imagelist.

Parameters

imlist the list of image

Returns: The number of images or -1 on error

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_fft_imagelist(), cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_image_new_from_accepted(), cpl_imagelist_cast(), cpl_imagelist_collapse_minmax_create(), cpl_imagelist_collapse_sigclip_create(), cpl_imagelist_load_frameset(), cpl_imagelist_swap_axis_create(), and cpl_test_get_bytes_imagelist().

◆ cpl_imagelist_is_uniform()

int cpl_imagelist_is_uniform ( const cpl_imagelist * imlist )

Determine if an imagelist contains images of equal size and type.

Parameters

imlist The imagelist to check

Returns: Zero if uniform, positive if non-uniform and negative on error.

The function returns 1 if the list is empty.

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, cpl_image_get_size_x(), cpl_image_get_size_y(), and cpl_image_get_type().

Referenced by cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_image_new_from_accepted(), cpl_imagelist_collapse_create(), cpl_imagelist_collapse_median_create(), cpl_imagelist_collapse_minmax_create(), cpl_imagelist_collapse_sigclip_create(), cpl_imagelist_save(), and cpl_imagelist_swap_axis_create().

◆ cpl_imagelist_load()

cpl_imagelist * cpl_imagelist_load	(	const char *	filename,
		cpl_type	im_type,
		cpl_size	xtnum
	)

Load a FITS file extension into a list of images.

Parameters

filename	The FITS file name
im_type	Type of the images in the created image list
xtnum	The extension number (0 for primary HDU)

Returns: The loaded list of images or NULL on error.

See also: cpl_image_load()

This function loads all the images of a specified extension (NAXIS=2 or 3) into an image list.

Type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_UNSPECIFIED. The loaded images have an empty bad pixel map.

The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if xtnum is negative
CPL_ERROR_FILE_IO if the file cannot be opened or does not exist
CPL_ERROR_DATA_NOT_FOUND if the specified extension has no image data
CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file including attempting to read beyond EOF
CPL_ERROR_INVALID_TYPE if the requested type is not supported

◆ cpl_imagelist_load_window()

cpl_imagelist * cpl_imagelist_load_window	(	const char *	filename,
		cpl_type	im_type,
		cpl_size	xtnum,
		cpl_size	llx,
		cpl_size	lly,
		cpl_size	urx,
		cpl_size	ury
	)

Load images windows from a FITS file extension into an image list.

Parameters

filename	The FITS file name
im_type	Type of the images in the created image list
xtnum	The extension number (0 for primary HDU)
llx	Lower left x position (FITS convention, 1 for leftmost)
lly	Lower left y position (FITS convention, 1 for lowest)
urx	Upper right x position (FITS convention)
ury	Upper right y position (FITS convention)

Returns: The loaded list of image windows or NULL on error.

See also: cpl_imagelist_load(), cpl_image_load_window()

Note: The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

This function loads all the image windows of a specified extension in an image list.

Type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT or CPL_TYPE_INT.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the passed extension number is negative or the window position is invalid
CPL_ERROR_FILE_IO if the file cannot be opened or does not exist
CPL_ERROR_DATA_NOT_FOUND if the specified extension has no image data
CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file including attempting to read beyond EOF
CPL_ERROR_INVALID_TYPE if the requested pixel type is not supported

◆ cpl_imagelist_logarithm()

cpl_error_code cpl_imagelist_logarithm	(	cpl_imagelist *	imlist,
		double	base
	)

Compute the elementwise logarithm of each image in the imlist.

Parameters

imlist	Imagelist to be modified in place.
base	Base of the logarithm.

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_logarithm()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_logarithm().

◆ cpl_imagelist_multiply()

cpl_error_code cpl_imagelist_multiply	(	cpl_imagelist *	in1,
		const cpl_imagelist *	in2
	)

Multiply two image lists, the first one is replaced by the result.

Parameters

in1	first input image list (modified)
in2	image list to multiply

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_multiply(); cpl_imagelist_add()

◆ cpl_imagelist_multiply_image()

cpl_error_code cpl_imagelist_multiply_image	(	cpl_imagelist *	imlist,
		const cpl_image *	img
	)

Multiply an image list by an image.

Parameters

imlist	input image list (modified)
img	image to multiply

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_multiply(); cpl_imagelist_add_image()

◆ cpl_imagelist_multiply_scalar()

cpl_error_code cpl_imagelist_multiply_scalar	(	cpl_imagelist *	imlist,
		double	factor
	)

Elementwise multiplication of the imlist with a scalar.

Parameters

imlist	Imagelist to be modified in place.
factor	Number to multiply with

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_imagelist_add_scalar()

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_multiply_scalar().

◆ cpl_imagelist_new()

cpl_imagelist * cpl_imagelist_new ( void )

Create an empty imagelist.

Returns: 1 newly allocated cpl_imagelist

See also: cpl_imagelist_set()

The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

References cpl_calloc().

Referenced by cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_combine(), cpl_imagelist_cast(), cpl_imagelist_duplicate(), cpl_imagelist_load_frameset(), and cpl_imagelist_swap_axis_create().

◆ cpl_imagelist_normalise()

cpl_error_code cpl_imagelist_normalise	(	cpl_imagelist *	imlist,
		cpl_norm	mode
	)

Normalize each image in the list.

Parameters

imlist	Imagelist to modify.
mode	Normalization mode.

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_normalise()

The list may be partly modified if an error occurs.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_normalise().

◆ cpl_imagelist_power()

cpl_error_code cpl_imagelist_power	(	cpl_imagelist *	imlist,
		double	exponent
	)

Compute the elementwise power of each image in the imlist.

Parameters

imlist	Imagelist to be modified in place.
exponent	Scalar exponent

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_power()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_power().

◆ cpl_imagelist_save()

cpl_error_code cpl_imagelist_save	(	const cpl_imagelist *	self,
		const char *	filename,
		cpl_type	type,
		const cpl_propertylist *	plist,
		unsigned	mode
	)

Save an imagelist to disk in FITS format.

Parameters

self	Imagelist to save
filename	Name of the FITS file to write
type	The type used to represent the data in the file
plist	Property list for the output header or NULL
mode	The desired output options (combined with bitwise or)

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_save()

This function saves an image list to a FITS file. If a property list is provided, it is written to the named file before the pixels are written.

Supported image lists types are CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT.

The type used in the file can be one of: CPL_TYPE_UCHAR (8 bit unsigned), CPL_TYPE_SHORT (16 bit signed), CPL_TYPE_USHORT (16 bit unsigned), CPL_TYPE_INT (32 bit signed), CPL_TYPE_FLOAT (32 bit floating point), or CPL_TYPE_DOUBLE (64 bit floating point). Additionally, the special value CPL_TYPE_UNSPECIFIED is allowed. This value means that the type used for saving is the pixel type of the input image. Using the image pixel type as saving type ensures that the saving incurs no loss of information.

Supported output modes are CPL_IO_CREATE (create a new file), CPL_IO_EXTEND (extend an existing file with a new extension) and CPL_IO_APPEND (append a list of images to the last data unit, which must already contain compatible image(s)).

For the CPL_IO_APPEND mode it is recommended to pass a NULL pointer for the output header, since updating the already existing header incurs significant overhead.

When the data written to disk are of an integer type, the output mode CPL_IO_EXTEND can be combined (via bit-wise or) with an option for tile-compression. This compression of integer data is lossless. The options are: CPL_IO_COMPRESS_GZIP, CPL_IO_COMPRESS_RICE, CPL_IO_COMPRESS_HCOMPRESS, CPL_IO_COMPRESS_PLIO. With compression the type must be CPL_TYPE_UNSPECIFIED or CPL_TYPE_INT.

In extend and append mode, make sure that the file has write permissions. You may have problems if you create a file in your application and append something to it with the umask set to 222. In this case, the file created by your application would not be writable, and the append would fail.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the type or the mode is not supported
CPL_ERROR_FILE_IO if the file cannot be written
CPL_ERROR_INVALID_TYPE if the passed image list type is not supported

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_imagelist_is_uniform().

◆ cpl_imagelist_set()

cpl_error_code cpl_imagelist_set	(	cpl_imagelist *	self,
		cpl_image *	im,
		cpl_size	pos
	)

Insert an image into an imagelist.

Parameters

self	The imagelist
im	The image to insert
pos	The list position (from 0 to number of images)

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

It is allowed to specify the position equal to the number of images in the list. This will increment the size of the imagelist.

No action occurs if an image is inserted more than once into the same position. It is allowed to insert the same image into two different positions in a list.

The image is inserted at the position pos in the image list. If the image already there is only present in that one location in the list, then the image is deallocated.

It is not allowed to insert images of different size into a list.

The added image is owned by the imagelist object, which deallocates it when cpl_imagelist_delete is called. Another option is to use cpl_imagelist_unset to recover ownership of the image, in which case the cpl_imagelist object is not longer responsible for deallocating it.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if pos is negative
CPL_ERROR_TYPE_MISMATCH if im and self are of different types
CPL_ERROR_INCOMPATIBLE_INPUT if im and self have different sizes
CPL_ERROR_ACCESS_OUT_OF_RANGE if pos is bigger than the number of images in self

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_TYPE_MISMATCH, cpl_image_delete(), cpl_image_get_bpm_const(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_image_unset_bpm(), and cpl_realloc().

Referenced by cpl_fit_imagelist_polynomial_window(), cpl_geom_img_offset_combine(), cpl_imagelist_cast(), cpl_imagelist_duplicate(), and cpl_imagelist_load_frameset().

◆ cpl_imagelist_subtract()

cpl_error_code cpl_imagelist_subtract	(	cpl_imagelist *	in1,
		const cpl_imagelist *	in2
	)

Subtract two image lists, the first one is replaced by the result.

Parameters

in1	first input image list (modified)
in2	image list to subtract

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_subtract(); cpl_imagelist_add()

◆ cpl_imagelist_subtract_image()

cpl_error_code cpl_imagelist_subtract_image	(	cpl_imagelist *	imlist,
		const cpl_image *	img
	)

Subtract an image from an image list.

Parameters

imlist	input image list (modified)
img	image to subtract

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_subtract(); cpl_imagelist_add_image()

◆ cpl_imagelist_subtract_scalar()

cpl_error_code cpl_imagelist_subtract_scalar	(	cpl_imagelist *	imlist,
		double	subtrahend
	)

Elementwise subtraction of a scalar from each image in the imlist.

Parameters

imlist	Imagelist to be modified in place.
subtrahend	Number to subtract

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_imagelist_add_scalar()

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_subtract_scalar().

◆ cpl_imagelist_swap_axis_create()

cpl_imagelist * cpl_imagelist_swap_axis_create	(	const cpl_imagelist *	ilist,
		cpl_swap_axis	mode
	)

Swap the axis of an image list.

Parameters

ilist	The image list to swap
mode	The swapping mode

Returns: The swapped image list or NULL in error case

This function is intended for users that want to use the cpl_imagelist object as a cube. Swapping the axis would give them access to the usual functions in the 3 dimensions. This has the cost that it duplicates the memory consumption, which can be a problem for big amounts of data.

Image list can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE. The mode can be either CPL_SWAP_AXIS_XZ or CPL_SWAP_AXIS_YZ

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if mode is not equal to one of the possible values or if the image list is not valid
CPL_ERROR_INVALID_TYPE if the passed image list type is not supported

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_image_reject_from_mask(), cpl_imagelist_get(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), cpl_imagelist_new(), cpl_mask_delete(), cpl_mask_get_data(), and cpl_mask_new().

◆ cpl_imagelist_threshold()

cpl_error_code cpl_imagelist_threshold	(	cpl_imagelist *	imlist,
		double	lo_cut,
		double	hi_cut,
		double	assign_lo_cut,
		double	assign_hi_cut
	)

Threshold all pixel values to an interval.

Parameters

imlist	Image list to threshold.
lo_cut	Lower bound.
hi_cut	Higher bound.
assign_lo_cut	Value to assign to pixels below low bound.
assign_hi_cut	Value to assign to pixels above high bound.

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_threshold()

Threshold the images of the list using cpl_image_threshold() The input image list is modified.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if lo_cut is bigger than hi_cut

References cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_image_threshold().

◆ cpl_imagelist_unset()

cpl_image * cpl_imagelist_unset	(	cpl_imagelist *	self,
		cpl_size	pos
	)

Remove an image from an imagelist.

Parameters

self	The imagelist
pos	The list position (from 0 to number of images-1)

Returns: The pointer to the removed image or NULL in error case

The specified image is not deallocated, it is simply removed from the list. The pointer to the image is returned to let the user decide to deallocate it or not. Eventually, the image will have to be deallocated with cpl_image_delete().

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if pos is negative
CPL_ERROR_ACCESS_OUT_OF_RANGE if pos is bigger than the number of images in self

References cpl_ensure, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_geom_img_offset_combine(), cpl_imagelist_cast(), and cpl_imagelist_empty().

◆ cpl_imagelist_unwrap()

void cpl_imagelist_unwrap ( cpl_imagelist * self )

Free memory used by a cpl_imagelist object, except the images.

Parameters

self	The image list or NULL

Returns: Nothing

See also: cpl_imagelist_empty()

Note: The caller must have pointers to all images in the list and is reponsible for their deallocation. If self is NULL nothing is done and no error is set.

References cpl_free().

Referenced by cpl_geom_img_offset_saa(), and cpl_imagelist_delete().