0
# Image Processing
1

2
Core image processing operations including scaling, rotation, color space conversion, filtering, and enhancement techniques for comprehensive image manipulation.
3

4
## Capabilities
5

6
### Scaling and Geometric Transformations
7

8
Scale, rotate, and transform images with various interpolation methods and boundary handling options.
9

10
```java { .api }
11
/**
12
 * Scale image by specified factors
13
 * @param pixs - Source image
14
 * @param scalex - Horizontal scaling factor
15
 * @param scaley - Vertical scaling factor  
16
 * @return Scaled PIX or null on failure
17
 */
18
PIX pixScale(PIX pixs, float scalex, float scaley);
19

20
/**
21
 * Scale to specific dimensions
22
 * @param pixs - Source image
23
 * @param wd - Target width
24
 * @param hd - Target height
25
 * @return Scaled PIX or null on failure
26
 */
27
PIX pixScaleToSize(PIX pixs, int wd, int hd);
28

29
/**
30
 * Scale with area mapping (high quality)
31
 * @param pixs - Source image
32
 * @param scalex - Horizontal scaling factor
33
 * @param scaley - Vertical scaling factor
34
 * @return Scaled PIX or null on failure
35
 */
36
PIX pixScaleAreaMap(PIX pixs, float scalex, float scaley);
37

38
/**
39
 * Rotate image by specified angle
40
 * @param pixs - Source image
41
 * @param angle - Rotation angle in radians
42
 * @param type - Rotation type (L_ROTATE_* constants)
43
 * @param incolor - Fill color for background
44
 * @param width - Output width (0 for auto)
45
 * @param height - Output height (0 for auto)
46
 * @return Rotated PIX or null on failure
47
 */
48
PIX pixRotate(PIX pixs, float angle, int type, int incolor, int width, int height);
49

50
/**
51
 * Rotate by specific angles (optimized)
52
 * @param pixs - Source image
53
 * @param quads - Number of 90-degree rotations (1, 2, or 3)
54
 * @return Rotated PIX or null on failure
55
 */
56
PIX pixRotateOrth(PIX pixs, int quads);
57

58
/**
59
 * Affine transformation
60
 * @param pixs - Source image
61
 * @param vc - 6-element transformation matrix
62
 * @param incolor - Fill color for background
63
 * @return Transformed PIX or null on failure
64
 */
65
PIX pixAffine(PIX pixs, FloatPointer vc, int incolor);
66

67
/**  
68
 * Projective transformation
69
 * @param pixs - Source image
70
 * @param vc - 8-element transformation matrix
71
 * @param incolor - Fill color for background
72
 * @return Transformed PIX or null on failure
73
 */
74
PIX pixProjective(PIX pixs, FloatPointer vc, int incolor);
75
```
76

77
**Usage Examples:**
78

79
```java
80
import org.bytedeco.leptonica.*;
81
import static org.bytedeco.leptonica.global.leptonica.*;
82

83
// Scale image to half size
84
PIX scaled = pixScale(sourcePix, 0.5f, 0.5f);
85

86
// Scale to specific dimensions (thumbnail)
87
PIX thumbnail = pixScaleToSize(sourcePix, 200, 150);
88

89
// High-quality scaling using area mapping
90
PIX highQuality = pixScaleAreaMap(sourcePix, 2.0f, 2.0f);
91

92
// Rotate 45 degrees
93
PIX rotated = pixRotate(sourcePix, (float)(Math.PI / 4), L_ROTATE_AREA_MAP, 
94
                       L_BRING_IN_WHITE, 0, 0);
95

96
// Rotate 90 degrees (optimized)
97
PIX rotated90 = pixRotateOrth(sourcePix, 1);
98

99
// Affine transformation (shear)
100
float[] matrix = {1.0f, 0.2f, 0.0f, 1.0f, 0.0f, 0.0f};
101
FloatPointer affine = new FloatPointer(matrix);
102
PIX sheared = pixAffine(sourcePix, affine, L_BRING_IN_WHITE);
103
```
104

105
### Color Space Conversion
106

107
Convert between different color spaces and bit depths with various algorithms and options.
108

