Functions
double	clipm_image_signal_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_image_signal_estimate_fwhm_round (const cpl_image *img, double x_peakpos, double y_peakpos, double bg_level)
	Estimate the FWHM of a round object. More...

cpl_error_code	clipm_image_signal_get_barycentre (const cpl_image img, const cpl_size window_xxyy[4], double bg_level, double lower_cutlevel, double out_xy_centre, double out_weight, cpl_size out_nused)
	Compute the barycentre of an object. More...

Detailed Description

This module provides image signal processing functions.

Function Documentation

double clipm_image_signal_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

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:

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_image_signal_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

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_image_signal_get_barycentre	(	const cpl_image *	img,
		const cpl_size	window_xxyy[4],
		double	bg_level,
		double	lower_cutlevel,
		double *	out_xy_centre,
		double *	out_weight,
		cpl_size *	out_nused
	)

Compute the barycentre of an object.

Parameters

img	Input image
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
bg_level	Input background level to subtract
lower_cutlevel	Lower limit of values to use (separately from bg_level) (values can be equal to or greater)
out_xy_centre	Mandatory (double) buffer of size 2 to contain the barycentre position after success
out_weight	(Optional) output weight of the peak, can be NULL
out_nused	(Optional) output number of used values, can be NULL

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

Note: With a combination of positive and negative values in the image, it is possible that the returned barycentre is outside the image. If not tolerated, this should be checked afterwards. This can be avoided by ensuring lower_cutlevel >= bg_level.

Error Handling:

The following errors 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: all pixels are bad
CPL_ERROR_DIVISION_BY_ZERO:
- no pixel was above lower_cutlevel (not that a division by zero has occurred, just one error has to be used for it)
- the sum over the signal is close to zero

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

: