MUSE Pipeline Reference Manual  2.1.1
Data Structures | Functions
Image handling for the MUSE format

Data Structures

struct  muse_image
 Structure definition of MUSE three extension FITS file. More...
 

Functions

muse_imagemuse_image_new (void)
 Allocate memory for a new muse_image object. More...
 
void muse_image_delete (muse_image *aImage)
 Deallocate memory associated to a muse_image object. More...
 
static muse_imagemuse_image_load_internal (const char *aFilename, unsigned char aIFU, const char *aID)
 Load the three extensions and the FITS headers of a MUSE image. More...
 
muse_imagemuse_image_load (const char *aFilename)
 Load the three extensions and the FITS headers of a MUSE image from a file. More...
 
muse_imagemuse_image_load_from_extensions (const char *aFilename, unsigned char aIFU)
 Load the three extensions and the FITS headers of a MUSE image from extensions of a merged file. More...
 
muse_imagemuse_image_load_from_raw (const char *aFilename, int aExtension)
 Load raw image into the data extension of a MUSE image. More...
 
cpl_error_code muse_image_save (muse_image *aImage, const char *aFilename)
 Save the three image extensions and the FITS headers of a MUSE image to a file. More...
 
muse_imagemuse_image_duplicate (const muse_image *aImage)
 Duplicate the three image extensions and the FITS headers of a MUSE image. More...
 
int muse_image_subtract (muse_image *aImage, muse_image *aSubtract)
 Subtract a muse_image from another with correct treatment of bad pixels and variance. More...
 
int muse_image_divide (muse_image *aImage, muse_image *aDivisor)
 Divide a muse_image by another with correct treatment of bad pixels and variance. More...
 
int muse_image_scale (muse_image *aImage, double aScale)
 Scale a muse_image with correct treatment of variance. More...
 
int muse_image_variance_create (muse_image *aImage, muse_image *aBias)
 Create the photon noise-based variance in the stat extension. More...
 
cpl_error_code muse_image_adu_to_count (muse_image *aImage)
 Convert the data units from raw adu to count (= electron) units. More...
 
cpl_error_code muse_image_reject_from_dq (muse_image *aImage)
 Reject pixels of a muse_image depending on its DQ data. More...
 
cpl_error_code muse_image_dq_to_nan (muse_image *aImage)
 Convert pixels flagged in the DQ extension to NANs in DATA (and STAT, if present). More...
 

Detailed Description

These functions wrap the respective CPL functions to easily handle the three-extension muse_image structure.

Function Documentation

cpl_error_code muse_image_adu_to_count ( muse_image aImage)

Convert the data units from raw adu to count (= electron) units.

Parameters
aImageinput muse_image to work with
Returns
CPL_ERROR_NONE on success or a different cpl_error_code in case of failure
Remarks
This function directly changes the input image.

This function gets the gain value (in count/adu) for each quadrant from the FITS header and then multiplies the data extension with this gain value and multiplies the variance extension with the squared gain value.

Exceptions
set and return CPL_ERROR_NULL_INPUTaImage or its header component are NULL
set and return CPL_ERROR_INCOMPATIBLE_INPUTthe header component of aImage does not contain BUNIT or its BUNIT is not "adu"
set and return CPL_ERROR_ILLEGAL_INPUTthe data buffer for the data and/or stat components cannot be retrieved

Definition at line 811 of file muse_image.c.

References data, header, muse_pfits_get_bunit(), muse_pfits_get_gain(), muse_quadrants_get_window(), and stat.

Referenced by muse_basicproc_params_delete().

void muse_image_delete ( muse_image aImage)

Deallocate memory associated to a muse_image object.

Parameters
aImageinput MUSE image

Just calls cpl_image_delete() and cpl_propertylist_delete() for the four components of a muse_image, and frees memory for the aImage pointer. As a safeguard, it checks if a valid pointer was passed, so that crashes cannot occur.

Definition at line 85 of file muse_image.c.

References data, dq, header, and stat.