109
```java { .api }
110
/**
111
 * Convert RGB to grayscale with weighted averaging
112
 * @param pixs - Source RGB image
113
 * @param rwt - Red weight (typically 0.3)
114
 * @param gwt - Green weight (typically 0.6)  
115
 * @param bwt - Blue weight (typically 0.1)
116
 * @return Grayscale PIX or null on failure
117
 */
118
PIX pixConvertRGBToGray(PIX pixs, float rwt, float gwt, float bwt);
119

120
/**
121
 * Convert grayscale to RGB
122
 * @param pixs - Source grayscale image
123
 * @return RGB PIX or null on failure
124
 */
125
PIX pixConvertGrayToColormap(PIX pixs);
126

127
/**
128
 * Convert to 8-bit depth
129
 * @param pixs - Source image
130
 * @param cmapflag - 1 to use colormap, 0 for direct conversion
131
 * @return 8-bit PIX or null on failure
132
 */
133
PIX pixConvertTo8(PIX pixs, int cmapflag);
134

135
/**
136
 * Convert to 32-bit RGB
137
 * @param pixs - Source image  
138
 * @return 32-bit RGB PIX or null on failure
139
 */
140
PIX pixConvertTo32(PIX pixs);
141

142
/**
143
 * Remove alpha channel from RGBA image
144
 * @param pixs - Source RGBA image
145
 * @return RGB PIX or null on failure
146
 */
147
PIX pixRemoveAlpha(PIX pixs);
148

149
/**
150
 * Add alpha channel to RGB image
151
 * @param pixs - Source RGB image
152
 * @param fract - Alpha value as fraction (0.0-1.0)
153
 * @param delta - Alpha variation
154
 * @return RGBA PIX or null on failure
155
 */
156
PIX pixAddAlphaToBlend(PIX pixs, float fract, int delta);
157

158
/**
159
 * Convert RGB to HSV color space
160
 * @param pixd - Destination (can be null)
161
 * @param pixs - Source RGB image
162
 * @return HSV PIX or null on failure
163
 */
164
PIX pixConvertRGBToHSV(PIX pixd, PIX pixs);
165

166
/**
167
 * Convert HSV to RGB color space
168
 * @param pixd - Destination (can be null)
169
 * @param pixs - Source HSV image
170
 * @return RGB PIX or null on failure
171
 */
172
PIX pixConvertHSVToRGB(PIX pixd, PIX pixs);
173
```
174

175
**Usage Examples:**
176

177
```java
178
// Convert RGB to grayscale with standard weights
179
PIX gray = pixConvertRGBToGray(rgbPix, 0.299f, 0.587f, 0.114f);
180

181
// Convert to 8-bit with colormap optimization
182
PIX eightBit = pixConvertTo8(sourcePix, 1);
183

184
// Convert any format to 32-bit RGB
185
PIX rgb32 = pixConvertTo32(sourcePix);
186

187
// Remove alpha channel
188
PIX rgb = pixRemoveAlpha(rgbaPix);
189

190
// Add semi-transparent alpha
191
PIX rgba = pixAddAlphaToBlend(rgbPix, 0.8f, 0);
192

193
// HSV conversion for color manipulation
194
PIX hsv = pixConvertRGBToHSV(null, rgbPix);
195
// ... modify HSV values ...
196
PIX modifiedRgb = pixConvertHSVToRGB(null, hsv);
197
```
198

199
### Filtering and Enhancement
200

201
Apply various filters and enhancement operations to improve image quality and extract features.
202

