SciPy - ndimage.label() Function

The scipy.ndimage.label() is a function in the scipy.ndimage module which is used to perform connected component labeling on a binary image. It labels distinct connected components in the input array based on the given connectivity such as 4-connectivity, 8-connectivity, etc.

The purpose of connected component labeling is to identify and label separate regions i.e., objects in a binary image. Each connected region is assigned a unique integer label which can then be used for further analysis such as object counting or region analysis.

This function works on binary images where non-zero elements are treated as foreground i.e., part of a connected component and zero elements are treated as the background.

Syntax

Following is the syntax of the function scipy.ndimage.label() to perform connected component labeling operation on the input image −

scipy.ndimage.label(input, structure=None, output=None)

Parameters

Following are the parameters of the scipy.ndimage.label() function −

• input: The input binary image (array) on which connected component labeling is applied. It can be a 2D or 3D binary array.
• structure (optional): The structuring element that defines the connectivity of the components. It is a binary array of the same shape as the input. If not specified the function uses a default structure representing 4-connectivity in 2D or 6-connectivity in 3D.
• output (optional): The array where the result of the operation is stored. If not specified then a new array is created.

Return Value

The scipy.ndimage.label() function returns two values as mentioned below −

• labeled_array: A labeled array of the same shape as the input where each connected component is assigned a unique integer label.
• num_features: The total number of connected components found in the input image.

Labeling Connected Components

Connected component labeling is commonly used in image analysis to identify distinct objects or regions. This function assigns each connected component a unique label which can then be used for counting, feature extraction or region-based analysis.

Below is an example that shows how to use scipy.ndimage.label() for labeling connected components in a binary image −

import numpy as np
from scipy.ndimage import label

# Create a binary image with connected components (2D)
binary_image = np.array([[0, 1, 1, 0],
                         [1, 1, 0, 0],
                         [0, 0, 1, 1],
                         [0, 1, 1, 0]])

# Perform connected component labeling
labeled_array, num_features = label(binary_image)

# Print the results
print("Labeled Array:")
print(labeled_array)
print("Number of Features:", num_features)

Here is the output of the function scipy.ndimage.label() used for connected component labeling in a 2D binary image −

Labeled Array:
[[0 1 1 0]
 [1 1 0 0]
 [0 0 2 2]
 [0 2 2 0]]
Number of Features: 2

Using Custom Connectivity

Connected component labeling can also be customized by specifying the connectivity structure using the structure parameter. In this example we will apply 8-connectivity to label connected components in a 2D image −

import numpy as np
from scipy.ndimage import label

# Create a binary image with connected components (2D)
binary_image = np.array([[0, 1, 1, 0],
                         [1, 1, 0, 0],
                         [0, 0, 1, 1],
                         [0, 1, 1, 0]])

# Define 8-connectivity structure
structure = np.array([[1, 1, 1],
                      [1, 1, 1],
                      [1, 1, 1]])

# Perform connected component labeling with 8-connectivity
labeled_array, num_features = label(binary_image, structure=structure)

# Print the results
print("Labeled Array (8-Connectivity):")
print(labeled_array)
print("Number of Features:", num_features)

Here is the output of the function scipy.ndimage.label() when 8-connectivity is used −

Labeled Array (8-Connectivity):
[[0 1 1 0]
 [1 1 0 0]
 [0 0 1 1]
 [0 1 1 0]]
Number of Features: 1

Labeling a 3D Volume

The scipy.ndimage.label() function can also be applied to 3D binary arrays. Below is an example that shows how to label connected components in a 3D volume −

import numpy as np
from scipy.ndimage import label

# 3D binary image
binary_volume = np.array([[[0, 1, 1],
                           [1, 1, 0],
                           [0, 0, 0]],
                          
                          [[1, 1, 0],
                           [0, 1, 1],
                           [0, 0, 0]],
                          
                          [[0, 0, 0],
                           [0, 1, 1],
                           [1, 1, 0]]])

# Perform labeling in 3D
labeled_volume, num_features = label(binary_volume)

# Print the results
print("Labeled Volume:")
print(labeled_volume)
print("Number of Features:", num_features)

Here is the output of the function scipy.ndimage.label() applied to a 3D volume −

Labeled Array (8-Connectivity):
[[0 1 1 0]
 [1 1 0 0]
 [0 0 1 1]
 [0 1 1 0]]
Number of Features: 1
PS D:\Tutorialspoint> python sample.py
Labeled Volume:
[[[0 1 1]
  [1 1 0]
  [0 0 0]]

 [[1 1 0]
  [0 1 1]
  [0 0 0]]

 [[0 0 0]
  [0 1 1]
  [1 1 0]]]
Number of Features: 1