MUSE Pipeline Reference Manual  2.1.1
Functions
Datacube handling

Functions

muse_imagemuse_euro3dcube_collapse (muse_euro3dcube *aEuro3D, const muse_table *aFilter)
 Integrate a Euro3D datacube along the wavelength direction. More...
 
muse_imagemuse_datacube_collapse (muse_datacube *aCube, const muse_table *aFilter)
 Integrate a FITS NAXIS=3 datacube along the wavelength direction. More...
 
cpl_error_code muse_datacube_save_recimages (const char *aFilename, muse_imagelist *aImages, cpl_array *aNames)
 Save reconstructed images of a cube in extra extensions. More...
 
cpl_error_code muse_euro3dcube_save (muse_euro3dcube *aEuro3D, const char *aFilename)
 Save a Euro3D cube object to a file. More...
 
void muse_euro3dcube_delete (muse_euro3dcube *aEuro3D)
 Deallocate memory associated to a muse_euro3dcube object. More...
 
cpl_error_code muse_datacube_convert_dq (muse_datacube *aCube)
 Convert the DQ extension of a datacube to NANs in DATA and STAT. More...
 
cpl_error_code muse_datacube_save (muse_datacube *aCube, const char *aFilename)
 Save the three cube extensions and the FITS headers of a MUSE datacube to a file. More...
 
muse_datacubemuse_datacube_load (const char *aFilename)
 Load header, DATA and optionally STAT and DQ extensions as well as the reconstructed images of a MUSE cube from disk. More...
 
cpl_error_code muse_datacube_concat (muse_datacube *aCube, const muse_datacube *aAppend)
 Concatenate one datacube at the end of another one. More...
 
void muse_datacube_delete (muse_datacube *aCube)
 Deallocate memory associated to a muse_datacube object. More...
 

Detailed Description

This contains all functions concerned with handling datacube in the FITS NAXIS=3 and Euro3D formats.

Function Documentation

muse_image* muse_datacube_collapse ( muse_datacube aCube,
const muse_table aFilter 
)

Integrate a FITS NAXIS=3 datacube along the wavelength direction.

Parameters
aCubethe datacube to integrate
aFilterthe filter response curve
Returns
A MUSE image of the field of view (with empty stat component) or NULL on error.

Loop through all wavelength planes of the input cube and add them up into the output image, weighting with the filter response curve at every wavelength. Optionally, if the environment variable MUSE_COLLAPSE_USE_VARIANCE is set to something positive, the variance information in the input cube will be used to weight the data according to their S/N.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input cube, its data, or its header are NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLthe input cube components, if they exist, are not of the expected type (float and int)
integrate over the whole wavelength rangefilter table is NULL

Definition at line 351 of file muse_datacube.c.

References muse_image::data, data, muse_image::dq, dq, header, muse_image::header, muse_image_new(), muse_pfits_get_cd(), muse_pfits_get_crpix(), muse_pfits_get_crval(), muse_pfits_get_ctype(), muse_utils_filter_copy_properties(), and stat.

Referenced by muse_postproc_cube_resample_and_collapse(), muse_postproc_process_exposure(), and muse_wcs_locate_sources().

cpl_error_code muse_datacube_concat ( muse_datacube aCube,
const muse_datacube aAppend 
)

Concatenate one datacube at the end of another one.

Parameters
aCubethe cube to append to
aAppendthe cube to append
Returns
CPL_ERROR_NONE on success, another CPL error code on failure
Note
The reconstructed images present in aCube are most likely meaningless after concatenating. Hence, they are removed by this function!
Both cubes must be of the same spectral type (AWAV or WAVE).
A logarithmic dispersion axis is currently not supported.
Exceptions
return and set CPL_ERROR_NULL_INPUTaCube and/or aAppend are NULL
return and set CPL_ERROR_ILLEGAL_INPUTimage planes of the cubes have different sizes
return and set CPL_ERROR_ILLEGAL_INPUTsampling in dispersion direction is different and/or not adjacent
return and set CPL_ERROR_ILLEGAL_INPUTcpl_imagelist sizes in one of the input cubes do not match between data and stat components

Definition at line 951 of file muse_datacube.c.

References data, dq, header, muse_imagelist_delete(), muse_pfits_get_cd(), muse_pfits_get_crpix(), muse_pfits_get_crval(), muse_pfits_get_ctype(), recimages, recnames, and stat.

cpl_error_code muse_datacube_convert_dq ( muse_datacube aCube)

Convert the DQ extension of a datacube to NANs in DATA and STAT.

Parameters
aCubeinput MUSE datacube
Returns
CPL_ERROR_NONE or the relevant cpl_error_code on error

This also converts the DQ extension of all reconstructed images that are part of the cube in the same way. All DQ components are deallocated and their pointers are set to NULL.

Exceptions
return CPL_ERROR_NULL_INPUTaCube or one of its data, stat, dq extensions are NULL

Definition at line 671 of file muse_datacube.c.

References data, dq, and stat.

Referenced by muse_postproc_cube_resample_and_collapse().

void muse_datacube_delete ( muse_datacube aCube)

Deallocate memory associated to a muse_datacube object.

Parameters
aCubeinput MUSE datacube

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

Definition at line 1037 of file muse_datacube.c.

References data, dq, header, muse_imagelist_delete(), recimages, recnames, and stat.

Referenced by muse_dar_check(), muse_flux_object_delete(), muse_postproc_cube_resample_and_collapse(), muse_postproc_process_exposure(), muse_resampling_cube(), muse_resampling_euro3d(), and muse_wcs_object_delete().

muse_datacube* muse_datacube_load ( const char *  aFilename)

Load header, DATA and optionally STAT and DQ extensions as well as the reconstructed images of a MUSE cube from disk.

Parameters
aFilenamename of the file on disk
Returns
a muse_datacube * or NULL on error
Remarks
The primary header of the returned cube is constructed from the primary HDU of the file and the WCS keywords as well as BUNIT of the DATA extension.
Both DQ and STAT components of the file are optional.
The types of the three primary extensions (DATA, DQ, and STAT) are are casted to float, int, and float, respectively, during loading. The types of the reconstructed images are taken from the file.
Warning
This function ignores the ESO-format headers like HDUCLASS.
Note
When loading extra reconstructed images from the cube file, this function assumes that DQ and STAT extensions belonging to a reconstructed image are in the extensions directly after the main image extension for that reconstructed image. I.e., if an image extension "filt1" exists, then the corresponding "filt1_DQ" and/or "filt1_STAT" extensions have to follow right after it. Since this is what muse_datacube_save() saves to disk, it should be true in most cases.
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaFilename is NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLaFilename does not exist
set CPL_ERROR_DATA_NOT_FOUND, return NULLaFilename does not contain a DATA extension
output error message, return NULLheader could not be loaded/merged from primary and DATA extensions

Definition at line 864 of file muse_datacube.c.

References muse_image::data, data, muse_image::dq, header, muse_image::header, muse_image_new(), muse_imagelist_get_size(), muse_imagelist_new(), muse_imagelist_set(), muse_pfits_get_extname(), recimages, recnames, muse_image::stat, and stat.

cpl_error_code muse_datacube_save ( muse_datacube aCube,
const char *  aFilename 
)

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

Parameters
aCubeinput MUSE datacube
aFilenamename of the output file
Returns
CPL_ERROR_NONE or the relevant cpl_error_code on error
Remarks
The primary header of the output file is constructed from the header member of the muse_datacube structure, but without WCS keys.
The extension headers will only contain the minimal keywords (including WCS) plus EXTNAMEs that advertise their function (DATA, DQ, STAT) and a comment explaining their purpose.
Both dq and stat components of aCube are optional, the saved result may not contain them.

Just calls cpl_imagelist_save() for the three components of a muse_datacube, using the keywords in the header element of the muse_datacube structure for construction of the primary header. It appends further image extensions for each reconstructed image in the cube structure.

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

Exceptions
return CPL_ERROR_NULL_INPUTaCube, its header component, or aFilename are NULL
propagate CPL error codefailure to save any of the three components

Definition at line 741 of file muse_datacube.c.

References data, dq, header, muse_datacube_save_recimages(), muse_pfits_get_bunit(), muse_utils_copy_modified_header(), muse_utils_set_hduclass(), MUSE_WCS_KEYS, recimages, recnames, and stat.

Referenced by muse_dar_check(), muse_flux_integrate_std(), muse_processing_save_cube(), and muse_wcs_locate_sources().

cpl_error_code muse_datacube_save_recimages ( const char *  aFilename,
muse_imagelist aImages,
cpl_array *  aNames 
)

Save reconstructed images of a cube in extra extensions.

