clipm_priv_vgit.c File Reference

#include "clipm_priv_vgit.h"
#include "clipm_math.h"
#include "clipm_math_rng.h"
#include "clipm_compatibility_replacements.h"
#include "clipm_priv_error.h"
#include "clipm_priv_image.h"

Macros
#define	clipm_priv_vgit_BODY(TYPE)

Functions
cpl_image *	clipm_priv_vgit_get_noise_dark (cpl_size xsize, cpl_size ysize)
	Generate a background for the VGI Transformation. More...
cpl_image *	clipm_priv_vgit (const cpl_image *gradient_angles, const cpl_image *absolute_gradient, int nr_angle_bins, double angle_tolerance, int use_median, int correct_background)
	Perform the Vector Gradient Intersection Transform (VGIT). More...

Macro Definition Documentation

#define clipm_priv_vgit_BODY

(

TYPE

)

Function Documentation

cpl_image* clipm_priv_vgit	(	const cpl_image *	gradient_angles,
		const cpl_image *	absolute_gradient,
		int	nr_angle_bins,
		double	angle_tolerance,
		int	use_median,
		int	correct_background
	)

Perform the Vector Gradient Intersection Transform (VGIT).

Parameters

gradient_angles	Image containing a gradient angle field
absolute_gradient	Image containing an absolute gradients field
nr_angle_bins	Number of angle bins per quadrant
angle_tolerance	Angular deviation sigma to be taken into account
use_median	Flag whether the result should be combined by taking the mean of the angle bins (0), or by taking the median of the angle bins (!= 0)
correct_background	Flag whether to subtract the background noise probability

Returns

Image of type CPL_TYPE_FLOAT containing peaks where centers of circles are located

Principle:

This function performs the a circle detection algorithm, called the VGIT. It consists of the following steps:

1. As input, the gradients of an image are taken. For generating image gradients, have a look at the function clipm_image_compute_gradient().
2. 2 * nr_angle_bins container frames are generated. The angles of the input gradients are mapped to respectively one frame, the range between 0 and Pi/2 is divided into nr_angle_bins bins, and the range between Pi/2 and Pi is divided into another nr_angle_bins bins. Angles between Pi and 2 Pi are mapped to their opposite one.
3. At every pixel position, the respective container frame is selected. In this frame, a light ray cone is drawn (with the spreading angle angle_tolerance) from this respective pixel position into the direction of the gradient, weighted by the gradient's intensity, by adding it to the pixel values. Oppositely oriented light cones are drawn into the same frame.
4. Every 2 frames which belong to perpendicular orientations are multiplied. This process generates peaks where perpendicular light cones are crossing each other, especially in the center of circles. The number of frames thus decreases from 2 * nr_angle_ranges to only 1 * nr_angle_ranges.
5. The remaining frames, containing peaks at all light cone intersections, are then combined. If use_median != 0, then the combination is done by taking the median values, otherwise by taking the average values. This combined image is the returned image containing peaks wherever directions of gradients are crossing each other perpendicularly.
6. If correct_background is != 0, then additionally the following background subtraction is performed:
   • The theoretical background noise probability is computed using the function clipm_priv_vgit_get_noise_dark().
   • At 100 random positions, the ratio between the theoretical background and the real peak image is computed.
   • The median of these ratios is selected, and used for correcting the brightness of the theoretical background. This is then subtracted from the real peak image.
   • Note: this is quite slow, since the theoretical background can only be numerically simulated.

Constraints:

• nr_angle_bins >= 1
• 0 <= angle_tolerance <= Pi/8, for performance reasons
• gradient_angles and absolute_gradient must be either both of type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.
• The "light cones" are drawn without pixel interpolation, for performance reasons. Other geometrical distortions in the image cause amplified distortions and noise in the peak images, which is normally well suppressed if the median is used for the combination. Nevertheless, because these influences are typically far beyond the precision of double number values, and because the calculation with double numbers is very often about 2 times slower than with float numbers, the produces output image is always of type CPL_TYPE_FLOAT.

Error Handling:

The following errors can occur:

• CPL_ERROR_NULL_INPUT: gradient_angles or absolute_gradient are NULL.
• CPL_ERROR_INCOMPATIBLE_INPUT: gradient_angles or absolute_gradient have different sizes or types.
• CPL_ERROR_ILLEGAL_INPUT: nr_angle_bins < 1, or angle_tolerance < 0, or angle_tolerance > Pi/8.
• CPL_ERROR_INVALID_TYPE: gradient_angles and absolute_gradient are not of type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

cpl_image* clipm_priv_vgit_get_noise_dark	(	cpl_size	xsize,
		cpl_size	ysize
	)

Generate a background for the VGI Transformation.

Parameters

xsize	Horizontal image size
ysize	Vertical image size

Returns

The background image of type CPL_TYPE_FLOAT, NULL in the case of error

Principle:

This function generates an image containing the general probabilities which are produced by background noise in the VGI Transform. This is intended to model the noise background, but its weight has to be adapted.

It is generated of the type CPL_TYPE_FLOAT, because the function clipm_priv_vgit() also only generates its output of this type.

Error Handling:

Possible error codes set by this function:

• CPL_IMAGE_ILLEGAL_INPUT: xsize or ysize are < 1