MUSE Pipeline Reference Manual  2.1.1
Functions | Variables
Quality flag handling

Functions

int muse_quality_dark_badpix (muse_image *aDark, double aSigmaLo, double aSigmaHi)
 Find bad (especially hot) pixels (in a master dark). More...
 
int muse_quality_bad_columns (muse_image *aBias, double aLow, double aHigh)
 Find bad columns (in a master bias). More...
 
int muse_quality_flat_badpix (muse_image *aFlat, cpl_table *aTrace, double aSigmaLo, double aSigmaHi)
 Find bad (especially dark) pixels (in a master flat). More...
 
int muse_quality_set_saturated (muse_image *aImage)
 Set all pixels above the saturation limit in the bad pixel image. More...
 
cpl_table * muse_quality_convert_dq (cpl_image *aDQ)
 Convert a data quality (DQ) image extension to a bad pixel table. More...
 
cpl_error_code muse_quality_merge_badpix (cpl_table *aTable, const cpl_table *aToMerge)
 Merge two bad pixel tables. More...
 
int muse_quality_image_reject_using_dq (cpl_image *aData, cpl_image *aDQ, cpl_image *aStat)
 Reject pixels of one or two images on a DQ image. More...
 
cpl_table * muse_quality_merge_badpix_from_file (const cpl_table *aTable, const char *aInFile, const char *aExtname, int *aExt)
 Merge bad pixel table in memory with table from file on disk. More...
 
cpl_error_code muse_quality_copy_badpix_table (const char *aInFile, const char *aOutFile, int aExtension, const cpl_table *aTable)
 Copy bad pixel table on disk, replacing the table in one extension. More...
 
static cpl_boolean muse_quality_is_usable (uint32_t aState, uint32_t aInclude)
 Check for usable pixel quality given a bitmask of usable states. More...
 

Variables

const muse_cpltable_def muse_badpix_table_def []
 

Detailed Description

These functions determine and handle the Euro3D-like 32bit integer quality flags of all pixels.

Function Documentation

int muse_quality_bad_columns ( muse_image aBias,
double  aLow,
double  aHigh 
)

Find bad columns (in a master bias).

Parameters
aBiasMUSE bias image to process
aLowsigma for low cut
aHighsigma for high cut
Returns
number of pixels in bad columns or a negative value on error

Operate per quadrant: determine columns that have lower or higher values than others. Within these columns, search for pixels that still have reasonable values. Mark all other pixels in these columns as EURO3D_DEADPIXEL.

Exceptions
return -1 and set CPL_ERROR_NULL_INPUTaBias or its components are NULL

Definition at line 193 of file muse_quality.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_cplvector_get_adev_const(), muse_quadrants_get_window(), and muse_image::stat.

Referenced by muse_quality_is_usable().

cpl_table* muse_quality_convert_dq ( cpl_image *  aDQ)

Convert a data quality (DQ) image extension to a bad pixel table.

Parameters
aDQthe data quality image
Returns
a bad pixel table on success or NULL on error

Note that the input image is assumed to be trimmed, i.e. overscans and prescans are missing. This function adds both back, assuming standard MUSE image sizes, so that the output table contains bad pixels in raw image coordinates.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaDQ is NULL
return empty table (zero rows)no bad pixels found in aDQ image

Definition at line 511 of file muse_quality.c.

References muse_badpix_table_def, muse_cpltable_new(), and muse_quadrants_coords_to_raw().

Referenced by muse_quality_is_usable().

cpl_error_code muse_quality_copy_badpix_table ( const char *  aInFile,
const char *  aOutFile,
int  aExtension,
const cpl_table *  aTable 
)

Copy bad pixel table on disk, replacing the table in one extension.

Parameters
aInFilefilename of the file to read
aOutFilefilename of the file to write
aExtensionFITS extension number to replace (has to be > 0)
aTabletable to save in given extension
Returns
CPL_ERROR_NONE on success, another cpl_error_code on failure

This function copies the primary FITS header and all binary table extensions from input to output, replacing one table in on extension. Extensions that are not binary tables are ignored.

This function is to be used from a muse_badpix tool, it outputs messages using stdio functions instead of CPL messages.

