seung-lab/connected-components-3d

Connected components on discrete and continuous multilabel 3D & 2D images. Handles 26, 18, and 6 connected variants; periodic boundaries (4, 8, & 6)

What it solves

cc3d is designed to solve the problem of Connected Component Labeling (CCL) in 3D images, specifically for images that are not just binary (black and white) but contain multiple labels (multilabel). Many existing tools are limited to binary images, which forces users to process each label one by one, making the process extremely slow for images with hundreds or thousands of labels. cc3d allows all connected components to be labeled in a single pass, significantly improving performance.

How it works

The project implements a 3D variant of the two-pass method by Rosenfeld and Pflatz, augmented with Tarjan's Union-Find disjoint set (with path compression and balancing) and a decision tree based on the work of Wu, Otoo, and Suzuki.

Key technical details include:

  • Connectivity Options: Supports 26, 18, or 6-connected neighborhoods in 3D, and 4 or 8-connected in 2D.
  • Multilabel Support: Works on images with many different labels simultaneously.
  • Continuous Value Support: Can process grayscale images by joining nearby values based on a user-defined delta threshold.
  • Memory Efficiency: Supports memmap files for images larger than RAM and a compressed CrackleArray for sequential processing of thick Z-sections.

Who it’s for

This tool is primarily for researchers and developers working with densely labeled 3D biomedical images (such as brain tissue microscopy) or any application involving instance segmentation and semantic labeling in 3D volumes.

Highlights

  • High Performance: Labels all connected components in one shot, often improving speed by one or more orders of magnitude over binary-only tools.
  • Flexible Connectivity: Offers multiple connectivity options for 2D and 3D spaces.
  • C++ and Python: Provides both Python bindings and a C++ implementation for maximum flexibility.
  • Advanced Analysis Tools: Includes functions for calculating centroids, bounding boxes, voxel counts, removing "dust" (small objects), and extracting the k-largest objects.
  • Surface Area Analysis: Can compute the contact surface area and contact networks between different labels.

Related

  • Project
    PointCloudLibrary/pcl

    A large-scale open-source library for 2D/3D image and point cloud processing, used widely in robotics and 3D perception.

  • Project
    ch-sa/labelCloud

    A lightweight 3D bounding box labeling tool for point clouds, used to generate training data for 3D object detection and 6D pose estimation.

  • Project
    NVIDIA-AI-IOT/Lidar_AI_Solution

    A collection of highly optimized CUDA and TensorRT implementations for 3D Lidar perception, speeding up sparse convolutions and sensor fusion for self-driving systems.

  • Project
    PaddlePaddle/PaddleClas

    A comprehensive image recognition and classification toolkit providing ultra-lightweight models and industrial-grade backbones for high-performance vision applications.

  • Project
    HumanSignal/label-studio

    An open-source data labeling tool that allows users to annotate audio, text, images, and video to prepare or improve training data for machine learning models.