Registry / data / connected-components-3d

connected-components-3d

JSON →
library4.0.0pypypi✓ verified 84d ago

Connected Components 3D (cc3d) is a Python library for performing connected component labeling on discrete and continuous multilabel 3D and 2D images. It efficiently handles 26, 18, and 6 connected variants for 3D images, and 4 or 8 connected variants for 2D images, including support for periodic boundaries. The library is currently at version 3.26.1 and is actively maintained, offering significant performance improvements over general-purpose libraries for multi-label and large volumetric datasets.

pip install connected-components-3d
INSTALL
IMPORT
SIG · CONNECTED-COMPONEN
C
connected-components-3d
datapythonv4.0.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✕ timeout
4/8 runs
py 3.11
✕ dependency_conflict
4/8 runs
py 3.12
✕ dependency_conflict
4/8 runs
py 3.13
✕ dependency_conflict
4/8 runs
py 3.9
✕ timeout
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.
fix
Upgrade 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.
fix
Refer 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.
fix
Use 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.
fix
Carefully 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.
Agent activity
21 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources