High-Level Data Reduction Library 1.6.0
High-Level data reduction routines for ESO pipelines
Loading...
Searching...
No Matches
Overscan Computation and Correction

This module contains functionality to compute and correct the overscan level of CCD image. More...

Data Structures

struct  hdrl_overscan_parameter
 

Functions

hdrl_parameterhdrl_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_parameterhdrl_overscan_parameter_get_collapse (const hdrl_parameter *p)
 Access the collapse method parameters in the Overscan Parameter.
 
hdrl_parameterhdrl_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_parameterhdrl_overscan_parameter_parse_parlist (const cpl_parameterlist *parlist, const char *prefix)
 Parse parameterlist to create input parameters for the Overscan method.
 
hdrl_overscan_compute_resulthdrl_overscan_compute (const cpl_image *source, const hdrl_parameter *params)
 Overscan correction computation.
 
hdrl_imagehdrl_overscan_compute_result_get_correction (const hdrl_overscan_compute_result *res)
 Access the correction in the Overscan Computation result object.
 
hdrl_imagehdrl_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_resulthdrl_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_imagehdrl_overscan_correct_result_get_corrected (const hdrl_overscan_correct_result *res)
 Access the corrected image in the Overscan Correction result object.
 
hdrl_imagehdrl_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.
 

Detailed Description

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

Function Documentation

◆ hdrl_overscan_compute()

hdrl_overscan_compute_result * hdrl_overscan_compute ( const cpl_image *  source,
const hdrl_parameter params 
)

Overscan correction computation.

Parameters
sourceinput image containing the Overscan region
paramsOverscan computation parameters
Returns
hdrl_overscan_compute_result structure containing the results of the computation. It must be de-allocated by the caller using hdrl_overscan_compute_result_delete(). In case of error, NULL is returned and an error code is set.
See also
hdrl_overscan_compute_result_delete()

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 $\chi^{2}$ (chi2) and the reduced $\chi^{2}$ (red_chi2), additionally sigclip_reject_low and _high if the sigma-clipping collapsing is used).

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 $\frac{ccd\_ron}{\sqrt{contribution}}$ for the mean, weighted mean and sigma-cliping methods. In case the method is the median one, it would contain $\sqrt{\frac{\pi}{2}}\times\frac{ccd\_ron}{\sqrt{contribution}}$ if contribution is strictly greater than 2 pixels and $\frac{ccd\_ron}{\sqrt{contribution}}$ when the contribution is 1 or 2 pixels.

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 $\frac{source - out.correction}{ccd\_ron}^2$

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.

See also
hdrl_kappa_sigma_clip
hdrl_overscan_correct

◆ hdrl_overscan_compute_result_delete()

void hdrl_overscan_compute_result_delete ( hdrl_overscan_compute_result result)

Deletes the Overscan Computation Result Structure.

Parameters
resultThe computation result structure to delete

◆ hdrl_overscan_compute_result_get_chi2()

cpl_image * hdrl_overscan_compute_result_get_chi2 ( const hdrl_overscan_compute_result res)

Access the CHI2 in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The CHI2 CPL image

◆ hdrl_overscan_compute_result_get_contribution()

cpl_image * hdrl_overscan_compute_result_get_contribution ( const hdrl_overscan_compute_result res)

Access the contribution in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The contribution CPL image

◆ hdrl_overscan_compute_result_get_correction()

hdrl_image * hdrl_overscan_compute_result_get_correction ( const hdrl_overscan_compute_result res)

Access the correction in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The correction HDRL image

◆ hdrl_overscan_compute_result_get_minmax_reject_high()

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.

Parameters
resThe Overscan Computation result object
Returns
The high threshold CPL image

◆ hdrl_overscan_compute_result_get_minmax_reject_low()

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.

Parameters
resThe Overscan Computation result object
Returns
The low threshold CPL image

◆ hdrl_overscan_compute_result_get_red_chi2()

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.

Parameters
resThe Overscan Computation result object
Returns
The reduced CHI2 CPL image

◆ hdrl_overscan_compute_result_get_sigclip_reject_high()

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.

Parameters
resThe Overscan Computation result object
Returns
The high threshold CPL image

◆ hdrl_overscan_compute_result_get_sigclip_reject_low()

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.

