scipy.ndimage.label

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

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.

References

1(1,2)

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
>>> 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]])

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]])