0
# JavaCPP Leptonica
1

2
JavaCPP Leptonica provides comprehensive Java bindings for the Leptonica image processing library, enabling industrial-strength image processing capabilities in Java applications. The library supports morphological operations, image enhancement, analysis, format conversion, OCR support, and document processing across multiple platforms with automatic memory management.
3

4
## Package Information
5

6
- **Package Name**: leptonica-platform
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.bytedeco</groupId>
13
    <artifactId>leptonica-platform</artifactId>
14
    <version>1.85.0-1.5.12</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.bytedeco.javacpp.Loader;
22
import org.bytedeco.leptonica.*;
23
import static org.bytedeco.leptonica.global.leptonica.*;
24
```
25

26
For comprehensive development:
27
```java
28
// Core image structures
29
import org.bytedeco.leptonica.PIX;
30
import org.bytedeco.leptonica.PIXA;
31
import org.bytedeco.leptonica.PIXAA;
32
import org.bytedeco.leptonica.FPIX;
33
import org.bytedeco.leptonica.DPIX;
34

35
// Geometric structures
36
import org.bytedeco.leptonica.BOX;
37
import org.bytedeco.leptonica.BOXA;
38
import org.bytedeco.leptonica.PTA;
39
import org.bytedeco.leptonica.PTAA;
40

41
// Morphological and recognition
42
import org.bytedeco.leptonica.SEL;
43
import org.bytedeco.leptonica.SELA;
44
import org.bytedeco.leptonica.L_RECOG;
45
import org.bytedeco.leptonica.L_DEWARP;
46
import org.bytedeco.leptonica.L_DEWARPA;
47

48
// Connected components and contours
49
import org.bytedeco.leptonica.CCBORD;
50
import org.bytedeco.leptonica.CCBORDA;
51

52
// Utility structures
53
import org.bytedeco.leptonica.NUMA;
54
import org.bytedeco.leptonica.SARRAY;
55
import org.bytedeco.leptonica.L_STACK;
56
import org.bytedeco.leptonica.PIXCMAP;
57

58
// All static functions
59
import static org.bytedeco.leptonica.global.leptonica.*;
60
```
61

62
For minimal imports:
63
```java
64
import org.bytedeco.leptonica.PIX;
65
import org.bytedeco.leptonica.BOX;
66
import static org.bytedeco.leptonica.global.leptonica.pixRead;
67
import static org.bytedeco.leptonica.global.leptonica.pixWrite;
68
```
69

70
## Basic Usage
71

72
```java
73
import org.bytedeco.leptonica.*;
74
import static org.bytedeco.leptonica.global.leptonica.*;
75

76
// Initialize the library
77
Loader.load(org.bytedeco.leptonica.global.leptonica.class);
78

79
// Read an image
80
PIX pixSource = pixRead("input.png");
81

82
// Create a processed copy using morphological operations  
83
SEL sel = selCreateBrick(5, 5, 2, 2);
84
PIX pixProcessed = pixDilate(null, pixSource, sel);
85

86
// Get image dimensions
87
int width = pixGetWidth(pixSource);
88
int height = pixGetHeight(pixSource);
89
int depth = pixGetDepth(pixSource);
90

91
// Write result
92
pixWrite("output.png", pixProcessed, IFF_PNG);
93

94
// Memory is automatically managed - no manual cleanup needed
95
```
96

97
## Architecture
98

99
JavaCPP Leptonica is built around several key components:
100

101
- **Core Image Types**: PIX, FPIX, DPIX classes with automatic memory management via Abstract base classes
102
- **Collections**: Comprehensive array types (PIXA, PIXAA, BOXA, PTA, etc.) for organizing related data
103
- **Global Functions**: 2000+ native functions accessible through static imports covering all image processing operations
104
- **Geometric Structures**: BOX, PTA classes for defining regions and coordinate sets
105
- **Specialized Processing**: Dedicated classes for morphology, recognition, document processing, and more
106
- **Cross-Platform Support**: Native binaries for Linux, macOS, Windows, and Android with automatic platform detection
107

108
## Capabilities
109

110
### Core Image Structures
111

112
Primary image containers and their management, supporting multiple bit depths and color models with automatic memory cleanup.
113

114
```java { .api }
115
class PIX extends AbstractPIX {
116
    static PIX create(int width, int height, int depth);
117
    static PIX createTemplate(PIX pixs);
118
    PIX clone();
119
    
120
    // Dimensions and properties
121
    int w(); // width in pixels
122
    int h(); // height in pixels  
123
    int d(); // depth in bits per pixel
124
    int spp(); // samples per pixel
125
    
126
    // Data access
127
    IntPointer data();
128
    PIXCMAP colormap();
129
    BytePointer text();
130
}
131