XXX this needs error handling for failure to save files, too...

Exceptions
return CPL_ERROR_NULL_INPUTaInFile, aOutFile, or aTable are NULL
propagate CPL error codeopening aInFile fails

Definition at line 764 of file muse_quality.c.

References muse_utils_get_ifu().

Referenced by muse_quality_is_usable().

int muse_quality_dark_badpix ( muse_image aDark,
double  aSigmaLo,
double  aSigmaHi 
)

Find bad (especially hot) pixels (in a master dark).

Parameters
aDarkMUSE dark image to process
aSigmaLosigma for low cut (in terms of median deviation)
aSigmaHisigma for high cut (in terms of median deviation)
Returns
number of bad pixels found or a negative value on error

This function is thought to operate on bias-subtracted dark images from which cosmic rays were removed (by suitable image combination).

Determine outliers that deviate too much from homogenous noise in each of the four CCD quadrants. The low pixels are flagged EURO3D_DEADPIXEL, the high (hot) pixels as EURO3D_HOTPIXEL, both are also rejected in the bad pixel mask of the cpl_image of the data and stat extensions. If one of the sigma arguments is non-positive, the respective cut is ignored.

Note that incoming bad pixels are excluded from the statistics, so they might be marked again as dark or hot and included in the final count.

Exceptions
set CPL_ERROR_NULL_INPUT and return -1aDark is NULL
set CPL_ERROR_ILLEGAL_INPUT and return -2the data buffers of the data or dq components of aDark could not be accessed

Definition at line 80 of file muse_quality.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_image_delete(), muse_image_new(), muse_image_save(), muse_quadrants_get_window(), muse_quality_image_reject_using_dq(), and muse_image::stat.

Referenced by muse_quality_is_usable().

int muse_quality_flat_badpix ( muse_image aFlat,
cpl_table *  aTrace,
double  aSigmaLo,
double  aSigmaHi 
)

Find bad (especially dark) pixels (in a master flat).

Parameters
aFlatMUSE flat image to process
aTracethe trace table to determine the slice edges
aSigmaLosigma for low cut (in terms of median deviation)
aSigmaHisigma for high cut (in terms of median deviation)
Returns
number of bad pixels found or a negative value on error

Operate per slice: loop along all rows in the y-direction. Within these rows, search for pixels that have lower or higher values than others. Mark low pixels as EURO3D_DARKPIXEL and high pixels as EURO3D_HOTPIXEL. Low pixels below 20% of the mean flat-field level are also marked as EURO3D_LOWQEPIXEL. Pixels near the edge of a slice (as given by the trace function) are excluded from the bad pixel search.

Finally, pixels with non-positive values are marked as EURO3D_BADOTHER, but are not added to the total number, since there are so many (at the CCD edges, between slices, at the blue end of the CCD).

Exceptions
set CPL_ERROR_NULL_INPUT and return -1aFlat or its components or aTrace are NULL

Definition at line 315 of file muse_quality.c.

References muse_image::data, muse_image::dq, muse_trace_polys_delete(), muse_trace_table_get_polys_for_slice(), and muse_image::stat.

Referenced by muse_quality_is_usable().

int muse_quality_image_reject_using_dq ( cpl_image *  aData,
cpl_image *  aDQ,
cpl_image *  aStat 
)

Reject pixels of one or two images on a DQ image.

Parameters
aDatathe data image to process
aDQthe image to use
aStatthe optional variance image to process
Returns
number of rejected pixels on success, a negative value on failure

Pixels in aData (and, if given, aStat) are set as bad depending on aDQ, using cpl_image_reject(). This is to let other CPL functions automatically ignore the bad pixels.

This function can be used instead of muse_image_reject_from_dq(), if one has data not in the form of a muse_image, but in separate structures. E.g. when processing planes from a muse_datacube. It also returns the count of bad pixels, in case that is needed.

Exceptions
set CPL_ERROR_NULL_INPUT, return -1aData or aDQ are NULL
set CPL_ERROR_INCOMPATIBLE_INPUT, return -2aData (and aStat, if given) and aDQ have different sizes
propagate error of cpl_image_get_data_int_const(), return -3aDQ is not of type CPL_TYPE_INT

