clipm_priv_image_signal.h File Reference

#include <cpl.h>

Go to the source code of this file.

Macros
#define	clipm_priv_image_LOOP_GOOD_DATA_CONST(TYPE, IMSIZE_XY, WDWSIZE_XY, DATA_WDW, BADP_WDW, YACTION, XACTION, XACTION_ONLY_WITH_BPM)
	Loop over a pixel buffer, only regarding good pixels. More...

Functions
double	clipm_priv_image_get_mean_perimeter (const void *data, cpl_type type, double xc, double yc, double r, cpl_size xsize, cpl_size ysize, const cpl_binary *badp, cpl_size *nrpix)
	Average values in a buffer along a perimeter. More...
cpl_error_code	clipm_priv_image_estimate_fwhm_xy (const cpl_image *img, const double *xy_peakpos, double bg_level, double *out_xy_fwhm, double *out_xy_middle, double *out_xy_edge_sigma)
	Estimate the FWHM of an object separable in x and y. More...
cpl_error_code	clipm_priv_image_get_kappa_sigma (const cpl_image *img, const cpl_size window_xxyy[4], double kappa, double initial_limits[], int nmax_iterations, double *out_mean, double *out_sigma, double *out_kappasigma, cpl_size *out_nused, int *out_niterations)
	Determine mean and sigma by iteratively ignoring outliers. More...
double	clipm_priv_image_estimate_low_kappa_sigma (const cpl_image *image, const cpl_size window_xxyy[4], double kappa, double *out_sigma, cpl_size *out_nused)
	Force the iterative kappa-sigma clipping to converge against the dark. More...
cpl_error_code	clipm_priv_image_get_psf_sigma (const cpl_image *img, const cpl_size window_xxyy[4], const double *centre_xy, double bg_level, double cut_lower, double cut_upper, double *sigma_xy, double gain, double *centre_err_xy)
	Compute the sigma (RMS) of an object (i.e. the PSF). More...
cpl_error_code	clipm_priv_image_collapse (const cpl_image *image, const cpl_size window_xxyy[4], cpl_array **horizontal, cpl_array **vertical, cpl_array **x_weight_map, cpl_array **y_weight_map)
	Collapse an image (by averaging) in both dimensions. More...
cpl_size	clipm_priv_image_pixel_count_below (const cpl_image *img, const cpl_size window_xxyy[4], double limit, cpl_size *out_nbad)
	Count all the pixels (strictly) below a given limit. More...
cpl_image *	clipm_priv_image_get_sat (const cpl_image *image, const int window_xxyy[4], cpl_image **contrib_sat)
cpl_image *	clipm_priv_image_conv_matrix (const cpl_image *input, const cpl_matrix *kernel, const cpl_size window_xxyy[4], int extend_bpm, int int2double)
	Convolve an image with a kernel stored in a matrix. More...
cpl_image *	clipm_priv_image_filter_lowpass (const cpl_image *image, const cpl_size window_xxyy[4], double sigma)
	Convolve an image with a gaussian bell curve. More...
double	clipm_priv_image_estimate_bg_in_region (const cpl_image *img, const cpl_size window_xxyy[4], double *out_sigma, cpl_size *out_nused)
	Estimate the background in a small image region. More...
double	clipm_priv_image_estimate_fwhm_round (const cpl_image *img, double x_peakpos, double y_peakpos, double bg_level)
	Estimate the FWHM of a round object. More...

Macro Definition Documentation

#define clipm_priv_image_LOOP_GOOD_DATA_CONST	(		TYPE,
			IMSIZE_XY,
			WDWSIZE_XY,
			DATA_WDW,
			BADP_WDW,
			YACTION,
			XACTION,
			XACTION_ONLY_WITH_BPM
	)

Loop over a pixel buffer, only regarding good pixels.

Parameters

