Common Pipeline Library Reference Manual  5.3.1
Functions
Images lists basic routines

Functions

cpl_image * cpl_image_new_from_accepted (const cpl_imagelist *imlist)
 Create a contribution map from the bad pixel maps of the images.
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_add_image (cpl_imagelist *imlist, const cpl_image *img)
 Add an image to an image list.
cpl_error_code cpl_imagelist_add_scalar (cpl_imagelist *imlist, double addend)
 Elementwise addition of a scalar to each image in the imlist.
cpl_image * cpl_imagelist_collapse_create (const cpl_imagelist *imlist)
 Average an imagelist to a single image.
cpl_image * cpl_imagelist_collapse_median_create (const cpl_imagelist *imlist)
 Compute the median of an image list to a single image.
cpl_image * cpl_imagelist_collapse_minmax_create (const cpl_imagelist *self, int nlow, int nhigh)
 Average with rejection an imagelist to a single image.
cpl_image * cpl_imagelist_collapse_sigclip_create (const cpl_imagelist *imlist, double kappalow, double kappahigh, double keep, unsigned mode, cpl_image *kept)
 Collapse an imagelist with kappa-sigma-clipping rejection.
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_divide_image (cpl_imagelist *imlist, const cpl_image *img)
 Divide an image list by an image.
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_exponential (cpl_imagelist *imlist, double base)
 Compute the elementwise exponential of each image in the imlist.
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_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_multiply_image (cpl_imagelist *imlist, const cpl_image *img)
 Multiply an image list by an image.
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_normalise (cpl_imagelist *imlist, cpl_norm mode)
 Normalize each image in the list.
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_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_subtract_image (cpl_imagelist *imlist, const cpl_image *img)
 Subtract an image from an image list.
cpl_error_code cpl_imagelist_subtract_scalar (cpl_imagelist *imlist, double subtrahend)
 Elementwise subtraction of a scalar from each image in the imlist.
cpl_imagelist * cpl_imagelist_swap_axis_create (const cpl_imagelist *ilist, cpl_swap_axis mode)
 Swap the axis of an image 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.

Detailed Description

This module provides basic functions to handle cpl_imagelist.

Synopsis:
   #include "cpl_imagelist_basic.h"

Function Documentation

cpl_image* cpl_image_new_from_accepted ( const cpl_imagelist *  imlist)

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

Parameters:
imlistThe 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the input image list is not valid
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:
in1first input image list (modified)
in2image 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the input images have different sizes
cpl_error_code cpl_imagelist_add_image ( cpl_imagelist *  imlist,
const cpl_image *  img 
)

Add an image to an image list.

Parameters:
imlistinput image list (modified)
imgimage 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 (one of) the input pointer(s) is NULL
cpl_error_code cpl_imagelist_add_scalar ( cpl_imagelist *  imlist,
double  addend 
)

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

Parameters:
imlistImagelist to be modified in place.
addendNumber 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 (one of) the input pointer(s) is NULL
cpl_image* cpl_imagelist_collapse_create ( const cpl_imagelist *  imlist)

Average an imagelist to a single image.

Parameters:
imlistthe 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the input image list is not valid
cpl_image* cpl_imagelist_collapse_median_create ( const cpl_imagelist *  imlist)

Compute the median of an image list to a single image.

Parameters:
imlistthe input images list
Returns:
the median 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 input frames are not taken into account, and the one of the created image is empty.

The input image list 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the input image list is not valid
  • CPL_ERROR_INVALID_TYPE if the passed image list type is not supported
cpl_image* cpl_imagelist_collapse_minmax_create ( const cpl_imagelist *  self,
int  nlow,
int  nhigh 
)

Average with rejection an imagelist to a single image.

Parameters:
selfThe image list to average
nlowNumber of low rejected values
nhighNumber 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.

The bad pixel maps of the input frames are not taken into account, and the one of the created image is empty.

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
cpl_image* cpl_imagelist_collapse_sigclip_create ( const cpl_imagelist *  imlist,
double  kappalow,
double  kappahigh,
double  keep,
unsigned  mode,
cpl_image *  kept 
)

Collapse an imagelist with kappa-sigma-clipping rejection.

Parameters:
imlistthe input imagelist
kappalowkappa-factor for lower boundary level
kappahighkappa-factor for upper boundary level
keepminimum percentage of values to keep (0.0 < keep < 1.0)
modecollapsing mode
keptimage containing kept values per position
Returns:
the collapsed image or NULL on error case.

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

The bad pixel maps of the input frames are not taken into account, and the one of the created image is empty.

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.

