scipy.ndimage.

label#

scipy.ndimage.label(input, structure=None, output=None)[source]#

Label features in an array.

Parameters:

inputarray_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.

structurearray_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:

labelndarray or int

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

num_featuresint

How many objects were found.

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

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

See also

find_objects: generate a list of slices for the labeled features (or objects); useful for finding features’ position or dimensions

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.

Array API Standard Support

label has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

Library	CPU	GPU
NumPy	✅	n/a
CuPy	n/a	✅
PyTorch	✅	⛔
JAX	⚠️ no JIT	⛔
Dask	⚠️ computes graph	n/a

See Support for the array API standard for more information.

References

[1]

James R. Weaver, “Centrosymmetric (cross-symmetric) matrices, their basic properties, eigenvalues, and eigenvectors.” The American Mathematical Monthly 92.10 (1985): 711-717.

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
4
>>> 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
2
>>> 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)