{ } Raw JSON

bundles / scipy latest / scipy / ndimage / _measurements / label

function

`scipy.ndimage._measurements:label`

source: /scipy/ndimage/_measurements.py :43

Signature

def label ( input , structure = None , output = None )

Summary

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.

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 dev-arrayapi for more information.

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
labeled_array

✓

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
labeled_array

✓

Aliases

scipy.ndimage.label