For each pixel position the pixels whose value is higher than center + kappahigh * stdev or lower than center - kappalow * stdev are discarded for the average computation, where center is either mean or median depending on the mode, and stdev is the standard deviation of the pixels at that position.

The collapsing is an iterative process which will stop once either it reaches convergence or the percentage of rejected values reaches 1.0 - keep.

The input parameter kept is optional. It must be either NULL or point to an allocated image of type CPL_TYPE_INT and equal size of the images in the imagelist. It will contain in output the number of kept (non-rejected) values after the iterating collapse process in every pixel position.

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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the input imagelist is not valid, if any of kappalow and kappahigh is negative, if keep is not within the expected interval (0.0, 1.0), if kept is non-NULL but the pointed image is not of type CPL_TYPE_INT or of different size if there are less than 2 images in the list
  • CPL_ERROR_INVALID_TYPE if the passed imagelist type is not supported
  • CPL_ERROR_UNSUPPORTED_MODE if the passed mode is none of the listed above
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:
in1first input image list (modified)
in2image list to divide
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_divide()
cpl_imagelist_add()
cpl_error_code cpl_imagelist_divide_image ( cpl_imagelist *  imlist,
const cpl_image *  img 
)

Divide an image list by an image.

Parameters:
imlistinput image list (modified)
imgimage for division
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_divide()
cpl_imagelist_add_image()
cpl_error_code cpl_imagelist_divide_scalar ( cpl_imagelist *  imlist,
double  divisor 
)

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

Parameters:
imlistImagelist to be modified in place.
divisorNon-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 (one of) the input pointer(s) is NULL
cpl_error_code cpl_imagelist_exponential ( cpl_imagelist *  imlist,
double  base 
)

Compute the elementwise exponential of each image in the imlist.

Parameters:
imlistImagelist to be modified in place.
baseBase 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 (one of) the input pointer(s) is NULL
cpl_error_code cpl_imagelist_logarithm ( cpl_imagelist *  imlist,
double  base 
)

Compute the elementwise logarithm of each image in the imlist.

Parameters:
imlistImagelist to be modified in place.
baseBase 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 (one of) the input pointer(s) is NULL
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:
in1first input image list (modified)
in2image list to multiply
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_multiply()
cpl_imagelist_add()
cpl_error_code cpl_imagelist_multiply_image ( cpl_imagelist *  imlist,
const cpl_image *  img 
)

Multiply an image list by an image.

Parameters:
imlistinput image list (modified)
imgimage to multiply
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_multiply()
cpl_imagelist_add_image()
cpl_error_code cpl_imagelist_multiply_scalar ( cpl_imagelist *  imlist,
double  factor 
)

Elementwise multiplication of the imlist with a scalar.

Parameters:
imlistImagelist to be modified in place.
factorNumber to multiply with
Returns:
CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error
See also:
cpl_imagelist_add_scalar()
cpl_error_code cpl_imagelist_normalise ( cpl_imagelist *  imlist,
cpl_norm  mode 
)

Normalize each image in the list.

Parameters:
imlistImagelist to modify.
modeNormalization 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 (one of) the input pointer(s) is NULL
cpl_error_code cpl_imagelist_power ( cpl_imagelist *  imlist,
double  exponent 
)

Compute the elementwise power of each image in the imlist.

Parameters:
imlistImagelist to be modified in place.
exponentScalar 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 (one of) the input pointer(s) is NULL
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:
in1first input image list (modified)
in2image list to subtract
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_subtract()
cpl_imagelist_add()
cpl_error_code cpl_imagelist_subtract_image ( cpl_imagelist *  imlist,
const cpl_image *  img 
)

Subtract an image from an image list.

Parameters:
imlistinput image list (modified)
imgimage to subtract
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_subtract()
cpl_imagelist_add_image()
cpl_error_code cpl_imagelist_subtract_scalar ( cpl_imagelist *  imlist,
double  subtrahend 
)

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

Parameters:
imlistImagelist to be modified in place.
subtrahendNumber to subtract
Returns:
CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error
See also:
cpl_imagelist_add_scalar()
cpl_imagelist* cpl_imagelist_swap_axis_create ( const cpl_imagelist *  ilist,
cpl_swap_axis  mode 
)

Swap the axis of an image list.

Parameters:
ilistThe image list to swap
modeThe 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 (one of) the input pointer(s) 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
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:
imlistImage list to threshold.
lo_cutLower bound.
hi_cutHigher bound.
assign_lo_cutValue to assign to pixels below low bound.
assign_hi_cutValue 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_INCOMPATIBLE_INPUT if lo_cut is bigger than hi_cut