Routines (alphabetical) > Routines: L > LABEL_REGION

# LABEL_REGION

The LABEL_REGION function consecutively labels all of the regions, or blobs, of a bi-level image with a unique region index. This process is sometimes called “blob coloring”. A region is a set of non-zero pixels within a neighborhood around the pixel under examination.

The argument for LABEL_REGION is an n-dimensional bi-level integer type array—only zero and non-zero values are considered.

Note: Due to the 3x3 kernel used to identify regions, pixels located along the edge of an image (for example, a pixel that is within 1 pixel of the edge), may not be identified as a region.

Statistics on each of the regions may be easily calculated using the HISTOGRAM function as shown in the examples below.

## Examples

This example counts the number of distinct regions within an image, and their population. Note that region 0 will contain the edges of the shapes, while region 1 contains the background pixels of the image.

file = FILEPATH('rbcells.jpg', $

SUBDIR=['examples', 'data'])

READ_JPEG, file, img

; Use Sobel for edge detection,

; pick a nice threshold and convert to a 0/1 mask.

sbl = SOBEL(img) lt 200

; Surround the mask with a two-pixel border, so that

; all of the outside regions are marked as background.

sbl[*,0:1] = 1

sbl[*,-2:-1] = 1

sbl[0:1,*] = 1

sbl[-2:-1,*] = 1

; Label all of the individual regions.

; label[0] will be the edges,

; label[1] will be the background, etc.

label = LABEL_REGION(sbl)

; Count number of pixels in each region,

; ignore background and edges

h = HISTOGRAM(label, MIN=2, REVERSE_INDICES=r)

; Turn the edges into the highest value, so we can see them.

label[WHERE(label eq 0)] = MAX(label) + 1

i1 = IMAGE(img, LAYOUT=[4,1,1], DIM=[900,300], RGB_TABLE=56)

i2 = IMAGE(255b*(~sbl), LAYOUT=[4,1,2], /CURRENT, RGB_TABLE=56)

i3 = IMAGE(label, LAYOUT=[4,1,3], /CURRENT, $

RGB_TABLE=COLORTABLE(39,/REVERSE))

p = PLOT(REVERSE(h[SORT(h)]), XRANGE=[0,100], $

LAYOUT=[4,1,4], /CURRENT, MARGIN=[0.15,0.25,0.05,0.25], $

/HISTOGRAM, /FILL_BACKGROUND, $

XTITLE='Region', TITLE='# of pixels in each region')

; Print the mean and standard deviation of each region

FOR i=0, N_ELEMENTS(h)-1 DO if h[i] gt 200 then $

PRINT, 'Region ', i, ', Population = ', h[i], $

', Standard Deviation = ', STDEV(img[r[r[i]:r[i+1]-1]], mean), $

', Mean = ', mean

IDL prints:

Region 6, Population = 563, Standard Deviation = 48.3602, Mean = 141.748

Region 41, Population = 665, Standard Deviation = 46.2527, Mean = 137.786

Region 85, Population = 678, Standard Deviation = 43.7675, Mean = 142.531

...

## Syntax

Result = LABEL_REGION( Data [, /ALL_NEIGHBORS] [, /ULONG] )

## Return Value

The result of the function is an unsigned integer array of the same dimensions with each pixel containing its region index. A region index of zero indicates that the original pixel was zero and belongs to no region. Output values range from 0 to the number of regions.

Note: If the number of regions exceeds the maximum unsigned integer (65535) then IDL will throw an error. In this case you should call LABEL_REGION again with the ULONG keyword.

## Arguments

### Data

A n-dimensional image to be labeled. Data is converted to integer type if necessary. Pixels at the edges of Data are considered to be zero.

Tip: If Data is a temporary array (an expression) of type integer (or type long if ULONG is set) then LABEL_REGION will be able to re-use the array for the result and avoid using extra memory. See TEMPORARY for details on converting an array to a temporary variable.

## Keywords

### ALL_NEIGHBORS

Set this keyword to indicate that all adjacent neighbors to a given pixel should be searched. (This is sometimes called 8-neighbor searching when the image is 2-dimensional). The default is to search only the neighbors that are exactly one unit in distance from the current pixel (sometimes called 4-neighbor searching when the image is 2-dimensional).

### ULONG

Set this keyword to specify that the output array should be an unsigned long integer. You should use this keyword if you suspect that the number of regions will be greater than 65535. Note however that setting this keyword will produce an output array that uses twice as much memory.

## Version History

Pre 4.0 | Introduced
Pre 6.1 | Deprecated the EIGHT keyword

## See Also

HISTOGRAM, SEARCH2D, SOBEL, TEMPORARY