MUSE Pipeline Reference Manual  2.1.1
Functions
Quadrants and other CCD regions

Functions

cpl_error_code muse_quadrants_overscan_stats (muse_image *aImage, const char *aRejection, unsigned int aIgnore)
 Compute overscan statistics of all quadrants and save in FITS header. More...
 
cpl_boolean muse_quadrants_overscan_check (muse_image *aImage, muse_image *aRefImage, double aSigma)
 Compare overscan statistics of all quadrants to those of reference image. More...
 
cpl_error_code muse_quadrants_overscan_correct (muse_image *aImage, muse_image *aRefImage)
 Adapt bias level to reference image using overscan statistics. More...
 
cpl_error_code muse_quadrants_overscan_polyfit_vertical (muse_image *aImage, unsigned aIgnore, unsigned char aOrder, double aSigma, const double aFRMS, double aFChiSq)
 Correct quadrants by polynomial representation of vertical overscan. More...
 
cpl_size * muse_quadrants_overscan_get_window (const muse_image *aImage, unsigned char aQuadrant, unsigned int aIgnore)
 Determine the overscan windows of a given quadrant on the CCD. More...
 
muse_imagemuse_quadrants_trim_image (muse_image *aImage)
 Trim the input image of pre- and over-scan regions of all quadrants. More...
 
cpl_error_code muse_quadrants_coords_to_raw (cpl_propertylist *aHeader, int *aX, int *aY)
 Convert coordinates of a trimmed image to raw-image coordinates. More...
 
cpl_boolean muse_quadrants_verify (cpl_propertylist *aHeader)
 Verify that quadrant locations and sizes meet the expectations. More...
 
cpl_size * muse_quadrants_get_window (const muse_image *aImage, unsigned char aQuadrant)
 Determine the data window of a given quadrant on the CCD. More...
 

Detailed Description

This group of functions handles regions on the CCDs, like quadrants, pre- and overscans, trimming of the pre- and overscans, and overscan statistics.

Function Documentation

cpl_error_code muse_quadrants_coords_to_raw ( cpl_propertylist *  aHeader,
int *  aX,
int *  aY 
)

Convert coordinates of a trimmed image to raw-image coordinates.

Parameters
aHeaderlist of FITS headers to check
aXthe horizontal position
aYthe vertical position
Returns
CPL_ERROR_NONE on success, another CPL error code on failure
Warning
Handling of an input header is not yet implemented!
Exceptions
return CPL_ERROR_NULL_INPUTboth aX and aY are NULL
assume standard layoutaHeader is NULL

Definition at line 958 of file muse_quadrants.c.

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

cpl_size* muse_quadrants_get_window ( const muse_image aImage,
unsigned char  aQuadrant 
)

Determine the data window of a given quadrant on the CCD.

Parameters
aImagemuse_image that holds the necessary data
aQuadrantthe quadrant number
Returns
the array of window coordinates or NULL on error

The returned window array contains four values, in the order xmin, xmax, ymin, ymax. It has to be deallocated using cpl_free() after use. For both trimmed and untrimmed data, the coordinates give the image window containing the data part of the quadrant, i.e. excluding pre- and overscans.

Exceptions
return CPL_ERROR_NULL_INPUTif aImage or its data or header component are NULL
return CPL_ERROR_ILLEGAL_INPUTan invalid quadrant number was given (>4 or < 1)

Definition at line 1074 of file muse_quadrants.c.

References muse_image::data, muse_image::header, muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_out_nx(), muse_pfits_get_out_ny(), muse_pfits_get_out_overscan_x(), muse_pfits_get_out_overscan_y(), muse_pfits_get_out_prescan_x(), and muse_pfits_get_out_prescan_y().

Referenced by muse_basicproc_params_delete(), muse_image_adu_to_count(), muse_image_variance_create(), muse_imagelist_compute_ron(), muse_quadrants_overscan_correct(), muse_quality_bad_columns(), muse_quality_dark_badpix(), and muse_trace_horizontal_cut().

cpl_boolean muse_quadrants_overscan_check ( muse_image aImage,
muse_image aRefImage,
double  aSigma 
)

Compare overscan statistics of all quadrants to those of reference image.

Parameters
aImagemuse_image that holds the header to check
aRefImagemuse_image that holds the header to use as reference
aSigmasigma to use for overscan comparison
Returns
CPL_TRUE on success or CPL_FALSE on error or for bad comparison.
Exceptions
set CPL_ERROR_NULL_INPUT, return CPL_FALSEif aImage or aRefImage or their header components are NULL

Definition at line 309 of file muse_quadrants.c.

References muse_image::header.

Referenced by muse_basicproc_params_delete().

cpl_error_code muse_quadrants_overscan_correct ( muse_image aImage,
muse_image aRefImage 
)

Adapt bias level to reference image using overscan statistics.

