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