Skip to main content
`Ctrl`+`K`
scipy.ndimage.

# label

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

  Label features in an array.

  Parameters:
    input array_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.

    structure array_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:
    label ndarray or int

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

    num_features int

      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)