Referenced by muse_basicproc_get_illum(), muse_basicproc_params_delete(), muse_dar_check(), muse_flux_object_delete(), muse_fov_load(), muse_image_duplicate(), muse_image_load_from_raw(), muse_image_load_internal(), muse_imagelist_delete(), muse_imagelist_set(), muse_postproc_cube_resample_and_collapse(), muse_postproc_process_exposure(), muse_quadrants_overscan_stats(), muse_quality_dark_badpix(), muse_resampling_collapse_pixgrid(), muse_resampling_image(), muse_trace(), muse_wave_calib(), muse_wave_calib_lampwise(), and muse_wcs_centroid_stars().

int muse_image_divide ( muse_image aImage,
muse_image aDivisor 
)

Divide a muse_image by another with correct treatment of bad pixels and variance.

Parameters
aImageimage to be changed
aDivisorthe image to divide by
Returns
0 on success or a different value in case of failure
Remarks
This function directly changes the input image.

Divide the data of aImage by aDivisor and modify the variance image accordingly (by multiplying the variance). The bad pixel extension of both input images are merged.

Exceptions
return -1first input image is NULL
return -2second input image is NULL
propagate CPL errorcpl_image_divide, cpl_image_multiply, or cpl_image_add fails

Definition at line 639 of file muse_image.c.

References data, dq, and stat.

Referenced by muse_basicproc_params_delete().

cpl_error_code muse_image_dq_to_nan ( muse_image aImage)

Convert pixels flagged in the DQ extension to NANs in DATA (and STAT, if present).

Parameters
aImagethe image to process
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

Pixels in the data (and, if present, stat) component of the input muse_image aImage are set as NAN depending on the dq component (all non-zero DQ values are assumed to be bad). The dq component is then deallocated and set to NULL.

This should be used only directly before saving an image, because the pipeline then cannot use DQ or other checks any more.

Exceptions
return CPL_ERROR_NULL_INPUTaImage or its data or dq extensions are NULL

Definition at line 904 of file muse_image.c.

References data, dq, and stat.

Referenced by muse_euro3dcube_delete(), muse_fov_load(), and muse_postproc_cube_resample_and_collapse().

muse_image* muse_image_duplicate ( const muse_image aImage)

Duplicate the three image extensions and the FITS headers of a MUSE image.

Parameters
aImageinput MUSE image
Returns
the newly created muse_image * or NULL on error
Remarks
The new image has to be deallocated using muse_image_delete().

Just calls muse_image_new() and uses CPL to copy the four components.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaImage is NULL
propagate CPL error code, return NULLfailure to duplicate any of the four components

Definition at line 510 of file muse_image.c.

References data, dq, header, muse_image_delete(), muse_image_new(), and stat.

Referenced by muse_basicproc_params_delete(), and muse_combine_images().

muse_image* muse_image_load ( const char *  aFilename)

Load the three extensions and the FITS headers of a MUSE image from a file.

Parameters
aFilenamename of the file to load
Returns
a new muse_image * or NULL on error
Remarks
The new image has to be deallocated using muse_image_delete().
Only FITS keywords from the primary FITS header will be loaded.

muse_image_new() is used to create a new muse_image *. The primary FITS header is loaded into the header element using cpl_propertylist_load(). The other three extensions are then loaded from the FITS extensions with the expected EXTNAMEs, using cpl_image_load() to allocate and load the three image components of the muse_image.

This function does not display any error messsage, but the user can take the error state to print one, if necessary.

Exceptions
return NULL, propagate CPL error codecpl_propertylist_load() fails (this handles the case of an invalid or empty filename)
set MUSE_ERROR_READ_DATA, MUSE_ERROR_READ_DQ, or MUSE_ERROR_READ_STAT depending on failed extension, clean up allocations, and return NULLfailure to load any extension

Definition at line 228 of file muse_image.c.

References muse_image_load_internal().

Referenced by muse_basicproc_load_reduced(), and muse_basicproc_params_delete().

muse_image* muse_image_load_from_extensions ( const char *  aFilename,
unsigned char  aIFU 
)

Load the three extensions and the FITS headers of a MUSE image from extensions of a merged file.

Parameters
aFilenamename of the file to load
aIFUIFU number to search for
Returns
a new muse_image * or NULL on error
Remarks
The new image has to be deallocated using muse_image_delete().
The FITS keywords of the primary FITS header will be merged with the HIERARCH keywords of the CHANnn.DATA extension.