132
class FPIX extends AbstractFPIX {
133
    // 32-bit float image operations
134
}
135

136
class DPIX extends AbstractDPIX {
137
    // 64-bit double image operations
138
}
139
```
140

141
[Core Image Structures](./core-images.md)
142

143
### Image I/O and Format Handling
144

145
Complete image reading, writing, and format conversion capabilities supporting all major image formats.
146

147
```java { .api }
148
// Reading images
149
PIX pixRead(String filename);
150
PIX pixReadStream(InputStream fp, int hint);
151
PIX pixReadMem(BytePointer data, long size);
152

153
// Writing images  
154
int pixWrite(String filename, PIX pix, int format);
155
int pixWriteStream(OutputStream fp, PIX pix, int format);
156
BytePointer pixWriteMem(PIX pix, long[] psize, int format);
157

158
// Format constants
159
static final int IFF_PNG = 1;
160
static final int IFF_JPEG = 2; 
161
static final int IFF_TIFF = 3;
162
```
163

164
[Image I/O Operations](./image-io.md)
165

166
### Image Processing and Transformations
167

168
Core image processing operations including scaling, rotation, morphological operations, and filtering.
169

170
```java { .api }
171
// Scaling and geometric transforms
172
PIX pixScale(PIX pixs, float scalex, float scaley);
173
PIX pixRotate(PIX pixs, float angle, int type, int incolor, int width, int height);
174
PIX pixAffine(PIX pixs, FloatPointer vc, int incolor);
175

176
// Morphological operations
177
PIX pixDilate(PIX pixd, PIX pixs, SEL sel);
178
PIX pixErode(PIX pixd, PIX pixs, SEL sel);
179
PIX pixOpen(PIX pixd, PIX pixs, SEL sel);
180
PIX pixClose(PIX pixd, PIX pixs, SEL sel);
181

182
// Color space conversion
183
PIX pixConvertRGBToGray(PIX pixs, float rwt, float gwt, float bwt);
184
PIX pixConvertGrayToColormap(PIX pixs);
185

186
// Image blending and compositing
187
PIX pixBlend(PIX pixs1, PIX pixs2, int x, int y, float fract);
188
PIX pixBlendColor(PIX pixd, PIX pixs1, PIX pixs2, int x, int y, float fract, int transparent, int transpix);
189

190
// Convolution and filtering  
191
PIX pixConvolve(PIX pixs, L_KERNEL kel, int outdepth, int normflag);
192
PIX pixSobelEdgeFilter(PIX pixs, int orientflag);
193
PIX pixUnsharpMasking(PIX pixs, int halfwidth, float fract);
194

195
// Convolution kernel type
196
class L_KERNEL extends Pointer {
197
    int sy();           // kernel height
198
    int sx();           // kernel width
199
    int cy();           // y origin coordinate  
200
    int cx();           // x origin coordinate
201
}
202
```
203

204
[Image Processing](./image-processing.md)
205

206
### Geometric Structures and Analysis
207

208
Rectangle and point operations for defining regions, measuring features, and spatial analysis.
209

210
```java { .api }
211
class BOX extends Pointer {
212
    int x(); // left coordinate
213
    int y(); // top coordinate  
214
    int w(); // width
215
    int h(); // height
216
}
217

218
class BOXA extends Pointer {
219
    // Array of BOX rectangles
220
}
221

222
class PTA extends Pointer {
223
    // Array of 2D points
224
}
225

226
// Box operations
227
BOX boxCreate(int x, int y, int w, int h);
228
int boxGetGeometry(BOX box, IntPointer px, IntPointer py, IntPointer pw, IntPointer ph);
229
BOX boxIntersection(BOX box1, BOX box2);
230
```
231

232
[Geometric Operations](./geometry.md)
233

234
### Morphological Operations and Structuring Elements
235

236
Advanced morphological processing with custom structuring elements for shape analysis and feature extraction.
237

238
```java { .api }
239
class SEL extends Pointer {
240
    // Structuring element for morphological operations
241
}
242

243
// Structuring element creation
244
SEL selCreateBrick(int h, int w, int cy, int cx);
245
SEL selCreateFromString(String text, int h, int w, String name);
246

247
// Advanced morphological operations
248
PIX pixMorphGradient(PIX pixs, SEL sel, int op);
249
PIX pixTophat(PIX pixs, SEL sel, int op);
250
PIX pixHMT(PIX pixd, PIX pixs, SEL sel);
251
```
252

253
[Morphological Operations](./morphology.md)
254

255
### Text Recognition and Document Processing
256

257
OCR capabilities, document analysis, and text extraction with specialized structures for character recognition.
258

259
```java { .api }
260
class L_RECOG extends Pointer {
261
    // Character recognition engine
262
}
263

264
class L_DEWARP extends Pointer {
265
    // Document dewarp correction
266
}
267

268
class L_DEWARPA extends Pointer {  
269
    // Multi-page dewarp processing
270
}
271

272
// Recognition functions
273
L_RECOG recogCreateFromRecog(L_RECOG recs, int scalew, int scaleh, int linew, int threshold, int maxyshift);
274
int recogTrainLabeled(L_RECOG recog, PIX pixs, BOX box, String text, int debug);
275
```
276

277
[Text Recognition](./text-recognition.md)
278

279
### Image Collections and Data Structures
280

281
Container classes for organizing and manipulating groups of images and associated metadata.
282

283
```java { .api }
284
class PIXA extends Pointer {
285
    // Array of PIX images with optional boxes
286
    int n(); // number of images
287
}
288

289
class PIXAA extends Pointer {
290
    // 2D array of PIXA structures  
291
}
292

293
// Collection operations
294
PIXA pixaCreate(int n);
295
int pixaAddPix(PIXA pixa, PIX pix, int copyflag);
296
PIX pixaGetPix(PIXA pixa, int index, int accesstype);
297
BOXA pixaGetBoxa(PIXA pixa, int accesstype);
298
```
299

300
[Image Collections](./collections.md)
301

302
### Connected Components and Contour Analysis
303

304
Comprehensive connected component analysis, contour processing, and border representations for object detection and shape analysis.
305

306
```java { .api }
307
class CCBORD extends Pointer {
308
    PIX pix();           // minimally-clipped bitmap of component
309
    BOXA boxa();         // boxes for primary component and holes
310
    PTA start();         // initial border pixel locations
311
    PTAA local();        // chain code for border (relative coords)
312
    PTAA global();       // global pixel locations of border
313
}
314

315
class CCBORDA extends Pointer {
316
    int n();             // number of ccbords
317
    CCBORD getCcbord(int index);
318
}
319

320
// Connected component functions
321
CCBORD ccbordCreate(PIX pixs, int connectivity);
322
PIX pixConnComp(PIX pixs, PIXA ppixa, int connectivity);
323
int pixCountConnComp(PIX pixs, int connectivity, IntPointer pcount);
324
PTA ptaGetBoundaryPixels(PIX pixs, int type);
325
```
326

327
[Connected Components](./connected-components.md)
328

329
### Utilities and Data Structures
330

331
Supporting data structures including arrays, stacks, queues, and utility functions for comprehensive image processing workflows.
332

333
```java { .api }
334
class NUMA extends Pointer {
335
    // Numeric array for statistics
336
}
337

338
class SARRAY extends Pointer {
339
    // String array
340
}
341

342
class L_STACK extends Pointer {
343
    // Stack data structure
344
}
345

346
// Utility functions
347
int pixCountPixels(PIX pix, IntPointer pcount, IntPointer tab8);
348
float pixGetAverageMasked(PIX pixs, PIX pixm, int x, int y, int w, int h, int factor, float[] pval);
349
```
350

351
[Utility Structures](./utilities.md)
352

353
## Error Handling
354

355
Most functions return status codes where 0 indicates success and non-zero indicates failure. For PIX creation functions, null return values indicate failure.
356

357
```java
358
PIX pix = pixRead("image.jpg");
359
if (pix == null) {
360
    System.err.println("Failed to read image");
361
    return;
362
}
363

364
int result = pixWrite("output.png", pix, IFF_PNG);
365
if (result != 0) {
366
    System.err.println("Failed to write image");
367
}
368
```
369

370
## Memory Management
371

372
JavaCPP provides automatic memory management through:
373
- Abstract base classes with automatic cleanup registration  
374
- Factory methods that handle deallocator registration
375
- Manual cleanup available via `destroy()` methods
376
- Reference counting for shared objects
377

378
The library handles native memory automatically, eliminating the need for manual memory management in most cases.