bundles / scipy 2.0.0.dev0+git20260907.41eeb59 / scipy / ndimage / _measurements / label

function

`scipy.ndimage._measurements:label`

source: build-install/usr/lib/python3.14/site-packages/scipy/ndimage/_measurements.py:43

Signature

def label(input, structure = None, output = None)

Summary

Label features in an array.

Parameters

input : array_like

An array-like object to be labeled. Any non-zero values in input are counted as features and zero values are considered the background.

structure : array_like, optional

A structuring element that defines feature connections. structure must be centrosymmetric (see Notes). If no structuring element is provided, one is automatically generated with a squared connectivity equal to one. That is, for a 2-D input array, the default structuring element is

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

output : (None, data-type, array_like), optional

If output is a data type, it specifies the type of the resulting labeled feature array. If output is an array-like object, then output will be updated with the labeled features from this function. This function can operate in-place, by passing output=input. Note that the output must be able to store the largest label, or this function will raise an Exception.

Returns

label : ndarray or int

An integer ndarray where each unique feature in input has a unique label in the returned array.

num_features : int

How many objects were found.

If output is None, this function returns a tuple of (labeled_array, num_features).

If output is an ndarray, then it will be updated with values in labeled_array and only num_features will be returned by this function.

Notes

A centrosymmetric matrix is a matrix that is symmetric about the center. See ^[1] for more information.

The structure matrix must be centrosymmetric to ensure two-way connections. For instance, if the structure matrix is not centrosymmetric and is defined as

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

and the input is

[[1,2],
 [0,3]]

then the structure matrix would indicate the entry 2 in the input is connected to 1, but 1 is not connected to 2.

Examples

Create an image with some features, then label it using the default (cross-shaped) structuring element:

from scipy.ndimage import label, generate_binary_structure
import numpy as np
a = np.array([[0,0,1,1,0,0],
              [0,0,0,1,0,0],
              [1,1,0,0,1,0],
              [0,0,0,1,0,0]])
labeled_array, num_features = label(a)

✓

Each of the 4 features are labeled with a different integer:

num_features
labeled_array

✓

array([[0, 0, 1, 1, 0, 0],
       [0, 0, 0, 1, 0, 0],
       [2, 2, 0, 0, 3, 0],
       [0, 0, 0, 4, 0, 0]], dtype=int32)

Generate a structuring element that will consider features connected even if they touch diagonally:

s = generate_binary_structure(2,2)

✓

or,

s = [[1,1,1],
     [1,1,1],
     [1,1,1]]

✓

Label the image using the new structuring element:

labeled_array, num_features = label(a, structure=s)

✓

Show the 2 labeled features (note that features 1, 3, and 4 from above are now considered a single feature):

num_features
labeled_array

✓

array([[0, 0, 1, 1, 0, 0],
       [0, 0, 0, 1, 0, 0],
       [2, 2, 0, 0, 1, 0],
       [0, 0, 0, 1, 0, 0]], dtype=int32)

Aliases

scipy.ndimage.label