0
# Morphological Operations
1

2
Advanced morphological processing with custom structuring elements for shape analysis, feature extraction, and binary image operations.
3

4
## Capabilities
5

6
### Structuring Elements
7

8
Define and create structuring elements for morphological operations with various shapes and orientations.
9

10
```java { .api }
11
/**
12
 * Structuring element for morphological operations
13
 */
14
class SEL extends Pointer {
15
    int sy(); // height of structuring element
16
    int sx(); // width of structuring element  
17
    int cy(); // y center coordinate
18
    int cx(); // x center coordinate
19
    BytePointer name(); // optional name
20
}
21

22
/**
23
 * Create rectangular structuring element
24
 * @param h - Height
25
 * @param w - Width
26
 * @param cy - Center y coordinate
27
 * @param cx - Center x coordinate
28
 * @return SEL structuring element or null on failure
29
 */
30
SEL selCreateBrick(int h, int w, int cy, int cx);
31

32
/**
33
 * Create structuring element from string pattern  
34
 * @param text - Text pattern (e.g., "ooo;oxo;ooo")
35
 * @param h - Height
36
 * @param w - Width
37
 * @param name - Optional name
38
 * @return SEL structuring element or null on failure
39
 */
40
SEL selCreateFromString(String text, int h, int w, String name);
41

42
/**
43
 * Create circular structuring element
44
 * @param r - Radius
45
 * @return SEL structuring element or null on failure
46
 */
47
SEL selCreateCircular(int r);
48

49
/**
50
 * Create plus-shaped structuring element
51
 * @param r - Radius
52
 * @return SEL structuring element or null on failure
53
 */
54
SEL selCreatePlus(int r);
55

56
/**
57
 * Rotate structuring element
58
 * @param sel - Source structuring element
59
 * @param angle - Rotation angle in radians
60
 * @return Rotated SEL or null on failure
61
 */
62
SEL selRotate(SEL sel, float angle);
63
```
64

65
### Basic Morphological Operations
66

67
Core morphological operations: dilation, erosion, opening, and closing for shape analysis and noise removal.
68

69
```java { .api }
70
/**
71
 * Dilate binary image (expand foreground)
72
 * @param pixd - Destination (can be null)
73
 * @param pixs - Source binary image
74
 * @param sel - Structuring element
75
 * @return Dilated PIX or null on failure
76
 */
77
PIX pixDilate(PIX pixd, PIX pixs, SEL sel);
78

79
/**
80
 * Erode binary image (shrink foreground)
81
 * @param pixd - Destination (can be null)
82
 * @param pixs - Source binary image
83
 * @param sel - Structuring element
84
 * @return Eroded PIX or null on failure
85
 */
86
PIX pixErode(PIX pixd, PIX pixs, SEL sel);
87

88
/**
89
 * Opening operation (erosion followed by dilation)
90
 * @param pixd - Destination (can be null)
91
 * @param pixs - Source binary image  
92
 * @param sel - Structuring element
93
 * @return Opened PIX or null on failure
94
 */
95
PIX pixOpen(PIX pixd, PIX pixs, SEL sel);
96

97
/**
98
 * Closing operation (dilation followed by erosion)
99
 * @param pixd - Destination (can be null)
100
 * @param pixs - Source binary image
101
 * @param sel - Structuring element
102
 * @return Closed PIX or null on failure
103
 */
104
PIX pixClose(PIX pixd, PIX pixs, SEL sel);
105

106
/**
107
 * Safe closing (handles boundary conditions)
108
 * @param pixs - Source binary image
109
 * @param size - Structuring element size
110
 * @return Safely closed PIX or null on failure
111
 */
112
PIX pixCloseSafe(PIX pixs, int size);
113

114
/**
115
 * Safe opening (handles boundary conditions)
116
 * @param pixs - Source binary image
117
 * @param size - Structuring element size
118
 * @return Safely opened PIX or null on failure
119
 */
120
PIX pixOpenSafe(PIX pixs, int size);
121
```
122

