Aperture Characterisation

Classes
struct	clipm_match_circle_par_t

Macros
#define	clipm_aperture_DEBUG_IMGSAVE(image, name)

Typedefs
typedef struct clipm_match_circle_par_t	clipm_match_circle_par_t

Functions
cpl_error_code	clipm_aperture_detect_circles (const cpl_image *input, const cpl_size window_xxyy[4], cpl_matrix **out_circles)
	Detect circular apertures.
cpl_error_code	clipm_aperture_characterise_circular (const cpl_image *input, const cpl_size window_xxyy[4], double *out_centre_x, double *out_centre_y, double *out_radius, double *out_r_sigma, cpl_matrix **statistics)
	Characterise a circular aperture.
cpl_error_code	clipm_aperture_characterise_rectangular (const cpl_image *input, const cpl_size window_xxyy[4], double *centre_x, double *centre_y, double *angle, double *length, double *width, cpl_matrix **statistics)
	Characterise a rectangular aperture. PROTOTYPE ONLY, NO IMPLEMENTATION YET.
cpl_error_code	clipm_aperture_characterise_square (const cpl_image *input, const int window_xxyy[4], cpl_vector **out_centre_coord, double *out_size, double *out_angle, cpl_mask **out_mask, cpl_stats **out_statistics, unsigned stats_bitmask)
	Characterise a square aperture. PROTOTYPE ONLY, NO IMPLEMENTATION YET.
cpl_error_code	clipm_aperture_slitpos (cpl_image *input, int max_width, double *out_x_centre, double *out_y_centre, double *out_angle, cpl_size *out_y_size)
	Get a slit position.
cpl_matrix *	clipm_aperture_get_rectangle_corners (double centre_x, double centre_y, double angle, double length, double width)
	Create a matrix with 4 corner positions of a rectangle.

Detailed Description

This module provides functions for the characterization of image objects (apertures).

Synopsis:

#include "ifw/odp/clipm/clipm_aperture.h"

Macro Definition Documentation

clipm_aperture_DEBUG_IMGSAVE

#define clipm_aperture_DEBUG_IMGSAVE	(		image,
			name )

Typedef Documentation

clipm_match_circle_par_t

typedef struct clipm_match_circle_par_t clipm_match_circle_par_t

Function Documentation

clipm_aperture_characterise_circular()

cpl_error_code clipm_aperture_characterise_circular	(	const cpl_image *	input,
		const cpl_size	window_xxyy[4],
		double *	out_centre_x,
		double *	out_centre_y,
		double *	out_radius,
		double *	out_r_sigma,
		cpl_matrix **	statistics )

Characterise a circular aperture.

Parameters

input	Input image (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
out_centre_x	(Optional output) x centre
out_centre_y	(Optional output) y centre
out_radius	(Optional output) radius
out_r_sigma	(Optional output) sigma of the radius' edge
statistics	Optional output statistics, can be NULL

Returns

CPL error code

Principle:

• A circular aperture is investigated. For more information about the search algorithm, please refer to clipm_aperture_detect_circles(). Only one aperture is returned.
• The regarded area is specified by window coordinates as mentioned above. If it is NULL, then the whole image is regarded.
• If successful, circle_params contains a vector containing the values {x_centre, y_centre, radius, radius_sigma}. radius_sigma means the sigma of absolute gradient's radial function at the aperture's edge.
• Statistics are computed and returned if statistics is not NULL. It is returned as a 2-column matrix. The first column (index 0) contains the mean, the median and the standard deviation inside the aperture, and the second column (index 1) contains the same for the backgound. Like following:
  
  

  Column	0: Aperture	1: Background
  Row 0: Mean	...	...
  Row 1: Median	...	...
  Row 2: Standard Deviation	...	...

  
  
  The number of rows in the matrix should not be taken as fixed. It could increase by future requests.
• The statistics are computed using:
  0.) the inner part of the aperture (i.e. inside radius - 3* radius_sigma)
  1.) the background (i.e. outside radius + 3* radius_sigma)

Error Handling:

The following error cases might happen, the respective code will then be set and returned:

• CPL_ERROR_NULL_INPUT: input image or circle_params is NULL
• CPL_ERROR_INVALID_TYPE: the passed image type is not supported
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window exceeds the image range
• CPL_ERROR_DATA_NOT_FOUND: no circular aperture could be found

Example:

#include <cpl.h>
#include <clipm.h>
#include <stdio.h>
 