203
```java { .api }
204
/**
205
 * Gaussian blur filter
206
 * @param pixs - Source image
207
 * @param sigmax - Horizontal standard deviation
208
 * @param sigmay - Vertical standard deviation  
209
 * @return Blurred PIX or null on failure
210
 */
211
PIX pixGaussianBlur(PIX pixs, float sigmax, float sigmay);
212

213
/**
214
 * Unsharp masking for image sharpening
215
 * @param pixs - Source image
216
 * @param halfwidth - Mask half-width
217
 * @param fract - Unsharp fraction
218
 * @return Sharpened PIX or null on failure
219
 */
220
PIX pixUnsharpMasking(PIX pixs, int halfwidth, float fract);
221

222
/**
223
 * Median filter for noise reduction
224
 * @param pixs - Source image
225
 * @param halfwidth - Filter half-width
226
 * @param halfheight - Filter half-height
227
 * @return Filtered PIX or null on failure
228
 */
229
PIX pixMedianFilter(PIX pixs, int halfwidth, int halfheight);
230

231
/**
232
 * Rank filter (generalized median)
233
 * @param pixs - Source image
234
 * @param halfwidth - Filter half-width
235
 * @param halfheight - Filter half-height  
236
 * @param rank - Rank value (0.0-1.0, 0.5 = median)
237
 * @return Filtered PIX or null on failure
238
 */
239
PIX pixRankFilter(PIX pixs, int halfwidth, int halfheight, float rank);
240

241
/**
242
 * Edge detection using Sobel operator
243
 * @param pixs - Source grayscale image
244
 * @return Edge map PIX or null on failure
245
 */
246
PIX pixSobelEdgeFilter(PIX pixs, int orientflag);
247

248
/**
249
 * Convolution with custom kernel
250
 * @param pixs - Source image
251
 * @param kel - Convolution kernel
252
 * @param outdepth - Output depth (8, 16, or 32)
253
 * @param normflag - 1 to normalize, 0 otherwise
254
 * @return Convolved PIX or null on failure
255
 */
256
PIX pixConvolve(PIX pixs, L_KERNEL kel, int outdepth, int normflag);
257

258
/**
259
 * Bilateral filter for noise reduction with edge preservation
260
 * @param pixs - Source image
261
 * @param spatial_stdev - Spatial standard deviation
262
 * @param range_stdev - Range standard deviation
263
 * @param ncomps - Number of components
264
 * @param reduction - Size reduction factor
265
 * @return Filtered PIX or null on failure
266
 */
267
PIX pixBilateralFilter(PIX pixs, float spatial_stdev, float range_stdev, int ncomps, int reduction);
268
```
269

270
**Usage Examples:**
271

272
```java
273
// Apply Gaussian blur
274
PIX blurred = pixGaussianBlur(sourcePix, 2.0f, 2.0f);
275

276
// Sharpen image with unsharp masking  
277
PIX sharpened = pixUnsharpMasking(sourcePix, 3, 0.3f);
278

279
// Remove noise with median filter
280
PIX denoised = pixMedianFilter(sourcePix, 1, 1);
281

282
// Edge detection
283
PIX edges = pixSobelEdgeFilter(grayPix, L_ALL_EDGES);
284

285
// Bilateral filter for advanced noise reduction
286
PIX filtered = pixBilateralFilter(sourcePix, 10.0f, 20.0f, 1, 1);
287

288
// Custom convolution with edge detection kernel
289
L_KERNEL kernel = kernelCreateFromString(3, 3, 1, 1, "-1 -1 -1; -1 8 -1; -1 -1 -1", 1.0f, "edge");
290
PIX convolved = pixConvolve(sourcePix, kernel, 8, 1);
291
```
292

293
### Thresholding and Binarization
294

295
Convert grayscale images to binary with various thresholding methods and adaptive algorithms.
296

297
```java { .api }
298
/**
299
 * Threshold to binary using fixed value
300
 * @param pixs - Source grayscale image
301
 * @param thresh - Threshold value (0-255)
302
 * @return Binary PIX or null on failure
303
 */
304
PIX pixThresholdToBinary(PIX pixs, int thresh);
305

306
/**
307
 * Otsu's automatic threshold selection
308
 * @param pixs - Source grayscale image
309
 * @param sx - Tile width for local adaptation
310
 * @param sy - Tile height for local adaptation
311
 * @param smoothx - Smoothing in x direction
312
 * @param smoothy - Smoothing in y direction
313
 * @param scorefract - Score fraction for validation
314
 * @param pthresh - Returns computed threshold
315
 * @return Binary PIX or null on failure
316
 */
317
PIX pixOtsuAdaptiveThreshold(PIX pixs, int sx, int sy, int smoothx, int smoothy, 
318
                            float scorefract, IntPointer pthresh);
319

320
/**
321
 * Sauvola's local adaptive thresholding
322
 * @param pixs - Source grayscale image
323
 * @param whsize - Window half-size
324
 * @param factor - Sauvola factor (typically 0.35)
325
 * @param addborder - 1 to add border, 0 otherwise
326
 * @return Binary PIX or null on failure
327
 */
328
PIX pixSauvolaOnContrastNorm(PIX pixs, int whsize, float factor, int addborder);
329

330
/**
331
 * Threshold with hysteresis (dual threshold)
332
 * @param pixs - Source grayscale image
333
 * @param lowthresh - Low threshold value
334
 * @param highthresh - High threshold value
335
 * @return Binary PIX or null on failure  
336
 */
337
PIX pixThresholdWithHysteresis(PIX pixs, int lowthresh, int highthresh);
338
```
339