muse_image_new() is used to create a new muse_image . The primary FITS header is loaded into the header element using cpl_propertylist_load(). The other three extensions are then loaded from the FITS extensions with the expected EXTNAMEs (CHANnn.NAME, where NAME is one of DATA, DQ, and STAT), using cpl_image_load() to allocate and load the three image components of the muse_image.

This function does not display any error messsage, but the user can take the error state to print one, if necessary.

Exceptions
return NULL, propagate CPL error codecpl_propertylist_load() fails (this handles the case of an invalid or empty filename)
set MUSE_ERROR_READ_DATA, MUSE_ERROR_READ_DQ, or MUSE_ERROR_READ_STAT depending on failed extension, clean up allocations, and return NULLfailure to load any extension

Definition at line 262 of file muse_image.c.

References muse_image_load_internal().

Referenced by muse_basicproc_load_reduced(), and muse_basicproc_params_delete().

muse_image* muse_image_load_from_raw ( const char *  aFilename,
int  aExtension 
)

Load raw image into the data extension of a MUSE image.

Parameters
aFilenamename of the file to load
aExtensionthe FITS extension number
Returns
a new muse_image * or NULL on error
Remarks
The new image has to be deallocated using muse_image_delete().

This function loads the specified extension from a file. The dq image is filled with 0 (no flaws) and the stat image is created (also filled with 0.0); this requires the caller of this function to fill in a correct estimate of the variance later!

The FITS header of the output image are created by merging the primary header with the extension header of the given extension.

Since the returned data is not corrected for the gain, the BUNIT in the header is set to "adu".

Exceptions
return NULL and propagate CPL error codecpl_image_load() fails
return NULL but set MUSE_ERROR_CHIP_NOT_LIVEcpl_image_load() fails but chip is known to be dead

Definition at line 292 of file muse_image.c.

References data, dq, header, muse_image_delete(), muse_image_new(), muse_pfits_get_chip_live(), muse_pfits_get_extname(), and stat.

Referenced by muse_basicproc_params_delete().

static muse_image* muse_image_load_internal ( const char *  aFilename,
unsigned char  aIFU,
const char *  aID 
)
static

Load the three extensions and the FITS headers of a MUSE image.

Parameters
aFilenamename of the file to load
aIFUIFU number to search for, or 0 if loading directly.
aIDfunction name to use for messages
Returns
a muse_image or NULL on error

Definition at line 117 of file muse_image.c.

References data, dq, header, muse_image_delete(), muse_image_new(), muse_pfits_get_bunit(), and stat.

Referenced by muse_image_load(), and muse_image_load_from_extensions().

muse_image* muse_image_new ( void  )

Allocate memory for a new muse_image object.

Returns
a new muse_image * or NULL on error
Remarks
The returned object has to be deallocated using muse_image_delete().
This function does not allocate the contents of the four elements, these have to be allocated with cpl_image_new() or cpl_propertylist_new(), respectively, or equivalent functions.

Simply allocate memory to store the pointers of the muse_image structure.

Definition at line 66 of file muse_image.c.

Referenced by muse_dar_check(), muse_datacube_collapse(), muse_datacube_load(), muse_euro3dcube_collapse(), muse_flux_integrate_cube(), muse_fov_load(), muse_image_duplicate(), muse_image_load_from_raw(), muse_image_load_internal(), muse_pixtable_to_imagelist(), muse_quadrants_overscan_stats(), muse_quadrants_trim_image(), muse_quality_dark_badpix(), muse_resampling_collapse_pixgrid(), muse_resampling_image(), muse_trace(), muse_wave_calib(), muse_wave_calib_lampwise(), muse_wcs_centroid_stars(), and muse_wcs_locate_sources().

cpl_error_code muse_image_reject_from_dq ( muse_image aImage)

Reject pixels of a muse_image depending on its DQ data.

Parameters
aImagethe image to process
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

Pixels in the data (and, if present, stat) extension of the input muse_image aImage are set as bad depending on the dq extension (all non-zero DQ values are assumed to be bad), using cpl_image_reject(). This is useful to let CPL functions automatically ignore the bad pixels.

