MUSE Pipeline Reference Manual  2.1.1
Functions
Combination of images

Functions

muse_imagemuse_combine_sum_create (muse_imagelist *aImages)
 Sum a list of input images. More...
 
muse_imagemuse_combine_average_create (muse_imagelist *aImages)
 Average a list of input images. More...
 
muse_imagemuse_combine_median_create (muse_imagelist *aImages)
 Median combine a list of input images. More...
 
muse_imagemuse_combine_minmax_create (muse_imagelist *aImages, int aMin, int aMax, int aKeep)
 Average a list of input images with minmax rejection. More...
 
muse_imagemuse_combine_sigclip_create (muse_imagelist *aImages, double aLow, double aHigh)
 Average a list of input images with sigma clipping rejection. More...
 
muse_combinepar * muse_combinepar_new (cpl_parameterlist *aParameters, const char *aPrefix)
 Create a new set of combination parameters. More...
 
void muse_combinepar_delete (muse_combinepar *aCPars)
 Clear the combination parameters. More...
 
muse_imagemuse_combine_images (muse_combinepar *aCPars, muse_imagelist *aImages)
 Combine several images into one. More...
 

Detailed Description

This contains functions to do image combination with and without rejection for muse_images. These functions all take a muse_imagelist * argument to take into account all three extensions of all input images.

All these functions propagate variance and bad pixel information but they do not use the variance to create an optimally weighted output image.

Function Documentation

muse_image* muse_combine_average_create ( muse_imagelist aImages)

Average a list of input images.

Parameters
aImagesthe list of images to average
Returns
a newly allocated muse_image* or NULL in case of failure
Remarks
This is similar to the function cpl_imagelist_collapse_create() available in the CPL library, but takes into account all three image elements of muse_images (data, data quality, and variance).

Loop through all pixels in the two image dimensions and compute the average for each pixel from the corresponding pixels in each input frame. Handle the bad pixel map and propagate the error using the Gaussian error propagation. The output contains only an empty header.

Quality Assessment:
Testing with a defined set of test images for which the input and output pixel values at a few positions are pre-computed.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input list of data images is NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLAn image component in the input list is missing
return NULLcannot create the output image

Definition at line 234 of file muse_combine.c.

References muse_imagelist_get_size().

Referenced by muse_combine_images().

muse_image* muse_combine_images ( muse_combinepar *  aCPars,
muse_imagelist aImages 
)

Combine several images into one.

Parameters
aCParsstructure of combination parameters
aImagesthe input MUSE imagelist
Returns
the combined image as a muse_image * or NULL on error

Combine several images into one, specified by the method in cpars. Note that it changes the input images if the "scale" option is used. The output contains a header that was duplicated from the first input image, excluding FITS headers contained in MUSE_HDR_TMP_REGEXP.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaCPars or aImages are NULL
return duplicate of the image in the listonly one image is present in the input list aImages
set CPL_ERROR_ILLEGAL_INPUT, return NULLunknown combination method given
propagate error code, return NULLimage combination failed

Definition at line 741 of file muse_combine.c.

References muse_image::header, muse_combine_average_create(), muse_combine_median_create(), muse_combine_minmax_create(), muse_combine_sigclip_create(), muse_combine_sum_create(), muse_image_duplicate(), muse_imagelist_get(), muse_imagelist_get_size(), and muse_imagelist_scale_exptime().

Referenced by muse_basicproc_combine_images_lampwise().

muse_image* muse_combine_median_create ( muse_imagelist aImages)

Median combine a list of input images.

Parameters
aImagesthe list of images to median combine
Returns
a newly allocated muse_image* or NULL in case of failure
Remarks
Similar to the function cpl_imagelist_collapse_median_create() available in the CPL library, but takes into account all three image elements of muse_images (data, data quality, and variance).

Loop through all pixels in the two image dimensions and compute the median for each pixel from the corresponding pixels in each input frame. Handle the bad pixel map according to Sect. 2.4. The output variance is taken from the median value (or propagated from the two values forming the median value). The output contains only an empty header.

Quality Assessment:
Testing with a defined set of test images for which the input and output pixel values at a few positions are pre-computed.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input list of data images is NULL
set CCPL_ERROR_INCOMPATIBLE_INPUT, return NULLAn image component in the input list is missing

Definition at line 316 of file muse_combine.c.

References muse_imagelist_get_size().

Referenced by muse_combine_images(), muse_dar_check(), muse_wave_calib(), muse_wave_calib_lampwise(), and muse_wcs_locate_sources().

muse_image* muse_combine_minmax_create ( muse_imagelist aImages,
int  aMin,
int  aMax,
int  aKeep 
)

Average a list of input images with minmax rejection.