340
**Usage Examples:**
341

342
```java
343
// Simple fixed threshold
344
PIX binary = pixThresholdToBinary(grayPix, 128);
345

346
// Otsu's adaptive threshold  
347
IntPointer threshold = new IntPointer(1);
348
PIX otsuBinary = pixOtsuAdaptiveThreshold(grayPix, 32, 32, 0, 0, 0.1f, threshold);
349
System.out.println("Otsu threshold: " + threshold.get());
350

351
// Sauvola's local adaptive threshold for documents
352
PIX sauvolaBinary = pixSauvolaOnContrastNorm(grayPix, 25, 0.35f, 1);
353

354
// Hysteresis thresholding for edge maps
355
PIX hysteresis = pixThresholdWithHysteresis(edgeMap, 50, 100);
356
```
357

358
### Histogram Operations
359

360
Analyze and manipulate image histograms for exposure correction and analysis.
361

362
```java { .api }
363
/**
364
 * Compute image histogram
365
 * @param pixs - Source image
366
 * @param factor - Sampling factor (1 = all pixels)
367
 * @return NUMA array containing histogram or null on failure
368
 */
369
NUMA pixGetGrayHistogram(PIX pixs, int factor);
370

371
/**
372
 * Histogram equalization
373
 * @param pixd - Destination (can be null)
374
 * @param pixs - Source grayscale image
375
 * @return Equalized PIX or null on failure
376
 */
377
PIX pixEqualizeHistogram(PIX pixd, PIX pixs);
378

379
/**
380
 * Histogram specification (matching)
381
 * @param pixs - Source image
382
 * @param nahisto - Target histogram as NUMA
383
 * @return Matched PIX or null on failure
384
 */
385
PIX pixHistogramSpecification(PIX pixs, NUMA nahisto);
386

387
/**
388
 * Linear transform: out = gain * in + offset
389
 * @param pixd - Destination (can be null)
390
 * @param pixs - Source image
391
 * @param gain - Multiplicative factor  
392
 * @param offset - Additive offset
393
 * @return Transformed PIX or null on failure
394
 */
395
PIX pixLinearTransform(PIX pixd, PIX pixs, float gain, float offset);
396
```
397

398
**Usage Examples:**
399

400
```java
401
// Get histogram for analysis
402
NUMA histogram = pixGetGrayHistogram(grayPix, 1);
403
int[] histArray = numaGetIArray(histogram);
404

405
// Histogram equalization for contrast enhancement
406
PIX equalized = pixEqualizeHistogram(null, grayPix);
407

408
// Brightness/contrast adjustment
409
PIX adjusted = pixLinearTransform(null, grayPix, 1.2f, 10.0f); // +20% contrast, +10 brightness
410
```
411

412
### Convolution and Advanced Filtering
413

414
High-performance convolution operations using custom kernels for edge detection, blurring, sharpening, and feature extraction.
415

416
```java { .api }
417
/**
418
 * Convolution kernel for image filtering operations
419
 */
420
class L_KERNEL extends Pointer {
421
    int sy();           // kernel height
422
    int sx();           // kernel width  
423
    int cy();           // y location of kernel origin
424
    int cx();           // x location of kernel origin
425
    FloatPointer data(int i); // kernel data access
426
    
427
    // Manual cleanup
428
    void destroy();
429
}
430

431
// Kernel creation functions
432
L_KERNEL kernelCreate(int height, int width, int cy, int cx);
433
L_KERNEL kernelCreateFromString(int h, int w, int cy, int cx, String kdata);
434
L_KERNEL kernelCreateFromFile(String filename);
435

436
// Convolution operations
437
PIX pixConvolve(PIX pixs, L_KERNEL kel, int outdepth, int normflag);
438
PIX pixConvolveSep(PIX pixs, L_KERNEL kelx, L_KERNEL kely, int outdepth, int normflag);
439
PIX pixConvolveRGB(PIX pixs, L_KERNEL kel);
440
PIX pixConvolveRGBSep(PIX pixs, L_KERNEL kelx, L_KERNEL kely);
441

442
// Edge detection filters
443
PIX pixSobelEdgeFilter(PIX pixs, int orientflag);
444
PIX pixTwoSidedEdgeFilter(PIX pixs, int orientflag);
445

446
// Image enhancement
447
PIX pixUnsharpMasking(PIX pixs, int halfwidth, float fract);
448
```
449