TYPE	C data type (e.g. int, float, double)
IMSIZE_XY	Int buffer of size 2, containing the image size [x, y]
WDWSIZE_XY	Int buffer of size 2, containing the window size
DATA_WDW	Pointer to bad pixel mask data (window)
BADP_WDW	Pointer to bad pixel mask data (window)
YACTION	Action to perform first in each row
XACTION	Action to always perform per pixel
XACTION_ONLY_WITH_BPM	Action to perform only if a bad pixel mask is provided (for speed reasons)

Function Documentation

cpl_error_code clipm_priv_image_collapse	(	const cpl_image *	image,
		const cpl_size	window_xxyy[4],
		cpl_array **	horizontal,
		cpl_array **	vertical,
		cpl_array **	x_weight_map,
		cpl_array **	y_weight_map
	)

Collapse an image (by averaging) in both dimensions.

Parameters

image	Input image
window_xxyy	Window coordinate buffer of the form {xa, xb, ya, yb}, can be NULL
horizontal	(Output) horizontal array of type CPL_TYPE_DOUBLE
vertical	(Output) vertical array of type CPL_TYPE_DOUBLE
x_weight_map	(Optional output) horizontal weighting map of type CPL_TYPE_INT
y_weight_map	(Optional output) vertical weighting map of type CPL_TYPE_INT

Returns

CPL error code

Principle:

• The image is averaged horizontally (all columns) and stored in *vertical, and vertically (all rows) and stored in *horizontal. In other words, the array names reflect the remaining signal direction.
• If provided, the arrays x_weight_map and y_weight_map contain at the end the number of non-bad pixels that had contributed to an average value in the above vectors. NULL is returned in the case of error.

Bad Pixel Handling:

Bad pixel maps are supported. This means that bad pixels are omitted during averaging. Completely bad rows or columns will lead to invalid entries in horizontal or vertical, respectively.

Error Handling:

In the case of error, horizontal and vertical are set to NULL.
The following error codes are reported:

• CPL_ERROR_NULL_INPUT: if image, horizontal or vertical is NULL
• CPL_ERROR_INVALID_TYPE if image is not of type int, float or double
• CPL_ERROR_ACCESS_OUT_OF_RANGE if window contains coordinates outside the image range

Todo:

• implement unit test

cpl_image* clipm_priv_image_conv_matrix	(	const cpl_image *	input,
		const cpl_matrix *	kernel,
		const cpl_size	window_xxyy[4],
		int	extend_bpm,
		int	int2double
	)

Convolve an image with a kernel stored in a matrix.

Parameters

input	Input image
kernel	Kernel
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
extend_bpm	Flag whether to extend the bad pixel flag to the range of coverage of the kernel (incl. the image border), otherwise normalise to covered kernel weight
int2double	Flag whether to convert integer to double (see below)

Returns

Convolved image, NULL in the case of error

Principle:

• An image is convolved with a kernel stored in a matrix.
• The matrix is used as literally defined and displayed on the screen (this means, the data buffer content is treated as vertically mirrored compared to an image).
• If window_xxyy is given, an output image with the corresponding size is created. The surrounding area in the input image, which is covered by the kernel, is used.
• If extend_bpm is true, then every pixel seeing a bad pixel or the border of the input image within the range of coverage of the kernel, is flagged as bad.
• If extend_bpm is false, then every output pixel is weighted with (kernel_sum / covered_kernel_sum), to compensate for gaps by bad pixels or input image borders. In this case, the sum over the kernel must be different from zero! (For example, a gradient operator, usually summing up to zero makes no sense here, this should be used with extend_bpm = true). If (kernel_sum / covered_kernel_sum) >= 1e3, then the respective pixel is flagged as bad (this is particularly useful for kernels containing zeros, like a shift operator).
• The centre of the kernel matrix is interpreted as the center of the impulse response.
• This function uses float or double intermediate values. If the input image is of type CPL_TYPE_INT, then double intermediate values are used. Per default, in this case the result is rounded back to integer. If int2double is true, then the result will be left as it is, this means the output for an input of type integer will be of type double.