123
### Advanced Morphological Operations
124

125
Sophisticated operations for gradient computation, feature extraction, and pattern matching.
126

127
```java { .api }
128
/**
129
 * Morphological gradient (dilation - erosion)
130
 * @param pixs - Source binary image
131
 * @param sel - Structuring element
132
 * @param op - Operation type (L_MORPH_DILATE or L_MORPH_ERODE)
133
 * @return Gradient PIX or null on failure
134
 */
135
PIX pixMorphGradient(PIX pixs, SEL sel, int op);
136

137
/**
138
 * Top-hat transform (original - opening)
139
 * @param pixs - Source binary image
140
 * @param sel - Structuring element
141
 * @param op - L_TOPHAT_WHITE or L_TOPHAT_BLACK
142
 * @return Top-hat PIX or null on failure
143
 */
144
PIX pixTophat(PIX pixs, SEL sel, int op);
145

146
/**
147
 * Hit-or-miss transform for pattern matching
148
 * @param pixd - Destination (can be null)
149
 * @param pixs - Source binary image
150
 * @param sel - Structuring element with hit/miss pattern
151
 * @return HMT result PIX or null on failure
152
 */
153
PIX pixHMT(PIX pixd, PIX pixs, SEL sel);
154

155
/**
156
 * Thinning operation
157
 * @param pixs - Source binary image
158
 * @param connectivity - 4 or 8 connectivity
159
 * @param maxiters - Maximum iterations (0 for convergence)
160
 * @return Thinned PIX or null on failure
161
 */
162
PIX pixThin(PIX pixs, int connectivity, int maxiters);
163

164
/**
165
 * Thickening operation
166
 * @param pixs - Source binary image
167
 * @param connectivity - 4 or 8 connectivity
168
 * @param maxiters - Maximum iterations (0 for convergence)
169
 * @return Thickened PIX or null on failure
170
 */
171
PIX pixThicken(PIX pixs, int connectivity, int maxiters);
172

173
/**
174
 * Skeletonization (medial axis transform)
175
 * @param pixs - Source binary image
176
 * @param connectivity - 4 or 8 connectivity
177
 * @return Skeleton PIX or null on failure
178
 */
179
PIX pixSkeleton(PIX pixs, int connectivity);
180
```
181

182
**Usage Examples:**
183

184
```java
185
import org.bytedeco.leptonica.*;
186
import static org.bytedeco.leptonica.global.leptonica.*;
187

188
// Create structuring elements
189
SEL brick = selCreateBrick(5, 5, 2, 2); // 5x5 rectangular
190
SEL circle = selCreateCircular(3); // radius 3 circular
191
SEL plus = selCreatePlus(2); // plus shape radius 2
192

193
// Basic morphological operations
194
PIX dilated = pixDilate(null, binaryImage, brick);
195
PIX eroded = pixErode(null, binaryImage, brick);
196
PIX opened = pixOpen(null, binaryImage, circle);
197
PIX closed = pixClose(null, binaryImage, circle);
198

199
// Remove small noise with opening
200
PIX denoised = pixOpenSafe(binaryImage, 3);
201

202
// Fill small gaps with closing
203
PIX filled = pixCloseSafe(binaryImage, 5);
204

205
// Extract boundaries with gradient
206
PIX boundaries = pixMorphGradient(binaryImage, brick, L_MORPH_DILATE);
207

208
// Extract fine features with top-hat
209
PIX features = pixTophat(binaryImage, circle, L_TOPHAT_WHITE);
210

211
// Skeletonize for shape analysis
212
PIX skeleton = pixSkeleton(binaryImage, 8);
213

214
// Thin lines to single pixel width
215
PIX thinned = pixThin(binaryImage, 8, 0);
216
```
217

218
### Grayscale Morphology
219

220
Morphological operations extended to grayscale images for texture analysis and filtering.
221

