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 ininput arecounted 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 toone. That is, for a 2-Dinput array, the default structuring elementis:

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

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

Ifoutput is a data type, it specifies the type of the resultinglabeled feature array.Ifoutput is an array-like object, thenoutput will be updatedwith the labeled features from this function. This function canoperate in-place, by passing output=input.Note that the output must be able to store the largest label, or thisfunction will raise an Exception.

Returns:

labelndarray or int

An integer ndarray where each unique feature ininput has a uniquelabel in the returned array.

num_featuresint

How many objects were found.

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

Ifoutput is a ndarray, then it will be updated with values inlabeled_array and onlynum_features will be returned by thisfunction.

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.

Thestructure matrix must be centrosymmetric to ensuretwo-way connections.For instance, if thestructure matrix is not centrosymmetricand is defined as:

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

and theinput is:

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

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

References

[1]

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

Examples

Try it in your browser!

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

>>>fromscipy.ndimageimportlabel,generate_binary_structure>>>importnumpyasnp>>>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_features4>>>labeled_arrayarray([[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 evenif 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 arenow considered a single feature):

>>>num_features2>>>labeled_arrayarray([[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)

Go BackOpen In Tab