Parameters
aImagemuse_image to be corrected
aRefImagemuse_image that holds the header to use as reference
Returns
CPL_ERROR_NONE on success or another CPL error code on failure.

This offsets the data values of aImage according to the mean overscan level difference between aImage and aRefImage. The variance of aImage is adjusted using the standard deviation of the overscan values of both images.

Exceptions
return CPL_ERROR_NULL_INPUTif aImage or aRefImage or their header components are NULL

Definition at line 363 of file muse_quadrants.c.

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

Referenced by muse_basicproc_params_delete().

cpl_size* muse_quadrants_overscan_get_window ( const muse_image aImage,
unsigned char  aQuadrant,
unsigned int  aIgnore 
)

Determine the overscan windows of a given quadrant on the CCD.

Parameters
aImagemuse_image that holds the necessary data
aQuadrantthe quadrant number
aIgnorenumber of pixels to ignore at the inner edge of the overscans
Returns
the array of eight window coordinates or NULL on error

The returned window array contains eight values, in the order xmin, xmax, ymin, ymax for the horizontal overscan region (indices 0 - 3), and then xmin, xmax, ymin, ymax for the vertical overscan region (indices 4 - 7). The small square where both overscans overlap is counted as part of the vertical overscan.

The returned array has to be deallocated using cpl_free() after use.

Since trimmed data does not contain header entries about pre- and overscans any more, such data will is incompatible input and will be rejected.

Note
This function has to assume a standard quadrant layout, one should use muse_quadrants_verify() to check this beforehand!
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLif aImage or its data or header component are NULL
set CPL_ERROR_ILLEGAL_INPUT, return NULLan invalid quadrant number was given (>4 or <1)
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLone of the quadrant parameters is missing or non-positive, or unexpected output port position was found in aImage
set CPL_ERROR_ILLEGAL_INPUT, return NULLaIgnore as large as the horizontal overscan width or larger

Definition at line 686 of file muse_quadrants.c.

References muse_image::data, muse_image::header, muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_out_nx(), muse_pfits_get_out_ny(), muse_pfits_get_out_output_x(), muse_pfits_get_out_output_y(), muse_pfits_get_out_overscan_x(), muse_pfits_get_out_overscan_y(), muse_pfits_get_out_prescan_x(), and muse_pfits_get_out_prescan_y().

Referenced by muse_quadrants_overscan_polyfit_vertical(), and muse_quadrants_overscan_stats().

cpl_error_code muse_quadrants_overscan_polyfit_vertical ( muse_image aImage,
unsigned  aIgnore,
unsigned char  aOrder,
double  aSigma,
const double  aFRMS,
double  aFChiSq 
)

Correct quadrants by polynomial representation of vertical overscan.

Parameters
aImagemuse_image to be corrected
aIgnorenumber of pixels to ignore at the inner edge of the overscans
aOrdermaximum polynomial order to use
aSigmarejection sigma level for the iterative fit
aFRMSimprovement limit in RMS
aFChiSqimprovement limit in chi**2
Returns
CPL_ERROR_NONE on success or another CPL error code on failure.

This function modifies the input image (the data component) and the header, trying to remove possible large-scale vertical bias structure. The steps involved are:

  • check all relevant header keywords related to the CCD sections
  • loop through the four quadrants: . set each valid input pixel and vertical position in the vertical overscan section into CPL structures . exclude pixels closer to the illuminated CCD sections than aIgnore pixels . use the CPL structures to fit 1D polynomials using subsequently higher polynomial order . aSigma is the sigma-level used for iterative rejection of points in each fit . the fit result with the higher order is compared to the previously lower order in terms of RMS and reduced chi**2: if the improvement in RMS is less than aFRMS and the improvement in chi**2 is less than aFChiSq, then the procedure is stopped; otherwise the next higher order fit is attempted . the resulting polynomial is then evaluated at each vertical position in the quadrant and that value is subtracted from along the whole row (including all pre- and overscan regions) The polynomial parameters used are saved in the FITS header of aImage: the macros MUSE_HDR_OVSC_PNC and MUSE_HDR_OVSC_PY are used to store the number of coefficients (polynomial order + 1) and the coefficients, respectively, for each quadrant.
Exceptions
return CPL_ERROR_NULL_INPUTaImage or its data, dq, or header components are NULL
return CPL_ERROR_ILLEGAL_INPUTaFRMS and/or aFChiSq are not > 1.
return CPL_ERROR_BAD_FILE_FORMATthe quadrant layout in aImage is non-standard, i.e. muse_quadrants_verify() fails
return CPL_ERROR_INCOMPATIBLE_INPUTone of the quadrant 1 parameters is missing from aImage or non-positive
return CPL_ERROR_ILLEGAL_INPUTgetting overscan regions, i.e. muse_quadrants_overscan_get_window() fails, possibly due to too large aIgnore
return CPL_ERROR_INCOMPATIBLE_INPUTunexpected output port position in aImage

Definition at line 461 of file muse_quadrants.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_out_nx(), muse_pfits_get_out_ny(), muse_pfits_get_out_output_x(), muse_pfits_get_out_output_y(), muse_pfits_get_out_overscan_x(), muse_pfits_get_out_overscan_y(), muse_pfits_get_out_prescan_x(), muse_pfits_get_out_prescan_y(), muse_quadrants_overscan_get_window(), muse_quadrants_verify(), muse_utils_get_ifu(), and muse_utils_iterate_fit_polynomial().

Referenced by muse_basicproc_params_delete().

cpl_error_code muse_quadrants_overscan_stats ( muse_image aImage,
const char *  aRejection,
unsigned int  aIgnore 
)

Compute overscan statistics of all quadrants and save in FITS header.

Parameters
aImagemuse_image that holds the image and header to work on
aRejectionrejection method (and possibly parameters)
aIgnorenumber of pixels to ignore at the inner edge of the overscans
Returns
CPL_ERROR_NONE on success or a cpl_error_code on error
Note
This function assumes that the sizes of all quadrants and their pre- and overscans are identical. It ensures this by calling muse_quadrants_verify().

Recognized aRejection methods are "none", "dcr" and "fit". aRejection may also contain more parameters for the respective type. Parameters to "none" are ignored. For "dcr" three unsigned integers and one float can be passed, like "dcr:128,32,3,2.5" (two box sizes, the number of passes, and the sigma threshold). For "fit" one float can be passed, like "fit:4.0" (the iterative rejection sigma).

Exceptions
return CPL_ERROR_NULL_INPUTif aImage or its data or header component are NULL
return CPL_ERROR_BAD_FILE_FORMATsection sizes are not equal for all quadrants
return CPL_ERROR_ILLEGAL_INPUTFITS headers are missing required keywords or aIgnore as large as the horizontal overscan width or larger

Definition at line 79 of file muse_quadrants.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_cosmics_dcr(), muse_image_delete(), muse_image_new(), muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_out_nx(), muse_pfits_get_out_ny(), muse_pfits_get_out_overscan_x(), muse_pfits_get_out_overscan_y(), muse_quadrants_overscan_get_window(), muse_quadrants_verify(), muse_utils_iterate_fit_polynomial(), and muse_image::stat.

Referenced by muse_basicproc_params_delete().

muse_image* muse_quadrants_trim_image ( muse_image aImage)

Trim the input image of pre- and over-scan regions of all quadrants.

Parameters
aImagemuse_image that holds the image to trim
Returns
the trimmed image or NULL on error
Exceptions
set CPL_ERROR_NULL_INPUT, return NULLif aImage or its data or header component are NULL
set CPL_ERROR_DATA_NOT_FOUND, return NULLFITS headers are missing required keywords
set CPL_ERROR_INCOMPATIBLE_INPUT, return NULLFITS headers contain incompatible read-out port setup (order of quadrants, differing sizes)
set CPL_ERROR_ILLEGAL_INPUT, return NULLFITS header in input lead to computation of too large or non-positive output sizes

Definition at line 773 of file muse_quadrants.c.

References muse_image::data, muse_image::dq, muse_image::header, muse_image_new(), muse_image_save(), muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_out_nx(), muse_pfits_get_out_ny(), muse_pfits_get_out_output_x(), muse_pfits_get_out_output_y(), muse_pfits_get_out_prescan_x(), muse_pfits_get_out_prescan_y(), and muse_image::stat.

Referenced by muse_basicproc_params_delete().

cpl_boolean muse_quadrants_verify ( cpl_propertylist *  aHeader)

Verify that quadrant locations and sizes meet the expectations.

Parameters
aHeaderlist of FITS headers to check
Returns
CPL_TRUE when verification succeeded, CPL_FALSE otherwise or on error

The expected quadrant locations are

4(=H) 3(=G)

1(=E) 2(=F)

Note that INM data has ports G and H switched.

Exceptions
set CPL_ERROR_NULL_INPUT, return CPL_FALSEthe input header is NULL
set CPL_ERROR_ILLEGAL_INPUT, return CPL_FALSEthe order of the ports is unexpected
set CPL_ERROR_INCOMPATIBLE_INPUT, return CPL_FALSEthe sizes of the quadrants are not equal

Definition at line 1006 of file muse_quadrants.c.

References muse_pfits_get_binx(), muse_pfits_get_biny(), muse_pfits_get_out_nx(), muse_pfits_get_out_ny(), muse_pfits_get_out_output_x(), muse_pfits_get_out_output_y(), muse_pfits_get_out_overscan_x(), muse_pfits_get_out_overscan_y(), muse_pfits_get_out_prescan_x(), and muse_pfits_get_out_prescan_y().

Referenced by muse_quadrants_overscan_polyfit_vertical(), and muse_quadrants_overscan_stats().