222
```java { .api }
223
/**
224
 * Grayscale dilation
225
 * @param pixd - Destination (can be null)
226
 * @param pixs - Source grayscale image
227
 * @param sel - Structuring element
228
 * @return Dilated PIX or null on failure
229
 */
230
PIX pixDilateGray(PIX pixd, PIX pixs, SEL sel);
231

232
/**
233
 * Grayscale erosion
234
 * @param pixd - Destination (can be null)
235
 * @param pixs - Source grayscale image
236
 * @param sel - Structuring element
237
 * @return Eroded PIX or null on failure
238
 */
239
PIX pixErodeGray(PIX pixd, PIX pixs, SEL sel);
240

241
/**
242
 * Grayscale opening
243
 * @param pixs - Source grayscale image
244
 * @param sel - Structuring element
245
 * @return Opened PIX or null on failure
246
 */
247
PIX pixOpenGray(PIX pixs, SEL sel);
248

249
/**
250
 * Grayscale closing
251
 * @param pixs - Source grayscale image
252
 * @param sel - Structuring element
253
 * @return Closed PIX or null on failure
254
 */
255
PIX pixCloseGray(PIX pixs, SEL sel);
256

257
/**
258
 * Grayscale top-hat transform
259
 * @param pixs - Source grayscale image
260
 * @param sel - Structuring element
261
 * @param op - L_TOPHAT_WHITE or L_TOPHAT_BLACK
262
 * @return Top-hat PIX or null on failure
263
 */
264
PIX pixTophatGray(PIX pixs, SEL sel, int op);
265
```
266

267
**Usage Examples:**
268

269
```java
270
// Grayscale morphological operations for texture processing
271
SEL disk = selCreateCircular(4);
272

273
// Enhance bright features
274
PIX brightFeatures = pixDilateGray(null, grayImage, disk);
275

276
// Suppress bright features
277
PIX darkFeatures = pixErodeGray(null, grayImage, disk);
278

279
// Smooth texture while preserving edges
280
PIX smoothed = pixOpenGray(grayImage, disk);
281

282
// Extract bright peaks
283
PIX peaks = pixTophatGray(grayImage, disk, L_TOPHAT_WHITE);
284

285
// Extract dark valleys  
286
PIX valleys = pixTophatGray(grayImage, disk, L_TOPHAT_BLACK);
287
```
288

289
### Grayscale Morphology
290

291
Morphological operations on grayscale images for advanced image processing and analysis.
292

293
```java { .api }
294
/**
295
 * Grayscale erosion
296
 * @param pixs - Source grayscale image
297
 * @param hsize - Horizontal structuring element size
298
 * @param vsize - Vertical structuring element size
299
 * @return Eroded grayscale PIX or null on failure
300
 */
301
PIX pixErodeGray(PIX pixs, int hsize, int vsize);
302

303
/**
304
 * Grayscale dilation
305
 * @param pixs - Source grayscale image
306
 * @param hsize - Horizontal structuring element size
307
 * @param vsize - Vertical structuring element size
308
 * @return Dilated grayscale PIX or null on failure
309
 */
310
PIX pixDilateGray(PIX pixs, int hsize, int vsize);
311

312
/**
313
 * Grayscale opening
314
 * @param pixs - Source grayscale image
315
 * @param hsize - Horizontal size
316
 * @param vsize - Vertical size
317
 * @return Opened grayscale PIX or null on failure
318
 */
319
PIX pixOpenGray(PIX pixs, int hsize, int vsize);
320

321
/**
322
 * Grayscale closing
323
 * @param pixs - Source grayscale image
324
 * @param hsize - Horizontal size
325
 * @param vsize - Vertical size
326
 * @return Closed grayscale PIX or null on failure
327
 */
328
PIX pixCloseGray(PIX pixs, int hsize, int vsize);
329
```
330

331
**Usage Examples:**
332

333
```java
334
// Grayscale morphological operations for texture analysis
335
PIX grayImage = pixRead("texture.jpg");
336

337
// Smooth bright features (erosion)
338
PIX eroded = pixErodeGray(grayImage, 5, 5);
339

340
// Enhance bright features (dilation)  
341
PIX dilated = pixDilateGray(grayImage, 5, 5);
342

343
// Remove bright noise (opening)
344
PIX opened = pixOpenGray(grayImage, 3, 3);
345

346
// Fill dark gaps (closing)
347
PIX closed = pixCloseGray(grayImage, 3, 3);
348
```
349

350
### Hit-or-Miss and Template Matching
351

352
Specialized morphological operations for pattern detection and template matching.
353

354
```java { .api }
355
/**
356
 * Hit-or-Miss transform for pattern detection
357
 * @param pixd - Destination (can be null)
358
 * @param pixs - Source binary image
359
 * @param sel - Structuring element with hit/miss pattern
360
 * @return HMT result PIX or null on failure
361
 */
362
PIX pixHMT(PIX pixd, PIX pixs, SEL sel);
363

364
/**
365
 * Top-hat transform (morphological gradient)
366
 * @param pixs - Source image
367
 * @param hsize - Horizontal size
368
 * @param vsize - Vertical size
369
 * @param type - L_TOPHAT_WHITE or L_TOPHAT_BLACK
370
 * @return Top-hat PIX or null on failure
371
 */
372
PIX pixTophat(PIX pixs, int hsize, int vsize, int type);
373

374
/**
375
 * Morphological gradient
376
 * @param pixs - Source image
377
 * @param hsize - Horizontal size
378
 * @param vsize - Vertical size
379
 * @param smoothing - Smoothing factor
380
 * @return Gradient PIX or null on failure
381
 */
382
PIX pixMorphGradient(PIX pixs, int hsize, int vsize, int smoothing);
383
```
384

385
**Usage Examples:**
386

387
```java
388
// Pattern detection with Hit-or-Miss
389
SEL cornerSel = selCreateFromString("ox.;oxx;...", 3, 3, "corner");
390
PIX corners = pixHMT(null, binaryImage, cornerSel);
391

392
// White top-hat to detect bright features smaller than structuring element
393
PIX brightFeatures = pixTophat(grayImage, 10, 10, L_TOPHAT_WHITE);
394

395
// Black top-hat to detect dark features
396
PIX darkFeatures = pixTophat(grayImage, 10, 10, L_TOPHAT_BLACK);
397

398
// Morphological gradient for edge detection
399
PIX edges = pixMorphGradient(grayImage, 3, 3, 1);
400
```
401

402
### Distance Transform and Watershed
403

404
Advanced algorithms for shape analysis and region segmentation.
405

406
```java { .api }
407
/**
408
 * Distance transform (distance to nearest background pixel)
409
 * @param pixs - Source binary image
410
 * @param connectivity - 4 or 8 connectivity
411
 * @return Distance transform PIX or null on failure
412
 */
413
PIX pixDistanceFunction(PIX pixs, int connectivity);
414

415
/**
416
 * Watershed segmentation data structure
417
 */
418
class L_WSHED extends Pointer {
419
    PIX pixs(); // source image
420
    PIX pixm(); // marker image
421
    PIX pixlab(); // labeled watershed regions
422
    int nseeds(); // number of seed points
423
}
424

425
/**
426
 * Create watershed segmentation structure
427
 * @param pixs - Source grayscale image (typically gradient)
428
 * @param pixm - Marker image (seed points)
429
 * @return L_WSHED structure or null on failure
430
 */
431
L_WSHED wshedCreate(PIX pixs, PIX pixm);
432

433
/**
434
 * Apply watershed algorithm
435
 * @param wshed - Watershed structure
436
 * @return 0 on success, 1 on failure
437
 */
438
int wshedApply(L_WSHED wshed);
439

440
/**
441
 * Get watershed basins
442
 * @param wshed - Watershed structure
443
 * @return PIX with labeled regions or null on failure
444
 */
445
PIX wshedBasins(L_WSHED wshed);
446
```
447

448
**Usage Examples:**
449