Parameters
resThe Overscan Computation result object
Returns
The low threshold CPL image

◆ hdrl_overscan_compute_result_unset_chi2()

cpl_image * hdrl_overscan_compute_result_unset_chi2 ( hdrl_overscan_compute_result res)

Unset the CHI2 in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The CHI2 CPL image that has been unset

◆ hdrl_overscan_compute_result_unset_contribution()

cpl_image * hdrl_overscan_compute_result_unset_contribution ( hdrl_overscan_compute_result res)

Unset the contribution in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The contribution CPL image that has been unset

◆ hdrl_overscan_compute_result_unset_correction()

hdrl_image * hdrl_overscan_compute_result_unset_correction ( hdrl_overscan_compute_result res)

Unset the correction in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The correction HDRL image that has been unset

◆ hdrl_overscan_compute_result_unset_minmax_reject_high()

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.

Parameters
resThe Overscan Computation result object
Returns
The high threshold CPL image that has been unset

◆ hdrl_overscan_compute_result_unset_minmax_reject_low()

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.

Parameters
resThe Overscan Computation result object
Returns
The low threshold CPL image that has been unset

◆ hdrl_overscan_compute_result_unset_red_chi2()

cpl_image * hdrl_overscan_compute_result_unset_red_chi2 ( hdrl_overscan_compute_result res)

Unset the reduced CHI2 in the Overscan Computation result object.

Parameters
resThe Overscan Computation result object
Returns
The reduced CHI2 CPL image that has been unset

◆ hdrl_overscan_compute_result_unset_sigclip_reject_high()

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.

Parameters
resThe Overscan Computation result object
Returns
The high threshold CPL image that has been unset

◆ hdrl_overscan_compute_result_unset_sigclip_reject_low()

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.

Parameters
resThe Overscan Computation result object
Returns
The low threshold CPL image that has been unset

◆ hdrl_overscan_correct()

hdrl_overscan_correct_result * hdrl_overscan_correct ( const hdrl_image source,
const hdrl_parameter region,
const hdrl_overscan_compute_result os_computation 
)

Overscan correction.

Parameters
sourceInput HDRL image that needs to be corrected
regionRegion from source that needs correction
os_computationResults of the Overscan computation
Returns
hdrl_overscan_correct_result structure containing the results of the correction. It must be freed with hdrl_overscan_correct_result_delete() On error, NULL is returned and an error code is set.

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: $\sqrt{(os\_computation.error^2 + source\_error^2)}$, which is the standard Gaussian error propagation. 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.

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.

◆ hdrl_overscan_correct_result_delete()

void hdrl_overscan_correct_result_delete ( hdrl_overscan_correct_result result)

Delete the Overscan Correction Result Structure.

Parameters
resultThe correction result structure to delete

◆ hdrl_overscan_correct_result_get_badmask()

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.

Parameters
resThe Overscan Correction result object
Returns
The bad pixels mask as a CPL image

◆ hdrl_overscan_correct_result_get_corrected()

hdrl_image * hdrl_overscan_correct_result_get_corrected ( const hdrl_overscan_correct_result res)

Access the corrected image in the Overscan Correction result object.

Parameters
resThe Overscan Correction result object
Returns
The HDLR corrected image

◆ hdrl_overscan_correct_result_unset_badmask()

cpl_image * hdrl_overscan_correct_result_unset_badmask ( hdrl_overscan_correct_result res)

Unset the bad pixels mask in the Overscan Correction result object.

Parameters
resThe Overscan Correction result object
Returns
The bad pixels mask as a CPL image that was unset

◆ hdrl_overscan_correct_result_unset_corrected()

hdrl_image * hdrl_overscan_correct_result_unset_corrected ( hdrl_overscan_correct_result res)

Unset the corrected image in the Overscan Correction result object.

Parameters
resThe Overscan Correction result object
Returns
The HDLR corrected image that was unset

◆ hdrl_overscan_parameter_check()

cpl_boolean hdrl_overscan_parameter_check ( const hdrl_parameter self)

Check that the parameter is an Overscan parameter.

Parameters
selfThe parameter to check
Returns
True or False

◆ hdrl_overscan_parameter_create()

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.