Constraints:

• The kernel size must be odd.
• If extend_bpm is false, then the sum over the kernel must be different from zero.

Bad Pixel Handling:

• See above.

Error Handling:

The following errors may occur:

• CPL_ERROR_NULL_INPUT: input or kernel is NULL
• CPL_ERROR_ACCESS_OUT_OF_RANGE: a window coordinate exceeds the image range
• CPL_ERROR_ILLEGAL_INPUT:
  • the kernel size is not odd
  • extend_bpm == false and the sum over the kernel is close to zero (< 1e-3)
• CPL_ERROR_INVALID_TYPE: input is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE

Todo:

:

• implement unit test

double clipm_priv_image_estimate_bg_in_region	(	const cpl_image *	img,
		const cpl_size	window_xxyy[4],
		double *	out_sigma,
		cpl_size *	out_nused
	)

Estimate the background in a small image region.

Parameters

img	Input image
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
out_sigma	(Optional output) background sigma, can be NULL, returns -1.0 in the case of error
out_nused	(Optional output) number of found background pixels, can be NULL, returns 0 in the case of error

Returns

Background value, -1.0 in the case of error

Introduction:

• This function is intended to find the background of a (small) image region, which might contain other (brighter) objects. It is not intended to estimate the background of a big picture.
• It solely operates on pixel statistics, i.e. it does not assume any shape of non-background objects.

Principle:

• The background is found initially by a strategy using iterative kappa-sigma-clipping:
  • the pixel value range is divided into an upper and a lower half range,
  • for both ranges an iterative kappa-sigma-clipping is performed, but it is allowed to leave the initial range (this will happen if the range limit is within a major gaussian value distribution),
  • both results are compared, if they are equal (within 1 sigma), then the result is regarded as a solution, else it means that different value distributions do exist, and this procedure is repeated with the lower half range.
• If 10% of the pixels inside the image region are below the found background distribution (this means if 11% are below the 99% limit which is mean - 2.58*sigma), then the background detection (using iterative kappa-sigma-clipping) is repeated for these 10%. If the result is good (judged by whether more than 5% of the pixels contribute to this solution), then this means that not the background has been found before, and the new result is accepted, otherwise the old result is restored. If the new result is accepted, then the check whether 10% are below the found background distribution is done again and this step is repeated if necessary, until this is not the case anymore.

Constraints:

• The background is expected to be darker than other objects in the image region.
• The image region must contain at least 5 non-bad pixels.

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image plane
• CPL_ERROR_DATA_NOT_FOUND: less than 5 pixels are good

double clipm_priv_image_estimate_fwhm_round	(	const cpl_image *	img,
		double	x_peakpos,
		double	y_peakpos,
		double	bg_level
	)

Estimate the FWHM of a round object.

Parameters

img	Input image
x_peakpos	Horizontal peak position
y_peakpos	Vertical peak position
bg_level	Input background level to subtract

Returns

The full-widt-half-maximum, -1.0 in the case of error

Overview:

Beginning at the provided peak position, the diameter is searched, at which the mean along the perimeter has fallen to half of the peak position.

The applied principle is just a fast and rough estimation, with the purpose of a quick estimation of a peak's size. But the radius-dependent brightness evaluation uses the whole perimeter, so that noise in outer radiuses is decreased. The peak is therefore expected to be round.

Bad Pixel Handling:

Bad pixel maps are supported. This means that bad pixels are ignored during the computation.

Error Handling:

This function can set the following error codes:

• CPL_ERROR_ACCESS_OUT_OF_RANGE: if peakpos is outside the image range
• CPL_ERROR_NULL_INPUT: if img is NULL
• CPL_ERROR_INVALID_TYPE: img is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_CONTINUE:
  • the peak is darker than bg_level
  • the FWHM could not be found