Parameters
aImagesthe list of images to average
aMinthe number of minimum pixels to reject
aMaxthe number of maximum pixels to reject
aKeepthe number pixels to keep
Returns
a newly allocated muse_image* or NULL in case of failure
Remarks
Similar to the function cpl_imagelist_collapse_minmax_create() available in the CPL library, but takes into account all three image elements of muse_images (data, data quality, and variance).

Loop through all pixels in the two image dimensions and compute the average for each pixel from the corresponding pixels in each input frame, after rejecting the aMin lowest and aMax highest pixels. Using aKeep it is possible to ensure that at least the given number of output pixels is used in the output image, despite the presence of bad pixels; in this case, the output value in the bad pixel map will be a superposition of all non-rejected bad pixel statuses at this position. The exception is when all input images have bad pixels at the same position. Then only the pixel with the least bad value is used. The variance is propagated using Gaussian error propagation. The output contains only an empty header.

Originally adapted from the VIMOS pipeline frCombMinMaxReject procedure written by P. Sartoretti & C. Izzo, (C) 2002-2004 European Southern Observatory.

Quality Assessment:
Testing with a defined set of test images for which the input and output pixel values at a few positions are pre-computed.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input list of data images is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLnot enough input images to for minmax rejection with the specified parameters (e.g. contradicting values of aMin, aMax, aKeep)
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLAn image component in the input list is missing

Definition at line 427 of file muse_combine.c.

References muse_imagelist_get_size().

Referenced by muse_combine_images().

muse_image* muse_combine_sigclip_create ( muse_imagelist aImages,
double  aLow,
double  aHigh 
)

Average a list of input images with sigma clipping rejection.

Parameters
aImagesthe list of images to average
aLowthe sigma for low level rejection
aHighthe sigma for high level rejection
Returns
a newly allocated muse_image* or NULL in case of failure
Remarks
Similar to the function cpl_imagelist_collapse_sigclip_create() available in the CPL library, but takes into account all three image elements of muse_images (data, data quality, and variance).

Loop through all pixels in the two image dimensions and compute the average for each pixel from the corresponding pixels in each input frame, rejecting high and low pixels which lie aLow sigma below or aHigh sigma (sigma in terms of median absolute deviation) above the median. Pixels that do not have a clean bad pixel status are ignored, the variance of the input images is propagated using the Gaussian error propagation. The output contains only an empty header.

Originally adapted from the VIMOS pipeline frCombKSigma procedure written by P. Sartoretti, (C) 2002-2004 European Southern Observatory.

Quality Assessment:
Testing with a defined set of test images for which the input and output pixel values at a few positions are pre-computed.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input list of data images is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLnot enough (<3) input images for sigclip rejection were specified
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLAn image component in the input list is missing

Definition at line 557 of file muse_combine.c.

References muse_cplvector_get_median_dev(), and muse_imagelist_get_size().

Referenced by muse_combine_images().

muse_image* muse_combine_sum_create ( muse_imagelist aImages)

Sum a list of input images.

Parameters
aImagesthe list of images to sum
Returns
a newly allocated muse_image* or NULL in case of failure
Remarks
This is similar to the function cpl_imagelist_collapse_create() available in the CPL library, but takes into account all three image elements of muse_images (data, data quality, and variance).

Loop through all pixels in the two image dimensions and compute the sum for each pixel from the corresponding pixels in each input frame. Handle the bad pixel map and propagate the error using the Gaussian error propagation. In case of bad pixels, the sum is extrapolated to the complete number of input images. The output contains only an empty header.

This is almost a duplicate of muse_combine_average_create().

Quality Assessment:
Testing with a defined set of test images for which the input and output pixel values at a few positions are pre-computed.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input list of data images is NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLAn image component in the input list is missing
return NULLcannot create the output image

Definition at line 153 of file muse_combine.c.

References muse_imagelist_get_size().

Referenced by muse_combine_images().

void muse_combinepar_delete ( muse_combinepar *  aCPars)

Clear the combination parameters.

Parameters
aCParsstruct of combination parameters

Definition at line 715 of file muse_combine.c.

Referenced by muse_basicproc_combine_images_lampwise().

muse_combinepar* muse_combinepar_new ( cpl_parameterlist *  aParameters,
const char *  aPrefix 
)

Create a new set of combination parameters.

Parameters
aParametersthe list of parameters
aPrefixthe prefix of the recipe
Returns
struct of combination parameters

Create a new set of combination parameters from a recipe parameter list. It takes the parameter "combine", "nlow", "nhigh", "nkeep", "lsigma", "hsigma", and "scale".

Use muse_combinepar_delete to free memory allocated by this function.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaParameters or aPrefix are NULL

Definition at line 672 of file muse_combine.c.

References muse_cplparamerterlist_find_prefix().

Referenced by muse_basicproc_combine_images_lampwise().