Registry /
data / connected-components-3d
Install & Compatibility
Where this runs
tested against v4.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.11
✕ dependency_conflict
4/8 runs
py 3.12
✕ dependency_conflict
4/8 runs
py 3.13
✕ dependency_conflict
4/8 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connected_components
✓ from cc3d import connected_components
✗ import cc3d
connected_components_stack
✓ from cc3d import connected_components_stack
✗ import cc3d
dust
✓ from cc3d import dust
✗ import cc3d
This quickstart demonstrates how to apply connected component labeling to a 3D NumPy array. It initializes a binary image, then uses `cc3d.connected_components` to label distinct regions. The `return_N=True` argument also provides the total count of components found. Different `connectivity` options (e.g., 6, 18, 26 for 3D; 4, 8 for 2D) can be specified, with 26 being the default for 3D.
import cc3d
import numpy as np
# Create a sample 3D binary image
labels_in = np.zeros((10, 10, 10), dtype=np.int32)
labels_in[2:5, 2:5, 2:5] = 1
labels_in[6:8, 6:8, 6:8] = 1
labels_in[4,4,4] = 0 # Introduce a gap for demonstration
print(f"Input shape: {labels_in.shape}, dtype: {labels_in.dtype}")
# Perform connected component labeling with 26-connectivity (default)
# Also return the number of connected components (N)
labels_out, N = cc3d.connected_components(labels_in, return_N=True, connectivity=26)
print(f"\nOutput labeled image (slice 5):\n{labels_out[:,:,5]}")
print(f"Number of connected components found: {N}")
# Example of extracting a single component
# for segid in range(1, N + 1):
# extracted_component = (labels_out == segid).astype(labels_in.dtype)
# print(f"Component {segid} volume: {np.sum(extracted_component)}")
Debug
Known issues
breakingOlder versions of connected-components-3d (pre-1.16 numpy compatibility) may exhibit 'numpy.ufunc size changed, may indicate binary incompatibility' errors, especially when the installed numpy version differs from the one it was compiled against.fixUpgrade your numpy version (`pip install --upgrade numpy`) or reinstall `connected-components-3d` from source using `pip install connected-components-3d --no-binary :all:`.
affects: <= 3.x (intermittently with older numpy)
gotchaWhen working with continuously valued raw data images (e.g., grayscale), ensure proper use of the `delta` argument to define the threshold for connecting values. Incorrect `delta` values can lead to over- or under-segmentation.fixRefer to the API documentation for `cc3d.connected_components` and experiment with the `delta` parameter to match your data's characteristics. `delta=0` implies strict equality for connection.
affects: >= 3.4.0
gotchaFor images that cross periodic boundaries (e.g., global climate data), ensure `periodic_boundary=True` is set in `cc3d.connected_components`. Older workarounds for this scenario can be less efficient and lead to incorrect labeling.fixUse the `periodic_boundary=True` argument directly in `cc3d.connected_components` for correct handling of wrapped connections.
affects: All versions, but direct support added in recent 3.x releases (confirmed post-v3.2.1).
gotchaThe `connectivity` parameter defines the neighborhood for component labeling. Using the wrong connectivity (e.g., 6-connected vs. 26-connected for 3D) can significantly alter labeling results, especially for complex shapes or sparse data.fixCarefully select the `connectivity` parameter (4 or 8 for 2D; 6, 18, or 26 for 3D) based on your image data and the definition of 'connected' relevant to your analysis.
affects: All versions
Upgrade
Version history
4.0.0latest on PyPI · released Jun 5, 2026
Audit
Dependencies
numpyrequiredCore data structure (NDArray) for image representation and fundamental operations.
crackle-codecoptionalRequired for 'stack' extra, enabling efficient compression and handling of stacked images larger than RAM.
fastremapoptionalRequired for 'stack' extra; can also improve performance for operations like `largest_k` by potentially changing label numbering.