0
# Segmentation
1
2
Image segmentation algorithms for partitioning images into meaningful regions or objects. Includes watershed, region growing, active contours, superpixel methods, and boundary detection algorithms.
3
4
## Capabilities
5
6
### Watershed Segmentation
7
8
Apply watershed algorithm for segmenting touching objects and complex structures using gradient information and markers.
9
10
```python { .api }
11
def watershed(image, markers=None, connectivity=1, offset=None, mask=None, compactness=0, watershed_line=False):
12
"""
13
Apply watershed segmentation algorithm.
14
15
Parameters:
16
image : array_like
17
Input grayscale image or gradient magnitude
18
markers : array_like, optional
19
Seed markers for watershed regions
20
connectivity : int, optional
21
Pixel connectivity (1, 2, or 3 for 2D; 1, 2, 3, or 26 for 3D)
22
offset : array_like, optional
23
Offset for connectivity
24
mask : array_like, optional
25
Mask limiting segmentation region
26
compactness : float, optional
27
Compactness factor for segments
28
watershed_line : bool, optional
29
Whether to compute watershed lines
30
31
Returns:
32
ndarray
33
Labeled segmentation image
34
"""
35
```
36
37
### Region Growing Segmentation
38
39
Segment images using region growing methods that expand from seed points based on similarity criteria.
40
41
```python { .api }
42
def random_walker(data, labels, beta=130, mode='bf', tol=0.001, copy=True, multichannel=False, return_full_prob=False, spacing=None, prob_tol=0.001, channel_axis=None):
43
"""
44
Apply random walker segmentation algorithm.
45
46
Parameters:
47
data : array_like
48
Input image data
49
labels : array_like
50
Seed labels with marked regions
51
beta : float, optional
52
Edge weighting parameter
53
mode : str, optional
54
Algorithm mode ('bf' or 'cg')
55
tol : float, optional
56
Convergence tolerance
57
copy : bool, optional
58
Whether to copy input data
59
multichannel : bool, optional
60
Whether last axis is channels (deprecated)
61
return_full_prob : bool, optional
62
Return full probability maps
63
spacing : array_like, optional
64
Pixel spacing for each dimension
65
prob_tol : float, optional
66
Probability tolerance
67
channel_axis : int, optional
68
Axis for color channels
69
70
Returns:
71
ndarray or tuple
72
Labeled segmentation and optionally probability maps
73
"""
74
```
75
76
### Superpixel Algorithms
77
78
Generate superpixels for over-segmentation and preprocessing using SLIC, Felzenszwalb, and QuickShift methods.
79
80
```python { .api }
81
def slic(image, n_segments=100, compactness=10, max_num_iter=10, sigma=0, spacing=None, multichannel=True, convert2lab=None, enforce_connectivity=True, min_size_factor=0.5, max_size_factor=3, slic_zero=False, start_label=1, mask=None, channel_axis=-1):
82
"""
83
Apply Simple Linear Iterative Clustering (SLIC) superpixel segmentation.
84
85
Parameters:
86
image : array_like
87
Input image
88
n_segments : int, optional
89
Approximate number of superpixels
90
compactness : float, optional
91
Balance between color similarity and spatial proximity
92
max_num_iter : int, optional
93
Maximum number of iterations
94
sigma : float, optional
95
Gaussian smoothing parameter
96
spacing : array_like, optional
97
Pixel spacing for each dimension
98
multichannel : bool, optional
99
Whether last axis is channels (deprecated)
100
convert2lab : bool, optional
101
Convert to LAB color space
102
enforce_connectivity : bool, optional
103
Enforce superpixel connectivity
104
min_size_factor : float, optional
105
Minimum superpixel size factor
106
max_size_factor : float, optional
107
Maximum superpixel size factor
108
slic_zero : bool, optional
109
Use SLIC-zero algorithm
110
start_label : int, optional
111
Starting label value
112
mask : array_like, optional
113
Mask limiting segmentation region
114
channel_axis : int, optional
115
Axis for color channels
116
117
Returns:
118
ndarray
119
Superpixel labeled image
120
"""
121
122
def felzenszwalb(image, scale=1, sigma=0.8, min_size=20, multichannel=True, channel_axis=-1):
123
"""
124
Apply Felzenszwalb efficient graph-based segmentation.
125
126
Parameters:
127
image : array_like
128
Input image
129
scale : float, optional
130
Scale parameter for segmentation
131
sigma : float, optional
132
Gaussian smoothing parameter
133
min_size : int, optional
134
Minimum segment size
135
multichannel : bool, optional
136
Whether last axis is channels (deprecated)
137
channel_axis : int, optional
138
Axis for color channels
139
140
Returns:
141
ndarray
142
Segmented labeled image
143
"""
144
145
def quickshift(image, ratio=1.0, kernel_size=5, max_dist=10, return_tree=False, sigma=0, convert2lab=True, random_seed=42, channel_axis=-1):
146
"""
147
Apply QuickShift clustering segmentation.
148
149
Parameters:
150
image : array_like
151
Input image
152
ratio : float, optional
153
Balance between color and spatial proximity
154
kernel_size : float, optional
155
Size of Gaussian kernel for density estimation
156
max_dist : float, optional
157
Maximum distance between segments
158
return_tree : bool, optional
159
Whether to return parent tree
160
sigma : float, optional
161
Gaussian smoothing parameter
162
convert2lab : bool, optional
163
Convert to LAB color space
164
random_seed : int, optional
165
Random seed
166
channel_axis : int, optional
167
Axis for color channels
168
169
Returns:
170
ndarray or tuple
171
Segmented image and optionally parent tree
172
"""
173
```
174
175
### Active Contours
176
177
Apply active contour models (snakes) for object boundary detection and segmentation.
178
179
```python { .api }
180
def active_contour(image, snake, alpha=0.01, beta=0.1, w_line=0, w_edge=1, gamma=0.01, max_px_move=1.0, max_num_iter=2500, convergence=0.1, boundary_condition='periodic', coordinates='rc'):
181
"""
182
Apply active contour model for boundary detection.
183
184
Parameters:
185
image : array_like
186
Input grayscale image
187
snake : array_like
188
Initial contour coordinates
189
alpha : float, optional
190
Snake length penalty parameter
191
beta : float, optional
192
Snake smoothness penalty parameter
193
w_line : float, optional
194
Line term weight
195
w_edge : float, optional
196
Edge term weight
197
gamma : float, optional
198
Explicit time stepping parameter
199
max_px_move : float, optional
200
Maximum pixel movement per iteration
201
max_num_iter : int, optional
202
Maximum number of iterations
203
convergence : float, optional
204
Convergence threshold
205
boundary_condition : str, optional
206
Boundary condition ('periodic', 'free', 'fixed')
207
coordinates : str, optional
208
Coordinate system ('rc' or 'xy')
209
210
Returns:
211
ndarray
212
Final contour coordinates
213
"""
214
215
def chan_vese(image, mu=0.25, lambda1=1, lambda2=1, tol=1e-3, max_num_iter=500, dt=0.5, init_level_set='checkerboard', extended_output=False):
216
"""
217
Apply Chan-Vese active contour segmentation.
218
219
Parameters:
220
image : array_like
221
Input grayscale image
222
mu : float, optional
223
Smoothing parameter
224
lambda1 : float, optional
225
Weight for inside region
226
lambda2 : float, optional
227
Weight for outside region
228
tol : float, optional
229
Convergence tolerance
230
max_num_iter : int, optional
231
Maximum number of iterations
232
dt : float, optional
233
Time step
234
init_level_set : str or array_like, optional
235
Initial level set ('checkerboard', 'disk', or array)
236
extended_output : bool, optional
237
Return additional outputs
238
239
Returns:
240
ndarray or tuple
241
Segmentation and optionally additional information
242
"""
243
244
def morphological_chan_vese(image, num_iter, init_level_set='checkerboard', smoothing=1, lambda1=1, lambda2=1, iter_callback=None):
245
"""
246
Apply morphological Chan-Vese segmentation.
247
248
Parameters:
249
image : array_like
250
Input grayscale image
251
num_iter : int
252
Number of iterations
253
init_level_set : str or array_like, optional
254
Initial level set ('checkerboard', 'disk', or array)
255
smoothing : int, optional
256
Number of smoothing iterations
257
lambda1 : float, optional
258
Weight for inside region
259
lambda2 : float, optional
260
Weight for outside region
261
iter_callback : callable, optional
262
Callback function for each iteration
263
264
Returns:
265
ndarray
266
Segmentation result
267
"""
268
269
def morphological_geodesic_active_contour(image, num_iter, init_level_set='checkerboard', smoothing=1, threshold='auto', balloon=0, iter_callback=None):
270
"""
271
Apply morphological geodesic active contour.
272
273
Parameters:
274
image : array_like
275
Input grayscale image or edge map
276
num_iter : int
277
Number of iterations
278
init_level_set : str or array_like, optional
279
Initial level set ('checkerboard', 'disk', or array)
280
smoothing : int, optional
281
Number of smoothing iterations
282
threshold : str or float, optional
283
Threshold for edge map ('auto' or value)
284
balloon : float, optional
285
Balloon force parameter
286
iter_callback : callable, optional
287
Callback function for each iteration
288
289
Returns:
290
ndarray
291
Segmentation result
292
"""
293
```
294
295
### Boundary Detection and Processing
296
297
Detect and manipulate region boundaries for visualization and analysis.
298
299
```python { .api }
300
def find_boundaries(label_img, connectivity=1, mode='thick', background=0):
301
"""
302
Find boundaries of labeled regions.
303
304
Parameters:
305
label_img : array_like
306
Labeled input image
307
connectivity : int, optional
308
Pixel connectivity (1, 2, or 3 for 2D)
309
mode : str, optional
310
Boundary mode ('thick', 'inner', 'outer', 'subpixel')
311
background : int, optional
312
Background label value
313
314
Returns:
315
ndarray
316
Boolean boundary image
317
"""
318
319
def mark_boundaries(image, label_img, color=(1, 1, 0), outline_color=None, mode='outer', background_label=0):
320
"""
321
Mark boundaries of labeled regions on RGB image.
322
323
Parameters:
324
image : array_like
325
Input RGB image
326
label_img : array_like
327
Labeled regions
328
color : tuple, optional
329
Boundary color (RGB)
330
outline_color : tuple, optional
331
Outline color for boundaries
332
mode : str, optional
333
Boundary mode ('inner', 'outer', 'thick', 'subpixel')
334
background_label : int, optional
335
Background label value
336
337
Returns:
338
ndarray
339
RGB image with marked boundaries
340
"""
341
```
342
343
### Segmentation Utilities
344
345
Utility functions for post-processing and manipulating segmentation results.
346
347
```python { .api }
348
def clear_border(labels, buffer_size=0, bgval=0, in_place=False, mask=None):
349
"""
350
Clear objects connected to image border.
351
352
Parameters:
353
labels : array_like
354
Labeled input image
355
buffer_size : int, optional
356
Border buffer size
357
bgval : int, optional
358
Background value
359
in_place : bool, optional
360
Whether to modify input array
361
mask : array_like, optional
362
Mask limiting clearing region
363
364
Returns:
365
ndarray
366
Cleared labeled image
367
"""
368
369
def expand_labels(label_image, distance=1):
370
"""
371
Expand labeled regions by specified distance.
372
373
Parameters:
374
label_image : array_like
375
Labeled input image
376
distance : float, optional
377
Expansion distance
378
379
Returns:
380
ndarray
381
Expanded labeled image
382
"""
383
384
def join_segmentations(s1, s2):
385
"""
386
Join two segmentation results.
387
388
Parameters:
389
s1 : array_like
390
First segmentation
391
s2 : array_like
392
Second segmentation
393
394
Returns:
395
ndarray
396
Combined segmentation
397
"""
398
399
def relabel_sequential(label_image, offset=1):
400
"""
401
Relabel image with sequential labels starting from offset.
402
403
Parameters:
404
label_image : array_like
405
Input labeled image
406
offset : int, optional
407
Starting label value
408
409
Returns:
410
tuple
411
(relabeled_image, forward_map, inverse_map)
412
"""
413
```
414
415
### Level Set Utilities
416
417
Utilities for level set initialization and processing in active contour methods.
418
419
```python { .api }
420
def inverse_gaussian_gradient(image, alpha=100.0, sigma=5.0):
421
"""
422
Compute inverse Gaussian gradient for level set evolution.
423
424
Parameters:
425
image : array_like
426
Input grayscale image
427
alpha : float, optional
428
Alpha parameter
429
sigma : float, optional
430
Gaussian smoothing parameter
431
432
Returns:
433
ndarray
434
Inverse gradient image
435
"""
436
437
def disk_level_set(image_shape, center=None, radius=None):
438
"""
439
Create disk-shaped initial level set.
440
441
Parameters:
442
image_shape : tuple
443
Shape of output level set
444
center : tuple, optional
445
Center of disk
446
radius : float, optional
447
Radius of disk
448
449
Returns:
450
ndarray
451
Disk-shaped level set
452
"""
453
454
def checkerboard_level_set(image_shape, square_size=5):
455
"""
456
Create checkerboard initial level set.
457
458
Parameters:
459
image_shape : tuple
460
Shape of output level set
461
square_size : int, optional
462
Size of checkerboard squares
463
464
Returns:
465
ndarray
466
Checkerboard level set
467
"""
468
```
469
470
## Usage Examples
471
472
### Watershed Segmentation
473
474
```python
475
from skimage import data, segmentation, feature, filters
476
from scipy import ndimage as ndi
477
import matplotlib.pyplot as plt
478
479
# Load image
480
image = data.coins()
481
482
# Create markers for watershed
483
distance = ndi.distance_transform_edt(image > filters.threshold_otsu(image))
484
local_maxima = feature.peak_local_maxima(distance, min_distance=20, threshold_abs=0.3*distance.max())
485
markers = np.zeros_like(image, dtype=bool)
486
markers[tuple(local_maxima.T)] = True
487
markers = ndi.label(markers)[0]
488
489
# Apply watershed
490
labels = segmentation.watershed(-distance, markers, mask=image > filters.threshold_otsu(image))
491
492
# Display results
493
fig, axes = plt.subplots(2, 2, figsize=(10, 8))
494
axes[0, 0].imshow(image, cmap='gray')
495
axes[0, 0].set_title('Original')
496
axes[0, 1].imshow(distance, cmap='gray')
497
axes[0, 1].set_title('Distance Transform')
498
axes[1, 0].imshow(markers, cmap='nipy_spectral')
499
axes[1, 0].set_title('Markers')
500
axes[1, 1].imshow(labels, cmap='nipy_spectral')
501
axes[1, 1].set_title('Watershed Segmentation')
502
plt.show()
503
```
504
505
### Superpixel Generation
506
507
```python
508
from skimage import data, segmentation
509
import matplotlib.pyplot as plt
510
511
# Load image
512
image = data.astronaut()
513
514
# Apply different superpixel methods
515
slic_segments = segmentation.slic(image, n_segments=300, compactness=10)
516
felzenszwalb_segments = segmentation.felzenszwalb(image, scale=100, sigma=0.5, min_size=50)
517
quickshift_segments = segmentation.quickshift(image, kernel_size=3, max_dist=6, ratio=0.5)
518
519
# Mark boundaries
520
slic_boundaries = segmentation.mark_boundaries(image, slic_segments)
521
felz_boundaries = segmentation.mark_boundaries(image, felzenszwalb_segments)
522
quick_boundaries = segmentation.mark_boundaries(image, quickshift_segments)
523
524
# Display results
525
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
526
axes[0, 0].imshow(image)
527
axes[0, 0].set_title('Original')
528
axes[0, 1].imshow(slic_boundaries)
529
axes[0, 1].set_title('SLIC')
530
axes[1, 0].imshow(felz_boundaries)
531
axes[1, 0].set_title('Felzenszwalb')
532
axes[1, 1].imshow(quick_boundaries)
533
axes[1, 1].set_title('QuickShift')
534
plt.show()
535
```
536
537
### Active Contour Segmentation
538
539
```python
540
from skimage import data, segmentation, filters
541
import numpy as np
542
543
# Load and preprocess image
544
image = data.astronaut()
545
gray = rgb2gray(image)
546
547
# Initialize contour as circle
548
s = np.linspace(0, 2*np.pi, 400)
549
r, c = 220 + 100*np.cos(s), 100 + 120*np.sin(s)
550
init = np.array([r, c]).T
551
552
# Apply active contour
553
snake = segmentation.active_contour(gray, init, alpha=0.015, beta=10, gamma=0.001)
554
555
# Apply Chan-Vese
556
chan_vese_result = segmentation.chan_vese(gray, mu=0.25, lambda1=1, lambda2=1,
557
tol=1e-3, max_num_iter=200)
558
559
print(f"Active contour converged with {len(snake)} points")
560
print(f"Chan-Vese segmentation completed")
561
```
562
563
### Region Growing
564
565
```python
566
from skimage import data, segmentation
567
import numpy as np
568
569
# Load image
570
image = data.camera()
571
572
# Create seed labels for random walker
573
labels = np.zeros_like(image, dtype=np.int32)
574
labels[image < 50] = 1 # Dark regions
575
labels[image > 150] = 2 # Bright regions
576
577
# Apply random walker
578
rw_result = segmentation.random_walker(image, labels, beta=10, mode='bf')
579
580
# Display statistics
581
unique_labels = np.unique(rw_result)
582
for label in unique_labels:
583
area = np.sum(rw_result == label)
584
print(f"Region {label}: {area} pixels ({100*area/image.size:.1f}%)")
585
```
586
587
## Types
588
589
```python { .api }
590
from typing import Union, Optional, Tuple, Callable
591
from numpy.typing import NDArray
592
import numpy as np
593
594
# Segmentation results
595
LabeledImage = NDArray[np.integer]
596
BinaryImage = NDArray[np.bool_]
597
ProbabilityMap = NDArray[np.floating]
598
599
# Contour types
600
Contour = NDArray[np.floating]
601
LevelSet = NDArray[np.floating]
602
603
# Segmentation parameters
604
Connectivity = int
605
SegmentationMode = str
606
BoundaryMode = str
607
608
# Algorithm-specific types
609
SuperpixelResult = LabeledImage
610
WatershedResult = LabeledImage
611
ActiveContourResult = Contour
612
RegionGrowingResult = Union[LabeledImage, Tuple[LabeledImage, ProbabilityMap]]
613
```