450
**Usage Examples:**
451

452
```java
453
// Create a Gaussian blur kernel
454
L_KERNEL gaussKernel = kernelCreateFromString(5, 5, 2, 2,
455
    "1  4  6  4  1 " +
456
    "4 16 24 16  4 " + 
457
    "6 24 36 24  6 " +
458
    "4 16 24 16  4 " +
459
    "1  4  6  4  1");
460

461
// Apply Gaussian blur
462
PIX pixBlurred = pixConvolve(pixSource, gaussKernel, 8, L_NORMALIZED);
463

464
// Edge detection with Sobel filter
465
PIX pixEdges = pixSobelEdgeFilter(pixSource, L_ALL_EDGES);
466

467
// Unsharp masking for sharpening
468
PIX pixSharp = pixUnsharpMasking(pixSource, 5, 0.3f);
469
```
470

471
### Image Blending and Compositing
472

473
Advanced blending operations for combining multiple images with various blend modes and transparency effects.
474

475
```java { .api }
476
// Basic blending operations
477
PIX pixBlend(PIX pixs1, PIX pixs2, int x, int y, float fract);
478
PIX pixBlendMask(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int type);
479
PIX pixBlendColor(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int transparent, int transpix);
480
PIX pixBlendColorByChannel(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float rfract, float gfract, float bfract, int transparent, int transpix);
481

482
// Advanced blend modes
483
PIX pixBlendHardLight(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract);
484
PIX pixBlendWithGrayMask(PIX pixs1, PIX pixs2, PIX pixg, int x, int y);
485
PIX pixBlendGrayAdapt(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int shift);
486

487
// Colormap blending
488
int pixBlendCmap(PIX pixs, PIX pixb, int x, int y, int sindex);
489
```
490

491
**Usage Examples:**
492

493
```java
494
// Load images for blending
495
PIX background = pixRead("background.jpg");
496
PIX overlay = pixRead("overlay.png");
497

498
// Simple alpha blending
499
PIX blended = pixBlend(background, overlay, 100, 50, 0.7f);
500

501
// Color blending with transparency (white pixels become transparent)
502
PIX colorBlend = pixBlendColor(null, background, overlay, 0, 0, 0.5f, 1, 0xffffff);
503

504
// Hard light blend mode for dramatic effects
505
PIX hardLight = pixBlendHardLight(null, background, overlay, 0, 0, 0.8f);
506
```
507

508
## Processing Constants
509

510
Key constants for image processing operations:
511

512
```java { .api }
513
// Rotation types
514
static final int L_ROTATE_SHEAR = 1;
515
static final int L_ROTATE_AREA_MAP = 2;
516
static final int L_ROTATE_SAMPLING = 3;
517

518
// Background fill colors
519
static final int L_BRING_IN_WHITE = 1;
520
static final int L_BRING_IN_BLACK = 2;
521

522
// Edge orientations
523
static final int L_HORIZONTAL_EDGES = 0;
524
static final int L_VERTICAL_EDGES = 1;
525
static final int L_ALL_EDGES = 2;
526

527
// Color channels
528
static final int COLOR_RED = 0;
529
static final int COLOR_GREEN = 1;
530
static final int COLOR_BLUE = 2;
531
static final int L_ALPHA_CHANNEL = 3;
532
```
533

534
## Performance Tips
535

536
- **In-place Operations**: Use `pixd` parameter when available for memory efficiency
537
- **Sampling**: Use `factor` parameter in histogram functions to sample large images
538
- **Bit Depth**: Convert to appropriate bit depth before processing (8-bit for most operations)
539
- **Filter Size**: Larger filter kernels provide better quality but slower processing
540
- **Gaussian vs Median**: Gaussian blur is faster but median filter better preserves edges