Parameters
correction_directionHDRL_X_AXIS or HDRL_Y_AXIS
ccd_ronThe CCD read out noise
box_hsizeThe running box half size
collapseThe collpase method parameters
rect_regionThe overscan computation region
Returns
The overscan parameters object. It needs to be deallocated with hdrl_parameter_delete() or _destroy()
See also
hdrl_parameter_delete()
hdrl_parameter_destroy()
hdrl_overscan_compute()

◆ hdrl_overscan_parameter_create_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.

Parameters
base_contextbase context of parameter (e.g. recipe name)
prefixprefix of parameter, may be empty string
corr_dir_defdefault correction direction value
box_hsize_defdefault box hsize value
ccd_ron_defdefault ccd ron value
rect_region_defdefault overscan region parameters
method_defdefault collapse method value
sigclip_defdefault sigma-clipping parameters
minmax_defdefault minmax-clipping parameters
mode_defdefault mode-clipping parameters
See also
hdrl_rect_region_parameter_create_parlist()
hdrl_collapse_parameter_create_parlist() Creates a parameterlist with the overscan computation parameters:
  • base_context.prefix.correction-direction
  • base_context.prefix.box-hsize
  • base_context.prefix.ccd-ron
  • base_context.prefix.calc-*
  • base_context.prefix.collapse.*

The CLI aliases omit the base_context.

◆ hdrl_overscan_parameter_get_box_hsize()

int hdrl_overscan_parameter_get_box_hsize ( const hdrl_parameter p)

Access the Box Half Size in the Overscan Parameter.

Parameters
pThe Overscan parameter
Returns
The box half size

◆ hdrl_overscan_parameter_get_ccd_ron()

double hdrl_overscan_parameter_get_ccd_ron ( const hdrl_parameter p)

Access the CCD read out noise in the Overscan Parameter.

Parameters
pThe Overscan parameter
Returns
The CCD read out noise

◆ hdrl_overscan_parameter_get_collapse()

hdrl_parameter * hdrl_overscan_parameter_get_collapse ( const hdrl_parameter p)

Access the collapse method parameters in the Overscan Parameter.

Parameters
pThe Overscan parameter
Returns
The collapse method parameters

◆ hdrl_overscan_parameter_get_correction_direction()

hdrl_direction hdrl_overscan_parameter_get_correction_direction ( const hdrl_parameter p)

Access the Correction Direction in the Overscan Parameter.

Parameters
pThe Overscan parameter
Returns
The correction direction

◆ hdrl_overscan_parameter_get_rect_region()

hdrl_parameter * hdrl_overscan_parameter_get_rect_region ( const hdrl_parameter p)

Access the Overscan Region parameters in the Overscan Parameter.

Parameters
pThe Overscan parameter
Returns
The Overscan region parameters

◆ hdrl_overscan_parameter_parse_parlist()

hdrl_parameter * hdrl_overscan_parameter_parse_parlist ( const cpl_parameterlist *  parlist,
const char *  prefix 
)

Parse parameterlist to create input parameters for the Overscan method.

Parameters
parlistparameter list to parse
prefixprefix of parameter name
Returns
Input parameters for the Overscan Computation Reads a Parameterlist in order to create overscan parameters. Expects a parameterlist containing:
  • prefix.correction-direction
  • prefix.box-hsize
  • prefix.ccd-ron
  • prefix.calc-llx
  • prefix.calc-lly
  • prefix.calc-urx
  • prefix.calc-ury
  • prefix.collapse.method
  • prefix.collapse.sigclip.kappa-low
  • prefix.collapse.sigclip.kappa-high
  • prefix.collapse.sigclip.niter
  • prefix.collapse.minmax.nlow
  • prefix.collapse.minmax.nhigh
  • prefix.collapse.mode.histo-min
  • prefix.collapse.mode.histo-max
  • prefix.collapse.mode.bin-size
  • prefix.collapse.mode.method
  • prefix.collapse.mode.error_niter

◆ hdrl_overscan_parameter_verify()

cpl_error_code hdrl_overscan_parameter_verify ( const hdrl_parameter param,
cpl_size  nx,
cpl_size  ny 
)

Verify basic correctness of the Overscan parameters.

Parameters
paramOverscan parameters
nxrequired X region size, set to < 0 to skip check
nyrequired Y region size, set to < 0 to skip check
Returns
CPL_ERROR_NONE if everything is ok, an error code otherwise