NAME

find_bright_spots_in_image - Finds bright spots in single image

SYNOPSIS

#include "seg/seg_spots.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


int find_bright_spots_in_image
(
	const KJB_image *img,
	const Matrix *background,
	const Matrix *thresholds,
	int min_brightness,
	int min_size,
	int max_size,
	double similarity,
	Int_matrix_vector **spots,
	Vector_vector **centroids
);

PARAMETERS

const KJB_image *img: image to be scanned
const Matrix *background: pixelwise non-bright baseline
const Matrix *thresholds: used to qualify brightest pixel B
int min_brightness: also qualifies brightest pixel B
int min_size: num. pixels in smallest spot
int max_size: num. pixels in largest spot
double similarity: factor of spot-pixel threshold
Int_matrix_vector **spots: Optional output matrices
Vector_vector **centroids: Mandatory output vectors

DESCRIPTION

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) spot. 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.

RETURNS

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.

find_bright_spots_in_image_sequence

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Ernesto Brau and Andrew Predoehl

DOCUMENTER