|
CR2RE Pipeline Reference Manual 1.6.7
|
This module contains functionality to compute and correct the overscan level of CCD image. More...
Functions | |
| hdrl_parameter * | hdrl_overscan_parameter_create (hdrl_direction correction_direction, double ccd_ron, int box_hsize, hdrl_parameter *collapse, hdrl_parameter *rect_region) |
| Creates Overscan Parameters object. | |
| cpl_error_code | hdrl_overscan_parameter_verify (const hdrl_parameter *param, cpl_size nx, cpl_size ny) |
| Verify basic correctness of the Overscan parameters. | |
| cpl_boolean | hdrl_overscan_parameter_check (const hdrl_parameter *self) |
| Check that the parameter is an Overscan parameter. | |
| hdrl_direction | hdrl_overscan_parameter_get_correction_direction (const hdrl_parameter *p) |
| Access the Correction Direction in the Overscan Parameter. | |
| double | hdrl_overscan_parameter_get_ccd_ron (const hdrl_parameter *p) |
| Access the CCD read out noise in the Overscan Parameter. | |
| int | hdrl_overscan_parameter_get_box_hsize (const hdrl_parameter *p) |
| Access the Box Half Size in the Overscan Parameter. | |
| hdrl_parameter * | hdrl_overscan_parameter_get_collapse (const hdrl_parameter *p) |
| Access the collapse method parameters in the Overscan Parameter. | |
| hdrl_parameter * | hdrl_overscan_parameter_get_rect_region (const hdrl_parameter *p) |
| Access the Overscan Region parameters in the Overscan Parameter. | |
| cpl_parameterlist * | hdrl_overscan_parameter_create_parlist (const char *base_context, const char *prefix, const char *corr_dir_def, int box_hsize_def, double ccd_ron_def, hdrl_parameter *rect_region_def, const char *method_def, hdrl_parameter *sigclip_def, hdrl_parameter *minmax_def, hdrl_parameter *mode_def) |
| Create parameter list for the Overscan computation. | |
| hdrl_parameter * | hdrl_overscan_parameter_parse_parlist (const cpl_parameterlist *parlist, const char *prefix) |
| Parse parameterlist to create input parameters for the Overscan method. | |
| hdrl_overscan_compute_result * | hdrl_overscan_compute (const cpl_image *source, const hdrl_parameter *params) |
| Overscan correction computation. | |
| hdrl_image * | hdrl_overscan_compute_result_get_correction (const hdrl_overscan_compute_result *res) |
| Access the correction in the Overscan Computation result object. | |
| hdrl_image * | hdrl_overscan_compute_result_unset_correction (hdrl_overscan_compute_result *res) |
| Unset the correction in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_contribution (const hdrl_overscan_compute_result *res) |
| Access the contribution in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_contribution (hdrl_overscan_compute_result *res) |
| Unset the contribution in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_chi2 (const hdrl_overscan_compute_result *res) |
| Access the CHI2 in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_chi2 (hdrl_overscan_compute_result *res) |
| Unset the CHI2 in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_red_chi2 (const hdrl_overscan_compute_result *res) |
| Access the reduced CHI2 in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_red_chi2 (hdrl_overscan_compute_result *res) |
| Unset the reduced CHI2 in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_sigclip_reject_low (const hdrl_overscan_compute_result *res) |
| Access the low threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_sigclip_reject_low (hdrl_overscan_compute_result *res) |
| Unset the low threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_sigclip_reject_high (const hdrl_overscan_compute_result *res) |
| Access the high threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_sigclip_reject_high (hdrl_overscan_compute_result *res) |
| Unset the high threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_minmax_reject_low (const hdrl_overscan_compute_result *res) |
| Access the low threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_minmax_reject_low (hdrl_overscan_compute_result *res) |
| Unset the low threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_get_minmax_reject_high (const hdrl_overscan_compute_result *res) |
| Access the high threshold in the Overscan Computation result object. | |
| cpl_image * | hdrl_overscan_compute_result_unset_minmax_reject_high (hdrl_overscan_compute_result *res) |
| Unset the high threshold in the Overscan Computation result object. | |
| void | hdrl_overscan_compute_result_delete (hdrl_overscan_compute_result *result) |
| Deletes the Overscan Computation Result Structure. | |
| hdrl_overscan_correct_result * | hdrl_overscan_correct (const hdrl_image *source, const hdrl_parameter *region, const hdrl_overscan_compute_result *os_computation) |
| Overscan correction. | |
| void | hdrl_overscan_correct_result_delete (hdrl_overscan_correct_result *result) |
| Delete the Overscan Correction Result Structure. | |
| hdrl_image * | hdrl_overscan_correct_result_get_corrected (const hdrl_overscan_correct_result *res) |
| Access the corrected image in the Overscan Correction result object. | |
| hdrl_image * | hdrl_overscan_correct_result_unset_corrected (hdrl_overscan_correct_result *res) |
| Unset the corrected image in the Overscan Correction result object. | |
| cpl_image * | hdrl_overscan_correct_result_get_badmask (const hdrl_overscan_correct_result *res) |
| Access the bad pixels mask in the Overscan Correction result object. | |
| cpl_image * | hdrl_overscan_correct_result_unset_badmask (hdrl_overscan_correct_result *res) |
| Unset the bad pixels mask in the Overscan Correction result object. | |
This module contains functionality to compute and correct the overscan level of CCD image.
The overscan (or prescan) region on a CCD can consist of physical pixels on the detector that are not illuminated, or it can consist of a set of virtual pixels created by reading out the serial register either before or after transferring the charge from the CCD for each column/row. A detector may have multiple regions (amplifiers) and each one usually has an associated overscan region.
This module is intended to be applied to a single overscan region.
The key parameter is box_hsize. When box_hsize is zero, then the overscan correction is calculated without smoothing over adjacent rows/columns. However, this may lead to a noisy overscan correction vector. Increasing box_hsize will increase the S/N of the values in the overscan correction vector, but will decrease the ability of the overscan correction to correct for rapid spatial changes in the bias level. A balance must be reached which will likely depend on the detector under consideration.
A typical overscan correction may be essentially independent of row/column, or it may vary smoothly or with abrupt gradient changes. Hence the implementation of a smoothing method as opposed to the fitting of an analytical function.
When choosing the overscan region, note that the first few rows/columns that are read out after the image area will have an artificially high bias level due to the charge transfer efficiency not being 100%. It is recommended therefore to not include the 2-3 rows/columns right next to the image region in the overscan region.
An interesting phenomenon is that a very bright star/object may increase the bias level for the few rows/columns that it covers. Hence it is not advisable to set box_hsize to a value that is much larger than the image point-spread-function FWHM.
An overscan correction is the correct way to correct for the detector bias level. It is preferable to do an overscan correction instead of using bias frames to determine a bias level.
This module allows the computation of the overscan correction for an image from a predefined overscan region. It also provides a function that applies the overscan correction to the image, using the result of the overscan computation.
\image html overscan_example.png
| hdrl_overscan_compute_result * hdrl_overscan_compute | ( | const cpl_image * | source, |
| const hdrl_parameter * | params | ||
| ) |
Overscan correction computation.
| source | input image containing the Overscan region |
| params | Overscan computation parameters |
The source image may contain more than the overscan region that is actually needed by the computation.
params->rect_region defines the overscan region in the source image. The bad pixels that might be present in the image are taken into account (i.e. excluded from the computations).
params->correction_direction is HDRL_X_AXIS (resp. HDRL_Y_AXIS) if the overscan region has to be collapsed along the X (resp. Y) axis in order to create the 1D resulting images (correction, error, contribution, the 

Each pixel of the resulting 1D images are computed from a running sub-window of the overscan region. params->box_hsize defines the half size of the sub-window used for the computation (in the direction orthogonal to params->correction_direction). If params->box_hsize value is HDRL_OVERSCAN_FULL_BOX, the calculation is done on the whole overscan region instead of a running sub-window. In this case, all pixels of the resulting 1D images will be identical.
params->collapse methods can be mean, weighted mean, median or sigclip, i.e. the collapse parameter can be created with hdrl_collapse_mean_parameter_create(), hdrl_collapse_weighted_mean_parameter_create(), hdrl_collapse_median_parameter_create() or hdrl_collapse_sigclip_parameter_create().
params->ccd_ron is the CCD read-out noise. The parameter is mandatory, must be strictly non-negative. It is used for the error, the chi2 and the red_chi2 computation.
In case the sigma-clipping collapsing method is used, a sigma clipping iterative rejection is applied in the overscan sub-window before the computation of the results.
The output hdrl_overscan_compute_result structure (in the following named 'out') contains the following members:
out.correction is a 1D HDRL image of type double. Its image contains the overscan correction values computed from the good pixels of the running sub-window (mean, median or mean after rejection, depending on the used collapsing method)
Its error contains 


out.contribution is a 1D CPL image of type integer. It contains the number of good pixels of the input running sub-window for the mean and median methods, and the remaining good pixels after the rejection for the sigma-clipping method.
out.chi2 and out.red_chi2 are 1D CPL images of type double.
out.chi2 contains the sum over the good pixels of the region to correct, i.e. of 
out.red_chi2 contains the reduced chi2, i.e. the chi2 divided by the number of contributing pixels.
out.sigclip_reject_low and _high are 1D CPL images of type double. They are only returned for the sigma-clipping method. They indicate the final thresholds of the sigma-clipping rejection.
Definition at line 686 of file hdrl_overscan.c.
References hdrl_collapse_parameter_is_minmax(), hdrl_collapse_parameter_is_sigclip(), hdrl_image_create(), hdrl_overscan_parameter_verify(), hdrl_rect_region_get_llx(), hdrl_rect_region_get_lly(), hdrl_rect_region_get_urx(), and hdrl_rect_region_get_ury().
| void hdrl_overscan_compute_result_delete | ( | hdrl_overscan_compute_result * | result | ) |
Deletes the Overscan Computation Result Structure.
| result | The computation result structure to delete |
Definition at line 1222 of file hdrl_overscan.c.
References hdrl_image_delete().
| cpl_image * hdrl_overscan_compute_result_get_chi2 | ( | const hdrl_overscan_compute_result * | res | ) |
Access the CHI2 in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1030 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_compute_result_get_contribution | ( | const hdrl_overscan_compute_result * | res | ) |
Access the contribution in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1000 of file hdrl_overscan.c.
| hdrl_image * hdrl_overscan_compute_result_get_correction | ( | const hdrl_overscan_compute_result * | res | ) |
Access the correction in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 970 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_compute_result_get_minmax_reject_high | ( | const hdrl_overscan_compute_result * | res | ) |
Access the high threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1195 of file hdrl_overscan.c.
References hdrl_overscan_compute_result_get_sigclip_reject_high().
| cpl_image * hdrl_overscan_compute_result_get_minmax_reject_low | ( | const hdrl_overscan_compute_result * | res | ) |
Access the low threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1169 of file hdrl_overscan.c.
References hdrl_overscan_compute_result_get_sigclip_reject_low().
| cpl_image * hdrl_overscan_compute_result_get_red_chi2 | ( | const hdrl_overscan_compute_result * | res | ) |
Access the reduced CHI2 in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1060 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_compute_result_get_sigclip_reject_high | ( | const hdrl_overscan_compute_result * | res | ) |
Access the high threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1132 of file hdrl_overscan.c.
Referenced by hdrl_overscan_compute_result_get_minmax_reject_high().
| cpl_image * hdrl_overscan_compute_result_get_sigclip_reject_low | ( | const hdrl_overscan_compute_result * | res | ) |
Access the low threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1090 of file hdrl_overscan.c.
Referenced by hdrl_overscan_compute_result_get_minmax_reject_low().
| cpl_image * hdrl_overscan_compute_result_unset_chi2 | ( | hdrl_overscan_compute_result * | res | ) |
Unset the CHI2 in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1044 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_compute_result_unset_contribution | ( | hdrl_overscan_compute_result * | res | ) |
Unset the contribution in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1014 of file hdrl_overscan.c.
| hdrl_image * hdrl_overscan_compute_result_unset_correction | ( | hdrl_overscan_compute_result * | res | ) |
Unset the correction in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 984 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_compute_result_unset_minmax_reject_high | ( | hdrl_overscan_compute_result * | res | ) |
Unset the high threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1208 of file hdrl_overscan.c.
References hdrl_overscan_compute_result_unset_sigclip_reject_high().
| cpl_image * hdrl_overscan_compute_result_unset_minmax_reject_low | ( | hdrl_overscan_compute_result * | res | ) |
Unset the low threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1182 of file hdrl_overscan.c.
References hdrl_overscan_compute_result_unset_sigclip_reject_low().
| cpl_image * hdrl_overscan_compute_result_unset_red_chi2 | ( | hdrl_overscan_compute_result * | res | ) |
Unset the reduced CHI2 in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1074 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_compute_result_unset_sigclip_reject_high | ( | hdrl_overscan_compute_result * | res | ) |
Unset the high threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1152 of file hdrl_overscan.c.
Referenced by hdrl_overscan_compute_result_unset_minmax_reject_high().
| cpl_image * hdrl_overscan_compute_result_unset_sigclip_reject_low | ( | hdrl_overscan_compute_result * | res | ) |
Unset the low threshold in the Overscan Computation result object.
| res | The Overscan Computation result object |
Definition at line 1110 of file hdrl_overscan.c.
Referenced by hdrl_overscan_compute_result_unset_minmax_reject_low().
| hdrl_overscan_correct_result * hdrl_overscan_correct | ( | const hdrl_image * | source, |
| const hdrl_parameter * | region, | ||
| const hdrl_overscan_compute_result * | os_computation | ||
| ) |
Overscan correction.
| source | Input HDRL image that needs to be corrected |
| region | Region from source that needs correction |
| os_computation | Results of the Overscan computation |
source is the input CPL image that needs to be corrected. It is a required input. Usually the same image is passed to hdrl_overscan_compute() to compute the overscan correction parameters.
source_error is the error used for error propagation. It is a required input.
region specifies which region of the source image must be corrected. If NULL or invalid, the whole image is corrected. The region size must fit the sixe of the os_computation.
os_computation contains all the parameters for the overscan correction. It has been produced by hdrl_overscan_compute().
Following results are available from the return value:
hdrl_overscan_correct_result_get_corrected(result): returns the HDRL image of type double of the same size as source.
Its image part contains the corrected values where all the pixels within the specified region were subtracted using the proper correction obtained in os_computation.correction. The pixels outside the specified region remain unchanged. Pixels for which a overscan value could not be determined (e.g. because all pixels in the overscan region are bad) are set to zero.
Its error part contains the error where all the pixels within the specified region are set to: 
hdrl_overscan_correct_result_get_badmask(result): returns an integer cpl_image of the same size as the input that contains a value of 1 for pixels that have not been corrected due to the overscan data being bad in that row/column.
Definition at line 1286 of file hdrl_overscan.c.
References hdrl_image_get_error_const(), hdrl_image_get_image_const(), hdrl_image_get_mask_const(), hdrl_image_get_size_x(), hdrl_image_get_size_y(), hdrl_rect_region_get_llx(), hdrl_rect_region_get_lly(), hdrl_rect_region_get_urx(), hdrl_rect_region_get_ury(), and hdrl_rect_region_parameter_verify().
| void hdrl_overscan_correct_result_delete | ( | hdrl_overscan_correct_result * | result | ) |
Delete the Overscan Correction Result Structure.
| result | The correction result structure to delete |
Definition at line 1438 of file hdrl_overscan.c.
References hdrl_image_delete().
| cpl_image * hdrl_overscan_correct_result_get_badmask | ( | const hdrl_overscan_correct_result * | res | ) |
Access the bad pixels mask in the Overscan Correction result object.
| res | The Overscan Correction result object |
Definition at line 1485 of file hdrl_overscan.c.
| hdrl_image * hdrl_overscan_correct_result_get_corrected | ( | const hdrl_overscan_correct_result * | res | ) |
Access the corrected image in the Overscan Correction result object.
| res | The Overscan Correction result object |
Definition at line 1455 of file hdrl_overscan.c.
| cpl_image * hdrl_overscan_correct_result_unset_badmask | ( | hdrl_overscan_correct_result * | res | ) |
Unset the bad pixels mask in the Overscan Correction result object.
| res | The Overscan Correction result object |
Definition at line 1499 of file hdrl_overscan.c.
| hdrl_image * hdrl_overscan_correct_result_unset_corrected | ( | hdrl_overscan_correct_result * | res | ) |
Unset the corrected image in the Overscan Correction result object.
| res | The Overscan Correction result object |
Definition at line 1469 of file hdrl_overscan.c.
| cpl_boolean hdrl_overscan_parameter_check | ( | const hdrl_parameter * | self | ) |
Check that the parameter is an Overscan parameter.
| self | The parameter to check |
Definition at line 269 of file hdrl_overscan.c.
Referenced by hdrl_overscan_parameter_verify().
| hdrl_parameter * hdrl_overscan_parameter_create | ( | hdrl_direction | correction_direction, |
| double | ccd_ron, | ||
| int | box_hsize, | ||
| hdrl_parameter * | collapse, | ||
| hdrl_parameter * | rect_region | ||
| ) |
Creates Overscan Parameters object.
| correction_direction | HDRL_X_AXIS or HDRL_Y_AXIS |
| ccd_ron | The CCD read out noise |
| box_hsize | The running box half size |
| collapse | The collpase method parameters |
| rect_region | The overscan computation region |
Definition at line 150 of file hdrl_overscan.c.
Referenced by hdrl_overscan_parameter_parse_parlist().
| cpl_parameterlist * hdrl_overscan_parameter_create_parlist | ( | const char * | base_context, |
| const char * | prefix, | ||
| const char * | corr_dir_def, | ||
| int | box_hsize_def, | ||
| double | ccd_ron_def, | ||
| hdrl_parameter * | rect_region_def, | ||
| const char * | method_def, | ||
| hdrl_parameter * | sigclip_def, | ||
| hdrl_parameter * | minmax_def, | ||
| hdrl_parameter * | mode_def | ||
| ) |
Create parameter list for the Overscan computation.
| base_context | base context of parameter (e.g. recipe name) |
| prefix | prefix of parameter, may be empty string |
| corr_dir_def | default correction direction value |
| box_hsize_def | default box hsize value |
| ccd_ron_def | default ccd ron value |
| rect_region_def | default overscan region parameters |
| method_def | default collapse method value |
| sigclip_def | default sigma-clipping parameters |
| minmax_def | default minmax-clipping parameters |
| mode_def | default mode-clipping parameters |
The CLI aliases omit the base_context.
Definition at line 367 of file hdrl_overscan.c.
References hdrl_collapse_parameter_create_parlist(), hdrl_collapse_parameter_is_minmax(), hdrl_collapse_parameter_is_mode(), hdrl_collapse_parameter_is_sigclip(), hdrl_join_string(), hdrl_rect_region_parameter_check(), and hdrl_rect_region_parameter_create_parlist().
| int hdrl_overscan_parameter_get_box_hsize | ( | const hdrl_parameter * | p | ) |
Access the Box Half Size in the Overscan Parameter.
| p | The Overscan parameter |
Definition at line 307 of file hdrl_overscan.c.
| double hdrl_overscan_parameter_get_ccd_ron | ( | const hdrl_parameter * | p | ) |
Access the CCD read out noise in the Overscan Parameter.
| p | The Overscan parameter |
Definition at line 294 of file hdrl_overscan.c.
| hdrl_parameter * hdrl_overscan_parameter_get_collapse | ( | const hdrl_parameter * | p | ) |
Access the collapse method parameters in the Overscan Parameter.
| p | The Overscan parameter |
Definition at line 320 of file hdrl_overscan.c.
| hdrl_direction hdrl_overscan_parameter_get_correction_direction | ( | const hdrl_parameter * | p | ) |
Access the Correction Direction in the Overscan Parameter.
| p | The Overscan parameter |
Definition at line 281 of file hdrl_overscan.c.
| hdrl_parameter * hdrl_overscan_parameter_get_rect_region | ( | const hdrl_parameter * | p | ) |
Access the Overscan Region parameters in the Overscan Parameter.
| p | The Overscan parameter |
Definition at line 333 of file hdrl_overscan.c.
| hdrl_parameter * hdrl_overscan_parameter_parse_parlist | ( | const cpl_parameterlist * | parlist, |
| const char * | prefix | ||
| ) |
Parse parameterlist to create input parameters for the Overscan method.
| parlist | parameter list to parse |
| prefix | prefix of parameter name |
Definition at line 473 of file hdrl_overscan.c.
References hdrl_collapse_parameter_parse_parlist(), hdrl_join_string(), hdrl_overscan_parameter_create(), hdrl_parameter_destroy(), and hdrl_rect_region_parameter_parse_parlist().
| cpl_error_code hdrl_overscan_parameter_verify | ( | const hdrl_parameter * | param, |
| cpl_size | nx, | ||
| cpl_size | ny | ||
| ) |
Verify basic correctness of the Overscan parameters.
| param | Overscan parameters |
| nx | required X region size, set to < 0 to skip check |
| ny | required Y region size, set to < 0 to skip check |
Definition at line 176 of file hdrl_overscan.c.
References hdrl_collapse_parameter_is_mean(), hdrl_collapse_parameter_is_median(), hdrl_collapse_parameter_is_minmax(), hdrl_collapse_parameter_is_mode(), hdrl_collapse_parameter_is_sigclip(), hdrl_collapse_parameter_is_weighted_mean(), hdrl_overscan_parameter_check(), hdrl_rect_region_get_llx(), hdrl_rect_region_get_lly(), hdrl_rect_region_get_urx(), hdrl_rect_region_get_ury(), and hdrl_rect_region_parameter_verify().
Referenced by hdrl_overscan_compute().