Parameters
aFilenamename of the output file
aImagesimage list to save as separate extensions
aNamesnames of all filters used to create the images
Returns
CPL_ERROR_NONE or the relevant cpl_error_code on error

Saving of the BUNIT keywords is modeled after muse_image_save(), i.e. the data extension uses the incoming BUNIT entry (if present), the variance extension gets the squared unit, and the data quality does not get any BUNIT.

Exceptions
return CPL_ERROR_NULL_INPUTaFilename is NULL
immediately return CPL_ERROR_NONEaImages or aNames are NULL

Definition at line 473 of file muse_datacube.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_imagelist_get(), muse_imagelist_get_size(), muse_pfits_get_bunit(), muse_utils_copy_modified_header(), muse_utils_set_hduclass(), MUSE_WCS_KEYS, and muse_image::stat.

Referenced by muse_datacube_save(), and muse_euro3dcube_save().

muse_image* muse_euro3dcube_collapse ( muse_euro3dcube aEuro3D,
const muse_table aFilter 
)

Integrate a Euro3D datacube along the wavelength direction.

Parameters
aEuro3Dthe Euro3D cube to integrate
aFilterthe filter response curve
Returns
A MUSE image of the field of view (with empty stat component) or NULL on error.

Loop through all wavelengths of the input Euro3D cube and add them up into the output image, weighting with the filter response curve. Optionally, if the environment variable MUSE_COLLAPSE_USE_VARIANCE is set to something positive, the variance information in the input Euro3D table will be used to weight the data according to their S/N.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLthe input Euro3D table or one of its components are NULL
integrate over the whole wavelength rangefilter table is NULL
output file will only contain the minimal set of FITS headersheader information NULL
set CPL_ERROR_DATA_NOT_FOUND, return NULLthe aEuro3D table does not contain units for the XPOS and/or YPOS column(s)

Definition at line 145 of file muse_datacube.c.

References muse_wcs::crval2, muse_image::data, muse_image::dq, muse_euro3dcube::dtable, muse_euro3dcube::hdata, muse_image::header, muse_euro3dcube::header, muse_wcs::iscelsph, muse_image_new(), muse_utils_filter_copy_properties(), muse_wcs_new(), muse_wcs_pixel_from_celestial_fast(), and muse_wcs_pixel_from_projplane_fast().

Referenced by muse_postproc_cube_resample_and_collapse().

void muse_euro3dcube_delete ( muse_euro3dcube aEuro3D)

Deallocate memory associated to a muse_euro3dcube object.

Parameters
aEuro3Dinput Euro3D cube

Just calls cpl_table_delete() and cpl_propertylist_delete() for the five components of a muse_euro3dcube, and frees memory for the aEuro3D pointer. As a safeguard, it checks if a valid pointer was passed, so that crashes cannot occur.

Definition at line 607 of file muse_datacube.c.

References muse_image::dq, muse_euro3dcube::dtable, muse_euro3dcube::gtable, muse_euro3dcube::hdata, muse_euro3dcube::header, muse_euro3dcube::hgroup, muse_image_dq_to_nan(), muse_imagelist_delete(), muse_imagelist_get(), muse_imagelist_get_size(), recimages, muse_euro3dcube::recimages, and muse_euro3dcube::recnames.

Referenced by muse_postproc_cube_resample_and_collapse().

cpl_error_code muse_euro3dcube_save ( muse_euro3dcube aEuro3D,
const char *  aFilename 
)

Save a Euro3D cube object to a file.

Parameters
aEuro3Dinput Euro3D cube
aFilenamename of the output file
Returns
CPL_ERROR_NONE or the relevant cpl_error_code on error

Just calls cpl_table_save() for the two table components of a muse_euro3dcube, using the header components to construct primary and both extension headers. It appends further image extensions for each reconstructed image in the Euro3D structure.

Exceptions
return CPL_ERROR_NULL_INPUTaEuro3D or aFilename are NULL
propagate CPL error codefailure to save one of the tables

Definition at line 571 of file muse_datacube.c.

References muse_euro3dcube::dtable, muse_euro3dcube::gtable, muse_euro3dcube::hdata, muse_euro3dcube::header, muse_euro3dcube::hgroup, muse_datacube_save_recimages(), muse_euro3dcube::recimages, and muse_euro3dcube::recnames.

Referenced by muse_processing_save_cube().