Connected-component labeling
Segmenting binary images into separate objects.
SciPy · Function
ndimage.label
Labels connected nonzero features in an array and counts them. Connectivity is controlled by an optional structuring element.
How it works
The function treats nonzero elements as foreground and groups them into connected features according to a structuring element. It returns an integer label array and the number of features, unless an output array is supplied, in which case that array is filled in and only the count is returned.
Syntax
scipy.ndimage.label(input, structure=None, output=None)Parameters
| Name | Type | Description |
|---|---|---|
input | array_like | Array-like object to label; nonzero values are features and zeros are background. |
structure | array_like, optional | Optional structuring element defining feature connections; it must be centrosymmetric. |
output | None, data-type, or array_like, optional | Optional output dtype or array-like destination for the labels. |
Returns
If output is None, returns (labeled_array, num_features). If output is an ndarray, updates it with labels and returns only num_features.
Key points
- The input is interpreted as a binary foreground mask: every nonzero element belongs to a feature candidate, while zero is background.
- Use structure to control which neighboring positions are considered connected.
- Omitting structure selects SciPy's default connectivity automatically.
- An output dtype lets you choose the numeric type used for generated labels.
- An existing array-like output buffer can receive the labels directly.
- The ordinary call returns both the labeled array and the number of detected features.
Common mistakes
- A custom connectivity structure must be centrosymmetric; otherwise the requested neighborhood relationship is not symmetric.
- Supplying an output array changes the return shape: the array is modified in place and the function returns only the feature count.
Example: Label connected components
import numpy as np
from scipy import ndimage
image = np.array([[1, 1, 0, 0],
[0, 1, 0, 1],
[0, 0, 0, 1]])
labels, count = ndimage.label(image)
print(labels)
print(count)This labels the two nonzero connected components and prints the label array plus their count.
When to use it
Feature counting
Counting isolated nonzero regions in masks or grids.
In-place output
Writing labels into preallocated memory for downstream processing.
Interview questions
QWhat does scipy.ndimage.label identify?
Nonzero input elements are treated as features and zeros as background. Connected nonzero regions receive distinct integer labels, and the function also reports how many regions it found.
Follow-up: How would connectivity be customized? Pass a structuring element through structure, ensuring that it is centrosymmetric.
QWhat is the default connectivity?
Without structure, SciPy creates a default structuring element with squared connectivity equal to one. In two dimensions this gives four-neighbor connectivity rather than diagonal connectivity.
Follow-up: What must a custom structure satisfy? It must be centrosymmetric so connections are reciprocal.
QHow does output affect the return value?
With output omitted or set to None, the result is a tuple containing the labeled array and the number of features. If output is an array, that array receives the labels and only the count is returned.
Follow-up: What can output specify besides an array? It can specify a data type for the resulting labeled feature array.
Related
scipy.ndimage.find_objectsscipy.ndimage.generate_binary_structurescipy.ndimage.sum