450
```java
451
// Distance transform for shape analysis
452
PIX distance = pixDistanceFunction(binaryImage, 8);
453

454
// Watershed segmentation
455
PIX gradient = pixSobelEdgeFilter(grayImage, L_ALL_EDGES);
456
PIX markers = createMarkers(grayImage); // hypothetical function
457

458
L_WSHED watershed = wshedCreate(gradient, markers);
459
wshedApply(watershed);
460
PIX regions = wshedBasins(watershed);
461
```
462

463
### Morphological Reconstruction
464

465
Reconstruction operations for connected component processing and feature extraction.
466

467
```java { .api }
468
/**
469
 * Morphological reconstruction by dilation
470
 * @param pixs - Source image (mask)
471
 * @param pixm - Marker image
472
 * @param connectivity - 4 or 8 connectivity
473
 * @return Reconstructed PIX or null on failure
474
 */
475
PIX pixMorphReconstructByDilation(PIX pixs, PIX pixm, int connectivity);
476

477
/**
478
 * Morphological reconstruction by erosion
479
 * @param pixs - Source image (mask)
480
 * @param pixm - Marker image
481
 * @param connectivity - 4 or 8 connectivity
482
 * @return Reconstructed PIX or null on failure
483
 */
484
PIX pixMorphReconstructByErosion(PIX pixs, PIX pixm, int connectivity);
485

486
/**
487
 * Hole filling using reconstruction
488
 * @param pixs - Source binary image
489
 * @param connectivity - 4 or 8 connectivity
490
 * @return PIX with holes filled or null on failure
491
 */
492
PIX pixFillHoles(PIX pixs, int connectivity);
493

494
/**
495
 * Remove border-connected components
496
 * @param pixs - Source binary image
497
 * @param connectivity - 4 or 8 connectivity
498
 * @return PIX with border components removed or null on failure
499
 */
500
PIX pixRemoveBorderConnComps(PIX pixs, int connectivity);
501
```
502

503
**Usage Examples:**
504

505
```java
506
// Fill holes in binary image
507
PIX filled = pixFillHoles(binaryImage, 4);
508

509
// Remove components touching border
510
PIX interior = pixRemoveBorderConnComps(binaryImage, 8);
511

512
// Reconstruction-based filtering
513
PIX marker = pixErode(null, binaryImage, selCreateBrick(3, 3, 1, 1));
514
PIX reconstructed = pixMorphReconstructByDilation(binaryImage, marker, 8);
515
```
516

517
## Morphological Constants
518

519
```java { .api }
520
// Operation types
521
static final int L_MORPH_DILATE = 1;
522
static final int L_MORPH_ERODE = 2;  
523
static final int L_MORPH_OPEN = 3;
524
static final int L_MORPH_CLOSE = 4;
525
static final int L_MORPH_HMT = 5;
526

527
// Top-hat types
528
static final int L_TOPHAT_WHITE = 0;
529
static final int L_TOPHAT_BLACK = 1;
530

531
// Connectivity
532
static final int L_CONNECTIVITY_4 = 0;
533
static final int L_CONNECTIVITY_8 = 1;
534
```
535

536
## Applications
537

538
### Noise Removal
539
```java
540
// Remove salt-and-pepper noise
541
PIX denoised = pixOpen(null, binaryImage, selCreateBrick(3, 3, 1, 1));
542
denoised = pixClose(denoised, selCreateBrick(3, 3, 1, 1));
543
```
544

545
### Feature Extraction
546
```java
547
// Extract thin lines
548
PIX thinLines = pixTophat(binaryImage, selCreateBrick(1, 15, 0, 7), L_TOPHAT_WHITE);
549

550
// Extract small objects
551
PIX smallObjects = pixTophat(binaryImage, selCreateCircular(10), L_TOPHAT_WHITE);
552
```
553

554
### Shape Analysis
555
```java
556
// Get object boundaries
557
PIX boundaries = pixMorphGradient(objects, selCreateBrick(3, 3, 1, 1), L_MORPH_DILATE);
558

559
// Skeletonize for shape matching
560
PIX skeleton = pixSkeleton(objects, 8);
561
```