Definition at line 628 of file muse_quality.c.

Referenced by muse_dar_check(), muse_flux_integrate_cube(), muse_flux_integrate_std(), muse_quality_dark_badpix(), muse_quality_is_usable(), and muse_wcs_centroid_stars().

static cpl_boolean muse_quality_is_usable ( uint32_t  aState,
uint32_t  aInclude 
)
static

Check for usable pixel quality given a bitmask of usable states.

Parameters
aStatepixel flags to compare
aIncludebitmask of allowed bad pixel flags (in addition to EURO3D_GOODPIXEL)
Returns
CPL_TRUE or CPL_FALSE

Definition at line 76 of file muse_quality.h.

References muse_quality_bad_columns(), muse_quality_convert_dq(), muse_quality_copy_badpix_table(), muse_quality_dark_badpix(), muse_quality_flat_badpix(), muse_quality_image_reject_using_dq(), muse_quality_merge_badpix(), muse_quality_merge_badpix_from_file(), and muse_quality_set_saturated().

cpl_error_code muse_quality_merge_badpix ( cpl_table *  aTable,
const cpl_table *  aToMerge 
)

Merge two bad pixel tables.

Parameters
aTablethe table to merge into
aToMergethe table to merge into the first one
Returns
CPL_ERROR_NONE on success, another CPL error code on failure

The tables are merged in such a way, that in the output table each pixel is only listed once, with the bad pixel flag ORed. The output table is sorted by the pixel coordinates.

Exceptions
return CPL_ERROR_NULL_INPUTaTable or aToMerge are NULL
propagate CPL error codeinserting the table fails

Definition at line 567 of file muse_quality.c.

Referenced by muse_quality_is_usable(), and muse_quality_merge_badpix_from_file().

cpl_table* muse_quality_merge_badpix_from_file ( const cpl_table *  aTable,
const char *  aInFile,
const char *  aExtname,
int *  aExt 
)

Merge bad pixel table in memory with table from file on disk.

Parameters
aTabletable to merge
aInFilethe filename of the file to read the other table from
aExtnamethe FITS extension name for the other table
aExtpointer to where to save the extension number from which the other table was read
Returns
the merged table or NULL on error

Load an existing bad pixel table from file and merge it with the input table, using muse_quality_merge_badpix().

This function is to be used from a muse_badpix tool, it outputs messages using stdio functions instead of CPL messages.

Exceptions
set CPL_ERROR_NULL_INPUT, return NULLaTable and/or aInFile are NULL
set CPL_ERROR_DATA_NOT_FOUND, return NULLextension aExtname was not found or table could not be loaded

Definition at line 698 of file muse_quality.c.

References muse_quality_merge_badpix().

Referenced by muse_quality_is_usable().

int muse_quality_set_saturated ( muse_image aImage)

Set all pixels above the saturation limit in the bad pixel image.

Parameters
aImageMUSE image to process
Returns
number of pixels detected as saturated, or a negative number on error

Saturated pixels are all those with data values higher than kMuseSaturationLimit or zero (less than FLT_EPSILON).

Exceptions
set CPL_ERROR_NULL_INPUT and return -1aImage or its relevant components are NULL

Definition at line 473 of file muse_quality.c.

References muse_image::data, and muse_image::dq.

Referenced by muse_basicproc_params_delete(), and muse_quality_is_usable().

Variable Documentation

const muse_cpltable_def muse_badpix_table_def[]

This is a FITS table, typically with 24 extensions. It is used in the low-level recipes working on raw data. Each extension lists known bad pixels of one CCD.

Columns:

  • 'xpos': X position of a bad pixel (on untrimmed raw data) [int]
  • 'ypos': Y position of a bad pixel (on untrimmed raw data) [int]
  • 'status': 32bit bad pixel mask as defined by Euro3D [int]
  • 'value': Extra value, e.g. depth for traps [float]

Definition at line 815 of file muse_data_format_z.c.

Referenced by muse_basicproc_params_delete(), muse_quality_convert_dq(), and muse_resampling_params_delete().