{"id":8033,"library":"connected-components-3d","title":"Connected Components 3D","description":"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.","status":"active","version":"3.26.1","language":"en","source_language":"en","source_url":"https://github.com/seung-lab/connected-components-3d/","tags":["connected components","3D image processing","image analysis","numpy","volumetric data","segmentation","bioimage analysis"],"install":[{"cmd":"pip install connected-components-3d","lang":"bash","label":"Standard installation"},{"cmd":"pip install numpy\npip install connected-components-3d --no-binary :all:","lang":"bash","label":"Installation from source (if binaries fail or for specific Numpy versions)"}],"dependencies":[{"reason":"Core data structure (NDArray) for image representation and fundamental operations.","package":"numpy","optional":false},{"reason":"Required for 'stack' extra, enabling efficient compression and handling of stacked images larger than RAM.","package":"crackle-codec","optional":true},{"reason":"Required for 'stack' extra; can also improve performance for operations like `largest_k` by potentially changing label numbering.","package":"fastremap","optional":true}],"imports":[{"note":"The common import pattern is `import cc3d`, then access functions via `cc3d.function_name`.","wrong":"from connected_components_3d import connected_components","symbol":"connected_components","correct":"import cc3d\n...\nlabels_out = cc3d.connected_components(data)"}],"quickstart":{"code":"import cc3d\nimport numpy as np\n\n# Create a sample 3D binary image\nlabels_in = np.zeros((10, 10, 10), dtype=np.int32)\nlabels_in[2:5, 2:5, 2:5] = 1\nlabels_in[6:8, 6:8, 6:8] = 1\nlabels_in[4,4,4] = 0 # Introduce a gap for demonstration\n\nprint(f\"Input shape: {labels_in.shape}, dtype: {labels_in.dtype}\")\n\n# Perform connected component labeling with 26-connectivity (default)\n# Also return the number of connected components (N)\nlabels_out, N = cc3d.connected_components(labels_in, return_N=True, connectivity=26)\n\nprint(f\"\\nOutput labeled image (slice 5):\\n{labels_out[:,:,5]}\")\nprint(f\"Number of connected components found: {N}\")\n\n# Example of extracting a single component\n# for segid in range(1, N + 1):\n#     extracted_component = (labels_out == segid).astype(labels_in.dtype)\n#     print(f\"Component {segid} volume: {np.sum(extracted_component)}\")","lang":"python","description":"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."},"warnings":[{"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:`.","message":"Older 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.","severity":"breaking","affected_versions":"<= 3.x (intermittently with older numpy)"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">= 3.4.0"},{"fix":"Use the `periodic_boundary=True` argument directly in `cc3d.connected_components` for correct handling of wrapped connections.","message":"For 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.","severity":"gotcha","affected_versions":"All versions, but direct support added in recent 3.x releases (confirmed post-v3.2.1)."},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install --upgrade numpy` and then reinstall `connected-components-3d` using `pip install connected-components-3d --no-binary :all:` to force recompilation against the current NumPy. This requires a C++ compiler.","cause":"Mismatch between the NumPy version `connected-components-3d` was compiled against and the currently installed NumPy version, often due to an upgrade or environment change.","error":"numpy.ufunc size changed, may indicate binary incompatibility. Expected 216 from C header, got 192 from PyObject"},{"fix":"Ensure the package is installed in your current environment by running `pip install connected-components-3d`. If the issue persists, verify your active Python environment or reinstall.","cause":"The `connected-components-3d` package was not installed correctly, or the Python environment where it was installed is not active.","error":"ModuleNotFoundError: No module named 'cc3d'"},{"fix":"When checking for conditions on the output `labels_out` array, use explicit boolean checks, e.g., `if np.any(labels_out > 0):` or `if (labels_out == some_label).any():`.","cause":"Attempting to use a NumPy array directly in a boolean context (e.g., `if array:`) instead of applying a boolean operation like `np.any()` or `np.all()`. This is a general NumPy error but can occur if output of cc3d is not handled properly.","error":"ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()"}]}