• CPL_ERROR_DATA_NOT_FOUND: around the centre, only bad pixels could be found

cpl_error_code clipm_priv_image_estimate_fwhm_xy	(	const cpl_image *	img,
		const double *	xy_peakpos,
		double	bg_level,
		double *	out_xy_fwhm,
		double *	out_xy_middle,
		double *	out_xy_edge_sigma
	)

Estimate the FWHM of an object separable in x and y.

Parameters

img	Input image
xy_peakpos	Peak position (double buffer of length 2 [x, y])
bg_level	Input background level to subtract
out_xy_fwhm	Output full-width-half-maximum (double buffer of length 2 [x, y])
out_xy_middle	(Optional output) middle position between left and right FWHM edges (double buffer of length 2 [x, y]), can be NULL
out_xy_edge_sigma	(Optional output) sigma of the smoothing of the edge, if not measurable -1.0, see also below, (double buffer of length 2 [x, y]), can be NULL

Returns

CPL error code

Principle:

• Beginning at the provided peak position, the full-width-half-maximum is first searched along the crossing row and column. Thenafter, the region is collapsed in x and y in a region around (+/- edge + 2.6 times the underlying edge sigma, if this could not be determined, then in the +/- FWHM region), and the FWHM is searched in the collapsed (marginal) signals.
• The peak must be brighter than the background.
• The image size must be equal or greater than 3x3 pixels.
• If the object appears to be a flat object, then out_xy_edge_sigma will return the estimated sigma of the smoothing function in x and y respectively. If not measurable, or if the object does not appear to be a smoothed step function, then it will contain -1.0 respectively.

Constraints:

Collapsing the signal in x and y means, that the result is only accurate for separable functions, like squares or a gaussian.

Note

It is allowed to provide the same pointer for xy_peakpos and out_xy_middle, for example for refinement purposes.

Bad Pixel Handling:

Bad pixel maps are supported. This means that bad pixels are ignored during the computation.

Error Handling:

This function can set the following error codes:

• CPL_ERROR_NULL_INPUT: if img or xy_peakpos or out_xy_fwhm is NULL
• CPL_ERROR_ACCESS_OUT_OF_RANGE: if xy_peakpos is outside the image range
• CPL_ERROR_ILLEGAL_INPUT: the image size is less than 3x3
• CPL_ERROR_INVALID_TYPE: img is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_CONTINUE: the FWHM could not be found
• CPL_ERROR_DATA_NOT_FOUND: too many bad pixels prevent the computation of the FWHM

In the case of error, {-1.0, -1.0} is returned.

Todo:

• test with flat object in unit test

double clipm_priv_image_estimate_low_kappa_sigma	(	const cpl_image *	image,
		const cpl_size	window_xxyy[4],
		double	kappa,
		double *	out_sigma,
		cpl_size *	out_nused
	)

Force the iterative kappa-sigma clipping to converge against the dark.

Parameters

image	Input image
window_xxyy	Coordinate buffer of the form {x1a, x1b, y1a, y1b}, minimum/maximum order is irrelevant
kappa	Kappa
out_sigma	(Optional output) RMS of the estimated background -1.0 in the case of error
out_nused	(Optional output) number of used pixels, 0 in the case of error

Returns

The estimated background level

Principle:

• This function is intended to find the background of a (small) image region, which might contain other (brighter) objects. It is not intended to estimate the background of a big picture.
• The minimum, median and maximum pixel values are used as initial limits for two runs of iterative kappa-sigma clipping. While these both converge to different values, the minimum, median and maximum are now taken from the lower part and the iterations of kappa-sigma clipping are re-run, until both converge to the same values. This is then an indication that both belong to the same statistics. It requires of course, that the kappa-sigma clipping routine can leave its initial limits.

Constraints:

The background is expected to be darker than other objects in the image region.

Bad Pixel Handling:

Bad pixels are left out.

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image plane
• CPL_ERROR_ILLEGAL_INPUT: kappa < 1.0
• CPL_ERROR_DATA_NOT_FOUND: less than 5 pixels are good

cpl_image* clipm_priv_image_filter_lowpass	(	const cpl_image *	image,
		const cpl_size	window_xxyy[4],
		double	sigma
	)

Convolve an image with a gaussian bell curve.

Parameters

image	Input image
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
sigma	Sigma of the gaussian

Returns

The new softened image, NULL on error

Principle:

• Since a 2d-Gaussian is separable, actually two convolutions are performed, one in x and y respectively. This leads to slightly different results if bad pixels are present, which must be considered neglegible if using this function.
• If window_xxyy is specified, the surrounding signal is also regarded in the convolution (to an extent of 4 sigma).

Constraints:

• Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.
• sigma must be greater than or equal to 0.

Error Handling:

Possible error codes set in this function:

• CPL_ERROR_NULL_INPUT if image is NULL
• CPL_ERROR_ACCESS_OUT_OF_RANGE: a window coordinate is outside the image
• CPL_ERROR_ILLEGAL_INPUT if sigma <= 0
• CPL_ERROR_INVALID_TYPE if the passed image type is not supported

Todo:

• implement unit test

cpl_error_code clipm_priv_image_get_kappa_sigma	(	const cpl_image *	img,
		const cpl_size	window_xxyy[4],
		double	kappa,
		double	initial_limits[],
		int	nmax_iterations,
		double *	out_mean,
		double *	out_sigma,
		double *	out_kappasigma,
		cpl_size *	out_nused,
		int *	out_niterations
	)

Determine mean and sigma by iteratively ignoring outliers.

Parameters

img	Input image
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
kappa	Ignore (abs(value - mean) > kappa * sigma), must be >= 1.0
initial_limits	(Optional) double buffer of the form {l1, l2}, can be NULL, minimum/maximum order is irrelevant
nmax_iterations	Maximum number of iterations, must be >= 0
out_mean	(Optional) mean, can be NULL
out_sigma	(Optional) sigma, can be NULL
out_kappasigma	(Optional) kappa * sigma, can be NULL
out_nused	(Optional) number of remaining (used) pixels, can be NULL
out_niterations	(Optional) number of performed iterations, can be NULL

Returns

CPL error code

Principle:

• If initial_limits is given, only values in this intial interval are used for the inital mean and sigma computation. This does not mean however, that the solution diverges out of this interval and later converges to a new range.

Bad Pixel Handling:

Bad pixel maps are supported. This means that bad pixels are ignored during the computation.

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: image is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image plane
• CPL_ERROR_ILLEGAL_INPUT:
  • kappa < 1.0, or
  • nmax_iterations < 0, or
  • img contains less than 2 pixels
• CPL_ERROR_DATA_NOT_FOUND: less than 2 pixels are good
• CPL_ERROR_CONTINUE: all pixels were removed during iteration, please try a higher kappa (since kappa is limited to >= 1.0, this should normally not happen)

In the case of error, the following values are returned:

• out_mean: -1.0
• out_sigma: -1.0
• out_kappasigma: -1.0
• out_nused: 0
• out_niterations: 0

Todo:

• test initial_limits in unit test, and that they can be left

double clipm_priv_image_get_mean_perimeter	(	const void *	data,
		cpl_type	type,
		double	xc,
		double	yc,
		double	r,
		cpl_size	xsize,
		cpl_size	ysize,
		const cpl_binary *	badp,
		cpl_size *	nrpix
	)

Average values in a buffer along a perimeter.

Parameters

data	Data buffer (unchecked)
type	CPL data type
xc	X centre
yc	Y centre
r	Radius
xsize	X buffer size
ysize	Y buffer size
badp	(Optional) bad pixel buffer of type cpl_binary, can be NULL
nrpix	(Optional output) number of averaged pixels

Returns

Integral value

Error Handling:

The following error cases can happen:

• CPL_ERROR_DATA_NOT_FOUND: no pixels were integrated, e.g. due to bad pixels or out of range
• CPL_ERROR_INVALID_TYPE: the type is not int, float or double

cpl_error_code clipm_priv_image_get_psf_sigma	(	const cpl_image *	img,
		const cpl_size	window_xxyy[4],
		const double *	centre_xy,
		double	bg_level,
		double	cut_lower,
		double	cut_upper,
		double *	sigma_xy,
		double	gain,
		double *	centre_err_xy
	)

Compute the sigma (RMS) of an object (i.e. the PSF).

Parameters

img	Input image
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
centre_xy	Peak position (double buffer of length 2 [x, y])
bg_level	Input background level to subtract
cut_lower	Lower limit for values to be taken into account
cut_upper	Upper limit for values to be taken into account
sigma_xy	(Output) Mandatory (double) buffer of size 2 to contain the barycentre position after success
gain	(Optional) detector gain value (input), in unit "ADU / electron", required for the computation of centre_err_xy, will be ignored otherwise
centre_err_xy	(Optional output) contains the centre error after success (double buffer of length 2 [x, y]), needs the gain to be set (!), can be NULL

Returns

CPL error code

Principle:

The lateral sigma (or PSF sigma) on an object is computed (or in better words, the root mean square (RMS)). It assumes, that the centre has already been well determined.

Bad Pixel Handling:

Bad pixel maps are supported. This means that bad pixels are ignored during the computation.

Constraints:

• The object peak must be positive (brighter than the background).
• The image or image window size must be >= 3x3 pixels.
• If centre_err_xy is requested, gain must be > 0.
• Generally, at least 2 pixels must be not bad and fulfill cut_lower <= pixel <= cut_upper.
• Theoretically it is possible (although rarely the case) that extreme negative noise values can mess up the sigma computation.
• The integral of the signal divided by the gain must be positive

Error Handling:

The following errors can be set and returned:

• CPL_ERROR_NULL_INPUT:
  • image is NULL
  • centre_xy is NULL
  • sigma_xy is NULL
• CPL_ERROR_ILLEGAL_INPUT:
  • centre_err_xy is requested, but gain == 0.0
  • the image (window) size is not >= 3x3
  • cut_upper <= cut_lower
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image plane
• CPL_ERROR_DATA_NOT_FOUND: all pixels (except none or 1) are bad
• CPL_ERROR_DIVISION_BY_ZERO: not at least 2 pixels fulfilled cut_lower <= pixel <= cut_upper (not that a division by zero has occurred, just one error has to be used for it)
• CPL_ERROR_CONTINUE:
  • extreme noise outliers led to invalid sigma computation
  • centre_err_xy is requested and was tried to be computed, but the flux is not positive or not sufficient

In the case of error, the following values are returned:

• sigma_xy: {-1.0, -1.0}
• centre_err_xy: {-1.0, -1.0}

Todo:

:

• implement unit test

cpl_image* clipm_priv_image_get_sat	(	const cpl_image *	image,
		const int	window_xxyy[4],
		cpl_image **	contrib_sat
	)

cpl_size clipm_priv_image_pixel_count_below	(	const cpl_image *	img,
		const cpl_size	window_xxyy[4],
		double	limit,
		cpl_size *	out_nbad
	)

Count all the pixels (strictly) below a given limit.

Parameters

img	Input image
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
limit	Limit
out_nbad	(Optional output) number of bad pixels in image (window), returns -1 in the case of error

Returns

Number of pixels below limit, 0 in the case of error

Bad Pixel Handling:

Bad pixels are not counted.

Error Handling:

The following errors can occur:

• CPL_ERROR_NULL_INPUT: img is NULL
• CPL_ERROR_INVALID_TYPE: image is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window_xxyy specifies coordinates outside the image range