Exceptions
return CPL_ERROR_NULL_INPUTaImage or its data or dq extensions are NULL

Definition at line 863 of file muse_image.c.

References data, dq, and stat.

Referenced by muse_dar_check(), muse_sky_create_skymask(), and muse_trace().

cpl_error_code muse_image_save ( muse_image aImage,
const char *  aFilename 
)

Save the three image extensions and the FITS headers of a MUSE image to a file.

Parameters
aImageinput MUSE image
aFilenamename of the output file
Returns
CPL_ERROR_NONE or the relevant cpl_error_code on error
Remarks
The primary headers of the output file will be constructed from the header member of the muse_image structure.
The extension headers will only contain the minimal keywords, plus EXTNAMEs that advertise their function (DATA, DQ, STAT) and a comment explaining their purpose.

Just calls cpl_image_save() for the three components of a muse_image, using the keywords in the header element of the muse_image structure for construction of the primary header.

This function uses muse_utils_set_hduclass() to add the special FITS headers to support the ESO format.

The data unit ("BUNIT") of the DATA and STAT extensions are set to be the incoming BUNIT (from the header component) and (BUNIT)**2, respectively. BUNIT and WCS keys are removed from the primary header before saving.

Exceptions
return CPL_ERROR_NULL_INPUTaImage, its data component, or aFilename are NULL
return CPL_ERROR_INCOMPATIBLE_INPUTthe header component of aImage does not contain a BUNIT
return CPL error codefailure to save any of the three components, if the respective component is non-NULL

Definition at line 405 of file muse_image.c.

References data, dq, header, muse_pfits_get_bunit(), muse_utils_set_hduclass(), MUSE_WCS_KEYS, and stat.

Referenced by muse_basicproc_params_delete(), muse_dar_check(), muse_processing_save_image(), muse_quadrants_trim_image(), muse_quality_dark_badpix(), muse_wave_lines_search(), and muse_wcs_locate_sources().

int muse_image_scale ( muse_image aImage,
double  aScale 
)

Scale a muse_image with correct treatment of variance.

Parameters
aImageimage to be changed
aScalethe scale factor
Returns
0 on success or a different value in case of failure
Remarks
This function directly changes the input image.

Apply the scale to the input data extension and apply it squared to the stat extension to keep the varianace in sync with the data.

Exceptions
return -1input image is NULL
propagate CPL errorcpl_image_multiply_scalar fails

Definition at line 703 of file muse_image.c.

References data, and stat.

Referenced by muse_basicproc_params_delete(), and muse_imagelist_scale_exptime().

int muse_image_subtract ( muse_image aImage,
muse_image aSubtract 
)

Subtract a muse_image from another with correct treatment of bad pixels and variance.

Parameters
aImageimage to be changed
aSubtractthe image to subtract
Returns
0 on success or a different value in case of failure
Remarks
This function directly changes the input image.

Subtract the image aSubtract from input image aImage and modify the variance image accordingly (by adding to the variance). The bad pixel extension of both input images are merged.

Exceptions
return -1first input image is NULL
return -2second input image is NULL
propagate CPL errorcpl_image_subtract or cpl_image_add fails

Definition at line 593 of file muse_image.c.

References data, dq, and stat.

Referenced by muse_basicproc_params_delete().

int muse_image_variance_create ( muse_image aImage,
muse_image aBias 
)

Create the photon noise-based variance in the stat extension.

Parameters
aImageinput muse_image to work with
aBiasinput bias image to take the RON from
Returns
0 on success or a different value in case of failure
Remarks
This function directly changes the input image.
Note
Warning: this function deletes an already existing stat extension!

This function computes the photon noise part of the variance formula (but in units of adu**2) i.e. sigma_photon^2 = (counts - bias) / gain (where gain is the conversion factor with the unit count/adu). The resulting sigma_photon^2 is ensured to be larger than zero by cutting off low values (that can occur due to noise in the bias level at low count values).

Exceptions
return -1input image is NULL
return -2input bias is NULL
return -3input images are of different size

Definition at line 747 of file muse_image.c.

References data, header, muse_pfits_get_gain(), muse_quadrants_get_window(), and stat.

Referenced by muse_basicproc_params_delete().