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