0
# Core Connected Components
1

2
The primary connected components labeling functionality that forms the foundation of cc3d. These functions implement optimized algorithms for identifying connected regions in 2D and 3D images with support for multiple connectivity patterns, continuous value processing, and memory-efficient operations.
3

4
## Capabilities
5

6
### Standard Connected Components Labeling
7

8
The main function for connected components analysis, supporting both discrete and continuous valued images with extensive configuration options for different use cases.
9

10
```python { .api }
11
def connected_components(
12
    data: NDArray[Any],
13
    max_labels: int = -1,
14
    connectivity: Literal[4, 6, 8, 18, 26] = 26,
15
    return_N: bool = False,
16
    delta: float = 0,
17
    out_dtype: DTypeLike = None,
18
    out_file: Union[str, BinaryIO, None] = None,
19
    periodic_boundary: bool = False,
20
    binary_image: bool = False,
21
) -> Union[NDArray[Union[np.uint16, np.uint32, np.uint64]], tuple[NDArray[Union[np.uint16, np.uint32, np.uint64]], int]]:
22
    """
23
    Connected components applied to 3D images with handling for multiple labels.
24

25
    Parameters:
26
    - data: Input weights in a 2D or 3D numpy array
27
    - max_labels: Save memory by predicting the maximum number of possible labels
28
    - connectivity: For 3D images, 6 (faces), 18 (+edges), or 26 (+corners). For 2D images, 4 (faces) or 8 (+corners)
29
    - return_N: If True, also return the number of connected components
30
    - delta: Connect together values whose difference is <= delta (for continuous images)
31
    - out_dtype: Output data type (np.uint16, np.uint32, or np.uint64)
32
    - out_file: If specified, output array will be memory-mapped to this file
33
    - periodic_boundary: The boundary edges wrap around
34
    - binary_image: Treat input as binary (foreground > 0, background == 0)
35

36
    Returns:
37
    - NDArray: Labeled components numbered from 1 to N
38
    - tuple[NDArray, int]: If return_N=True, returns (labeled_array, num_components)
39
    """
40
```
41

42
Usage examples:
43

44
```python
45
import cc3d
46
import numpy as np
47

48
# Basic usage with default 26-connectivity
49
labels_in = np.random.randint(0, 5, (100, 100, 100), dtype=np.int32)
50
labels_out = cc3d.connected_components(labels_in)
51

52
# Specify connectivity (6, 18, or 26 for 3D; 4 or 8 for 2D)
53
labels_out = cc3d.connected_components(labels_in, connectivity=6)
54

55
# Get number of components
56
labels_out, N = cc3d.connected_components(labels_in, return_N=True)
57
print(f"Found {N} connected components")
58

59
# Binary image processing
60
binary_image = (labels_in > 0).astype(np.uint8)
61
labels_out = cc3d.connected_components(binary_image, binary_image=True)
62

63
# Continuous value CCL with delta threshold
64
grayscale = np.random.random((50, 50, 50)) * 255
65
labels_out = cc3d.connected_components(grayscale, delta=10)
66

67
# Periodic boundary conditions (for simulations)
68
labels_out = cc3d.connected_components(
69
    labels_in, connectivity=6, periodic_boundary=True
70
)
71

72
# Memory-mapped output for large datasets
73
labels_out = cc3d.connected_components(
74
    labels_in, out_file="large_output.bin"
75
)
76

77
# Control output data type
78
labels_out = cc3d.connected_components(
79
    labels_in, out_dtype=np.uint64
80
)
81
```
82

83
### Large Dataset Processing
84

85
Process datasets larger than available RAM using iterative processing with compressed output format, ideal for very large 3D volumes.
86

87
```python { .api }
88
def connected_components_stack(
89
    stacked_images: typing.Iterable[NDArray[typing.Any]], 
90
    connectivity: Literal[6,26] = 26,
91
    return_N: bool = False,
92
    out_dtype: DTypeLike = None,
93
    binary_image: bool = False,
94
) -> Union[CrackleArray, tuple[CrackleArray, int]]:
95
    """
96
    Connected component labeling on arrays larger than RAM.
97

98
    Parameters:
99
    - stacked_images: Sequence of 3D images in sequential z-order
100
    - connectivity: 6 (faces) or 26 (faces+edges+corners)  
101
    - return_N: If True, return (CrackleArray, num_components)
102
    - out_dtype: Output data type
103
    - binary_image: Treat input images as binary
104

105
    Returns:
106
    - CrackleArray: Compressed array with random access by z-slice
107
    - tuple[CrackleArray, int]: If return_N=True, includes component count
108
    """
109
```
110

111
Usage example:
112

113
```python
114
import cc3d
115
import numpy as np
116

117
def create_image_sections(full_image):
118
    """Generator that yields thick Z slices sequentially."""
119
    for z in range(0, full_image.shape[2], 100):
120
        yield full_image[:, :, z:z+100]
121

122
# Process very large dataset
123
# Note: requires 'pip install connected-components-3d[stack]'
124
large_image = np.random.randint(0, 1000, (2000, 2000, 2000))
125
compressed_labels = cc3d.connected_components_stack(
126
    create_image_sections(large_image),
127
    connectivity=26
128
)
129

130
# Access parts of the result
131
slice_data = compressed_labels[:, :, 500:600]
132

133
# Save compressed result
134
compressed_labels.save("huge_ccl_result.ckl")
135

136
# Convert to numpy (only if it fits in RAM)
137
full_result = compressed_labels.numpy()
138
```
139

140
### Utility Functions
141

142
Helper functions for memory estimation and low-level operations.
143

144
```python { .api }
145
def estimate_provisional_labels(
146
    data: NDArray[Any],
147
) -> tuple[int, int, int]:
148
    """Estimate the number of provisional labels required for connected components."""
149
```
150

151
Usage example:
152

153
```python
154
# Estimate memory requirements before processing
155
estimates = cc3d.estimate_provisional_labels(large_array)
156
x_transitions, total_estimate, static_estimate = estimates
157
print(f"Estimated provisional labels: {total_estimate}")
158
```