void my_circles(            cpl_image   *image,
                            int         xmin,
                            int         ymin,
                            int         xmax,
                            int         ymax)
{
    cpl_vector      *circle = NULL;
    cpl_matrix      *stats = NULL;
    int             window[4];
    
    window[0] = xmin;
    window[1] = xmax;
    window[2] = ymin;
    window[3] = ymax;
    
    clipm_aperture_characterise_circular(
                            image,
                            window,
                            &circle,
                            &stats);
    
    if (circle != NULL)
    {
        printf(             "circle at [x, y] = [%.2f, %.2f],"
                            cpl_vector_get(circle, 0),
                            cpl_vector_get(circle, 1));
        printf(             " radius = %.2f\n",
                            cpl_vector_get(circle, 2));
        printf(             "median of circle: %.2f\n",
                            cpl_matrix_get(stats, 1, 0));
        printf(             "median of background: %.2f\n",
                            cpl_matrix_get(stats, 1, 1));
        cpl_vector_delete(circle);
        cpl_apertures_delete(stats);
    }
    else
    {
        printf(             "no circle found\n");
    }
}

Todo

• Export statistics computation into other function
• check bad pixel handling

clipm_aperture_characterise_rectangular()

cpl_error_code clipm_aperture_characterise_rectangular	(	const cpl_image *	input,
		const cpl_size	window_xxyy[4],
		double *	centre_x,
		double *	centre_y,
		double *	angle,
		double *	length,
		double *	width,
		cpl_matrix **	statistics )

Characterise a rectangular aperture. PROTOTYPE ONLY, NO IMPLEMENTATION YET.

Parameters

input	Input image (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
centre_x	(Optional output) x centre
centre_y	(Optional output) y centre
angle	(Optional output) angle (mathematically positive, i.e. counterclockwise)
length	(Optional output) length (in direction of angle)
width	(Optional output) width
statistics	(Optional output) statistics, can be NULL

Returns

CPL error code

Principle:

• A rectangular aperture is investigated. The rough steps are:
  • the gradient orientation is analyzed,
  • the image (window) is rotated,
  • the centre of the object is found,
  • the FWHM is searched in x and y to find the object's size,
  • the signal is collapsed in the object range,
  • the FWHM is searched again,
  • statistics are computed (if requested) excluding the object's edge.
• The regarded area is specified by window coordinates as mentioned above. If it is NULL, then the whole image is regarded.
• Statistics are computed and returned if statistics is not NULL. It is returned as a 2-column matrix. The first column (index 0) contains the mean, the median and the standard deviation inside the aperture, and the second column (index 1) contains the same for the backgound. Like following:
  
  

  Column	0: Aperture	1: Background
  Row 0: Mean	...	...
  Row 1: Median	...	...
  Row 2: Standard Deviation	...	...

  
  
  The number of rows in the matrix should not be taken as fixed. It could increase by future requests.
• The statistics are computed using:
  0.) the inner part of the aperture (i.e. inside radius - 3* radius_sigma)
  1.) the background (i.e. outside radius + 3* radius_sigma)

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: input image is NULL
• CPL_ERROR_ACCESS_OUT_OF_RANGE: a window coordinate is outside the image range
• CPL_ERROR_INVALID_TYPE: input is neither of type CPL_TYPE_INT, CPL_TYPE_FLOAT, nor of type CPL_TYPE_DOUBLE
• CPL_ERROR_CONTINUE:
  • no rectangular object could be found, or
  • the object was found but the statistics computation failed
• CPL_ERROR_DATA_NOT_FOUND:
  • less than 5 pixels in the image (window) are good

Todo

• If input is integer, convert rotated to double inside clipm_priv_image_lineartrans_bilinear()
• Improve object detection step: just taking the barycentre is poor...:-(
• Export statistics computation into other function
• create a fitting routine to optimize the result (or alternatively, measure the angle again in the region around the rectangle, then correct)
• document bad pixel handling

clipm_aperture_characterise_square()

cpl_error_code clipm_aperture_characterise_square	(	const cpl_image *	input,
		const int	window_xxyy[4],
		cpl_vector **	out_centre_coord,
		double *	out_size,
		double *	out_angle,
		cpl_mask **	out_mask,
		cpl_stats **	out_statistics,
		unsigned	stats_bitmask )

Characterise a square aperture. PROTOTYPE ONLY, NO IMPLEMENTATION YET.

Parameters

input	Input image (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
out_centre_coord	Output centre coordinate
out_size	Output aperture size (edge length)
out_angle	Output rotation angle
out_mask	Optional output pixel mask, can be NULL
out_statistics	Optional output statistics, can be NULL
stats_bitmask	Statistics type definition

Returns

CPL error code

clipm_aperture_detect_circles()

cpl_error_code clipm_aperture_detect_circles	(	const cpl_image *	input,
		const cpl_size	window_xxyy[4],
		cpl_matrix **	out_circles )

Detect circular apertures.

Parameters

input	Input image (FITS convention)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
out_circles	Output matrix containing the circle parameters for every found aperture (see below), NULL in the case of error

Returns

CPL error code

Interface:

• In an image or an image window, circular apertures are searched.
• The regarded area is specified by window coordinates as mentioned above. If it is NULL, then the whole image is regarded.
• out_circles returns a 5-row matrix, containing 1 column for every found aperture, containing the following values:
  • x centre
  • y centre
  • radius
  • radius sigma (i.e. the 1-sigma of the gradient's peak shape in radial direction, not the uncertainty)
  • gradient peak intensity (the maximum of the gradient's mean along the perimeter, i.e. the gradient's mean along the perimeter at the returned radius)

Purpose:

• The algorithm is designed to find flat, circular apertures - this means round objects with an edge.
• The circular edge of the aperture does not need to be complete. A half-circle is already sufficient.
• Star-like objects or objects with a Gaussian shape should rather be characterized using for example clipm_centroiding_gauss().
• Single bright pixels are not in the focus, but might theoretically be found if there is no other image information. So, bad pixels should be interpolated before using this function.

Algorithm Principle:

• The applied algorithm is a gradient transformation, creating probabilities for all the pixels for being the center of a circle. Peaks in this probability map are found, and from their point of view the radius is determined.
• This means, that each pixel's probability for being a centre, takes into account all other pixels. The algorithm is optimized to a complexity of N*sqrt(N), but still it is obvious that:
  1. the complexity indicates a usage on limited image windows, and
  2. images containing many different objects with high gradients can distort the internal probablity computation, a limited number of objects in the image window is recommended,
  3. but generally it is possible to have multiple objects in a window.
• The returned radius indicates the perimeter distance at which the highest average gradient is found.
• The centres and radiuses are optimized until the accuracy is better than 1/20 of a pixel. This accuracy is of course only meaningful, if the aperture has a clear border.

Constraints:

• Only apertures with a centroid inside the image or image window are returned.
• Only apertures which are brighter than the background are searched.

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: input or out_circles is NULL
• CPL_ERROR_INVALID_TYPE: the passed image type is not supported
• CPL_ERROR_ACCESS_OUT_OF_RANGE: window exceeds the image range
• CPL_ERROR_DATA_NOT_FOUND: no circular aperture could be found

Todo

• try clipm_image_signal_estimate_bg_in_region() for the Background Sigma Estimation
• split up the function into more atomic parts
• check bad pixel handling

clipm_aperture_get_rectangle_corners()

cpl_matrix * clipm_aperture_get_rectangle_corners	(	double	centre_x,
		double	centre_y,
		double	angle,
		double	length,
		double	width )

Create a matrix with 4 corner positions of a rectangle.

Parameters

centre_x	X centre position
centre_y	Y centre position
angle	Orientation (mathematically positive, i.e. counterclockwise)
length	Length, in the direction of angle
width	Width

Returns

The resulting 2x4 matrix, containing (x,y) tuples in 4 columns.

Error Handling:

No error case is foreseen in this function.

clipm_aperture_slitpos()

cpl_error_code clipm_aperture_slitpos	(	cpl_image *	input,
		int	max_width,
		double *	out_x_centre,
		double *	out_y_centre,
		double *	out_angle,
		cpl_size *	out_y_size )

Get a slit position.

Parameters

input	Input image (FITS convention)
max_width	Maximum slit width
out_x_centre	Output central x position
out_y_centre	Output central y position
out_angle	Output angle (mathematically positive) 0...Pi
out_y_size	Output number of image lines

Returns

CPL error code

Principle:

• A rectangular slit is analysed. The central line is determined, and described by a centre point and the orientation.
• The slit is assumed to be approximately vertical, i.e. that the image rows are crossing the slit.
• The approximate vertical expansion is returned via out_y_size.
• The centre position is determined and put out. Since the slit ending positions are not determined exactly in a sub-pixel way, the centre position actually is on the central slit line, but it might be shifted by small fractions in the slit's orientation.
• The physical slit length can roughly be estimated by

  ((*out_y_size) / sin(*out_angle))

Error Handling:

The following error codes can be set and returned:

• CPL_ERROR_NULL_INPUT: any of the input/output pointers is NULL
• CPL_ERROR_INVALID_TYPE: input is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE
• CPL_ERROR_DATA_NOT_FOUND: the slit was not found in the image