find_bright_spots_in_image - Finds bright spots in single image
Example compile flags (system dependent):
-DLINUX_X86_64 -DLINUX_X86_64_OPTERON -DGNU_COMPILER
-lKJB -lfftw3 -lgsl -lgslcblas -ljpeg -lSVM -lstdc++ -lpthread -lSLATEC -lg2c -lacml -lacml_mv -lblas -lg2c -lncursesw
const KJB_image *img,
const Matrix *background,
const Matrix *thresholds,
const KJB_image *img
image to be scanned
const Matrix *background
pixelwise non-bright baseline
const Matrix *thresholds
used to qualify brightest pixel B
also qualifies brightest pixel B
num. pixels in smallest spot
num. pixels in largest spot
factor of spot-pixel threshold
Optional output matrices
Mandatory output vectors
This accepts a single image and finds local neighborhoods of pixels that are
all "bright" according to the complicated definition below -- basically,
exceeding a relative threshold determined from inputs 'background,'
'thresholds,' 'min_brightness' and 'similarity.' The only shape constraint
on the neighborhoods is that they must be 8-connected regions of pixels,
within a given size range, i.e., a feasible pixel count.
The image is converted to a matrix by uniform (!) weighting of RGB channels.
Then the background matrix is subtracted, element-wise. You, the caller,
might prepare this matrix as the elementwise arithmetic average of pixel
intensities in a series. After subtracting, we search the image and locate
the pixel B (for bright) with the highest remaining intensity, i.e., B has
the biggest intensity shift above the background value. Pixel B is used to
judge whether the input image is "bright enough" to process. There are two
requirements to be "bright enough." First, the intensity of 'img' at
location B must equal or exceed 'min_brightness.' Second, the magnitude of
the intensity shift above background at location B must equal or exceed the
value of 'thresholds' at location B. If both are true, the image is
bright enough that it might generate bright spots. Otherwise, 'img' is not
bright enough: the function immediately returns NO_ERROR, and the output
containers are empty (although they still must be freed by you, the caller).
The 'thresholds' matrix contains local threshold values at each pixel
location. You, the caller, might compute this matrix as the element-wise
standard deviations of the pixel intensities in a series, or a scaled
version thereof, or something similar. It does not represent a threshold
value for all bright pixels, just a threshold value to be compared with
relatively bright pixel B.
An image pixel is intense enough to be a candidate for a bright spot if its
intensity shift above background exceeds the product of 'similarity' times
the intensity shift above background at B. Thus 'similarity' should be a
positive value typically less than 1. (A 'similarity' value above 1 is
silently clipped back to 1.) Such pixels are grouped into eight-connected
regions. If the region's total size (i.e., its pixel count) is at least
'min_size' and at most 'max_size' then it is formally considered a (bright)
The function produces two kinds of output. The first output, *spots, is
optional, listing the exact positions of all spot pixels. The second
output, *centroids, is required, listing the position of each spot's center
of mass. If the pixel coordinates are not required, you can call the
routine with 'spots' equal to NULL. You, the caller, of course have
ownership of the output container object(s) and must free them, whether
or not the image has any bright spots of acceptable size.
To elaborate: at successful exit,
(*centroids)->length contains the number of spots that were detected.
The centroid of the pixels of the i-th spot can then be found in
(*centroids)->elements[i], which points to a 2-element Vector. Its index-0
and index-1 elements contain, respectively, the centroid X and Y coords.
If parameter 'spots' does not equal NULL, then at successful
exit, *spots points to an array of Int_matrix objects. Then,
(*spots)->elements[i] points to an M-by-2 Int_matrix, where M is the number
of pixels in the i-th spot. Row k, column 0 contains the k-th pixel's X
coordinate, and row k column 1 contains its Y coordinate.
On error this routine returns ERROR with an error message being set.
On success it returns NO_ERROR. Absence of bright spots is not an error.
This software is not adequatedly tested. It is recomended that
results are checked independantly where appropriate.
Ernesto Brau and Andrew Predoehl
Ernesto Brau and Andrew Predoehl