NAME
label_four_connected_regions - Binary connected component labeling using 4-connectivity definition.
SYNOPSIS
#include "seg/seg_connected_components.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 label_four_connected_regions
(
Int_matrix **out_mpp,
KJB_region_list **region_list_rlpp,
Segmentation_t3 **segmentation_ptr_ptr,
int *num_regions_intp,
int *max_label_intp,
const KJB_image *in_ip,
const Int_matrix *in_mp,
const int merge_eqvlnt_labels
);
DESCRIPTION
This routine does connected component labeling using 4-connectivity
definition. It employs a custom data structure (KJB_region) to achieve fast
connected component labeling by doing only one pass through the image. The
custom data structure is designed so that all the information required to
uniquely label the 4-connected regions in the image is available after a
single raster scan.
The input binary image contained in in_mp is assumed to be an Int_matrix with
foreground pixels represented by non-zero integers. All the foreground
connected components are labeled by this routine.
The argument region_list_rlpp is a pointer to a pointer to custom data
type named KJB_region_list. The data structure KJB_region_list encloses an
array of elements of type KJB_region. If it is not NULL, then it is resized
by the routine to contain (ceil(num_rows*num_cols/2) + 1) elements. If it is
NULL, then a local KJB_region_list is allocated and deallocated when done.
This is to give the user the option of passing in an appropriately pre-allocated
KJB_region_list and cutting down on the time spent in memory allocation within the
routine. This might be helpful in cases where the routine is called repeatedly
from a higher level routine using different input images of the same size
but with the same pre-allocated KJB_region_list to re-use memory.
The allocation size is related to the fact that the maximum number of
4-connected components in an image is ceil(num_rows*num_cols/2) plus one
for the background component.
segmentation_ptr_ptr is used to store information about individual
connected components in the image. It is a pointer to a pointer to a
Segmentation_t3 data structure. If it is not NULL, then an input image,
which is the source for binary image in_mp, must be passed to this routine
through the in_ip argument. in_ip is used in computing a number of useful
properties for each component. Otherwise the routine returns an ERROR with an
appropriate error message being set. If segmentation_ptr_ptr is NULL, then
no information about individual connected components is computed to store into
that data structure.
The labeled image with a unique positive integer label for each foreground
pixel is returned in out_mpp. It is allocated or resized to the same size
as the input image following the semantics of the KJB library. If
merge_eqvlnt_labels is set to 1, then a unique label is assigned to all
the pixels of a connected component and the unique labels are consecutive
positive integers (1, 2, ....) for the different components. Otherwise a
unique label is not guaranteed for all the pixels of a connected
component. However the distinct labels are equivalent and can be resolved
using the (*region_list_rlpp) array, when region_list_rlpp is not NULL.
The output parameter (*num_regions_intp) stores the total number of
connected components in the image. max_label_intp points to an integer
that is the maximum label value among all pixels in the output image before
the equivalent labels are resolved.
The fast labeling algorithm is an extension of the region coloring
algorithm proposed by Ballard and Brown:
D.H. Ballard and C.M. Brown, "Computer Vision", Prentice Hall, NJ, 1982.
The work in the following paper served as a starting point for thoughts on
ways to extend the basic region coloring algorithm:
A. Amir, L. Zimet, A. Sangiovanni-Vincentelli,and S. Kao, "An embedded
system for an eye-detection sensor", CVIU, 98(1):104-123, April 2005.
RETURNS
On error this routine returns ERROR.
On success it returns NO_ERROR.
WARNING
This routine results in memory leaks when fails to execute completely.
DISCLAIMER
This software is not adequatedly tested. It is recomended that
results are checked independantly where appropriate.
AUTHOR
Kobus Barnard
DOCUMENTER
Kobus Barnard
SEE ALSO
get_target_region_list
,
free_region_list
,
label_eight_connected_regions