scipy.ndimage.label¶

scipy.ndimage.
label
(input, structure=None, output=None)[source]¶ Label features in an array.
 Parameters
 inputarray_like
An arraylike object to be labeled. Any nonzero 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 2D input array, the default structuring element is:
[[0,1,0], [1,1,1], [0,1,0]]
 output(None, datatype, array_like), optional
If output is a data type, it specifies the type of the resulting labeled feature array. If output is an arraylike object, then output will be updated with the labeled features from this function. This function can operate inplace, 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 twoway 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
James R. Weaver, “Centrosymmetric (crosssymmetric) matrices, their basic properties, eigenvalues, and eigenvectors.” The American Mathematical Monthly 92.10 (1985): 711717.
Examples
Create an image with some features, then label it using the default (crossshaped) 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]])